@ceed/ads 1.29.0 → 1.30.0-next.1

package/dist/components/navigation/Menu.md

@@ -1,8 +1,8 @@
 # Menu
 
-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.
+## Introduction
 
-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.
+Menu와 MenuItem 컴포넌트는 드롭다운 메뉴의 콘텐츠를 구성하는 컴포넌트입니다. Joy UI의 Menu와 MenuItem을 기반으로 합니다.. Dropdown 컴포넌트와 함께 사용하여 사용자에게 선택 가능한 옵션들을 제공합니다. 네비게이션, 액션 메뉴, 컨텍스트 메뉴 등 다양한 용도로 활용할 수 있습니다.
 
 ```tsx
 <Box sx={{
@@ -26,42 +26,27 @@ Menu is built on Joy UI's Menu component and supports sizes, placements, custom
 ## Usage
 
 ```tsx
-import { Dropdown, Menu, MenuItem } from '@ceed/ads';
-import { MenuButton } from '@ceed/ads';
+import { Dropdown, MenuButton, Menu, MenuItem } from '@ceed/ads';
 
 function MyComponent() {
   return (
     <Dropdown>
-      <MenuButton>Open Menu</MenuButton>
+      <MenuButton>메뉴 열기</MenuButton>
       <Menu>
-        <MenuItem>Option 1</MenuItem>
-        <MenuItem>Option 2</MenuItem>
-        <MenuItem>Option 3</MenuItem>
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+        <MenuItem>옵션 3</MenuItem>
       </Menu>
     </Dropdown>
   );
 }
 ```
 
-## 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
+## Examples
 
 ### Basic Menu
 
-A standard menu with simple text items, optionally separated by dividers.
+가장 기본적인 Menu 사용법입니다.
 
 ```tsx
 <Stack direction="row" spacing={3}>
@@ -92,7 +77,7 @@ A standard menu with simple text items, optionally separated by dividers.
 
 ### 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}>
@@ -133,7 +118,7 @@ Menu supports `sm`, `md`, and `lg` sizes that affect the padding and font size o
 
 ### MenuItem States
 
-MenuItems can be `selected`, `disabled`, or colored with semantic colors like `primary`, `danger`, `success`, and `warning`.
+MenuItem의 다양한 상태를 표현할 수 있습니다.
 
 ```tsx
 <Dropdown>
@@ -152,7 +137,7 @@ MenuItems can be `selected`, `disabled`, or colored with semantic colors like `p
 
 ### MenuItem with Icons
 
-Add icons before item text to improve scannability. Use consistent icon sizing with `sx={{ mr: 1.5, fontSize: 'lg' }}`.
+메뉴 아이템에 아이콘을 추가할 수 있습니다.
 
 ```tsx
 <Dropdown>
@@ -195,7 +180,7 @@ Add icons before item text to improve scannability. Use consistent icon sizing w
 
 ### Actions Menu
 
-Build action menus for CRUD operations. Use `color="danger"` to highlight destructive actions.
+편집, 삭제 등의 액션 메뉴로 활용할 수 있습니다.
 
 ```tsx
 <Dropdown>
@@ -238,7 +223,7 @@ Build action menus for CRUD operations. Use `color="danger"` to highlight destru
 
 ### Clickable Menu Items
 
-Attach `onClick` handlers to menu items to respond to user selections.
+메뉴 아이템에 클릭 이벤트를 연결할 수 있습니다.
 
 ```tsx
 <Stack spacing={2}>
@@ -257,7 +242,7 @@ Attach `onClick` handlers to menu items to respond to user selections.
 
 ### Menu as Links
 
-Use the `component="a"` prop on MenuItem to render items as anchor links for navigation.
+메뉴 아이템을 링크로 사용할 수 있습니다.
 
 ```tsx
 <Dropdown>
@@ -281,7 +266,7 @@ Use the `component="a"` prop on MenuItem to render items as anchor links for nav
 
 ### Profile Menu
 
-Combine custom Box content (user info header) with standard MenuItem entries for rich profile menus.
+사용자 프로필 메뉴의 완성된 예제입니다.
 
 ```tsx
 <Dropdown>
@@ -351,7 +336,7 @@ Combine custom Box content (user info header) with standard MenuItem entries for
 
 ### 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={{
@@ -420,7 +405,7 @@ Control the position of the menu panel relative to the trigger using the `placem
 
 ### Long Scrollable Menu
 
