@ceed/cds 1.22.2 → 1.22.4

package/dist/components/navigation/Dropdown.md

@@ -1,8 +1,8 @@
 # Dropdown
 
-## Introduction
+Dropdown is the stateful container that orchestrates the open/close behavior of a menu system. It acts as the invisible glue between a trigger element (such as MenuButton or IconMenuButton) and the Menu that appears when activated. Dropdown itself renders no visible UI -- it provides context so that its children can coordinate with each other.
 
-Dropdown 컴포넌트는 메뉴나 옵션 목록을 표시하는 컨테이너 역할을 하는 컴포넌트입니다. Joy UI의 Dropdown을 그대로 사용하며, MenuButton과 Menu 컴포넌트와 함께 사용하여 사용자가 클릭할 때 선택 가능한 옵션들을 보여줍니다. 네비게이션 메뉴, 필터 옵션, 사용자 프로필 메뉴 등 다양한 용도로 활용할 수 있습니다.
+Dropdown is part of a **composition pattern** together with Menu, MenuItem, MenuButton, and IconMenuButton. While MenuButton and IconMenuButton are higher-level convenience components that bundle trigger + menu into a single prop-driven API, Dropdown gives you full control over the trigger element, menu content, and layout when you need custom compositions.
 
 ```tsx
 <Dropdown>
@@ -24,27 +24,39 @@ Dropdown 컴포넌트는 메뉴나 옵션 목록을 표시하는 컨테이너
 ## Usage
 
 ```tsx
-import { Dropdown, MenuButton, Menu, MenuItem } from '@ceed/cds';
+import { Dropdown, Menu, MenuItem } from '@ceed/cds';
+import { MenuButton } from '@ceed/cds';
 
 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
+
+Dropdown, Menu, MenuItem, MenuButton, and IconMenuButton form a **menu component family**. Choose the right level of abstraction for your use case:
+
+| Approach                             | When to use                                             |
+| ------------------------------------ | ------------------------------------------------------- |
+| `MenuButton` (standalone)            | Simple text-triggered menus with a list of items        |
+| `IconMenuButton` (standalone)        | Icon-only triggers in space-constrained areas           |
+| `Dropdown` + `MenuButton` + `Menu`   | Custom menu content (headers, dividers, mixed elements) |
+| `Dropdown` + custom trigger + `Menu` | Fully custom trigger elements                           |
+
+## Features
 
 ### Basic Dropdown
 
-가장 기본적인 Dropdown 사용법입니다.
+The simplest Dropdown pairs a MenuButton trigger with a Menu of items.
 
 ```tsx
 <Stack direction="row" spacing={2}>
@@ -72,7 +84,7 @@ function MyComponent() {
 
 ### Button Variants
 
-MenuButton의 다양한 스타일 변형을 사용할 수 있습니다.
+MenuButton supports `plain`, `outlined`, `soft`, and `solid` variants to match your design context.
 
 ```tsx
 <Stack direction="row" spacing={2} flexWrap="wrap">
@@ -112,7 +124,7 @@ MenuButton의 다양한 스타일 변형을 사용할 수 있습니다.
 
 ### Button Colors
 
