@ceed/ads 1.35.1 → 1.36.0

package/dist/components/navigation/Dropdown.md

@@ -1,20 +1,20 @@
 # 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.
+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 (`MenuButtonTrigger`) 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 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 is part of a **composition pattern** together with `MenuButtonTrigger`, `Menu`, and `MenuItem`. `MenuButtonTrigger` is the low-level trigger that connects to the Dropdown context; the standalone `MenuButton` and `IconMenuButton` are higher-level convenience components that bundle trigger + menu into a single prop-driven API. Use the Dropdown composition when you need full control over the trigger element, menu content, and layout. All of these symbols are imported from `@ceed/ads`.
 
 ```tsx
 <Dropdown>
-  <MenuButton variant="outlined" endDecorator={<ExpandMoreIcon />}>
-    메뉴 열기
-  </MenuButton>
-  <Menu>
-    <MenuItem>옵션 1</MenuItem>
-    <MenuItem>옵션 2</MenuItem>
-    <MenuItem>옵션 3</MenuItem>
-  </Menu>
-</Dropdown>
+    <MenuButtonTrigger variant="outlined" endDecorator={<ExpandMoreIcon />}>
+      메뉴 열기
+    </MenuButtonTrigger>
+    <Menu>
+      <MenuItem>옵션 1</MenuItem>
+      <MenuItem>옵션 2</MenuItem>
+      <MenuItem>옵션 3</MenuItem>
+    </Menu>
+  </Dropdown>
 ```
 
 | Field                        | Description | Default |
