@ceed/ads 1.29.1 → 1.30.0-next.1

package/dist/components/navigation/Dropdown.md

@@ -1,8 +1,8 @@
 # Dropdown
 
-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.
+## Introduction
 
-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.
+Dropdown 컴포넌트는 메뉴나 옵션 목록을 표시하는 컨테이너 역할을 하는 컴포넌트입니다. Joy UI의 Dropdown을 그대로 사용하며, MenuButton과 Menu 컴포넌트와 함께 사용하여 사용자가 클릭할 때 선택 가능한 옵션들을 보여줍니다. 네비게이션 메뉴, 필터 옵션, 사용자 프로필 메뉴 등 다양한 용도로 활용할 수 있습니다.
 
 ```tsx
 <Dropdown>
@@ -24,39 +24,27 @@ Dropdown is part of a **composition pattern** together with Menu, MenuItem, Menu
 ## 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
-
-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
+## Examples
 
 ### Basic Dropdown
 
-The simplest Dropdown pairs a MenuButton trigger with a Menu of items.
+가장 기본적인 Dropdown 사용법입니다.
 
 ```tsx
 <Stack direction="row" spacing={2}>
@@ -84,7 +72,7 @@ The simplest Dropdown pairs a MenuButton trigger with a Menu of items.
 
 ### Button Variants
 
-MenuButton supports `plain`, `outlined`, `soft`, and `solid` variants to match your design context.
+MenuButton의 다양한 스타일 변형을 사용할 수 있습니다.
 
 ```tsx
 <Stack direction="row" spacing={2} flexWrap="wrap">
@@ -124,7 +112,7 @@ MenuButton supports `plain`, `outlined`, `soft`, and `solid` variants to match y
 
 ### Button Colors
 
-Apply semantic colors to the trigger button for different emphasis levels.
+MenuButton에 다양한 색상을 적용할 수 있습니다.
 
 ```tsx
 <Stack direction="row" spacing={2} flexWrap="wrap">
@@ -182,7 +170,7 @@ Apply semantic colors to the trigger button for different emphasis levels.
 
 ### Menu Placements
 
-Control where the menu appears relative to the trigger using the `placement` prop on Menu.
+메뉴가 나타나는 위치를 설정할 수 있습니다.
 
 ```tsx
 <Stack direction="row" spacing={2} sx={{
@@ -228,7 +216,7 @@ Control where the menu appears relative to the trigger using the `placement` pro
 
 ### With Icons
 
-Add icons to menu items and decorators to the trigger button for richer visual communication.
+아이콘이 포함된 메뉴를 만들 수 있습니다.
 
 ```tsx
 <Dropdown>
@@ -261,7 +249,7 @@ Add icons to menu items and decorators to the trigger button for richer visual c
 
 ### Actions Menu
 
-Build action menus for edit, delete, and other operations. Use `color="danger"` on destructive items.
+편집, 삭제 등의 액션 메뉴로 활용할 수 있습니다.
 
 ```tsx
 <Dropdown>
@@ -292,7 +280,7 @@ Build action menus for edit, delete, and other operations. Use `color="danger"`
 
 ### Filter Menu
 
-Use Dropdown as an interactive filter selector with state management.
+필터링 기능을 위한 드롭다운 메뉴입니다.
 
 ```tsx
 <Dropdown>
@@ -310,7 +298,7 @@ Use Dropdown as an interactive filter selector with state management.
 
 ### Profile Dropdown
 
-Combine custom content (user info header) with standard menu items for profile menus.
+사용자 프로필 메뉴로 활용할 수 있습니다.
 
 ```tsx
 <Dropdown>
@@ -362,7 +350,7 @@ Combine custom content (user info header) with standard menu items for profile m
 
 ### Nested Menus
 
-Place multiple Dropdown instances side by side to create menu bar patterns.
+여러 개의 드롭다운 메뉴를 나란히 배치할 수 있습니다.
 
 ```tsx
 <Stack direction="row" spacing={3}>
@@ -403,7 +391,7 @@ Place multiple Dropdown instances side by side to create menu bar patterns.
 
 ### Controlled Dropdown
 
-Use the `open` and `onOpenChange` props to programmatically control the menu state.
+프로그래밍 방식으로 메뉴의 열림/닫힘 상태를 제어할 수 있습니다.
 
 ```tsx
 <Stack spacing={2}>
@@ -428,7 +416,7 @@ Use the `open` and `onOpenChange` props to programmatically control the menu sta
 
 ### Disabled State
 
-Disable the entire trigger button or individual menu items.
+비활성 상태의 드롭다운과 메뉴 아이템을 표시할 수 있습니다.
 
 ```tsx
 <Stack direction="row" spacing={2}>
