ContextMenu
좌표로 여는 컨텍스트 메뉴 컴포넌트입니다.
개요
CALS ContextMenu는 Foundation ContextMenu를 래핑합니다. shadcn처럼 트리거를 감싸지 않고, 소비자가 여는 이벤트를 받아 open·x·y로 넘깁니다.
주요 특징
- ✅ 좌표로 열기:
x·y는 뷰포트 좌표(clientX·clientY) - ✅ 여는 이벤트는 소비자 몫: 우클릭·ContextMenu 키·Shift+F10이 모두
contextmenu이벤트 - ✅ 항목 배열:
items로 항목·구분선·비활성·숨김·destructive를 정한다 - ✅ 위치 조정:
side·align·sideOffset·alignOffset
기본 사용
대상의 onContextMenu에서 기본 메뉴를 막고 좌표와 열림 상태를 넘깁니다.
Preview
우클릭하세요
선택: 없음
항목 상태 (disabled / hidden / destructive)
disabled는 누를 수 없고, hidden은 그리지 않으며, type: "destructive"는 위험 동작 색으로 그립니다.
Preview
우클릭 - disabled/hidden/destructive
항목 클릭 후 닫기 (hideOnClick)
기본(true)은 항목을 누르면 닫힙니다. false면 눌러도 열린 채로 둡니다.
Preview
우클릭 - 기본(닫힘)
우클릭 - hideOnClick={false}
위치 (side / align / sideOffset / alignOffset)
좌표(x·y)를 기준으로 펼칠 방향과 간격을 정합니다. 기본은 bottom·start·0·0입니다.
Preview
우클릭 - 기본
우클릭 - side=right align=center sideOffset=8
팝업 꾸밈 (className / style)
className·style은 메뉴 팝업(role="menu")에 붙습니다.
Preview
우클릭 - className·style
메뉴 이름 (aria-label)
aria-label(또는 aria-labelledby)이 메뉴 이름이 됩니다.
Preview
우클릭 - aria-label=탭 메뉴
키보드로 열기
대상에 tabIndex를 주면 onContextMenu 하나로 우클릭·ContextMenu 키·Shift+F10이 모두 열립니다. 키보드로 열면 좌표가 없어 요소 위치로 계산합니다.
Preview
Tab으로 들어와 ContextMenu 키 또는 Shift+F10
API Reference
Props
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
open | boolean | - | 열림/닫힘 상태 |
onOpenChange | (open: boolean) => void | - | 상태 변경 콜백 |
x | number | 0 | 메뉴 X 좌표 |
y | number | 0 | 메뉴 Y 좌표 |
position | "fixed" | "absolute" | "fixed" | CSS position 전략 |
items | ContextMenuItem[] | [] | 메뉴 항목 목록 |
onItemClick | (item: ContextMenuItem) => void | - | 항목 클릭 콜백 |
hideOnClick | boolean | true | 클릭 후 자동 닫힘 |
side | "top" | "bottom" | "left" | "right" | … | "bottom" | 좌표 기준 펼침 방향 |
align | "start" | "center" | "end" | "start" | 정렬 |
sideOffset | number | 0 | 방향 쪽 간격(px) |
alignOffset | number | 0 | 정렬 쪽 간격(px) |
aria-label / aria-labelledby | string | - | 메뉴 이름 |
className | string | - | 메뉴 팝업 className |
style | CSSProperties | - | 메뉴 팝업 인라인 스타일 (className과 같은 요소) |
ContextMenuItem
| Prop | 타입 | 기본값 | 설명 |
|---|---|---|---|
key | string | - | 고유 키 |
label | string | - | 표시 텍스트 |
type | "default" | "destructive" | "separator" | "default" | 항목 유형 |
hidden | boolean | false | 숨김 여부 |
disabled | boolean | false | 비활성화 여부 |
접근성
role="menu", 각 항목role="menuitem"- 키보드 탐색: ArrowUp/Down, Enter
- Escape 키 또는 외부 클릭으로 닫히고, 닫으면 열기 전 요소로 포커스가 돌아온다
권장 사항
- ✅ 키보드로도 열 수 있게 대상에
tabIndex를 주고onContextMenu하나로 받는다 - ✅ 메뉴 이름이 필요하면
aria-label(또는aria-labelledby)을 준다 - ❌ 메뉴에만 있는 기능을 두지 않는다 (우클릭을 모르는 사용자도 쓸 수 있는 다른 경로를 둔다)
관련 컴포넌트
- DropdownMenu: 트리거를 감싸는 메뉴가 필요할 때
- TagView: 탭 우클릭 메뉴를 내장한 컴포넌트
Last updated on