Popover

트리거 클릭 시 부가 콘텐츠를 표시하는 팝오버 컴포넌트

개요

Popover 컴포넌트는 base-ui의 Popover Primitive를 기반으로 구축된 팝오버 컴포넌트입니다. 트리거를 클릭하면 플로팅 콘텐츠가 표시되며, 위치 지정, 헤더/제목/설명 구조를 지원합니다. 브라우저 뒤로가기/앞으로가기 시 자동으로 닫히는 처리가 포함되어 있습니다.

주요 특징

• ✅ 컴파운드 컴포넌트: Trigger, Content, Header, Title, Description 조합
• ✅ 위치 지정: side, align, sideOffset 등 포지셔닝 제어
• ✅ 포커스 관리: 열릴 때 포커스 이동, 닫힐 때 트리거로 복귀
• ✅ 히스토리 대응: 브라우저 뒤로가기 시 팝오버 자동 닫힘
• ✅ 접근성: role="dialog", ARIA 속성 자동 적용
• ✅ 디자인 토큰: 테마 커스터마이징 지원

구조 (Anatomy)

<Popover>
  <PopoverTrigger render={<Button>열기</Button>} />
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle>제목</PopoverTitle>
      <PopoverDescription>설명</PopoverDescription>
    </PopoverHeader>
    콘텐츠
  </PopoverContent>
</Popover>

사용 예시

기본 사용

트리거 버튼을 클릭하면 팝오버가 표시됩니다.

<Popover>
  <PopoverTrigger render={<Button variant="outline">팝오버 열기</Button>} />
  <PopoverContent>
    <div className="text-sm">팝오버 콘텐츠가 여기에 표시됩니다.</div>
  </PopoverContent>
</Popover>

헤더 포함

PopoverHeader, PopoverTitle, PopoverDescription으로 구조화된 콘텐츠를 구성합니다.

<Popover>
  <PopoverTrigger render={<Button variant="outline">설정</Button>} />
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle>표시 설정</PopoverTitle>
      <PopoverDescription>
        화면에 표시될 항목을 설정합니다.
      </PopoverDescription>
    </PopoverHeader>
    <div className="text-sm">추가 콘텐츠가 여기에 표시됩니다.</div>
  </PopoverContent>
</Popover>

위치 지정

side prop으로 팝오버 표시 위치를 지정합니다.

<Popover>
  <PopoverTrigger render={<Button variant="outline">Top</Button>} />
  <PopoverContent side="top">
    <div className="text-sm">위쪽 팝오버</div>
  </PopoverContent>
</Popover>
 
<Popover>
  <PopoverTrigger render={<Button variant="outline">Right</Button>} />
  <PopoverContent side="right">
    <div className="text-sm">오른쪽 팝오버</div>
  </PopoverContent>
</Popover>
 
<Popover>
  <PopoverTrigger render={<Button variant="outline">Bottom</Button>} />
  <PopoverContent side="bottom">
    <div className="text-sm">아래쪽 팝오버</div>
  </PopoverContent>
</Popover>
 
<Popover>
  <PopoverTrigger render={<Button variant="outline">Left</Button>} />
  <PopoverContent side="left">
    <div className="text-sm">왼쪽 팝오버</div>
  </PopoverContent>
</Popover>

API Reference

Popover

팝오버의 루트 컴포넌트입니다. base-ui Popover.Root를 래핑하며 열림 상태를 관리합니다.

PopoverTrigger

팝오버를 여는 트리거입니다. render prop으로 트리거 요소를 지정합니다.

PopoverContent

팝오버 콘텐츠 컨테이너입니다. Portal로 렌더링됩니다.

PopoverHeader

제목과 설명을 감싸는 헤더 컨테이너입니다.

PopoverTitle

팝오버 제목입니다. 콘텐츠의 접근성 라벨로 사용됩니다.

PopoverDescription

팝오버 설명입니다. 콘텐츠의 접근성 설명으로 사용됩니다.

기본 사용법

import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverHeader,
  PopoverTitle,
  PopoverDescription,
  Button,
} from "@vortex/ui-foundation"
 
<Popover>
  <PopoverTrigger render={<Button variant="outline">열기</Button>} />
  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle>제목</PopoverTitle>
      <PopoverDescription>설명 텍스트</PopoverDescription>
    </PopoverHeader>
    콘텐츠
  </PopoverContent>
</Popover>

접근성

ARIA 속성

• base-ui Popover 기반으로 팝오버에 role="dialog" 자동 적용
• PopoverTitle/PopoverDescription이 팝오버의 aria-labelledby/aria-describedby로 자동 연결
• 트리거에 aria-expanded, aria-haspopup 상태 자동 설정

포커스 관리

• 팝오버가 열리면 포커스가 콘텐츠 내부로 이동
• Esc 키로 닫기, 닫힌 후 포커스는 트리거로 복귀
• 외부 클릭 시 자동 닫힘

권장 사항

• ✅ 간단한 부가 정보나 설정 UI 표시에 사용
• ✅ PopoverTitle/PopoverDescription으로 콘텐츠에 라벨 제공
• ❌ 상호작용이 복잡한 콘텐츠는 Modal 사용

관련 컴포넌트

• DropdownMenu: 액션 메뉴 드롭다운
• Modal: 모달 다이얼로그
• Combobox: 검색 가능한 선택 팝업