-For menus with many items, apply `maxHeight` and `overflow: 'auto'` through the `sx` prop.
+많은 옵션이 있는 메뉴는 스크롤을 적용할 수 있습니다.
 
 ```tsx
 <Dropdown>
@@ -438,7 +423,7 @@ For menus with many items, apply `maxHeight` and `overflow: 'auto'` through the
 
 ### Custom Styled Menu
 
-Customize the menu panel appearance with border-radius, shadows, borders, and custom item spacing.
+CSS 스타일을 이용해 메뉴를 커스터마이징할 수 있습니다.
 
 ```tsx
 <Stack direction="row" spacing={3}>
@@ -502,7 +487,7 @@ Customize the menu panel appearance with border-radius, shadows, borders, and cu
 
 ### Menu in Card
 
-Embed a Dropdown menu inside cards or other container components for contextual actions.
+카드나 다른 컴포넌트 내에서 메뉴를 사용할 수 있습니다.
 
 ```tsx
 <Sheet variant="outlined" sx={{
@@ -562,7 +547,7 @@ Embed a Dropdown menu inside cards or other container components for contextual
 
 ### Nested Content
 
-Menu can contain non-MenuItem elements like Box, Typography, and progress indicators alongside standard items.
+메뉴 내에 복잡한 콘텐츠를 구성할 수 있습니다.
 
 ```tsx
 <Dropdown>
@@ -646,42 +631,93 @@ Menu can contain non-MenuItem elements like Box, Typography, and progress indica
 </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
 
-### Action Menu with Icons
+### Navigation Menu
 
 ```tsx
 <Dropdown>
-  <MenuButton variant="plain" size="sm">Actions</MenuButton>
+  <MenuButton>네비게이션</MenuButton>
   <Menu>
-    <MenuItem onClick={handleEdit}>
-      <EditIcon sx={{ mr: 1 }} />
-      Edit
+    <MenuItem component="a" href="/home">
+      홈
     </MenuItem>
-    <MenuItem onClick={handleCopy}>
-      <CopyIcon sx={{ mr: 1 }} />
-      Copy
+    <MenuItem component="a" href="/products">
+      제품
+    </MenuItem>
+    <MenuItem component="a" href="/services">
+      서비스
     </MenuItem>
     <ListDivider />
-    <MenuItem color="danger" onClick={handleDelete}>
-      <DeleteIcon sx={{ mr: 1 }} />
-      Delete
+    <MenuItem component="a" href="/contact">
+      문의하기
     </MenuItem>
   </Menu>
 </Dropdown>
 ```
 
-### Navigation Menu
+### Action Menu with Icons
 
 ```tsx
 <Dropdown>
-  <MenuButton>Navigate</MenuButton>
+  <MenuButton variant="plain" size="sm">
+    작업
+  </MenuButton>
   <Menu>
-    <MenuItem component="a" href="/home">Home</MenuItem>
-    <MenuItem component="a" href="/products">Products</MenuItem>
-    <MenuItem component="a" href="/services">Services</MenuItem>
+    <MenuItem onClick={handleEdit}>
+      <EditIcon sx={{ mr: 1 }} />
+      편집
+    </MenuItem>
+    <MenuItem onClick={handleCopy}>
+      <CopyIcon sx={{ mr: 1 }} />
+      복사
+    </MenuItem>
+    <MenuItem onClick={handleShare}>
+      <ShareIcon sx={{ mr: 1 }} />
+      공유
+    </MenuItem>
     <ListDivider />
-    <MenuItem component="a" href="/contact">Contact</MenuItem>
+    <MenuItem color="danger" onClick={handleDelete}>
+      <DeleteIcon sx={{ mr: 1 }} />
+      삭제
+    </MenuItem>
   </Menu>
 </Dropdown>
 ```