@@ -452,7 +440,7 @@ Disable the entire trigger button or individual menu items.
 
 ### Long Menu
 
-Apply `maxHeight` and `overflow: 'auto'` to Menu for scrollable lists with many items.
+많은 옵션이 있는 메뉴는 스크롤을 적용할 수 있습니다.
 
 ```tsx
 <Dropdown>
@@ -472,7 +460,7 @@ Apply `maxHeight` and `overflow: 'auto'` to Menu for scrollable lists with many
 
 ### Custom Styling
 
-Customize borders, shadows, border-radius, and gradients through the `sx` prop.
+CSS 스타일을 이용해 드롭다운을 커스터마이징할 수 있습니다.
 
 ```tsx
 <Stack direction="row" spacing={2}>
@@ -527,27 +515,89 @@ Customize borders, shadows, border-radius, and gradients through the `sx` prop.
 </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">Menu</MenuButton>
+  <MenuButton variant="plain">메뉴</MenuButton>
   <Menu>
-    <MenuItem component="a" href="/home">Home</MenuItem>
-    <MenuItem component="a" href="/about">About</MenuItem>
-    <MenuItem component="a" href="/products">Products</MenuItem>
+    <MenuItem component="a" href="/home">홈</MenuItem>
+    <MenuItem component="a" href="/about">회사소개</MenuItem>
+    <MenuItem component="a" href="/products">제품</MenuItem>
     <ListDivider />
-    <MenuItem component="a" href="/contact">Contact</MenuItem>
+    <MenuItem component="a" href="/contact">문의하기</MenuItem>
   </Menu>
 </Dropdown>
 ```
 
-### Filter Selector
+### User Profile Menu
 
 ```tsx
-const [filter, setFilter] = useState('All');
+<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('전체');
 
 <Dropdown>
   <MenuButton
@@ -555,85 +605,164 @@ const [filter, setFilter] = useState('All');
     startDecorator={<FilterListIcon />}
     endDecorator={<ExpandMoreIcon />}
   >
-    Filter: {filter}
+    필터: {filter}
   </MenuButton>
   <Menu>
-    <MenuItem onClick={() => setFilter('All')}>All</MenuItem>
-    <MenuItem onClick={() => setFilter('Active')}>Active</MenuItem>
-    <MenuItem onClick={() => setFilter('Inactive')}>Inactive</MenuItem>
+    <MenuItem onClick={() => setFilter('전체')}>전체</MenuItem>
+    <MenuItem onClick={() => setFilter('활성')}>활성</MenuItem>
+    <MenuItem onClick={() => setFilter('비활성')}>비활성</MenuItem>
   </Menu>
 </Dropdown>
 ```
 
-### Controlled State with External Toggle
+### Action Menu
 
 ```tsx
-const [open, setOpen] = useState(false);
+<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>
+  </Menu>
+</Dropdown>
+```
+
+### Language Selector
 
-<Dropdown open={open} onOpenChange={(event, isOpen) => setOpen(isOpen)}>
-  <MenuButton>Controlled Menu</MenuButton>
+```tsx
+const [language, setLanguage] = useState('한국어');
+
+<Dropdown>
+  <MenuButton variant="soft" size="sm">
+    {language}
+  </MenuButton>
   <Menu>
-    <MenuItem onClick={() => setOpen(false)}>Option A</MenuItem>
-    <MenuItem onClick={() => setOpen(false)}>Option B</MenuItem>
+    <MenuItem onClick={() => setLanguage('한국어')}>
+      한국어
+    </MenuItem>
+    <MenuItem onClick={() => setLanguage('English')}>
+      English
+    </MenuItem>
+    <MenuItem onClick={() => setLanguage('日本語')}>
+      日本語
+    </MenuItem>
   </Menu>
 </Dropdown>
+```
+
+### Sort Options
 
-<Button onClick={() => setOpen(!open)}>
-  {open ? 'Close' : 'Open'} Menu
-</Button>
+```tsx
+const [sortBy, setSortBy] = useState('이름순');
+
+<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>
 ```
 
 ## Best Practices
 
-- **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.
+1. **명확한 라벨**: MenuButton의 텍스트는 메뉴의 내용을 명확히 나타내야 합니다.
 
-  ```tsx
-  {/* ✅ Good: Simple list -- use MenuButton directly */}
-  <MenuButton buttonText="Actions" items={[{ text: 'Edit' }, { text: 'Delete' }]} />
+2. **적절한 아이콘 사용**: 드롭다운임을 나타내는 화살표 아이콘을 사용하세요.
+   ```tsx
+   <MenuButton endDecorator={<ExpandMoreIcon />}>
+   ```
 