-MenuButton에 다양한 색상을 적용할 수 있습니다.
+Apply semantic colors to the trigger button for different emphasis levels.
 
 ```tsx
 <Stack direction="row" spacing={2} flexWrap="wrap">
@@ -170,7 +182,7 @@ MenuButton에 다양한 색상을 적용할 수 있습니다.
 
 ### Menu Placements
 
-메뉴가 나타나는 위치를 설정할 수 있습니다.
+Control where the menu appears relative to the trigger using the `placement` prop on Menu.
 
 ```tsx
 <Stack direction="row" spacing={2} sx={{
@@ -216,7 +228,7 @@ MenuButton에 다양한 색상을 적용할 수 있습니다.
 
 ### With Icons
 
-아이콘이 포함된 메뉴를 만들 수 있습니다.
+Add icons to menu items and decorators to the trigger button for richer visual communication.
 
 ```tsx
 <Dropdown>
@@ -249,7 +261,7 @@ MenuButton에 다양한 색상을 적용할 수 있습니다.
 
 ### Actions Menu
 
-편집, 삭제 등의 액션 메뉴로 활용할 수 있습니다.
+Build action menus for edit, delete, and other operations. Use `color="danger"` on destructive items.
 
 ```tsx
 <Dropdown>
@@ -280,7 +292,7 @@ MenuButton에 다양한 색상을 적용할 수 있습니다.
 
 ### Filter Menu
 
-필터링 기능을 위한 드롭다운 메뉴입니다.
+Use Dropdown as an interactive filter selector with state management.
 
 ```tsx
 <Dropdown>
@@ -298,7 +310,7 @@ MenuButton에 다양한 색상을 적용할 수 있습니다.
 
 ### Profile Dropdown
 
-사용자 프로필 메뉴로 활용할 수 있습니다.
+Combine custom content (user info header) with standard menu items for profile menus.
 
 ```tsx
 <Dropdown>
@@ -350,7 +362,7 @@ MenuButton에 다양한 색상을 적용할 수 있습니다.
 
 ### Nested Menus
 
-여러 개의 드롭다운 메뉴를 나란히 배치할 수 있습니다.
+Place multiple Dropdown instances side by side to create menu bar patterns.
 
 ```tsx
 <Stack direction="row" spacing={3}>
@@ -391,7 +403,7 @@ MenuButton에 다양한 색상을 적용할 수 있습니다.
 
 ### Controlled Dropdown
 
-프로그래밍 방식으로 메뉴의 열림/닫힘 상태를 제어할 수 있습니다.
+Use the `open` and `onOpenChange` props to programmatically control the menu state.
 
 ```tsx
 <Stack spacing={2}>
@@ -416,7 +428,7 @@ MenuButton에 다양한 색상을 적용할 수 있습니다.
 
 ### Disabled State
 
-비활성 상태의 드롭다운과 메뉴 아이템을 표시할 수 있습니다.
+Disable the entire trigger button or individual menu items.
 
 ```tsx
 <Stack direction="row" spacing={2}>
@@ -440,7 +452,7 @@ MenuButton에 다양한 색상을 적용할 수 있습니다.
 
 ### Long Menu
 
-많은 옵션이 있는 메뉴는 스크롤을 적용할 수 있습니다.
+Apply `maxHeight` and `overflow: 'auto'` to Menu for scrollable lists with many items.
 
 ```tsx
 <Dropdown>
@@ -460,7 +472,7 @@ MenuButton에 다양한 색상을 적용할 수 있습니다.
 
 ### Custom Styling
 
-CSS 스타일을 이용해 드롭다운을 커스터마이징할 수 있습니다.
+Customize borders, shadows, border-radius, and gradients through the `sx` prop.
 
 ```tsx
 <Stack direction="row" spacing={2}>
@@ -515,242 +527,113 @@ CSS 스타일을 이용해 드롭다운을 커스터마이징할 수 있습니
 </Stack>
 ```
 
-## Component Structure
-
-Dropdown은 다음 컴포넌트들과 함께 사용됩니다:
-
-```tsx
-<Dropdown>
-  <MenuButton>트리거 버튼</MenuButton>
-  <Menu>
-    <MenuItem>메뉴 아이템 1</MenuItem>
-    <MenuItem>메뉴 아이템 2</MenuItem>
-    <ListDivider /> {/* 구분선 */}
-    <MenuItem>메뉴 아이템 3</MenuItem>
-  </Menu>
-</Dropdown>
-```
-
-### MenuButton Props
-
-MenuButton 컴포넌트의 주요 props:
-
-- `variant`: `'plain' | 'outlined' | 'soft' | 'solid'`
-- `color`: `'primary' | 'neutral' | 'danger' | 'success' | 'warning'`
-- `size`: `'sm' | 'md' | 'lg'`
-- `startDecorator`: 앞쪽에 표시할 요소
-- `endDecorator`: 뒤쪽에 표시할 요소
-- `disabled`: 비활성 상태
-
-### Menu Props
-
-Menu 컴포넌트의 주요 props:
-
-- `placement`: `'top-start' | 'top' | 'top-end' | 'bottom-start' | 'bottom' | 'bottom-end'`
-- `size`: `'sm' | 'md' | 'lg'`
-- `sx`: 스타일 커스터마이징
-
 ## Common Use Cases
 
 ### Navigation Menu
 
 ```tsx
 <Dropdown>
-  <MenuButton variant="plain">메뉴</MenuButton>
+  <MenuButton variant="plain">Menu</MenuButton>
   <Menu>
-    <MenuItem component="a" href="/home">
-      홈
-    </MenuItem>
-    <MenuItem component="a" href="/about">
-      회사소개
-    </MenuItem>
-    <MenuItem component="a" href="/products">
-      제품
-    </MenuItem>
+    <MenuItem component="a" href="/home">Home</MenuItem>
+    <MenuItem component="a" href="/about">About</MenuItem>
+    <MenuItem component="a" href="/products">Products</MenuItem>
     <ListDivider />
-    <MenuItem component="a" href="/contact">
-      문의하기
-    </MenuItem>
+    <MenuItem component="a" href="/contact">Contact</MenuItem>
   </Menu>
 </Dropdown>
 ```
 
-### User Profile Menu
+### Filter Selector
 
 ```tsx
-<Dropdown>
-  <MenuButton variant="plain" startDecorator={<Avatar size="sm" />} endDecorator={<ExpandMoreIcon />}>
-    사용자명
-  </MenuButton>
-  <Menu>
-    <Stack px={2} py={1}>
-      <Typography level="title-sm">사용자명</Typography>
-      <Typography level="body-xs" color="neutral">
-        user@example.com
-      </Typography>
-    </Stack>
-    <ListDivider />
-    <MenuItem>프로필</MenuItem>
-    <MenuItem>설정</MenuItem>
-    <ListDivider />
-    <MenuItem>로그아웃</MenuItem>
-  </Menu>
-</Dropdown>
-```
-
-### Filter Dropdown
-
-```tsx
-const [filter, setFilter] = useState('전체');
+const [filter, setFilter] = useState('All');
 
 <Dropdown>
-  <MenuButton variant="outlined" startDecorator={<FilterListIcon />} endDecorator={<ExpandMoreIcon />}>
-    필터: {filter}
+  <MenuButton
+    variant="outlined"
+    startDecorator={<FilterListIcon />}
+    endDecorator={<ExpandMoreIcon />}
+  >
+    Filter: {filter}
   </MenuButton>
   <Menu>
-    <MenuItem onClick={() => setFilter('전체')}>전체</MenuItem>
-    <MenuItem onClick={() => setFilter('활성')}>활성</MenuItem>
-    <MenuItem onClick={() => setFilter('비활성')}>비활성</MenuItem>
-  </Menu>
-</Dropdown>;
-```
-
-### Action Menu
-
-```tsx
-<Dropdown>
-  <MenuButton variant="plain" size="sm">
-    작업
-  </MenuButton>
-  <Menu>
-    <MenuItem>
-      <EditIcon sx={{ mr: 1 }} />
-      편집
-    </MenuItem>
-    <MenuItem>
-      <CopyIcon sx={{ mr: 1 }} />
-      복사
-    </MenuItem>
-    <MenuItem color="danger">
-      <DeleteIcon sx={{ mr: 1 }} />
-      삭제
-    </MenuItem>
+    <MenuItem onClick={() => setFilter('All')}>All</MenuItem>
+    <MenuItem onClick={() => setFilter('Active')}>Active</MenuItem>
+    <MenuItem onClick={() => setFilter('Inactive')}>Inactive</MenuItem>
   </Menu>
 </Dropdown>
 ```
 
-### Language Selector
+### Controlled State with External Toggle
 
 ```tsx
-const [language, setLanguage] = useState('한국어');
+const [open, setOpen] = useState(false);
 
-<Dropdown>
-  <MenuButton variant="soft" size="sm">
-    {language}
-  </MenuButton>
+<Dropdown open={open} onOpenChange={(event, isOpen) => setOpen(isOpen)}>
+  <MenuButton>Controlled Menu</MenuButton>
   <Menu>
-    <MenuItem onClick={() => setLanguage('한국어')}>한국어</MenuItem>
-    <MenuItem onClick={() => setLanguage('English')}>English</MenuItem>
-    <MenuItem onClick={() => setLanguage('日本語')}>日本語</MenuItem>
+    <MenuItem onClick={() => setOpen(false)}>Option A</MenuItem>
+    <MenuItem onClick={() => setOpen(false)}>Option B</MenuItem>
   </Menu>
-</Dropdown>;
-```
-
-### Sort Options
-
-```tsx
-const [sortBy, setSortBy] = useState('이름순');
+</Dropdown>
 
-<Dropdown>
-  <MenuButton variant="outlined" startDecorator={<SortIcon />} endDecorator={<ExpandMoreIcon />}>
-    정렬: {sortBy}
-  </MenuButton>
-  <Menu>
-    <MenuItem onClick={() => setSortBy('이름순')}>이름순</MenuItem>
-    <MenuItem onClick={() => setSortBy('날짜순')}>날짜순</MenuItem>
-    <MenuItem onClick={() => setSortBy('크기순')}>크기순</MenuItem>
-  </Menu>
-</Dropdown>;
+<Button onClick={() => setOpen(!open)}>
+  {open ? 'Close' : 'Open'} Menu
+</Button>
 ```
 
 ## Best Practices
 
-1. **명확한 라벨**: MenuButton의 텍스트는 메뉴의 내용을 명확히 나타내야 합니다.
-
-2. **적절한 아이콘 사용**: 드롭다운임을 나타내는 화살표 아이콘을 사용하세요.
-
-   ```tsx
-   <MenuButton endDecorator={<ExpandMoreIcon />}>
-   ```
-
-3. **메뉴 아이템 그룹화**: 관련된 메뉴 아이템들은 ListDivider로 구분하세요.
-
-4. **키보드 접근성**: 키보드 탐색이 가능하도록 적절한 props를 설정하세요.
-
-5. **적절한 배치**: 화면 공간을 고려하여 메뉴의 placement를 설정하세요.
-
-6. **로딩 상태**: 필요한 경우 MenuButton에 loading 상태를 표시하세요.
-
-7. **일관된 스타일**: 애플리케이션 전반에서 일관된 드롭다운 스타일을 유지하세요.
-
-8. **모바일 고려**: 모바일에서도 사용하기 쉽도록 충분한 터치 영역을 확보하세요.
-
-## Controlled vs Uncontrolled
+- **Use the right abstraction level.** If you only need a simple list of text items, prefer `MenuButton` or `IconMenuButton` standalone components. Use `Dropdown` + `Menu` when you need dividers, custom headers, or mixed content inside the menu.
 
-### Uncontrolled (기본)
+  ```tsx
+  {/* ✅ Good: Simple list -- use MenuButton directly */}
+  <MenuButton buttonText="Actions" items={[{ text: 'Edit' }, { text: 'Delete' }]} />
 
-```tsx
-<Dropdown>
-  <MenuButton>메뉴</MenuButton>
-  <Menu>
-    <MenuItem>옵션</MenuItem>
-  </Menu>
-</Dropdown>
-```
+  {/* ✅ Good: Complex content -- use Dropdown composition */}
+  <Dropdown>
+    <MenuButton>User</MenuButton>
+    <Menu>
+      <Box sx={{ px: 2, py: 1 }}>
+        <Typography level="title-sm">User Name</Typography>
+      </Box>
+      <ListDivider />
+      <MenuItem>Settings</MenuItem>
+      <MenuItem>Logout</MenuItem>
+    </Menu>
+  </Dropdown>
+  ```
 
-### Controlled
+- **Group related items with ListDivider.** Visually separate logical groups of menu items so users can scan options quickly.
 
-```tsx
-const [open, setOpen] = useState(false);
-
-<Dropdown open={open} onOpenChange={(event, isOpen) => setOpen(isOpen)}>
-  <MenuButton>메뉴</MenuButton>
+  ```tsx
+  {/* ✅ Good: Grouped by function */}
   <Menu>
-    <MenuItem onClick={() => setOpen(false)}>옵션</MenuItem>
+    <MenuItem>Edit</MenuItem>
+    <MenuItem>Duplicate</MenuItem>
+    <ListDivider />
+    <MenuItem color="danger">Delete</MenuItem>
   </Menu>
-</Dropdown>;
-```
+  ```
 
-## Accessibility
+- **Indicate dropdown affordance.** Use `endDecorator={<ExpandMoreIcon />}` on the trigger button so users understand it opens a menu.
 
-Dropdown은 접근성을 위한 기본적인 기능들을 제공합니다:
+  ```tsx
+  {/* ✅ Good: Clear dropdown indicator */}
+  <MenuButton endDecorator={<ExpandMoreIcon />}>Options</MenuButton>
 
-- **키보드 탐색**: Tab, Enter, Escape, 화살표 키 지원
-- **ARIA 속성**: 적절한 ARIA 라벨과 역할 자동 설정
-- **포커스 관리**: 메뉴가 열릴 때 첫 번째 아이템으로 포커스 이동
-- **스크린 리더**: 메뉴의 상태와 옵션들을 적절히 읽어줌
+  {/* ❌ Avoid: No visual hint that a menu will appear */}
+  <MenuButton>Options</MenuButton>
+  ```
 
-추가적인 접근성을 위해:
+- **Keep menu item count reasonable.** Aim for 3-7 items. For longer lists, apply `maxHeight` with scrolling or consider a different UI pattern like a dialog or searchable list.
 
-- 메뉴 아이템에 적절한 라벨 제공
-- 위험한 작업(삭제 등)에 대한 확인 절차 제공
-- 색상에만 의존하지 않는 시각적 피드백
+- **Use controlled mode sparingly.** Uncontrolled mode (no `open` prop) handles most scenarios. Only use controlled mode when external events need to open or close the menu.
 
-## When to Use Dropdown
-
-### ✅ 사용하기 좋은 경우
-
-- **메뉴 시스템**: 네비게이션이나 컨텍스트 메뉴가 필요할 때
-- **필터링**: 여러 옵션 중 하나를 선택하는 필터가 필요할 때
-- **액션 목록**: 특정 항목에 대한 여러 작업이 있을 때
-- **사용자 메뉴**: 프로필, 설정, 로그아웃 등의 사용자 관련 기능
-- **공간 절약**: 화면 공간이 제한적일 때 여러 옵션을 숨기고 싶을 때
-
-### ❌ 사용하지 않는 것이 좋은 경우
-
-- **단일 액션**: 하나의 간단한 작업만 있을 때는 일반 Button 사용
-- **긴 폼**: 폼에서는 Select 컴포넌트가 더 적절
-- **항상 보여야 하는 옵션**: 중요한 옵션들은 항상 표시하는 것이 좋음
-- **너무 많은 옵션**: 20개 이상의 옵션이 있다면 다른 UI 패턴 고려
+## Accessibility
 
-Dropdown은 사용자에게 깔끔하고 직관적인 메뉴 경험을 제공하는 강력한 컴포넌트입니다. 적절히 사용하면 공간을 효율적으로 활용하면서도 풍부한 기능을 제공할 수 있습니다.
+- **Keyboard navigation**: Tab focuses the trigger button. Enter or Space opens the menu. Arrow keys navigate between items. Escape closes the menu and returns focus to the trigger.
+- **ARIA attributes**: Dropdown automatically sets `aria-haspopup`, `aria-expanded`, `role="menu"`, and `role="menuitem"` on the appropriate elements.
+- **Focus management**: When the menu opens, focus moves to the first menu item. When the menu closes, focus returns to the trigger button.
+- **Color is not the only indicator**: When using `color="danger"` on destructive items, pair it with a clear text label (e.g., "Delete") so the meaning is not conveyed by color alone.