@@ -690,75 +726,232 @@ Menu can contain non-MenuItem elements like Box, Typography, and progress indica
 
 ```tsx
 <Dropdown>
-  <MenuButton
-    startDecorator={<Avatar size="sm" src="/avatar.jpg" />}
-    endDecorator={<ExpandMoreIcon />}
-  >
-    Username
+  <MenuButton startDecorator={<Avatar size="sm" src="/avatar.jpg" />} endDecorator={<ExpandMoreIcon />}>
+    사용자명
   </MenuButton>
   <Menu>
+    {/* 프로필 헤더 */}
     <Box sx={{ px: 2, py: 1.5 }}>
-      <Typography level="title-sm">Username</Typography>
-      <Typography level="body-xs" color="neutral">user@example.com</Typography>
+      <Typography level="title-sm">사용자명</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>
 ```
 
-## Best Practices
+### Filter Menu
 
-- **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
+const [filter, setFilter] = useState('전체');
 
-  ```tsx
-  {/* ✅ Good: Grouped actions with divider */}
+<Dropdown>
+  <MenuButton startDecorator={<FilterListIcon />} endDecorator={<ExpandMoreIcon />}>
+    필터: {filter}
+  </MenuButton>
   <Menu>
-    <MenuItem>Edit</MenuItem>
-    <MenuItem>Duplicate</MenuItem>
-    <ListDivider />
-    <MenuItem color="danger">Delete</MenuItem>
+    <MenuItem selected={filter === '전체'} onClick={() => setFilter('전체')}>
+      전체
+    </MenuItem>
+    <MenuItem selected={filter === '활성'} onClick={() => setFilter('활성')}>
+      활성
+    </MenuItem>
+    <MenuItem selected={filter === '비활성'} onClick={() => setFilter('비활성')}>
+      비활성
+    </MenuItem>
   </Menu>
-  ```
+</Dropdown>;
+```
 
-- **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.
+### Context Menu (Right-click Menu)
 
-  ```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>
+```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>;
+```
 
-  {/* ❌ Avoid: Inconsistent icon sizes */}
-  <MenuItem><EditIcon sx={{ mr: 1 }} />Edit</MenuItem>
-  <MenuItem><DeleteIcon sx={{ mr: 2, fontSize: 'xl' }} />Delete</MenuItem>
-  ```
+### Submenu Pattern
 
-- **Limit menu length.** Aim for 3-7 visible items. For longer lists, set `maxHeight` on Menu to enable scrolling, or reconsider the UI pattern.
+```tsx
+<Dropdown>
+  <MenuButton>파일</MenuButton>
+  <Menu>
+    <MenuItem>새 파일</MenuItem>
+    <MenuItem>열기</MenuItem>
 
-  ```tsx
-  {/* ✅ Good: Scrollable long menu */}
-  <Menu sx={{ maxHeight: 300, overflow: 'auto' }}>
-  ```
+    {/* 서브메뉴는 별도 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>
+
+    <ListDivider />
+    <MenuItem>저장</MenuItem>
+    <MenuItem>종료</MenuItem>
+  </Menu>
+</Dropdown>
+```
 
-- **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.
+## Menu Placement
 
-- **Provide clear labels.** Every MenuItem should have a concise, action-oriented label that makes its purpose obvious without needing additional context.
+메뉴의 위치는 `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
 
-- **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.
+Menu 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:
+
+### 키보드 탐색
+
+- **Tab**: 메뉴 버튼으로 포커스 이동
+- **Enter/Space**: 메뉴 열기/닫기
+- **↑/↓**: 메뉴 아이템 간 이동
+- **Escape**: 메뉴 닫기
+- **Enter**: 메뉴 아이템 선택
+
+### ARIA 속성
+
+- `role="menu"`: 메뉴 역할 정의
+- `role="menuitem"`: 메뉴 아이템 역할 정의
+- `aria-expanded`: 메뉴 열림/닫힘 상태
+- `aria-haspopup`: 팝업 메뉴 존재 표시
+
+### 추가 접근성 고려사항
+
+```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 }}> {/* 최소 터치 영역 보장 */}
+   ```
+
+Menu와 MenuItem은 사용자 친화적이고 접근성이 뛰어난 메뉴 시스템을 구축하는 핵심 컴포넌트입니다. 적절히 활용하면 직관적이고 효율적인 사용자 인터페이스를 만들 수 있습니다.