-  {/* ✅ 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>
-  ```
+3. **메뉴 아이템 그룹화**: 관련된 메뉴 아이템들은 ListDivider로 구분하세요.
+
+4. **키보드 접근성**: 키보드 탐색이 가능하도록 적절한 props를 설정하세요.
+
+5. **적절한 배치**: 화면 공간을 고려하여 메뉴의 placement를 설정하세요.
 
-- **Group related items with ListDivider.** Visually separate logical groups of menu items so users can scan options quickly.
+6. **로딩 상태**: 필요한 경우 MenuButton에 loading 상태를 표시하세요.
 
-  ```tsx
-  {/* ✅ Good: Grouped by function */}
+7. **일관된 스타일**: 애플리케이션 전반에서 일관된 드롭다운 스타일을 유지하세요.
+
+8. **모바일 고려**: 모바일에서도 사용하기 쉽도록 충분한 터치 영역을 확보하세요.
+
+## Controlled vs Uncontrolled
+
+### Uncontrolled (기본)
+
+```tsx
+<Dropdown>
+  <MenuButton>메뉴</MenuButton>
   <Menu>
-    <MenuItem>Edit</MenuItem>
-    <MenuItem>Duplicate</MenuItem>
-    <ListDivider />
-    <MenuItem color="danger">Delete</MenuItem>
+    <MenuItem>옵션</MenuItem>
+  </Menu>
+</Dropdown>
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Dropdown
+  open={open}
+  onOpenChange={(event, isOpen) => setOpen(isOpen)}
+>
+  <MenuButton>메뉴</MenuButton>
+  <Menu>
+    <MenuItem onClick={() => setOpen(false)}>옵션</MenuItem>
   </Menu>
-  ```
+</Dropdown>
+```
 
-- **Indicate dropdown affordance.** Use `endDecorator={<ExpandMoreIcon />}` on the trigger button so users understand it opens a menu.
+## Accessibility
 
-  ```tsx
-  {/* ✅ Good: Clear dropdown indicator */}
-  <MenuButton endDecorator={<ExpandMoreIcon />}>Options</MenuButton>
+Dropdown은 접근성을 위한 기본적인 기능들을 제공합니다:
 
-  {/* ❌ Avoid: No visual hint that a menu will appear */}
-  <MenuButton>Options</MenuButton>
-  ```
+- **키보드 탐색**: Tab, Enter, Escape, 화살표 키 지원
+- **ARIA 속성**: 적절한 ARIA 라벨과 역할 자동 설정
+- **포커스 관리**: 메뉴가 열릴 때 첫 번째 아이템으로 포커스 이동
+- **스크린 리더**: 메뉴의 상태와 옵션들을 적절히 읽어줌
 
-- **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.
+- 메뉴 아이템에 적절한 라벨 제공
+- 위험한 작업(삭제 등)에 대한 확인 절차 제공
+- 색상에만 의존하지 않는 시각적 피드백
 
-## Accessibility
+## When to Use Dropdown
+
+### ✅ 사용하기 좋은 경우
+
+- **메뉴 시스템**: 네비게이션이나 컨텍스트 메뉴가 필요할 때
+- **필터링**: 여러 옵션 중 하나를 선택하는 필터가 필요할 때
+- **액션 목록**: 특정 항목에 대한 여러 작업이 있을 때
+- **사용자 메뉴**: 프로필, 설정, 로그아웃 등의 사용자 관련 기능
+- **공간 절약**: 화면 공간이 제한적일 때 여러 옵션을 숨기고 싶을 때
+
+### ❌ 사용하지 않는 것이 좋은 경우
+
+- **단일 액션**: 하나의 간단한 작업만 있을 때는 일반 Button 사용
+- **긴 폼**: 폼에서는 Select 컴포넌트가 더 적절
+- **항상 보여야 하는 옵션**: 중요한 옵션들은 항상 표시하는 것이 좋음
+- **너무 많은 옵션**: 20개 이상의 옵션이 있다면 다른 UI 패턴 고려
 
-- **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.
+Dropdown은 사용자에게 깔끔하고 직관적인 메뉴 경험을 제공하는 강력한 컴포넌트입니다. 적절히 사용하면 공간을 효율적으로 활용하면서도 풍부한 기능을 제공할 수 있습니다.