@ceed/ads 1.23.2 → 1.23.4

package/dist/components/navigation/Menu.md

@@ -1,8 +1,8 @@
 # Menu
 
-## Introduction
+Menu and MenuItem are the content layer of a dropdown menu system. Menu renders the floating panel that contains a list of selectable items, while MenuItem represents each individual option. Together with Dropdown (the state container) and a trigger component (MenuButton or IconMenuButton), they form a complete menu composition.
 
-Menu와 MenuItem 컴포넌트는 드롭다운 메뉴의 콘텐츠를 구성하는 컴포넌트입니다. Joy UI의 Menu와 MenuItem을 기반으로 합니다.. Dropdown 컴포넌트와 함께 사용하여 사용자에게 선택 가능한 옵션들을 제공합니다. 네비게이션, 액션 메뉴, 컨텍스트 메뉴 등 다양한 용도로 활용할 수 있습니다.
+Menu is built on Joy UI's Menu component and supports sizes, placements, custom styling, and rich content inside menu items such as icons, links, and nested layouts.
 
 ```tsx
 <Box sx={{
@@ -26,27 +26,42 @@ Menu와 MenuItem 컴포넌트는 드롭다운 메뉴의 콘텐츠를 구성하
 ## Usage
 
 ```tsx
-import { Dropdown, MenuButton, Menu, MenuItem } from '@ceed/ads';
+import { Dropdown, Menu, MenuItem } from '@ceed/ads';
+import { MenuButton } from '@ceed/ads';
 
 function MyComponent() {
   return (
     <Dropdown>
-      <MenuButton>메뉴 열기</MenuButton>
+      <MenuButton>Open Menu</MenuButton>
       <Menu>
-        <MenuItem>옵션 1</MenuItem>
-        <MenuItem>옵션 2</MenuItem>
-        <MenuItem>옵션 3</MenuItem>
+        <MenuItem>Option 1</MenuItem>
+        <MenuItem>Option 2</MenuItem>
+        <MenuItem>Option 3</MenuItem>
       </Menu>
     </Dropdown>
   );
 }
 ```
 
-## Examples
+## Composition Pattern
+
+Menu is always used inside a Dropdown together with a trigger element. The full composition looks like this:
+
+```
+Dropdown          -- state container (open/close)
+  MenuButton      -- trigger element (or IconMenuButton)
+  Menu            -- floating panel
+    MenuItem      -- individual option
+    ListDivider   -- visual separator between groups
+```
+
+See the [Dropdown](?path=/docs/components-navigation-dropdown--docs) documentation for guidance on when to use the composition pattern versus the standalone MenuButton/IconMenuButton components.
+
+## Features
 
 ### Basic Menu
 
-가장 기본적인 Menu 사용법입니다.
+A standard menu with simple text items, optionally separated by dividers.
 
 ```tsx
 <Stack direction="row" spacing={3}>