@@ -24,13 +24,12 @@ 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, MenuButtonTrigger, Menu, MenuItem } from '@ceed/ads';
 
 function MyComponent() {
   return (
     <Dropdown>
-      <MenuButton>Open Menu</MenuButton>
+      <MenuButtonTrigger>Open Menu</MenuButtonTrigger>
       <Menu>
         <MenuItem>Option 1</MenuItem>
         <MenuItem>Option 2</MenuItem>
@@ -41,83 +40,338 @@ function MyComponent() {
 }
 ```
 
+> **`MenuButtonTrigger` vs `MenuButton`**: `MenuButtonTrigger` is the low-level trigger for the Dropdown composition (Joy UI's `MenuButton`, re-exported from `@ceed/ads` under this name). The separate `MenuButton` exported from `@ceed/ads` is a higher-level, self-contained component (driven by `buttonText` / `items` props) that renders its **own** Dropdown internally — it cannot be nested inside `<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                           |
+| 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` + `MenuButtonTrigger` + `Menu` | Custom menu content (headers, dividers, mixed elements) |
+| `Dropdown` + custom trigger + `Menu`      | Fully custom trigger elements                           |
 
-## Dropdown Basic
+## Custom Trigger Components
 
-The simplest Dropdown pairs a MenuButton trigger with a Menu of items.
+The Dropdown trigger is **not limited to a plain button**. `MenuButtonTrigger` is simply the element that wires the open/close behavior — `onClick`, `aria-haspopup`, `aria-expanded`, focus management, and a `ref` — into the Dropdown context. You can render that behavior into a different component in two ways:
+
+- **`slots={{ root: YourComponent }}`** — replace the trigger entirely with another component (e.g. `Button`, `IconButton`). `MenuButtonTrigger` injects all of the trigger behavior into your component as the root slot. Pass props to it via `slotProps={{ root: { ... } }}`.
+- **`slotProps={{ root: { component: 'a' } }}`** (or the `component` prop) — keep `MenuButtonTrigger`'s styling and behavior but render a different HTML element.
+
+This is exactly how the higher-level `IconMenuButton` is built internally (`slots={{ root: IconButton }}`). The only requirement is that the chosen root is focusable and clickable — prefer button-like components (`Button`, `IconButton`). For non-interactive components like `Avatar`, wrap them in a button-like root rather than using them directly.
 
 ```tsx
-<Stack direction="row" spacing={2}>
-  <Dropdown>
-    <MenuButton>기본 메뉴</MenuButton>
+import { Dropdown, MenuButtonTrigger, Menu, MenuItem, Button } from '@ceed/ads';
+
+// Any button-like component as the trigger
+<Dropdown>
+  <MenuButtonTrigger slots={{ root: Button }} slotProps={{ root: { variant: 'soft', color: 'primary' } }}>
+    Open
+  </MenuButtonTrigger>
+  <Menu>
+    <MenuItem>Option 1</MenuItem>
+    <MenuItem>Option 2</MenuItem>
+  </Menu>
+</Dropdown>;
+```
+
+> **Note**: Every component above — including `MenuButtonTrigger` — is imported from `@ceed/ads`. No direct `@mui/joy` import is required.
+
+## Button as Dropdown Trigger
+
+Replace the trigger with the HDS `Button` via `slots={{ root: Button }}` to match your button styling system.
+
+```tsx
+<Dropdown>
+    <MenuButtonTrigger
+      slots={{
+        root: Button
+      }}
+      slotProps={{
+        root: {
+          variant: "soft",
+          color: "primary",
+          endDecorator: <KeyboardArrowDownIcon />
+        }
+      }}
+    >
+      HDS Button 트리거
+    </MenuButtonTrigger>
     <Menu>
-      <MenuItem>첫 번째 옵션</MenuItem>
-      <MenuItem>두 번째 옵션</MenuItem>
-      <MenuItem>세 번째 옵션</MenuItem>
+      <MenuItem>옵션 1</MenuItem>
+      <MenuItem>옵션 2</MenuItem>
+      <MenuItem>옵션 3</MenuItem>
     </Menu>
   </Dropdown>
+```
 
-  <Dropdown>
-    <MenuButton variant="outlined" endDecorator={<ExpandMoreIcon />}>
-      아이콘 포함
-    </MenuButton>
-    <Menu>
-      <MenuItem>옵션 A</MenuItem>
-      <MenuItem>옵션 B</MenuItem>
-      <MenuItem>옵션 C</MenuItem>
+## IconButton Trigger
+
+For space-constrained areas like table rows or card headers, use an `IconButton` as the trigger. Always provide an `aria-label`.
+
+```tsx
+<Dropdown>
+    <MenuButtonTrigger
+      slots={{
+        root: IconButton
+      }}
+      slotProps={{
+        root: {
+          variant: "plain",
+          color: "neutral",
+          "aria-label": "추가 작업"
+        }
+      }}
+    >
+      <MoreVertIcon />
+    </MenuButtonTrigger>
+    <Menu placement="bottom-end">
+      <MenuItem>
+        <EditIcon
+          sx={{
+            mr: 1
+          }}
+        />
+        편집
+      </MenuItem>
+      <MenuItem>
+        <DeleteIcon
+          sx={{
+            mr: 1,
+            color: "danger.500"
+          }}
+        />
+        <Typography color="danger">삭제</Typography>
+      </MenuItem>
     </Menu>
   </Dropdown>
-</Stack>
 ```
 
-## Dropdown Button Variants
+## Avatar Trigger
 
-MenuButton supports `plain`, `outlined`, `soft`, and `solid` variants to match your design context.
+Profile menus often use an avatar as the trigger. Wrap the `Avatar` in a button-like `IconButton` root so the trigger stays keyboard- and screen-reader-accessible.
 
 ```tsx
-<Stack direction="row" spacing={2} flexWrap="wrap">
-  <Dropdown>
-    <MenuButton variant="plain">Plain</MenuButton>
-    <Menu>
-      <MenuItem>옵션 1</MenuItem>
-      <MenuItem>옵션 2</MenuItem>
+<Dropdown>
+    <MenuButtonTrigger
+      slots={{
+        root: IconButton
+      }}
+      slotProps={{
+        root: {
+          variant: "plain",
+          color: "neutral",
+          "aria-label": "프로필 메뉴",
+          sx: {
+            borderRadius: "50%",
+            p: 0
+          }
+        }
+      }}
+    >
+      <Avatar size="sm" variant="soft" color="primary">
+        김
+      </Avatar>
+    </MenuButtonTrigger>
+    <Menu
+      placement="bottom-end"
+      sx={{
+        minWidth: 180
+      }}
+    >
+      <Stack px={2} py={1} spacing={0.5}>
+        <Typography level="title-sm" fontWeight="bold">
+          김철수
+        </Typography>
+        <Typography level="body-xs" color="neutral">
+          kim@example.com
+        </Typography>
+      </Stack>
+      <ListDivider />
+      <MenuItem>
+        <PersonIcon
+          sx={{
+            mr: 1
+          }}
+        />
+        내 프로필
+      </MenuItem>
+      <MenuItem>
+        <LogoutIcon
+          sx={{
+            mr: 1
+          }}
+        />
+        로그아웃
+      </MenuItem>
     </Menu>
   </Dropdown>
+```
 
-  <Dropdown>
-    <MenuButton variant="outlined">Outlined</MenuButton>
+## Custom Trigger Element
+
+To keep `MenuButtonTrigger`'s behavior and styling but render a different HTML tag, set `slotProps={{ root: { component: 'a' } }}`.
+
+```tsx
+<Dropdown>
+    <MenuButtonTrigger
+      variant="outlined"
+      slotProps={{
+        root: {
+          component: "a",
+          role: "button"
+        }
+      }}
+      endDecorator={<ExpandMoreIcon />}
+      sx={{
+        cursor: "pointer"
+      }}
+    >
+      앵커(a) 엘리먼트 트리거
+    </MenuButtonTrigger>
     <Menu>
       <MenuItem>옵션 1</MenuItem>
       <MenuItem>옵션 2</MenuItem>
     </Menu>
   </Dropdown>
+```
 
-  <Dropdown>
-    <MenuButton variant="soft">Soft</MenuButton>
+## useMenuButton Hook Trigger
+
+When you want a fully custom trigger element without using `MenuButtonTrigger` at all, use the `useMenuButton` hook. Call it inside a child of `<Dropdown>` and spread `getRootProps()` onto any element — the hook wires `onClick`, `aria-*`, and the `ref` into the Dropdown context. Render a native `<button>` (or add keyboard handling) so the trigger stays accessible.
+
+```tsx
+import { Dropdown, useMenuButton, Menu, MenuItem, Box } from '@ceed/ads';
+
+function HookTrigger({ children }) {
+  const { getRootProps, open } = useMenuButton();
+  return (
+    <Box component="button" {...getRootProps()} sx={{ cursor: 'pointer' /* custom styles */ }}>
+      {children}
+    </Box>
+  );
+}
+
+<Dropdown>
+  <HookTrigger>Custom trigger</HookTrigger>
+  <Menu>
+    <MenuItem>Option 1</MenuItem>
+    <MenuItem>Option 2</MenuItem>
+  </Menu>
+</Dropdown>;
+```
+
+```tsx
+<Dropdown>
+    <HookTrigger>완전 커스텀 트리거 (useMenuButton)</HookTrigger>
     <Menu>
       <MenuItem>옵션 1</MenuItem>
       <MenuItem>옵션 2</MenuItem>
+      <MenuItem>옵션 3</MenuItem>
     </Menu>
   </Dropdown>
+```
 
-  <Dropdown>
-    <MenuButton variant="solid">Solid</MenuButton>
+> **Note**: A trigger is always required — Dropdown itself renders no UI and only provides open/close state plus the anchor context. The trigger can be `MenuButtonTrigger` (optionally with `slots` / `component`) or your own element wired via `useMenuButton`. Both read the same Dropdown context, and both are available from `@ceed/ads`.
+
+## useMenuButton with Button
+
+You can also spread `getRootProps()` onto the HDS `Button`. Because `Button` renders a native `<button>`, it already provides focusability, Enter/Space activation, and the `button` role — so accessibility is preserved by adding only the `aria-*` / `onClick` / `ref` from the hook. `getRootProps()` does not include `onKeyDown`, which is why a native button (not a `div`) matters here.
+
+```tsx
+import { Dropdown, useMenuButton, Menu, MenuItem, Button } from '@ceed/ads';
+
+function HookButton({ children }) {
+  const { getRootProps, open } = useMenuButton();
+  return (
+    <Button {...getRootProps()} variant={open ? 'soft' : 'outlined'} color="neutral">
+      {children}
+    </Button>
+  );
+}
+```
+
+```tsx
+<Dropdown>
+    <HookButton>useMenuButton + Button</HookButton>
     <Menu>
       <MenuItem>옵션 1</MenuItem>
       <MenuItem>옵션 2</MenuItem>
+      <MenuItem>옵션 3</MenuItem>
     </Menu>
   </Dropdown>
-</Stack>
+```
+
+> **Tip**: For a plain button trigger, prefer `MenuButtonTrigger slots={{ root: Button }}` — it is more concise and wires the menu keyboard behavior for you. Reach for `useMenuButton` when you need a non-button or deeply custom trigger element.
+
+## Dropdown Basic
+
+The simplest Dropdown pairs a `MenuButtonTrigger` with a Menu of items.
+
+```tsx
+<Stack direction="row" spacing={2}>
+    <Dropdown>
+      <MenuButtonTrigger>기본 메뉴</MenuButtonTrigger>
+      <Menu>
+        <MenuItem>첫 번째 옵션</MenuItem>
+        <MenuItem>두 번째 옵션</MenuItem>
+        <MenuItem>세 번째 옵션</MenuItem>
+      </Menu>
+    </Dropdown>
+
+    <Dropdown>
+      <MenuButtonTrigger variant="outlined" endDecorator={<ExpandMoreIcon />}>
+        아이콘 포함
+      </MenuButtonTrigger>
+      <Menu>
+        <MenuItem>옵션 A</MenuItem>
+        <MenuItem>옵션 B</MenuItem>
+        <MenuItem>옵션 C</MenuItem>
+      </Menu>
+    </Dropdown>
+  </Stack>
+```
+
+## Dropdown Button Variants
+
+`MenuButtonTrigger` supports `plain`, `outlined`, `soft`, and `solid` variants to match your design context.
+
+```tsx
+<Stack direction="row" spacing={2} flexWrap="wrap">
+    <Dropdown>
+      <MenuButtonTrigger variant="plain">Plain</MenuButtonTrigger>
+      <Menu>
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+      </Menu>
+    </Dropdown>
+
+    <Dropdown>
+      <MenuButtonTrigger variant="outlined">Outlined</MenuButtonTrigger>
+      <Menu>
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+      </Menu>
+    </Dropdown>
+
+    <Dropdown>
+      <MenuButtonTrigger variant="soft">Soft</MenuButtonTrigger>
+      <Menu>
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+      </Menu>
+    </Dropdown>
+
+    <Dropdown>
+      <MenuButtonTrigger variant="solid">Solid</MenuButtonTrigger>
+      <Menu>
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+      </Menu>
+    </Dropdown>
+  </Stack>
 ```
 
 ## Dropdown Button Colors
@@ -126,56 +380,56 @@ Apply semantic colors to the trigger button for different emphasis levels.
 
 ```tsx
 <Stack direction="row" spacing={2} flexWrap="wrap">
-  <Dropdown>
-    <MenuButton color="primary" variant="soft">
-      Primary
-    </MenuButton>
-    <Menu>
-      <MenuItem>옵션 1</MenuItem>
-      <MenuItem>옵션 2</MenuItem>
-    </Menu>
-  </Dropdown>
+    <Dropdown>
+      <MenuButtonTrigger color="primary" variant="soft">
+        Primary
+      </MenuButtonTrigger>
+      <Menu>
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+      </Menu>
+    </Dropdown>
 
-  <Dropdown>
-    <MenuButton color="neutral" variant="soft">
-      Neutral
-    </MenuButton>
-    <Menu>
-      <MenuItem>옵션 1</MenuItem>
-      <MenuItem>옵션 2</MenuItem>
-    </Menu>
-  </Dropdown>
+    <Dropdown>
+      <MenuButtonTrigger color="neutral" variant="soft">
+        Neutral
+      </MenuButtonTrigger>
+      <Menu>
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+      </Menu>
+    </Dropdown>
 
-  <Dropdown>
-    <MenuButton color="danger" variant="soft">
-      Danger
-    </MenuButton>
-    <Menu>
-      <MenuItem>옵션 1</MenuItem>
-      <MenuItem>옵션 2</MenuItem>
-    </Menu>
-  </Dropdown>
+    <Dropdown>
+      <MenuButtonTrigger color="danger" variant="soft">
+        Danger
+      </MenuButtonTrigger>
+      <Menu>
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+      </Menu>
+    </Dropdown>
 
-  <Dropdown>
-    <MenuButton color="success" variant="soft">
-      Success
-    </MenuButton>
-    <Menu>
-      <MenuItem>옵션 1</MenuItem>
-      <MenuItem>옵션 2</MenuItem>
-    </Menu>
-  </Dropdown>
+    <Dropdown>
+      <MenuButtonTrigger color="success" variant="soft">
+        Success
+      </MenuButtonTrigger>
+      <Menu>
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+      </Menu>
+    </Dropdown>
 
-  <Dropdown>
-    <MenuButton color="warning" variant="soft">
-      Warning
-    </MenuButton>
-    <Menu>
-      <MenuItem>옵션 1</MenuItem>
-      <MenuItem>옵션 2</MenuItem>
-    </Menu>
-  </Dropdown>
-</Stack>
+    <Dropdown>
+      <MenuButtonTrigger color="warning" variant="soft">
+        Warning
+      </MenuButtonTrigger>
+      <Menu>
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+      </Menu>
+    </Dropdown>
+  </Stack>
 ```
 
 ## Dropdown Menu Placements
@@ -183,45 +437,49 @@ Apply semantic colors to the trigger button for different emphasis levels.
 Control where the menu appears relative to the trigger using the `placement` prop on Menu.
 
 ```tsx
-<Stack direction="row" spacing={2} sx={{
-  mt: 4
-}}>
-<Dropdown>
-  <MenuButton variant="outlined">Bottom Start</MenuButton>
-  <Menu placement="bottom-start">
-    <MenuItem>옵션 1</MenuItem>
-    <MenuItem>옵션 2</MenuItem>
-    <MenuItem>옵션 3</MenuItem>
-  </Menu>
-</Dropdown>
+<Stack
+    direction="row"
+    spacing={2}
+    sx={{
+      mt: 4
+    }}
+  >
+    <Dropdown>
+      <MenuButtonTrigger variant="outlined">Bottom Start</MenuButtonTrigger>
+      <Menu placement="bottom-start">
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+        <MenuItem>옵션 3</MenuItem>
+      </Menu>
+    </Dropdown>
 
-<Dropdown>
-  <MenuButton variant="outlined">Bottom</MenuButton>
-  <Menu placement="bottom">
-    <MenuItem>옵션 1</MenuItem>
-    <MenuItem>옵션 2</MenuItem>
-    <MenuItem>옵션 3</MenuItem>
-  </Menu>
-</Dropdown>
+    <Dropdown>
+      <MenuButtonTrigger variant="outlined">Bottom</MenuButtonTrigger>
+      <Menu placement="bottom">
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+        <MenuItem>옵션 3</MenuItem>
+      </Menu>
+    </Dropdown>
 
-<Dropdown>
-  <MenuButton variant="outlined">Bottom End</MenuButton>
-  <Menu placement="bottom-end">
-    <MenuItem>옵션 1</MenuItem>
-    <MenuItem>옵션 2</MenuItem>
-    <MenuItem>옵션 3</MenuItem>
-  </Menu>
-</Dropdown>
+    <Dropdown>
+      <MenuButtonTrigger variant="outlined">Bottom End</MenuButtonTrigger>
+      <Menu placement="bottom-end">
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+        <MenuItem>옵션 3</MenuItem>
+      </Menu>
+    </Dropdown>
 
-<Dropdown>
-  <MenuButton variant="outlined">Top Start</MenuButton>
-  <Menu placement="top-start">
-    <MenuItem>옵션 1</MenuItem>
-    <MenuItem>옵션 2</MenuItem>
-    <MenuItem>옵션 3</MenuItem>
-  </Menu>
-</Dropdown>
-</Stack>
+    <Dropdown>
+      <MenuButtonTrigger variant="outlined">Top Start</MenuButtonTrigger>
+      <Menu placement="top-start">
+        <MenuItem>옵션 1</MenuItem>
+        <MenuItem>옵션 2</MenuItem>
+        <MenuItem>옵션 3</MenuItem>
+      </Menu>
+    </Dropdown>
+  </Stack>
 ```
 
 ## Dropdown with Icons
@@ -230,31 +488,41 @@ Add icons to menu items and decorators to the trigger button for richer visual c
 
 ```tsx
 <Dropdown>
-  <MenuButton variant="outlined" startDecorator={<PersonIcon />} endDecorator={<ExpandMoreIcon />}>
-    사용자 메뉴
-  </MenuButton>
-  <Menu>
-    <MenuItem>
-      <PersonIcon sx={{
-        mr: 1
-      }} />
-      프로필 보기
-    </MenuItem>
-    <MenuItem>
-      <SettingsIcon sx={{
-        mr: 1
-      }} />
-      설정
-    </MenuItem>
-    <ListDivider />
-    <MenuItem>
-      <LogoutIcon sx={{
-        mr: 1
-      }} />
-      로그아웃
-    </MenuItem>
-  </Menu>
-</Dropdown>
+    <MenuButtonTrigger
+      variant="outlined"
+      startDecorator={<PersonIcon />}
+      endDecorator={<ExpandMoreIcon />}
+    >
+      사용자 메뉴
+    </MenuButtonTrigger>
+    <Menu>
+      <MenuItem>
+        <PersonIcon
+          sx={{
+            mr: 1
+          }}
+        />
+        프로필 보기
+      </MenuItem>
+      <MenuItem>
+        <SettingsIcon
+          sx={{
+            mr: 1
+          }}
+        />
+        설정
+      </MenuItem>
+      <ListDivider />
+      <MenuItem>
+        <LogoutIcon
+          sx={{
+            mr: 1
+          }}
+        />
+        로그아웃
+      </MenuItem>
+    </Menu>
+  </Dropdown>
 ```
 
 ## Dropdown Actions Menu
@@ -263,29 +531,38 @@ Build action menus for edit, delete, and other operations. Use `color="danger"`
 
 ```tsx
 <Dropdown>
-  <MenuButton variant="plain" color="neutral" endDecorator={<ExpandMoreIcon />} sx={{
-    fontSize: 'sm'
-  }}>
-  작업
-</MenuButton>
-<Menu>
-  <MenuItem>
-    <EditIcon sx={{
-      mr: 1,
-      fontSize: 'sm'
-    }} />
-    편집
-  </MenuItem>
-  <MenuItem>
-    <DeleteIcon sx={{
-      mr: 1,
-      fontSize: 'sm',
-      color: 'danger.500'
-    }} />
-    <Typography color="danger">삭제</Typography>
-  </MenuItem>
-</Menu>
-</Dropdown>
+    <MenuButtonTrigger
+      variant="plain"
+      color="neutral"
+      endDecorator={<ExpandMoreIcon />}
+      sx={{
+        fontSize: "sm"
+      }}
+    >
+      작업
+    </MenuButtonTrigger>
+    <Menu>
+      <MenuItem>
+        <EditIcon
+          sx={{
+            mr: 1,
+            fontSize: "sm"
+          }}
+        />
+        편집
+      </MenuItem>
+      <MenuItem>
+        <DeleteIcon
+          sx={{
+            mr: 1,
+            fontSize: "sm",
+            color: "danger.500"
+          }}
+        />
+        <Typography color="danger">삭제</Typography>
+      </MenuItem>
+    </Menu>
+  </Dropdown>
 ```
 
 ## Dropdown Filter Menu
@@ -294,16 +571,20 @@ Use Dropdown as an interactive filter selector with state management.
 
 ```tsx
 <Dropdown>
-  <MenuButton variant="outlined" startDecorator={<FilterListIcon />} endDecorator={<ExpandMoreIcon />}>
-    필터: {selectedFilter}
-  </MenuButton>
-  <Menu>
-    <MenuItem onClick={() => setSelectedFilter('전체')}>전체</MenuItem>
-    <MenuItem onClick={() => setSelectedFilter('활성')}>활성</MenuItem>
-    <MenuItem onClick={() => setSelectedFilter('비활성')}>비활성</MenuItem>
-    <MenuItem onClick={() => setSelectedFilter('대기중')}>대기중</MenuItem>
-  </Menu>
-</Dropdown>
+    <MenuButtonTrigger
+      variant="outlined"
+      startDecorator={<FilterListIcon />}
+      endDecorator={<ExpandMoreIcon />}
+    >
+      필터: {selectedFilter}
+    </MenuButtonTrigger>
+    <Menu>
+      <MenuItem onClick={() => setSelectedFilter("전체")}>전체</MenuItem>
+      <MenuItem onClick={() => setSelectedFilter("활성")}>활성</MenuItem>
+      <MenuItem onClick={() => setSelectedFilter("비활성")}>비활성</MenuItem>
+      <MenuItem onClick={() => setSelectedFilter("대기중")}>대기중</MenuItem>
+    </Menu>
+  </Dropdown>
 ```
 
 ## Dropdown Profile
@@ -312,50 +593,67 @@ Combine custom content (user info header) with standard menu items for profile m
 
 ```tsx
 <Dropdown>
-  <MenuButton variant="plain" color="neutral" startDecorator={<Avatar size="sm" variant="soft" color="primary">
-    김
-  </Avatar>} endDecorator={<ExpandMoreIcon />} sx={{
-  gap: 1,
-  padding: 1
-}}>
-김철수
-</MenuButton>
-<Menu sx={{
-  minWidth: 200
-}}>
-<Stack px={2} py={1.5} spacing={0.5}>
-  <Typography level="title-sm" fontWeight="bold">
-    김철수
-  </Typography>
-  <Typography level="body-xs" color="neutral">
-    kim@example.com
-  </Typography>
-</Stack>
-
-<ListDivider />
-
-<MenuItem>
-  <PersonIcon sx={{
-    mr: 1
-  }} />내 프로필
-</MenuItem>
-<MenuItem>
-  <SettingsIcon sx={{
-    mr: 1
-  }} />
-  계정 설정
-</MenuItem>
-
-<ListDivider />
-
-<MenuItem>
-  <LogoutIcon sx={{
-    mr: 1
-  }} />
-  로그아웃
-</MenuItem>
-</Menu>
-</Dropdown>
+    <MenuButtonTrigger
+      variant="plain"
+      color="neutral"
+      startDecorator={
+        <Avatar size="sm" variant="soft" color="primary">
+          김
+        </Avatar>
+      }
+      endDecorator={<ExpandMoreIcon />}
+      sx={{
+        gap: 1,
+        padding: 1
+      }}
+    >
+      김철수
+    </MenuButtonTrigger>
+    <Menu
+      sx={{
+        minWidth: 200
+      }}
+    >
+      <Stack px={2} py={1.5} spacing={0.5}>
+        <Typography level="title-sm" fontWeight="bold">
+          김철수
+        </Typography>
+        <Typography level="body-xs" color="neutral">
+          kim@example.com
+        </Typography>
+      </Stack>
+
+      <ListDivider />
+
+      <MenuItem>
+        <PersonIcon
+          sx={{
+            mr: 1
+          }}
+        />
+        내 프로필
+      </MenuItem>
+      <MenuItem>
+        <SettingsIcon
+          sx={{
+            mr: 1
+          }}
+        />
+        계정 설정
+      </MenuItem>
+
+      <ListDivider />
+
+      <MenuItem>
+        <LogoutIcon
+          sx={{
+            mr: 1
+          }}
+        />
+        로그아웃
+      </MenuItem>
+    </Menu>
+  </Dropdown>
 ```
 
 ## Dropdown Nested Menus
@@ -364,39 +662,39 @@ Place multiple Dropdown instances side by side to create menu bar patterns.
 
 ```tsx
 <Stack direction="row" spacing={3}>
-  <Dropdown>
-    <MenuButton variant="outlined" endDecorator={<ExpandMoreIcon />}>
-      파일
-    </MenuButton>
-    <Menu>
-      <MenuItem>새 파일</MenuItem>
-      <MenuItem>열기</MenuItem>
-      <MenuItem disabled>최근 파일</MenuItem>
-      <ListDivider />
-      <MenuItem>저장</MenuItem>
-      <MenuItem>다른 이름으로 저장</MenuItem>
-      <ListDivider />
-      <MenuItem>인쇄</MenuItem>
-    </Menu>
-  </Dropdown>
+    <Dropdown>
+      <MenuButtonTrigger variant="outlined" endDecorator={<ExpandMoreIcon />}>
+        파일
+      </MenuButtonTrigger>
+      <Menu>
+        <MenuItem>새 파일</MenuItem>
+        <MenuItem>열기</MenuItem>
+        <MenuItem disabled>최근 파일</MenuItem>
+        <ListDivider />
+        <MenuItem>저장</MenuItem>
+        <MenuItem>다른 이름으로 저장</MenuItem>
+        <ListDivider />
+        <MenuItem>인쇄</MenuItem>
+      </Menu>
+    </Dropdown>
 
-  <Dropdown>
-    <MenuButton variant="outlined" endDecorator={<ExpandMoreIcon />}>
-      편집
-    </MenuButton>
-    <Menu>
-      <MenuItem>실행 취소</MenuItem>
-      <MenuItem>다시 실행</MenuItem>
-      <ListDivider />
-      <MenuItem>잘라내기</MenuItem>
-      <MenuItem>복사</MenuItem>
-      <MenuItem>붙여넣기</MenuItem>
-      <ListDivider />
-      <MenuItem>모두 선택</MenuItem>
-      <MenuItem>찾기</MenuItem>
-    </Menu>
-  </Dropdown>
-</Stack>
+    <Dropdown>
+      <MenuButtonTrigger variant="outlined" endDecorator={<ExpandMoreIcon />}>
+        편집
+      </MenuButtonTrigger>
+      <Menu>
+        <MenuItem>실행 취소</MenuItem>
+        <MenuItem>다시 실행</MenuItem>
+        <ListDivider />
+        <MenuItem>잘라내기</MenuItem>
+        <MenuItem>복사</MenuItem>
+        <MenuItem>붙여넣기</MenuItem>
+        <ListDivider />
+        <MenuItem>모두 선택</MenuItem>
+        <MenuItem>찾기</MenuItem>
+      </Menu>
+    </Dropdown>
+  </Stack>
 ```
 
 ## Dropdown Controlled State
@@ -405,23 +703,23 @@ Use the `open` and `onOpenChange` props to programmatically control the menu sta
 
 ```tsx
 <Stack spacing={2}>
-  <Typography level="body-sm">메뉴 상태: {open ? '열림' : '닫힘'}</Typography>
+    <Typography level="body-sm">메뉴 상태: {open ? "열림" : "닫힘"}</Typography>
 
-  <Dropdown open={open} onOpenChange={(event, isOpen) => setOpen(isOpen)}>
-    <MenuButton variant="outlined" endDecorator={<ExpandMoreIcon />}>
-      제어된 메뉴
-    </MenuButton>
-    <Menu>
-      <MenuItem onClick={() => setOpen(false)}>옵션 1</MenuItem>
-      <MenuItem onClick={() => setOpen(false)}>옵션 2</MenuItem>
-      <MenuItem onClick={() => setOpen(false)}>옵션 3</MenuItem>
-    </Menu>
-  </Dropdown>
+    <Dropdown open={open} onOpenChange={(event, isOpen) => setOpen(isOpen)}>
+      <MenuButtonTrigger variant="outlined" endDecorator={<ExpandMoreIcon />}>
+        제어된 메뉴
+      </MenuButtonTrigger>
+      <Menu>
+        <MenuItem onClick={() => setOpen(false)}>옵션 1</MenuItem>
+        <MenuItem onClick={() => setOpen(false)}>옵션 2</MenuItem>
+        <MenuItem onClick={() => setOpen(false)}>옵션 3</MenuItem>
+      </Menu>
+    </Dropdown>
 
-  <Button variant="soft" size="sm" onClick={() => setOpen(!open)}>
-    {open ? '메뉴 닫기' : '메뉴 열기'}
-  </Button>
-</Stack>
+    <Button variant="soft" size="sm" onClick={() => setOpen(!open)}>
+      {open ? "메뉴 닫기" : "메뉴 열기"}
+    </Button>
+  </Stack>
 ```
 
 ## Dropdown Disabled State
@@ -430,22 +728,22 @@ Disable the entire trigger button or individual menu items.
 
 ```tsx
 <Stack direction="row" spacing={2}>
-  <Dropdown>
-    <MenuButton disabled>비활성 메뉴</MenuButton>
-    <Menu>
-      <MenuItem>접근 불가</MenuItem>
-    </Menu>
-  </Dropdown>
+    <Dropdown>
+      <MenuButtonTrigger disabled>비활성 메뉴</MenuButtonTrigger>
+      <Menu>
+        <MenuItem>접근 불가</MenuItem>
+      </Menu>
+    </Dropdown>
 
-  <Dropdown>
-    <MenuButton variant="outlined">일부 옵션 비활성</MenuButton>
-    <Menu>
-      <MenuItem>활성 옵션</MenuItem>
-      <MenuItem disabled>비활성 옵션</MenuItem>
-      <MenuItem>활성 옵션 2</MenuItem>
-    </Menu>
-  </Dropdown>
-</Stack>
+    <Dropdown>
+      <MenuButtonTrigger variant="outlined">일부 옵션 비활성</MenuButtonTrigger>
+      <Menu>
+        <MenuItem>활성 옵션</MenuItem>
+        <MenuItem disabled>비활성 옵션</MenuItem>
+        <MenuItem>활성 옵션 2</MenuItem>
+      </Menu>
+    </Dropdown>
+  </Stack>
 ```
 
 ## Dropdown Long Menu
@@ -454,18 +752,25 @@ Apply `maxHeight` and `overflow: 'auto'` to Menu for scrollable lists with many
 
 ```tsx
 <Dropdown>
-  <MenuButton variant="outlined" endDecorator={<ExpandMoreIcon />}>
-    긴 목록 메뉴
-  </MenuButton>
-  <Menu sx={{
-    maxHeight: 300,
-    overflow: 'auto'
-  }}>
-  {Array.from({
-    length: 20
-  }, (_, index) => <MenuItem key={index}>옵션 {index + 1}</MenuItem>)}
-</Menu>
-</Dropdown>
+    <MenuButtonTrigger variant="outlined" endDecorator={<ExpandMoreIcon />}>
+      긴 목록 메뉴
+    </MenuButtonTrigger>
+    <Menu
+      sx={{
+        maxHeight: 300,
+        overflow: "auto"
+      }}
+    >
+      {Array.from(
+        {
+          length: 20
+        },
+        (_, index) => (
+          <MenuItem key={index}>옵션 {index + 1}</MenuItem>
+        )
+      )}
+    </Menu>
+  </Dropdown>
 ```
 
 ## Dropdown Custom Styling
@@ -474,68 +779,98 @@ Customize borders, shadows, border-radius, and gradients through the `sx` prop.
 
 ```tsx
 <Stack direction="row" spacing={2}>
-  <Dropdown>
-    <MenuButton variant="soft" color="primary" endDecorator={<ExpandMoreIcon />} sx={{
-      borderRadius: 'xl',
-      fontWeight: 'bold'
-    }}>
-    커스텀 버튼
-  </MenuButton>
-  <Menu sx={{
-    borderRadius: 'md',
-    boxShadow: 'lg',
-    border: '2px solid',
-    borderColor: 'primary.200'
-  }}>
-  <MenuItem sx={{
-    borderRadius: 'sm',
-    mx: 0.5,
-    my: 0.25
-  }}>둥근 아이템 1</MenuItem>
-  <MenuItem sx={{
-    borderRadius: 'sm',
-    mx: 0.5,
-    my: 0.25
-  }}>둥근 아이템 2</MenuItem>
-  <MenuItem sx={{
-    borderRadius: 'sm',
-    mx: 0.5,
-    my: 0.25
-  }}>둥근 아이템 3</MenuItem>
-</Menu>
-</Dropdown>
+    <Dropdown>
+      <MenuButtonTrigger
+        variant="soft"
+        color="primary"
+        endDecorator={<ExpandMoreIcon />}
+        sx={{
+          borderRadius: "xl",
+          fontWeight: "bold"
+        }}
+      >
+        커스텀 버튼
+      </MenuButtonTrigger>
+      <Menu
+        sx={{
+          borderRadius: "md",
+          boxShadow: "lg",
+          border: "2px solid",
+          borderColor: "primary.200"
+        }}
+      >
+        <MenuItem
+          sx={{
+            borderRadius: "sm",
+            mx: 0.5,
+            my: 0.25
+          }}
+        >
+          둥근 아이템 1
+        </MenuItem>
+        <MenuItem
+          sx={{
+            borderRadius: "sm",
+            mx: 0.5,
+            my: 0.25
+          }}
+        >
+          둥근 아이템 2
+        </MenuItem>
+        <MenuItem
+          sx={{
+            borderRadius: "sm",
+            mx: 0.5,
+            my: 0.25
+          }}
+        >
+          둥근 아이템 3
+        </MenuItem>
+      </Menu>
+    </Dropdown>
 
-<Dropdown>
-  <MenuButton variant="outlined" sx={{
-    background: 'linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)',
-    border: 0,
-    borderRadius: 3,
-    color: 'white',
-    '&:hover': {
-      background: 'linear-gradient(45deg, #FE6B8B 60%, #FF8E53 100%)'
-    }
-  }}>
-  그라데이션 버튼
-</MenuButton>
-<Menu>
-  <MenuItem>스타일링된 메뉴</MenuItem>
-  <MenuItem>아이템 2</MenuItem>
-</Menu>
-</Dropdown>
-</Stack>
+    <Dropdown>
+      <MenuButtonTrigger
+        variant="outlined"
+        sx={{
+          background: "linear-gradient(45deg, #FE6B8B 30%, #FF8E53 90%)",
+          border: 0,
+          borderRadius: 3,
+          color: "white",
+          "&:hover": {
+            background: "linear-gradient(45deg, #FE6B8B 60%, #FF8E53 100%)"
+          }
+        }}
+      >
+        그라데이션 버튼
+      </MenuButtonTrigger>
+      <Menu>
+        <MenuItem>스타일링된 메뉴</MenuItem>
+        <MenuItem>아이템 2</MenuItem>
+      </Menu>
+    </Dropdown>
+  </Stack>
 ```
 
 ## Navigation Menu
 
 ```tsx
 <Dropdown>
-  <MenuButton variant="plain">Menu</MenuButton>
+  <MenuButtonTrigger variant="plain">Menu</MenuButtonTrigger>
   <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">
+      Home
+    </MenuItem>
+    <MenuItem component="a" href="/about">
+      About
+    </MenuItem>
+    <MenuItem component="a" href="/products">
+      Products
+    </MenuItem>
     <ListDivider />
-    <MenuItem component="a" href="/contact">Contact</MenuItem>
+    <MenuItem component="a" href="/contact">
+      Contact
+    </MenuItem>
   </Menu>
 </Dropdown>
 ```
@@ -546,19 +881,15 @@ Customize borders, shadows, border-radius, and gradients through the `sx` prop.
 const [filter, setFilter] = useState('All');
 
 <Dropdown>
-  <MenuButton
-    variant="outlined"
-    startDecorator={<FilterListIcon />}
-    endDecorator={<ExpandMoreIcon />}
-  >
+  <MenuButtonTrigger variant="outlined" startDecorator={<FilterListIcon />} endDecorator={<ExpandMoreIcon />}>
     Filter: {filter}
-  </MenuButton>
+  </MenuButtonTrigger>
   <Menu>
     <MenuItem onClick={() => setFilter('All')}>All</MenuItem>
     <MenuItem onClick={() => setFilter('Active')}>Active</MenuItem>
     <MenuItem onClick={() => setFilter('Inactive')}>Inactive</MenuItem>
   </Menu>
-</Dropdown>
+</Dropdown>;
 ```
 
 ## Controlled State with External Toggle
@@ -567,7 +898,7 @@ const [filter, setFilter] = useState('All');
 const [open, setOpen] = useState(false);
 
 <Dropdown open={open} onOpenChange={(event, isOpen) => setOpen(isOpen)}>
-  <MenuButton>Controlled Menu</MenuButton>
+  <MenuButtonTrigger>Controlled Menu</MenuButtonTrigger>
   <Menu>
     <MenuItem onClick={() => setOpen(false)}>Option A</MenuItem>
     <MenuItem onClick={() => setOpen(false)}>Option B</MenuItem>
@@ -583,26 +914,30 @@ const [open, setOpen] = useState(false);
 
 ### Key Props
 
-| Prop           | Type                             | Default | Description                          |
-| -------------- | -------------------------------- | ------- | ------------------------------------ |
-| `children`     | `ReactNode`                      | -       | Dropdown content (MenuButton + Menu) |
-| `open`         | `boolean`                        | -       | Controlled open state                |
-| `defaultOpen`  | `boolean`                        | `false` | Initial open state (uncontrolled)    |
-| `onOpenChange` | `(event, open: boolean) => void` | -       | Callback when open state changes     |
+| Prop           | Type                             | Default | Description                                 |
+| -------------- | -------------------------------- | ------- | ------------------------------------------- |
+| `children`     | `ReactNode`                      | -       | Dropdown content (MenuButtonTrigger + Menu) |
+| `open`         | `boolean`                        | -       | Controlled open state                       |
+| `defaultOpen`  | `boolean`                        | `false` | Initial open state (uncontrolled)           |
+| `onOpenChange` | `(event, open: boolean) => void` | -       | Callback when open state changes            |
 
-> **Note**: Dropdown accepts all Joy UI Dropdown props. It is a state management wrapper — style props go on Menu and MenuButton.
+> **Note**: Dropdown accepts all Joy UI Dropdown props. It is a state management wrapper — style props go on Menu and `MenuButtonTrigger`.
 
 ## 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.
 
   ```tsx
-  {/* ✅ Good: Simple list -- use MenuButton directly */}
-  <MenuButton buttonText="Actions" items={[{ text: 'Edit' }, { text: 'Delete' }]} />
-
-  {/* ✅ Good: Complex content -- use Dropdown composition */}
+  {
+    /* ✅ Good: Simple list -- use MenuButton directly */
+  }
+  <MenuButton buttonText="Actions" items={[{ text: 'Edit' }, { text: 'Delete' }]} />;
+
+  {
+    /* ✅ Good: Complex content -- use Dropdown composition */
+  }
   <Dropdown>
-    <MenuButton>User</MenuButton>
+    <MenuButtonTrigger>User</MenuButtonTrigger>
     <Menu>
       <Box sx={{ px: 2, py: 1 }}>
         <Typography level="title-sm">User Name</Typography>
@@ -611,29 +946,35 @@ const [open, setOpen] = useState(false);
       <MenuItem>Settings</MenuItem>
       <MenuItem>Logout</MenuItem>
     </Menu>
-  </Dropdown>
+  </Dropdown>;
   ```
 
 - **Group related items with ListDivider.** Visually separate logical groups of menu items so users can scan options quickly.
 
   ```tsx
-  {/* ✅ Good: Grouped by function */}
+  {
+    /* ✅ Good: Grouped by function */
+  }
   <Menu>
     <MenuItem>Edit</MenuItem>
     <MenuItem>Duplicate</MenuItem>
     <ListDivider />
     <MenuItem color="danger">Delete</MenuItem>
-  </Menu>
+  </Menu>;
   ```
 
 - **Indicate dropdown affordance.** Use `endDecorator={<ExpandMoreIcon />}` on the trigger button so users understand it opens a menu.
 
   ```tsx
-  {/* ✅ Good: Clear dropdown indicator */}
-  <MenuButton endDecorator={<ExpandMoreIcon />}>Options</MenuButton>
-
-  {/* ❌ Avoid: No visual hint that a menu will appear */}
-  <MenuButton>Options</MenuButton>
+  {
+    /* ✅ Good: Clear dropdown indicator */
+  }
+  <MenuButtonTrigger endDecorator={<ExpandMoreIcon />}>Options</MenuButtonTrigger>;
+
+  {
+    /* ❌ Avoid: No visual hint that a menu will appear */
+  }
+  <MenuButtonTrigger>Options</MenuButtonTrigger>;
   ```
 
 - **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.