@@ -77,7 +92,7 @@ function MyComponent() {
 
 ### Menu Sizes
 
-다양한 크기의 메뉴를 사용할 수 있습니다.
+Menu supports `sm`, `md`, and `lg` sizes that affect the padding and font size of all items.
 
 ```tsx
 <Stack direction="row" spacing={3}>
@@ -118,7 +133,7 @@ function MyComponent() {
 
 ### MenuItem States
 
-MenuItem의 다양한 상태를 표현할 수 있습니다.
+MenuItems can be `selected`, `disabled`, or colored with semantic colors like `primary`, `danger`, `success`, and `warning`.
 
 ```tsx
 <Dropdown>
@@ -137,7 +152,7 @@ MenuItem의 다양한 상태를 표현할 수 있습니다.
 
 ### MenuItem with Icons
 
-메뉴 아이템에 아이콘을 추가할 수 있습니다.
+Add icons before item text to improve scannability. Use consistent icon sizing with `sx={{ mr: 1.5, fontSize: 'lg' }}`.
 
 ```tsx
 <Dropdown>
@@ -180,7 +195,7 @@ MenuItem의 다양한 상태를 표현할 수 있습니다.
 
 ### Actions Menu
 
-편집, 삭제 등의 액션 메뉴로 활용할 수 있습니다.
+Build action menus for CRUD operations. Use `color="danger"` to highlight destructive actions.
 
 ```tsx
 <Dropdown>
@@ -223,7 +238,7 @@ MenuItem의 다양한 상태를 표현할 수 있습니다.
 
 ### Clickable Menu Items
 
-메뉴 아이템에 클릭 이벤트를 연결할 수 있습니다.
+Attach `onClick` handlers to menu items to respond to user selections.
 
 ```tsx
 <Stack spacing={2}>
@@ -242,7 +257,7 @@ MenuItem의 다양한 상태를 표현할 수 있습니다.
 
 ### Menu as Links
 
-메뉴 아이템을 링크로 사용할 수 있습니다.
+Use the `component="a"` prop on MenuItem to render items as anchor links for navigation.
 
 ```tsx
 <Dropdown>
@@ -266,7 +281,7 @@ MenuItem의 다양한 상태를 표현할 수 있습니다.
 
 ### Profile Menu
 
-사용자 프로필 메뉴의 완성된 예제입니다.
+Combine custom Box content (user info header) with standard MenuItem entries for rich profile menus.
 
 ```tsx
 <Dropdown>
@@ -336,7 +351,7 @@ MenuItem의 다양한 상태를 표현할 수 있습니다.
 
 ### Menu Placements
 
-메뉴가 나타나는 위치를 다양하게 설정할 수 있습니다.
+Control the position of the menu panel relative to the trigger using the `placement` prop. Supported values include `top-start`, `top`, `top-end`, `bottom-start`, `bottom`, and `bottom-end`.
 
 ```tsx
 <Stack spacing={4} alignItems="center" sx={{
@@ -405,7 +420,7 @@ MenuItem의 다양한 상태를 표현할 수 있습니다.
 
 ### Long Scrollable Menu
 
-많은 옵션이 있는 메뉴는 스크롤을 적용할 수 있습니다.
+For menus with many items, apply `maxHeight` and `overflow: 'auto'` through the `sx` prop.
 
 ```tsx
 <Dropdown>
@@ -423,7 +438,7 @@ MenuItem의 다양한 상태를 표현할 수 있습니다.
 
 ### Custom Styled Menu
 
-CSS 스타일을 이용해 메뉴를 커스터마이징할 수 있습니다.
+Customize the menu panel appearance with border-radius, shadows, borders, and custom item spacing.
 
 ```tsx
 <Stack direction="row" spacing={3}>
@@ -487,7 +502,7 @@ CSS 스타일을 이용해 메뉴를 커스터마이징할 수 있습니다.
 
 ### Menu in Card
 
-카드나 다른 컴포넌트 내에서 메뉴를 사용할 수 있습니다.
+Embed a Dropdown menu inside cards or other container components for contextual actions.
 
 ```tsx
 <Sheet variant="outlined" sx={{
@@ -547,7 +562,7 @@ CSS 스타일을 이용해 메뉴를 커스터마이징할 수 있습니다.
 
 ### Nested Content
 
-메뉴 내에 복잡한 콘텐츠를 구성할 수 있습니다.
+Menu can contain non-MenuItem elements like Box, Typography, and progress indicators alongside standard items.
 
 ```tsx
 <Dropdown>
@@ -631,93 +646,42 @@ CSS 스타일을 이용해 메뉴를 커스터마이징할 수 있습니다.
 </Dropdown>
 ```
 
-## Component Structure
-
-Menu는 다음과 같은 구조로 구성됩니다:
-
-```tsx
-<Dropdown>
-  <MenuButton>트리거</MenuButton>
-  <Menu>
-    {/* 기본 메뉴 아이템 */}
-    <MenuItem>기본 아이템</MenuItem>
-
-    {/* 아이콘이 있는 메뉴 아이템 */}
-    <MenuItem>
-      <Icon sx={{ mr: 1 }} />
-      아이콘 아이템
-    </MenuItem>
-
-    {/* 구분선 */}
-    <ListDivider />
-
-    {/* 색상이 있는 메뉴 아이템 */}
-    <MenuItem color="danger">위험한 작업</MenuItem>
-
-    {/* 비활성 메뉴 아이템 */}
-    <MenuItem disabled>비활성 아이템</MenuItem>
-
-    {/* 링크 메뉴 아이템 */}
-    <MenuItem component="a" href="/link">
-      링크 아이템
-    </MenuItem>
-
-    {/* 클릭 핸들러가 있는 메뉴 아이템 */}
-    <MenuItem onClick={handleClick}>클릭 가능한 아이템</MenuItem>
-  </Menu>
-</Dropdown>
-```
-
 ## Common Use Cases
 
-### Navigation Menu
+### Action Menu with Icons
 
 ```tsx
 <Dropdown>
-  <MenuButton>네비게이션</MenuButton>
+  <MenuButton variant="plain" size="sm">Actions</MenuButton>
   <Menu>
-    <MenuItem component="a" href="/home">
-      홈
-    </MenuItem>
-    <MenuItem component="a" href="/products">
-      제품
+    <MenuItem onClick={handleEdit}>
+      <EditIcon sx={{ mr: 1 }} />
+      Edit
     </MenuItem>
-    <MenuItem component="a" href="/services">
-      서비스
+    <MenuItem onClick={handleCopy}>
+      <CopyIcon sx={{ mr: 1 }} />
+      Copy
     </MenuItem>
     <ListDivider />
-    <MenuItem component="a" href="/contact">
-      문의하기
+    <MenuItem color="danger" onClick={handleDelete}>
+      <DeleteIcon sx={{ mr: 1 }} />
+      Delete
     </MenuItem>
   </Menu>
 </Dropdown>
 ```
 
-### Action Menu with Icons
+### Navigation Menu
 
 ```tsx
 <Dropdown>
-  <MenuButton variant="plain" size="sm">
-    작업
-  </MenuButton>
+  <MenuButton>Navigate</MenuButton>
   <Menu>
-    <MenuItem onClick={handleEdit}>
-      <EditIcon sx={{ mr: 1 }} />
-      편집
-    </MenuItem>
-    <MenuItem onClick={handleCopy}>
-      <CopyIcon sx={{ mr: 1 }} />
-      복사
-    </MenuItem>
-    <MenuItem onClick={handleShare}>
-      <ShareIcon sx={{ mr: 1 }} />
-      공유
-    </MenuItem>
+    <MenuItem component="a" href="/home">Home</MenuItem>
+    <MenuItem component="a" href="/products">Products</MenuItem>
+    <MenuItem component="a" href="/services">Services</MenuItem>
     <ListDivider />
-    <MenuItem color="danger" onClick={handleDelete}>
-      <DeleteIcon sx={{ mr: 1 }} />
-      삭제
-    </MenuItem>
+    <MenuItem component="a" href="/contact">Contact</MenuItem>
   </Menu>
 </Dropdown>
 ```
@@ -726,232 +690,75 @@ Menu는 다음과 같은 구조로 구성됩니다:
 
 ```tsx
 <Dropdown>
-  <MenuButton startDecorator={<Avatar size="sm" src="/avatar.jpg" />} endDecorator={<ExpandMoreIcon />}>
-    사용자명
+  <MenuButton
+    startDecorator={<Avatar size="sm" src="/avatar.jpg" />}
+    endDecorator={<ExpandMoreIcon />}
+  >
+    Username
   </MenuButton>
   <Menu>
-    {/* 프로필 헤더 */}
     <Box sx={{ px: 2, py: 1.5 }}>
-      <Typography level="title-sm">사용자명</Typography>
-      <Typography level="body-xs" color="neutral">
-        user@example.com
-      </Typography>
+      <Typography level="title-sm">Username</Typography>
+      <Typography level="body-xs" color="neutral">user@example.com</Typography>
     </Box>
-
     <ListDivider />
-
     <MenuItem>
       <PersonIcon sx={{ mr: 1 }} />
-      프로필 보기
+      Profile
     </MenuItem>
     <MenuItem>
       <SettingsIcon sx={{ mr: 1 }} />
-      설정
+      Settings
     </MenuItem>
-
     <ListDivider />
-
     <MenuItem>
       <LogoutIcon sx={{ mr: 1 }} />
-      로그아웃
+      Logout
     </MenuItem>
   </Menu>
 </Dropdown>
 ```
 
-### Filter Menu
-
-```tsx
-const [filter, setFilter] = useState('전체');
-
-<Dropdown>
-  <MenuButton startDecorator={<FilterListIcon />} endDecorator={<ExpandMoreIcon />}>
-    필터: {filter}
-  </MenuButton>
-  <Menu>
-    <MenuItem selected={filter === '전체'} onClick={() => setFilter('전체')}>
-      전체
-    </MenuItem>
-    <MenuItem selected={filter === '활성'} onClick={() => setFilter('활성')}>
-      활성
-    </MenuItem>
-    <MenuItem selected={filter === '비활성'} onClick={() => setFilter('비활성')}>
-      비활성
-    </MenuItem>
-  </Menu>
-</Dropdown>;
-```
-
-### Context Menu (Right-click Menu)
-
-```tsx
-const [contextMenu, setContextMenu] = useState(null);
-
-const handleContextMenu = (event) => {
-  event.preventDefault();
-  setContextMenu({
-    mouseX: event.clientX - 2,
-    mouseY: event.clientY - 4,
-  });
-};
-
-<div onContextMenu={handleContextMenu}>
-  우클릭 가능한 영역
-  {contextMenu && (
-    <Menu
-      open
-      anchorReference="anchorPosition"
-      anchorPosition={{
-        top: contextMenu.mouseY,
-        left: contextMenu.mouseX,
-      }}
-      onClose={() => setContextMenu(null)}
-    >
-      <MenuItem>복사</MenuItem>
-      <MenuItem>붙여넣기</MenuItem>
-      <MenuItem>삭제</MenuItem>
-    </Menu>
-  )}
-</div>;
-```
+## Best Practices
 
-### Submenu Pattern
+- **Use ListDivider to group related items.** Logical grouping helps users scan the menu faster. Place destructive actions (like Delete) in their own group at the bottom.
 
-```tsx
-<Dropdown>
-  <MenuButton>파일</MenuButton>
+  ```tsx
+  {/* ✅ Good: Grouped actions with divider */}
   <Menu>
-    <MenuItem>새 파일</MenuItem>
-    <MenuItem>열기</MenuItem>
-
-    {/* 서브메뉴는 별도 Dropdown으로 구현 */}
-    <MenuItem>
-      최근 파일
-      <Dropdown>
-        <MenuButton variant="plain" size="sm" sx={{ ml: 'auto' }}>
-          ▶
-        </MenuButton>
-        <Menu placement="right-start">
-          <MenuItem>파일1.txt</MenuItem>
-          <MenuItem>파일2.txt</MenuItem>
-          <MenuItem>파일3.txt</MenuItem>
-        </Menu>
-      </Dropdown>
-    </MenuItem>
-
+    <MenuItem>Edit</MenuItem>
+    <MenuItem>Duplicate</MenuItem>
     <ListDivider />
-    <MenuItem>저장</MenuItem>
-    <MenuItem>종료</MenuItem>
+    <MenuItem color="danger">Delete</MenuItem>
   </Menu>
-</Dropdown>
-```
+  ```
 
-## Menu Placement
+- **Keep icon sizing consistent.** When using icons in menu items, apply the same `fontSize` and `mr` (margin-right) to all icons so items align cleanly.
 
-메뉴의 위치는 `placement` prop으로 조정할 수 있습니다:
-
-```tsx
-<Menu placement="top-start">      {/* 위쪽 왼쪽 정렬 */}
-<Menu placement="top">            {/* 위쪽 중앙 정렬 */}
-<Menu placement="top-end">        {/* 위쪽 오른쪽 정렬 */}
-<Menu placement="bottom-start">   {/* 아래쪽 왼쪽 정렬 (기본값) */}
-<Menu placement="bottom">         {/* 아래쪽 중앙 정렬 */}
-<Menu placement="bottom-end">     {/* 아래쪽 오른쪽 정렬 */}
-```
-
-## Accessibility
+  ```tsx
+  {/* ✅ Good: Consistent icon styling */}
+  <MenuItem><EditIcon sx={{ mr: 1.5, fontSize: 'lg' }} />Edit</MenuItem>
+  <MenuItem><DeleteIcon sx={{ mr: 1.5, fontSize: 'lg' }} />Delete</MenuItem>
 
-Menu 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:
+  {/* ❌ Avoid: Inconsistent icon sizes */}
+  <MenuItem><EditIcon sx={{ mr: 1 }} />Edit</MenuItem>
+  <MenuItem><DeleteIcon sx={{ mr: 2, fontSize: 'xl' }} />Delete</MenuItem>
+  ```
 
-### 키보드 탐색
+- **Limit menu length.** Aim for 3-7 visible items. For longer lists, set `maxHeight` on Menu to enable scrolling, or reconsider the UI pattern.
 
-- **Tab**: 메뉴 버튼으로 포커스 이동
-- **Enter/Space**: 메뉴 열기/닫기
-- **↑/↓**: 메뉴 아이템 간 이동
-- **Escape**: 메뉴 닫기
-- **Enter**: 메뉴 아이템 선택
+  ```tsx
+  {/* ✅ Good: Scrollable long menu */}
+  <Menu sx={{ maxHeight: 300, overflow: 'auto' }}>
+  ```
 
-### ARIA 속성
+- **Use semantic colors intentionally.** Reserve `color="danger"` for destructive actions. Do not use multiple colors in the same menu unless each color carries a distinct meaning.
 
-- `role="menu"`: 메뉴 역할 정의
-- `role="menuitem"`: 메뉴 아이템 역할 정의
-- `aria-expanded`: 메뉴 열림/닫힘 상태
-- `aria-haspopup`: 팝업 메뉴 존재 표시
+- **Provide clear labels.** Every MenuItem should have a concise, action-oriented label that makes its purpose obvious without needing additional context.
 
-### 추가 접근성 고려사항
-
-```tsx
-<MenuItem aria-label="사용자 프로필 편집">
-  <EditIcon />
-  편집
-</MenuItem>
-
-<MenuItem disabled aria-label="현재 사용할 수 없는 기능">
-  사용 불가
-</MenuItem>
-```
-
-## Best Practices
-
-1. **명확한 라벨링**: 메뉴 아이템은 명확하고 이해하기 쉬운 텍스트를 사용하세요.
-
-2. **아이콘 일관성**: 아이콘을 사용할 때는 일관된 크기와 스타일을 유지하세요.
-
-   ```tsx
-   <MenuItem>
-     <EditIcon sx={{ mr: 1.5, fontSize: 'lg' }} />
-     편집
-   </MenuItem>
-   ```
-
-3. **논리적 그룹화**: 관련된 메뉴 아이템들은 ListDivider로 구분하세요.
-
-4. **위험한 작업 구분**: 삭제와 같은 위험한 작업은 색상으로 구분하세요.
-
-   ```tsx
-   <MenuItem color="danger">
-     <DeleteIcon sx={{ mr: 1 }} />
-     삭제
-   </MenuItem>
-   ```
-
-5. **적절한 메뉴 크기**: 너무 긴 메뉴는 스크롤을 적용하거나 서브메뉴로 나누세요.
-
-   ```tsx
-   <Menu sx={{ maxHeight: 300, overflow: 'auto' }}>
-   ```
-
-6. **상태 피드백**: 선택된 아이템이나 현재 상태를 명확히 표시하세요.
-
-7. **모바일 고려**: 터치 기기에서 사용하기 쉽도록 충분한 터치 영역을 제공하세요.
-
-## Performance Considerations
-
-1. **메뉴 지연 로딩**: 복잡한 메뉴는 필요할 때만 렌더링하세요.
-
-2. **가상화**: 매우 긴 메뉴 목록에는 가상화를 고려하세요.
-
-3. **메모이제이션**: 정적인 메뉴 아이템들은 메모이제이션을 활용하세요.
-
-## Troubleshooting
-
-### 흔한 문제들
-
-1. **메뉴가 화면을 벗어남**
-
-   ```tsx
-   <Menu placement="top-end"> {/* placement 조정 */}
-   ```
-
-2. **긴 메뉴 스크롤 문제**
-
-   ```tsx
-   <Menu sx={{ maxHeight: 400, overflow: 'auto' }}>
-   ```
-
-3. **모바일에서 터치 영역 부족**
-   ```tsx
-   <MenuItem sx={{ minHeight: 44 }}> {/* 최소 터치 영역 보장 */}
-   ```
+## Accessibility
 
-Menu와 MenuItem은 사용자 친화적이고 접근성이 뛰어난 메뉴 시스템을 구축하는 핵심 컴포넌트입니다. 적절히 활용하면 직관적이고 효율적인 사용자 인터페이스를 만들 수 있습니다.
+- **ARIA roles**: Menu automatically receives `role="menu"` and each MenuItem receives `role="menuitem"`. These roles help assistive technologies announce the menu structure correctly.
+- **Keyboard navigation**: When the menu is open, Arrow Up/Down moves between items, Enter selects the focused item, and Escape closes the menu and returns focus to the trigger.
+- **Disabled items**: Use the `disabled` prop on MenuItem to prevent interaction. Disabled items remain in the tab order but cannot be activated, allowing screen readers to announce them as unavailable.
+- **Icon-only items**: If a MenuItem contains only an icon without visible text, add an `aria-label` to provide an accessible name.