@commercetools/nimbus-mcp 0.1.0 → 2.11.0

package/data/docs/routes/components-navigation-menu.json

@@ -0,0 +1,546 @@
+{
+  "meta": {
+    "id": "Components-Menu",
+    "title": "Menu",
+    "exportName": "Menu",
+    "description": "A temporary surface that displays a list of choices or actions. It typically appears when a user interacts with an element like a button or icon, or performs a specific action.",
+    "lifecycleState": "Stable",
+    "order": 999,
+    "repoPath": "packages/nimbus/src/components/menu/menu.mdx",
+    "menu": [
+      "Components",
+      "Navigation",
+      "Menu"
+    ],
+    "route": "components/navigation/menu",
+    "tags": [
+      "component",
+      "menu",
+      "dropdown",
+      "actions",
+      "context menu"
+    ],
+    "toc": [
+      {
+        "value": "Overview",
+        "href": "#overview",
+        "depth": 2,
+        "numbering": [
+          1,
+          1
+        ],
+        "parent": "root"
+      },
+      {
+        "value": "Resources",
+        "href": "#resources",
+        "depth": 3,
+        "numbering": [
+          1,
+          1,
+          1
+        ],
+        "parent": "root"
+      }
+    ],
+    "figmaLink": "https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=346-2569",
+    "layout": "app-frame",
+    "tabs": [
+      {
+        "key": "overview",
+        "title": "Overview",
+        "order": 0
+      },
+      {
+        "key": "guidelines",
+        "title": "Guidelines",
+        "order": 2
+      },
+      {
+        "key": "dev",
+        "title": "Implementation",
+        "order": 3
+      },
+      {
+        "key": "a11y",
+        "title": "Accessibility",
+        "order": 4
+      }
+    ]
+  },
+  "mdx": "\n## Overview\n\nMenus present short, actionable items in a vertical list, ensuring easy\nnavigation and selection. They display below the trigger with a 8px space. To\nclose a menu, a user makes a selection, or in the case several selections may be\nmade, after a confirm button or a click off the active area.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React ARIA](https://react-spectrum.adobe.com/react-aria/Menu.html)\n[ARIA Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/)\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=346-2569)\n",
+  "views": {
+    "overview": {
+      "mdx": "\n## Overview\n\nMenus present short, actionable items in a vertical list, ensuring easy\nnavigation and selection. They display below the trigger with a 8px space. To\nclose a menu, a user makes a selection, or in the case several selections may be\nmade, after a confirm button or a click off the active area.\n\n### Resources\n\nDeep dive into implementation details and access the Nimbus design library.\n\n[React ARIA](https://react-spectrum.adobe.com/react-aria/Menu.html)\n[ARIA Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/)\n[Figma library](https://www.figma.com/design/AvtPX6g7OGGCRvNlatGOIY/NIMBUS-design-system?node-id=346-2569)\n",
+      "toc": [
+        {
+          "value": "Overview",
+          "href": "#overview",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "a11y": {
+      "mdx": "\n## Accessibility\n\nA dropdown popover is a temporary, compact list of options or actions that\nappears on user interaction, designed for quick selections and efficient\nnavigation.\n\n```jsx live\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger asChild>\n      <Button variant=\"solid\" colorPalette=\"primary\">\n        <Icons.FolderOpen />\n        File Menu\n      </Button>\n    </Menu.Trigger>\n   <Menu.Content>\n      <Menu.Item id=\"duplicate\">\n        <Icon slot=\"icon\"><Icons.ContentCopy /></Icon>\n        <Text slot=\"label\">Duplicate</Text>\n        <Kbd slot=\"keyboard\">⌘T</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"rename\">\n        <Icon slot=\"icon\"><Icons.Create /></Icon>\n        <Text slot=\"label\">Rename</Text>\n        <Kbd slot=\"keyboard\">⌘R</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"share\">\n        <Icon slot=\"icon\"><Icons.IosShare /></Icon>\n        <Text slot=\"label\">Share</Text>\n        <Kbd slot=\"keyboard\">⌘W</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"pin\">\n        <Icon slot=\"icon\"><Icons.PushPin /></Icon>\n        <Text slot=\"label\">Pin</Text>\n        <Kbd slot=\"keyboard\">⌘P</Kbd>\n      </Menu.Item>\n      <Separator />\n      <Menu.Item id=\"delete\" isCritical>\n        <Icon slot=\"icon\"><Icons.Delete /></Icon>\n        <Text slot=\"label\">Delete</Text>\n        <Kbd slot=\"keyboard\">⌘D</Kbd>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n### Accessibility standards\n\n- **Keyboard Navigation:** Ensure users can open, navigate (arrow keys), select\n  (Enter/Space), and close (Esc) the menu using only the keyboard.\n- **ARIA Roles & States:** Properly apply ARIA roles (e.g., `role=\"menu\"`,\n  `role=\"menuitem\"`, `aria-haspopup`) and states (e.g., `aria-expanded`,\n  `aria-checked`) to convey semantic meaning.\n- **Focus Management:** Confirm focus correctly moves into the menu when opened,\n  cycles within it, and returns to the trigger when closed.\n- **Contrast & Visibility:** Verify sufficient color contrast for menu items and\n  a clear visual focus indicator for selected/hovered items.\n",
+      "toc": [
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility standards",
+          "href": "#accessibility-standards",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "dev": {
+      "mdx": "\n## Getting started\n\n### Import\n\n```tsx\nimport { Menu, type MenuRootProps, type MenuItemProps } from '@commercetools/nimbus';\n```\n\n### Basic usage\n\nThe simplest implementation creates an action menu with items:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root onAction={(key) => alert(`Action: ${key}`)}>\n    <Menu.Trigger>Actions</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"edit\">Edit</Menu.Item>\n      <Menu.Item id=\"duplicate\">Duplicate</Menu.Item>\n      <Menu.Item id=\"delete\">Delete</Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n## Usage examples\n\n### Custom triggers\n\nUse `asChild` to render custom trigger elements like Button or IconButton:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Menu.Root>\n      <Menu.Trigger asChild>\n        <Button variant=\"solid\" colorPalette=\"primary\">\n          <Icons.KeyboardArrowDown />\n          Button Trigger\n        </Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"option1\">Option 1</Menu.Item>\n        <Menu.Item id=\"option2\">Option 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n\n    <Menu.Root>\n      <Menu.Trigger asChild>\n        <IconButton\n          variant=\"ghost\"\n          colorPalette=\"neutral\"\n          aria-label=\"More options\"\n        >\n          <Icons.MoreVert />\n        </IconButton>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"edit\">Edit</Menu.Item>\n        <Menu.Item id=\"delete\">Delete</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n  </Stack>\n)\n```\n\n### Menu placement\n\nControl where the menu appears relative to the trigger with the `placement` prop:\n\n```jsx live-dev\nconst App = () => (\n  <Stack direction=\"row\" gap=\"400\">\n    <Menu.Root placement=\"bottom start\">\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">Bottom Start</Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"1\">Item 1</Menu.Item>\n        <Menu.Item id=\"2\">Item 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n\n    <Menu.Root placement=\"bottom end\">\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">Bottom End</Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"1\">Item 1</Menu.Item>\n        <Menu.Item id=\"2\">Item 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n\n    <Menu.Root placement=\"right\">\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">Right</Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"1\">Item 1</Menu.Item>\n        <Menu.Item id=\"2\">Item 2</Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n  </Stack>\n)\n```\n\n### Rich item content\n\nMenu items support icons, labels, descriptions, and keyboard shortcuts using slots:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Edit Menu</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"copy\">\n        <Icon slot=\"icon\"><Icons.ContentCopy /></Icon>\n        <Text slot=\"label\">Copy</Text>\n        <Text slot=\"description\">Copy to clipboard</Text>\n        <Kbd slot=\"keyboard\">⌘C</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"paste\">\n        <Icon slot=\"icon\"><Icons.ContentPaste /></Icon>\n        <Text slot=\"label\">Paste</Text>\n        <Text slot=\"description\">Paste from clipboard</Text>\n        <Kbd slot=\"keyboard\">⌘V</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"cut\">\n        <Icon slot=\"icon\"><Icons.ContentCut /></Icon>\n        <Text slot=\"label\">Cut</Text>\n        <Kbd slot=\"keyboard\">⌘X</Kbd>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Critical items\n\nUse `isCritical` to highlight destructive actions:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>File Actions</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"rename\">\n        <Icon slot=\"icon\"><Icons.Edit /></Icon>\n        <Text slot=\"label\">Rename</Text>\n      </Menu.Item>\n      <Menu.Item id=\"archive\">\n        <Icon slot=\"icon\"><Icons.Archive /></Icon>\n        <Text slot=\"label\">Archive</Text>\n      </Menu.Item>\n      <Separator />\n      <Menu.Item id=\"delete\" isCritical>\n        <Icon slot=\"icon\"><Icons.Delete /></Icon>\n        <Text slot=\"label\">Delete</Text>\n        <Text slot=\"description\">This action cannot be undone</Text>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Disabled items\n\nUse `isDisabled` on individual items to prevent interaction:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Edit</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"undo\">\n        <Text slot=\"label\">Undo</Text>\n        <Kbd slot=\"keyboard\">⌘Z</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"redo\" isDisabled>\n        <Text slot=\"label\">Redo</Text>\n        <Text slot=\"description\">Nothing to redo</Text>\n        <Kbd slot=\"keyboard\">⌘⇧Z</Kbd>\n      </Menu.Item>\n      <Separator />\n      <Menu.Item id=\"paste\" isDisabled>\n        <Text slot=\"label\">Paste</Text>\n        <Text slot=\"description\">Clipboard is empty</Text>\n        <Kbd slot=\"keyboard\">⌘V</Kbd>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Sections with labels\n\nGroup related items using `Menu.Section` with a label:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Application Menu</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Section label=\"File\">\n        <Menu.Item id=\"new\">New Document</Menu.Item>\n        <Menu.Item id=\"open\">Open</Menu.Item>\n        <Menu.Item id=\"save\">Save</Menu.Item>\n      </Menu.Section>\n      <Separator />\n      <Menu.Section label=\"Edit\">\n        <Menu.Item id=\"undo\">Undo</Menu.Item>\n        <Menu.Item id=\"redo\">Redo</Menu.Item>\n      </Menu.Section>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Single selection mode\n\nUse `selectionMode=\"single\"` for radio-button-like behavior within a section:\n\n```jsx live-dev\nconst App = () => {\n  const [selected, setSelected] = useState<string>(\"medium\");\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Menu.Root\n        selectionMode=\"single\"\n        selectedKeys={new Set([selected])}\n        onSelectionChange={(keys) => {\n          if (keys !== \"all\") {\n            const newKey = Array.from(keys)[0] as string;\n            setSelected(newKey);\n          }\n        }}\n      >\n        <Menu.Trigger asChild>\n          <Button variant=\"outline\">Text Size: {selected}</Button>\n        </Menu.Trigger>\n        <Menu.Content>\n          <Menu.Section label=\"Choose Size\">\n            <Menu.Item id=\"small\">\n              <Text slot=\"label\">Small</Text>\n            </Menu.Item>\n            <Menu.Item id=\"medium\">\n              <Text slot=\"label\">Medium</Text>\n            </Menu.Item>\n            <Menu.Item id=\"large\">\n              <Text slot=\"label\">Large</Text>\n            </Menu.Item>\n          </Menu.Section>\n        </Menu.Content>\n      </Menu.Root>\n      <Text fontSize=\"sm\">Selected: {selected}</Text>\n    </Stack>\n  );\n}\n```\n\n### Multiple selection mode\n\nUse `selectionMode=\"multiple\"` for checkbox-like behavior:\n\n```jsx live-dev\nconst App = () => {\n  const [selected, setSelected] = useState<Set<string>>(new Set([\"bold\"]));\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Menu.Root\n        selectionMode=\"multiple\"\n        selectedKeys={selected}\n        onSelectionChange={(keys) => {\n          if (keys !== \"all\") {\n            setSelected(new Set(Array.from(keys) as string[]));\n          }\n        }}\n      >\n        <Menu.Trigger asChild>\n          <Button variant=\"outline\">Text Formatting</Button>\n        </Menu.Trigger>\n        <Menu.Content>\n          <Menu.Section label=\"Style Options\">\n            <Menu.Item id=\"bold\">\n              <Text slot=\"label\">Bold</Text>\n              <Kbd slot=\"keyboard\">⌘B</Kbd>\n            </Menu.Item>\n            <Menu.Item id=\"italic\">\n              <Text slot=\"label\">Italic</Text>\n              <Kbd slot=\"keyboard\">⌘I</Kbd>\n            </Menu.Item>\n            <Menu.Item id=\"underline\">\n              <Text slot=\"label\">Underline</Text>\n              <Kbd slot=\"keyboard\">⌘U</Kbd>\n            </Menu.Item>\n          </Menu.Section>\n        </Menu.Content>\n      </Menu.Root>\n      <Text fontSize=\"sm\">\n        Selected: {Array.from(selected).join(\", \") || \"None\"}\n      </Text>\n    </Stack>\n  );\n}\n```\n\n### Submenus\n\nCreate nested menus using `Menu.SubmenuTrigger` and `Menu.Submenu`:\n\n```jsx live-dev\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger>Settings</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"general\">\n        <Icon slot=\"icon\"><Icons.Settings /></Icon>\n        <Text slot=\"label\">General</Text>\n      </Menu.Item>\n      <Menu.SubmenuTrigger>\n        <Menu.Item>\n          <Icon slot=\"icon\"><Icons.AccountCircle /></Icon>\n          <Text slot=\"label\">Account</Text>\n          <Text slot=\"description\">Manage your account</Text>\n        </Menu.Item>\n        <Menu.Submenu>\n          <Menu.Item id=\"profile\">Profile</Menu.Item>\n          <Menu.Item id=\"security\">Security</Menu.Item>\n          <Menu.Item id=\"notifications\">Notifications</Menu.Item>\n        </Menu.Submenu>\n      </Menu.SubmenuTrigger>\n      <Menu.SubmenuTrigger>\n        <Menu.Item>\n          <Icon slot=\"icon\"><Icons.Palette /></Icon>\n          <Text slot=\"label\">Appearance</Text>\n        </Menu.Item>\n        <Menu.Submenu>\n          <Menu.Item id=\"theme\">Theme</Menu.Item>\n          <Menu.Item id=\"language\">Language</Menu.Item>\n        </Menu.Submenu>\n      </Menu.SubmenuTrigger>\n    </Menu.Content>\n  </Menu.Root>\n)\n```\n\n### Uncontrolled mode\n\nFor simpler use cases, use `defaultOpen` and `onOpenChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [lastAction, setLastAction] = useState<string>(\"None\");\n\n  return (\n    <Stack direction=\"column\" gap=\"400\">\n      <Menu.Root\n        onAction={(key) => setLastAction(key as string)}\n        onOpenChange={(isOpen) => console.log(\"Menu open:\", isOpen)}\n        placement=\"bottom end\"\n      >\n        <Menu.Trigger>Quick Actions</Menu.Trigger>\n        <Menu.Content>\n          <Menu.Item id=\"new\">New File</Menu.Item>\n          <Menu.Item id=\"open\">Open</Menu.Item>\n          <Menu.Item id=\"save\">Save</Menu.Item>\n        </Menu.Content>\n      </Menu.Root>\n      <Text fontSize=\"sm\">Last action: {lastAction}</Text>\n    </Stack>\n  );\n}\n```\n\n### Controlled mode\n\nFor programmatic control, use `isOpen` and `onOpenChange`:\n\n```jsx live-dev\nconst App = () => {\n  const [isOpen, setIsOpen] = useState<boolean>(false);\n\n  return (\n    <Stack direction=\"row\" gap=\"400\" alignItems=\"center\">\n      <Menu.Root isOpen={isOpen} onOpenChange={setIsOpen}>\n        <Menu.Trigger>Controlled Menu</Menu.Trigger>\n        <Menu.Content>\n          <Menu.Item id=\"item1\">Item 1</Menu.Item>\n          <Menu.Item id=\"item2\">Item 2</Menu.Item>\n          <Menu.Item id=\"item3\">Item 3</Menu.Item>\n        </Menu.Content>\n      </Menu.Root>\n      <Button onClick={() => setIsOpen(!isOpen)}>\n        {isOpen ? \"Close\" : \"Open\"} Menu\n      </Button>\n      <Text fontSize=\"sm\">Menu is {isOpen ? \"open\" : \"closed\"}</Text>\n    </Stack>\n  );\n}\n```\n\n## Component requirements\n\n## Accessibility\n\nThe Menu handles most accessibility requirements internally through React Aria. However, you must ensure proper labeling:\n\n- **For default triggers**: The trigger text serves as the accessible name\n- **For icon-only triggers**: Always provide `aria-label`:\n\n```tsx\n<Menu.Trigger asChild>\n  <IconButton aria-label=\"More options\">\n    <Icons.MoreVert />\n  </IconButton>\n</Menu.Trigger>\n```\n\n- **For custom triggers**: Ensure the trigger element has an accessible name\n\nIf your use case requires tracking and analytics for this component, it is good practice to add a **persistent**, **unique** id to the component:\n\n```tsx\nconst PERSISTENT_ID = \"example-menu\";\n\nexport const Example = () => (\n  <Menu.Root id={PERSISTENT_ID}>\n    <Menu.Trigger>Actions</Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"edit\">Edit</Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n#### Keyboard navigation\n\nThe component supports full keyboard interaction:\n\n- `Tab` / `Shift+Tab`: Navigate to/from the menu trigger\n- `Enter` / `Space`: Open the menu when trigger is focused\n- `Arrow Down` / `Arrow Up`: Navigate through menu items\n- `Arrow Right`: Open submenu (when focused on submenu trigger)\n- `Arrow Left`: Close submenu and return to parent menu\n- `Enter`: Select the focused item\n- `Space`: Toggle selection in selection modes\n- `Escape`: Close the menu\n- `Home` / `End`: Jump to first/last item\n- Type to search: Type characters to jump to matching items\n\n## API reference\n\n<PropsTable id=\"Menu\" />\n\n## Common patterns\n\n### Context menu for list items\n\nA common pattern for providing actions on list items:\n\n```jsx live-dev\nconst App = () => {\n  const items = [\n    { id: \"1\", name: \"Document A.pdf\" },\n    { id: \"2\", name: \"Spreadsheet B.xlsx\" },\n    { id: \"3\", name: \"Presentation C.pptx\" },\n  ];\n\n  const handleAction = (itemId, action) => {\n    alert(`${action} on ${itemId}`);\n  };\n\n  return (\n    <Stack direction=\"column\" gap=\"200\">\n      {items.map((item) => (\n        <Box\n          key={item.id}\n          display=\"flex\"\n          justifyContent=\"space-between\"\n          alignItems=\"center\"\n          padding=\"300\"\n          borderRadius=\"200\"\n          bg=\"neutral.2\"\n        >\n          <Text>{item.name}</Text>\n          <Menu.Root onAction={(action) => handleAction(item.id, action)}>\n            <Menu.Trigger asChild>\n              <IconButton\n                variant=\"ghost\"\n                aria-label={`Actions for ${item.name}`}\n              >\n                <Icons.MoreVert />\n              </IconButton>\n            </Menu.Trigger>\n            <Menu.Content>\n              <Menu.Item id=\"open\">\n                <Icon slot=\"icon\"><Icons.FolderOpen /></Icon>\n                <Text slot=\"label\">Open</Text>\n              </Menu.Item>\n              <Menu.Item id=\"rename\">\n                <Icon slot=\"icon\"><Icons.Edit /></Icon>\n                <Text slot=\"label\">Rename</Text>\n              </Menu.Item>\n              <Menu.Item id=\"download\">\n                <Icon slot=\"icon\"><Icons.Download /></Icon>\n                <Text slot=\"label\">Download</Text>\n              </Menu.Item>\n              <Separator />\n              <Menu.Item id=\"delete\" isCritical>\n                <Icon slot=\"icon\"><Icons.Delete /></Icon>\n                <Text slot=\"label\">Delete</Text>\n              </Menu.Item>\n            </Menu.Content>\n          </Menu.Root>\n        </Box>\n      ))}\n    </Stack>\n  );\n}\n```\n\n### Dynamic menu items\n\nBuild menus from data arrays:\n\n```jsx live-dev\nconst App = () => {\n  const menuItems = [\n    { id: \"new\", label: \"New File\", icon: Icons.InsertDriveFile, kbd: \"⌘N\" },\n    { id: \"open\", label: \"Open\", icon: Icons.FolderOpen, kbd: \"⌘O\" },\n    { id: \"save\", label: \"Save\", icon: Icons.Save, kbd: \"⌘S\" },\n    { id: \"divider\" },\n    { id: \"delete\", label: \"Delete\", icon: Icons.Delete, critical: true },\n  ];\n\n  return (\n    <Menu.Root onAction={(key) => alert(`Action: ${key}`)}>\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\">\n          <Icons.MoreVert />\n          File Menu\n        </Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        {menuItems.map((item) => {\n          if (item.id === \"divider\") {\n            return <Separator key={Math.random()} />;\n          }\n          return (\n            <Menu.Item key={item.id} id={item.id} isCritical={item.critical}>\n              {item.icon && (\n                <Icon slot=\"icon\"><item.icon /></Icon>\n              )}\n              <Text slot=\"label\">{item.label}</Text>\n              {item.kbd && <Kbd slot=\"keyboard\">{item.kbd}</Kbd>}\n            </Menu.Item>\n          );\n        })}\n      </Menu.Content>\n    </Menu.Root>\n  );\n}\n```\n\n## Testing your implementation\n\nThese examples demonstrate how to test your implementation when using Menu within your application. As the component's internal functionality is already tested by Nimbus, these patterns help you verify your integration and application-specific logic.\n\n### Basic Rendering Tests\n\nVerify the menu renders with expected elements\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Basic rendering\", () => {\n  it(\"renders menu trigger\", () => {\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    expect(screen.getByRole(\"button\", { name: \"Actions\" })).toBeInTheDocument();\n  });\n\n  it(\"renders menu items when opened\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n            <Menu.Item id=\"delete\">Delete</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    expect(screen.getByRole(\"menuitem\", { name: \"Edit\" })).toBeInTheDocument();\n    expect(\n      screen.getByRole(\"menuitem\", { name: \"Delete\" })\n    ).toBeInTheDocument();\n  });\n});\n```\n\n### Interaction Tests\n\nTest user interactions with the menu\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Interactions\", () => {\n  it(\"opens menu on trigger click\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n  });\n\n  it(\"closes menu when item is selected\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"menuitem\", { name: \"Edit\" }));\n\n    expect(handleAction).toHaveBeenCalledWith(\"edit\");\n    await waitFor(() => {\n      expect(screen.queryByRole(\"menu\")).not.toBeInTheDocument();\n    });\n  });\n\n  it(\"closes menu on Escape key\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.keyboard(\"{Escape}\");\n\n    await waitFor(() => {\n      expect(screen.queryByRole(\"menu\")).not.toBeInTheDocument();\n    });\n  });\n});\n```\n\n### Action Callback Tests\n\nTest the onAction callback behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Action callback\", () => {\n  it(\"calls onAction with item id when clicked\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"copy\">Copy</Menu.Item>\n            <Menu.Item id=\"paste\">Paste</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"menuitem\", { name: \"Copy\" }));\n\n    expect(handleAction).toHaveBeenCalledWith(\"copy\");\n  });\n\n  it(\"calls onAction with Enter key\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"save\">Save</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // First item should have focus\n    await waitFor(() => {\n      expect(screen.getByRole(\"menuitem\", { name: \"Save\" })).toHaveFocus();\n    });\n\n    await user.keyboard(\"{Enter}\");\n\n    expect(handleAction).toHaveBeenCalledWith(\"save\");\n  });\n});\n```\n\n### Controlled Mode Tests\n\nTest controlled open/close behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Controlled mode\", () => {\n  it(\"opens when isOpen is true\", async () => {\n    render(\n      <NimbusProvider>\n        <Menu.Root isOpen={true} onOpenChange={() => {}}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n  });\n\n  it(\"calls onOpenChange when menu is opened\", async () => {\n    const user = userEvent.setup();\n    const handleOpenChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root isOpen={false} onOpenChange={handleOpenChange}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    expect(handleOpenChange).toHaveBeenCalledWith(true);\n  });\n});\n```\n\n### Disabled Items Tests\n\nTest disabled item behavior\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Disabled items\", () => {\n  it(\"renders disabled item with aria-disabled\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"edit\">Edit</Menu.Item>\n            <Menu.Item id=\"paste\" isDisabled>\n              Paste\n            </Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    const disabledItem = screen.getByRole(\"menuitem\", { name: \"Paste\" });\n    expect(disabledItem).toHaveAttribute(\"aria-disabled\", \"true\");\n  });\n\n  it(\"does not call onAction for disabled items\", async () => {\n    const user = userEvent.setup();\n    const handleAction = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root onAction={handleAction}>\n          <Menu.Trigger>Actions</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"paste\" isDisabled>\n              Paste\n            </Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Actions\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // Disabled items have pointer-events: none, so click won't fire\n    // We verify the item is disabled\n    const disabledItem = screen.getByRole(\"menuitem\", { name: \"Paste\" });\n    expect(disabledItem).toHaveAttribute(\"aria-disabled\", \"true\");\n\n    // onAction should not have been called\n    expect(handleAction).not.toHaveBeenCalled();\n  });\n});\n```\n\n### Selection Mode Tests\n\nTest single and multiple selection modes\n\n```tsx\nimport { describe, it, expect, vi } from \"vitest\";\nimport { render, screen, waitFor } from \"@testing-library/react\";\nimport userEvent from \"@testing-library/user-event\";\nimport { Menu, NimbusProvider } from \"@commercetools/nimbus\";\n\ndescribe(\"Menu - Selection mode\", () => {\n  it(\"renders radio items in single selection mode\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root selectionMode=\"single\" selectedKeys={new Set([\"medium\"])}>\n          <Menu.Trigger>Size</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"small\">Small</Menu.Item>\n            <Menu.Item id=\"medium\">Medium</Menu.Item>\n            <Menu.Item id=\"large\">Large</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Size\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // Items should be radio items in single selection mode\n    expect(\n      screen.getByRole(\"menuitemradio\", { name: \"Medium\" })\n    ).toHaveAttribute(\"data-selected\");\n  });\n\n  it(\"renders checkbox items in multiple selection mode\", async () => {\n    const user = userEvent.setup();\n    render(\n      <NimbusProvider>\n        <Menu.Root\n          selectionMode=\"multiple\"\n          selectedKeys={new Set([\"bold\", \"italic\"])}\n        >\n          <Menu.Trigger>Formatting</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"bold\">Bold</Menu.Item>\n            <Menu.Item id=\"italic\">Italic</Menu.Item>\n            <Menu.Item id=\"underline\">Underline</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Formatting\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    // Items should be checkbox items in multiple selection mode\n    expect(\n      screen.getByRole(\"menuitemcheckbox\", { name: \"Bold\" })\n    ).toHaveAttribute(\"data-selected\");\n    expect(\n      screen.getByRole(\"menuitemcheckbox\", { name: \"Italic\" })\n    ).toHaveAttribute(\"data-selected\");\n    expect(\n      screen.getByRole(\"menuitemcheckbox\", { name: \"Underline\" })\n    ).not.toHaveAttribute(\"data-selected\");\n  });\n\n  it(\"calls onSelectionChange when selection changes\", async () => {\n    const user = userEvent.setup();\n    const handleSelectionChange = vi.fn();\n\n    render(\n      <NimbusProvider>\n        <Menu.Root\n          selectionMode=\"single\"\n          selectedKeys={new Set([\"small\"])}\n          onSelectionChange={handleSelectionChange}\n        >\n          <Menu.Trigger>Size</Menu.Trigger>\n          <Menu.Content>\n            <Menu.Item id=\"small\">Small</Menu.Item>\n            <Menu.Item id=\"medium\">Medium</Menu.Item>\n          </Menu.Content>\n        </Menu.Root>\n      </NimbusProvider>\n    );\n\n    await user.click(screen.getByRole(\"button\", { name: \"Size\" }));\n\n    await waitFor(() => {\n      expect(screen.getByRole(\"menu\")).toBeInTheDocument();\n    });\n\n    await user.click(screen.getByRole(\"menuitemradio\", { name: \"Medium\" }));\n\n    expect(handleSelectionChange).toHaveBeenCalled();\n  });\n});\n```\n\n\n## Resources\n\n- [Storybook](https://nimbus-storybook.vercel.app/?path=/docs/components-menu--docs)\n- [React Aria Menu](https://react-spectrum.adobe.com/react-aria/Menu.html)\n- [ARIA Menu Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/)\n",
+      "toc": [
+        {
+          "value": "Getting started",
+          "href": "#getting-started",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Import",
+          "href": "#import",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic usage",
+          "href": "#basic-usage",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage examples",
+          "href": "#usage-examples",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Custom triggers",
+          "href": "#custom-triggers",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Menu placement",
+          "href": "#menu-placement",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Rich item content",
+          "href": "#rich-item-content",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Critical items",
+          "href": "#critical-items",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled items",
+          "href": "#disabled-items",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Sections with labels",
+          "href": "#sections-with-labels",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Single selection mode",
+          "href": "#single-selection-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Multiple selection mode",
+          "href": "#multiple-selection-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            8
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Submenus",
+          "href": "#submenus",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            9
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Uncontrolled mode",
+          "href": "#uncontrolled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            10
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled mode",
+          "href": "#controlled-mode",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            11
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Component requirements",
+          "href": "#component-requirements",
+          "depth": 2,
+          "numbering": [
+            1,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Accessibility",
+          "href": "#accessibility",
+          "depth": 2,
+          "numbering": [
+            1,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keyboard navigation",
+          "href": "#keyboard-navigation",
+          "depth": 4,
+          "numbering": [
+            1,
+            4,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "API reference",
+          "href": "#api-reference",
+          "depth": 2,
+          "numbering": [
+            1,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common patterns",
+          "href": "#common-patterns",
+          "depth": 2,
+          "numbering": [
+            1,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Context menu for list items",
+          "href": "#context-menu-for-list-items",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Dynamic menu items",
+          "href": "#dynamic-menu-items",
+          "depth": 3,
+          "numbering": [
+            1,
+            6,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Testing your implementation",
+          "href": "#testing-your-implementation",
+          "depth": 2,
+          "numbering": [
+            1,
+            7
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Basic Rendering Tests",
+          "href": "#basic-rendering-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Interaction Tests",
+          "href": "#interaction-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Action Callback Tests",
+          "href": "#action-callback-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Controlled Mode Tests",
+          "href": "#controlled-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            4
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Disabled Items Tests",
+          "href": "#disabled-items-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            5
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Selection Mode Tests",
+          "href": "#selection-mode-tests",
+          "depth": 3,
+          "numbering": [
+            1,
+            7,
+            6
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Resources",
+          "href": "#resources",
+          "depth": 2,
+          "numbering": [
+            1,
+            8
+          ],
+          "parent": "root"
+        }
+      ]
+    },
+    "guidelines": {
+      "mdx": "\n## Guidelines\n\nMenu guidelines focus on providing temporary, contextual information or actions\nin a clear and accessible manner, ensuring they are easily triggered, navigable\nvia keyboard, and don't disrupt the user's primary workflow.\n\n### Best practices\n\n- **Clear trigger:** Make the trigger element visually distinct and interactive.\n  Use consistent icons or labels for dropdown triggers.\n- **Logical content:** Order options logically (alphabetical, frequency, etc.).\n  Keep content concise and actionable.\n- **Easy interaction:** If interaction involves a single selection, close the\n  popover upon selection. Keep the popover open if more complicated content\n  needs several selections.\n- **Responsive behavior:** Adapt the dropdown's position and size to different\n  screen sizes. Ensure it works well on touch devices.\n- **Visual feedback:** Highlight the selected option. Use clear hover states.\n- **Keyboard navigation:** Allow users to navigate options with arrow keys.\n  Enable selection with Enter/Spacebar. Enable closing the popover with the\n  Escape key.\n- **ARIA attributes:** Use `aria-haspopup`, `aria-expanded`, and `aria-label`\n  for screen reader support. Manage focus correctly when the popover opens and\n  closes.\n- **Avoid nested dropdowns:** Keep the structure simple and avoid nested menus.\n- **Contextual placement:** Position the dropdown near the trigger element\n  without obscuring important content.\n- **Limit content:** Keep the content to simple actions, or short text.\n- **Use sections correctly:** Use sections only if you have more than 2 groups\n  to organize. It is unneeded to have sections if the information is collected\n  together.\n\n#### Common popover content\n\nThese are some of the most seen uses of popover content. These are included in\nthe figma library components to make designing common shared uses easier.\n\n**Simple list**\n\nAllows the user to select one option, add a search to allow users to make\nselection easier if there are many options. For options 5 or fewer, a search is\nnot needed.\n\n```jsx live\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger asChild>\n      <IconButton\n        variant=\"ghost\"\n        colorPalette=\"neutral\"\n        aria-label=\"More options\"\n      >\n        <Icons.MoreVert />\n      </IconButton>\n    </Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"menu-item-1\">Menu Item</Menu.Item>\n      <Menu.Item id=\"menu-item-2\">Menu Item</Menu.Item>\n      <Menu.Item id=\"menu-item-3\">Menu Item</Menu.Item>\n      <Menu.Item id=\"menu-item-4\">Menu Item</Menu.Item>\n      <Menu.Item id=\"menu-item-5\">Menu Item</Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n**Action list**\n\nInclude icons, offer tips or shortcuts, color coding for semantic clues, and\nsectioning. For options 5 or fewer, a search is not needed.\n\n```jsx live\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger asChild>\n      <Button variant=\"solid\" colorPalette=\"primary\">\n        <Icons.FolderOpen />\n        File Menu\n      </Button>\n    </Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"duplicate\">\n        <Icon slot=\"icon\">\n          <Icons.ContentCopy />\n        </Icon>\n        <Text slot=\"label\">Duplicate</Text>\n        <Kbd slot=\"keyboard\">⌘T</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"rename\">\n        <Icon slot=\"icon\">\n          <Icons.Create />\n        </Icon>\n        <Text slot=\"label\">Rename</Text>\n        <Kbd slot=\"keyboard\">⌘R</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"share\">\n        <Icon slot=\"icon\">\n          <Icons.IosShare />\n        </Icon>\n        <Text slot=\"label\">Share</Text>\n        <Kbd slot=\"keyboard\">⌘W</Kbd>\n      </Menu.Item>\n      <Menu.Item id=\"pin\">\n        <Icon slot=\"icon\">\n          <Icons.PushPin />\n        </Icon>\n        <Text slot=\"label\">Pin</Text>\n        <Kbd slot=\"keyboard\">⌘P</Kbd>\n      </Menu.Item>\n      <Separator />\n      <Menu.Item id=\"delete\" isCritical>\n        <Icon slot=\"icon\">\n          <Icons.Delete />\n        </Icon>\n        <Text slot=\"label\">Delete</Text>\n        <Kbd slot=\"keyboard\">⌘D</Kbd>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n**Section list**\n\nLets the user perform a one time action. Features optional section titles and\ndescriptions. For options 5 or fewer, a search is not needed.\n\n```jsx live\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger asChild>\n      <Button variant=\"outline\" colorPalette=\"primary\">\n        Actions\n      </Button>\n    </Menu.Trigger>\n    <Menu.Content>\n      <Menu.Section label=\"Import\">\n        <Menu.Item id=\"import-csv\">Import from CSV</Menu.Item>\n        <Menu.Item id=\"import-drive\">Import from Drive</Menu.Item>\n      </Menu.Section>\n      <Separator />\n      <Menu.Section label=\"Export\">\n        <Menu.Item id=\"export-csv\">Export to CSV</Menu.Item>\n        <Menu.Item id=\"export-drive\">Export to Drive</Menu.Item>\n      </Menu.Section>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n**Custom content**\n\nProvide a different experience to suit what your user needs within a popover.\nMake sure that this content is best suited for smaller areas. Options are very\ncustomizable to suit your needs.\n\n## Usage\n\nMenus are essential to hold actions and tools in a compact and handy area of the\nUI for a user. Make sure to use them correctly to allow the user to work more\nefficiently and not to overwhelm. Recognizing experience patterns in your\nproduct will also help in creating successful interactions for your users.\n\n> [!TIP]\\\n> When to use\n\n- **Short, actionable lists:** Lists of options for filtering, sorting, or\n  selecting specific actions. Menu items that are clearly labeled and easily\n  understood.\n- **Simple form elements:** Basic form inputs like radio buttons or checkboxes\n  for quick selections.\n- **Contextual actions:** Actions related to the item or element that triggered\n  the dropdown. Quick links to related settings or preferences.\n\n> [!CAUTION]\\\n> When not to use\n\n- **Long paragraphs of text:** Menus are not suitable for displaying large\n  amounts of text. Keep content concise and focused.\n- **Complex forms or interactions:** Avoid placing complex forms or multi-step\n  processes within a menu dropdown. These should be handled on dedicated pages\n  or modals.\n- **Critical information:** Do not rely on menu dropdown to display essential\n  information that users need to see immediately. Important content should be\n  readily visible on the page.\n- **Unrelated content:** Ensure that the content of the menu is directly related\n  to the trigger element. Avoid including unrelated or irrelevant information.\n- **Nested dropdown:** Nested drop down within menu can be confusing and\n  difficult to navigate.\n- **Content that changes the page layout:** Avoid content that will cause the\n  page to reflow when the menu opens.\n\n### Solid-styled widths\n\nThese placements are more regular, they have either a maximum width of 268px or\nform wide. The menu width should match the width of the field itself.\n\n> [!TIP]\\\n> **Do**\n>\n> - The form is at maximum size (when not in a full page form) and the menu\n>   matches the width of the field.\n> - Longer options flow to the next lines, and when chosen, those longer texts\n>   are truncated so the user can still see the icons clearly.\n\n```jsx live\nconst App = () => (\n  <Stack direction=\"horizontal\" gap=\"400\" alignItems=\"flex-start\">\n    <Menu.Root>\n      <Menu.Trigger asChild>\n        <Button variant=\"outline\" colorPalette=\"neutral\">\n          Project 1\n          <Icons.KeyboardArrowDown />\n        </Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"long-name\">Project with a very long name</Menu.Item>\n        <Menu.Item id=\"project-1\">Project 1</Menu.Item>\n        <Menu.Item id=\"abc\">ABC</Menu.Item>\n        <Menu.Item id=\"even-longer\">\n          Project with an even longer name that breaks into 2 lines\n        </Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n    <Menu.Root>\n      <Menu.Trigger asChild>\n        <Button variant=\"ghost\" colorPalette=\"neutral\">\n          Project 1\n          <Icons.KeyboardArrowDown />\n        </Button>\n      </Menu.Trigger>\n      <Menu.Content>\n        <Menu.Item id=\"long-name-2\">Project with a very long name</Menu.Item>\n        <Menu.Item id=\"project-1-2\">Project 1</Menu.Item>\n        <Menu.Item id=\"abc-2\">ABC</Menu.Item>\n        <Menu.Item id=\"even-longer-2\">\n          Project with an even longer name that breaks into 2 lines\n        </Menu.Item>\n      </Menu.Content>\n    </Menu.Root>\n  </Stack>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not have different widths for select inputs.\n> - Do not change the width of the field to match the content once selected.\n\n```jsx live\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger asChild>\n      <Button variant=\"ghost\" colorPalette=\"neutral\">\n        Project 1\n        <Icons.KeyboardArrowDown />\n      </Button>\n    </Menu.Trigger>\n    <Menu.Content maxW=\"130px\">\n      <Menu.Item id=\"long-name\">Project with a very long name</Menu.Item>\n      <Menu.Item id=\"project-1\">Project 1</Menu.Item>\n      <Menu.Item id=\"abc\">ABC</Menu.Item>\n      <Menu.Item id=\"even-longer\">\n        Project with an even longer name that breaks into 2 lines\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n### Icons within action lists\n\nHaving icons can make actions easier for a user to select quickly, especially\nfor common and repetitive actions across products. Make sure to keep aligned\nwith familiar patterns to ensure user recognition. Actions can also be organized\nwith sections.\n\n> [!TIP]\\\n> **Do**\n>\n> - Use common icons and clear and concise labels that are easily understood by\n>   users.\n> - Use destructive-styled icons for the actions that apply.\n\n```jsx live\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger asChild>\n      <Button variant=\"outline\" colorPalette=\"neutral\">\n        Actions\n      </Button>\n    </Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"duplicate\">\n        <Icon slot=\"icon\">\n          <Icons.ContentCopy />\n        </Icon>\n        <Text slot=\"label\">Duplicate</Text>\n      </Menu.Item>\n      <Menu.Item id=\"upload\">\n        <Icon slot=\"icon\">\n          <Icons.IosShare />\n        </Icon>\n        <Text slot=\"label\">Upload</Text>\n      </Menu.Item>\n      <Menu.Item id=\"delete\" isCritical>\n        <Icon slot=\"icon\">\n          <Icons.Delete />\n        </Icon>\n        <Text slot=\"label\">Delete</Text>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Do not use uncommon icons, and do not shorten labels of actions unless it is\n>   common and user tested.\n> - Do not use destructive styled actions for actions that are not destructive\n\n```jsx live\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger asChild>\n      <Button variant=\"outline\" colorPalette=\"neutral\">\n        Actions\n      </Button>\n    </Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"dupli\">\n        <Icon slot=\"icon\">\n          <Icons.FilterList />\n        </Icon>\n        <Text slot=\"label\">Dupli</Text>\n      </Menu.Item>\n      <Menu.Item id=\"upload\" isCritical>\n        <Icon slot=\"icon\">\n          <Icons.IosShare />\n        </Icon>\n        <Text slot=\"label\">Upload</Text>\n      </Menu.Item>\n      <Menu.Item id=\"delete\" isCritical>\n        <Icon slot=\"icon\">\n          <Icons.Delete />\n        </Icon>\n        <Text slot=\"label\">Delete</Text>\n      </Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n### Keep menu items concise\n\nKeep menu items short and concise. Long menu items that cause text to wrap\nmultiple lines are discouraged. If text wrapping becomes a frequent concern,\nconsider revising the text or use alternative UI patterns that will give your\ncontent more space.\n\n> [!TIP]\\\n> **Do**\n>\n> - Use a short and easily understandable label. Describe, do not use labels as\n>   instructions.\n> - Text can flow to three lines, but truncate further text.\n\n```jsx live\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger asChild>\n      <Button variant=\"outline\" colorPalette=\"neutral\">\n        Discount type\n        <Icons.KeyboardArrowDown />\n      </Button>\n    </Menu.Trigger>\n    <Menu.Content>\n      <Menu.Section label=\"Product discounts\">\n        <Menu.Item id=\"pct-off-product\">Percentage off product</Menu.Item>\n        <Menu.Item id=\"amt-off-product\">Amount off product</Menu.Item>\n      </Menu.Section>\n      <Separator />\n      <Menu.Section label=\"Cart discounts with line items\">\n        <Menu.Item id=\"pct-off-cart\">Percentage off item(s) on cart</Menu.Item>\n        <Menu.Item id=\"amt-off-cart\">Amount off item(s) in cart</Menu.Item>\n        <Menu.Item id=\"buy-x-get-x\">Buy x get x with percentage off</Menu.Item>\n        <Menu.Item id=\"fixed-price\">Fixed-price in cart</Menu.Item>\n        <Menu.Item id=\"shipping\">Discounted shipping</Menu.Item>\n        <Menu.Item id=\"gift\">Gift with purchase</Menu.Item>\n        <Menu.Item id=\"amt-total\">Amount off based on total spend</Menu.Item>\n        <Menu.Item id=\"pct-total\">\n          Percentage off based on total spend\n        </Menu.Item>\n      </Menu.Section>\n      <Separator />\n      <Menu.Section label=\"Cart discounts with custom line items\">\n        <Menu.Item id=\"custom-pct-off\">\n          Percentage off item(s) on cart\n        </Menu.Item>\n        <Menu.Item id=\"custom-amt-off\">Amount off item(s) in cart</Menu.Item>\n        <Menu.Item id=\"custom-buy-x\">Buy x get x with percentage off</Menu.Item>\n      </Menu.Section>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Keep content short or make sure that the location has enough room to display\n>   content with more space.\n> - Don’t use additional labels or explainers when unneeded.\n> - Do not encourage lengthy text for drop down experiences. Text can flow to\n>   three lines, but truncate further text.\n> - Punctuation is not needed.\n\n```jsx live\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger asChild>\n      <Button variant=\"outline\" colorPalette=\"neutral\">\n        Discount type\n        <Icons.KeyboardArrowDown />\n      </Button>\n    </Menu.Trigger>\n    <Menu.Content>\n      <Menu.Section label=\"Product discounts\">\n        <Menu.Item id=\"pct-off-product\">\n          <Text slot=\"label\">\n            Discount the target item(s) relative to its price.\n          </Text>\n          <Text slot=\"description\">Discount type: relative</Text>\n        </Menu.Item>\n        <Menu.Item id=\"amt-off-product\">\n          <Text slot=\"label\">\n            Discount the target item(s) by an absolute amount.\n          </Text>\n          <Text slot=\"description\">Discount type: absolute</Text>\n        </Menu.Item>\n      </Menu.Section>\n      <Separator />\n      <Menu.Section label=\"Cart discounts with line items\">\n        <Menu.Item id=\"pct-off-cart\">\n          <Text slot=\"label\">\n            Discount the target item(s) relative to its price.\n          </Text>\n          <Text slot=\"description\">Discount type: relative</Text>\n        </Menu.Item>\n        <Menu.Item id=\"amt-off-cart\">\n          <Text slot=\"label\">\n            Discount the target item(s) by an absolute amount.\n          </Text>\n          <Text slot=\"description\">Discount type: absolute</Text>\n        </Menu.Item>\n        <Menu.Item id=\"buy-x-get-x\">\n          <Text slot=\"label\">\n            A relative (% off) discount is applied when the shopper buys a\n            specified quantity of an item.\n          </Text>\n          <Text slot=\"description\">Discount type: multi-buy</Text>\n        </Menu.Item>\n        <Menu.Item id=\"fixed-price\">\n          <Text slot=\"label\">\n            Discount the target item(s) by setting a fixed price.\n          </Text>\n          <Text slot=\"description\">Discount type: fixed-price</Text>\n        </Menu.Item>\n        <Menu.Item id=\"shipping\">\n          <Text slot=\"label\">\n            Discount the cart's shipping cost for the customer.\n          </Text>\n          <Text slot=\"description\">Discount type: shipping</Text>\n        </Menu.Item>\n        <Menu.Item id=\"gift\">\n          <Text slot=\"label\">\n            Discount adds a free line item(s) to the cart when the specified\n            conditions are met.\n          </Text>\n          <Text slot=\"description\">Discount type: gift line item</Text>\n        </Menu.Item>\n        <Menu.Item id=\"amt-total\">\n          <Text slot=\"label\">\n            Discount an absolute amount based on cart total.\n          </Text>\n          <Text slot=\"description\">Discount type: absolute</Text>\n        </Menu.Item>\n        <Menu.Item id=\"pct-total\">\n          <Text slot=\"label\">\n            Discount an amount relative to the cart total.\n          </Text>\n          <Text slot=\"description\">Discount type: relative</Text>\n        </Menu.Item>\n      </Menu.Section>\n      <Separator />\n      <Menu.Section label=\"Cart discounts with custom line items\">\n        <Menu.Item id=\"custom-pct-off\">\n          <Text slot=\"label\">\n            Discount the target custom line item(s) relative to its price.\n          </Text>\n          <Text slot=\"description\">Discount type: relative</Text>\n        </Menu.Item>\n        <Menu.Item id=\"custom-amt-off\">\n          <Text slot=\"label\">\n            Discount the target custom line item(s) by an absolute amount.\n          </Text>\n          <Text slot=\"description\">Discount type: absolute</Text>\n        </Menu.Item>\n        <Menu.Item id=\"custom-buy-x\">\n          <Text slot=\"label\">\n            A relative (% off) discount is applied when the shopper buys a\n            specified quantity of an item defined as a custom line item.\n          </Text>\n          <Text slot=\"description\">Discount type: multibuy</Text>\n        </Menu.Item>\n      </Menu.Section>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n### Organize dropdown content when possible\n\nUse grouping structures if all items in a list can be grouped for a better user\nexperience. By default, organize by alphabetical order.\n\n> [!TIP]\\\n> **Do**\n>\n> - Use labels within popover/drop downs to organize content.\n> - If actions lists become bulky and hard to scan, consider another experience\n>   for the user.\n\n```jsx live\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger asChild>\n      <Button variant=\"outline\" colorPalette=\"neutral\">\n        Actions\n        <Icons.KeyboardArrowDown />\n      </Button>\n    </Menu.Trigger>\n    <Menu.Content>\n      <Menu.Section label=\"Common actions\">\n        <Menu.Item id=\"publish\">Publish</Menu.Item>\n        <Menu.Item id=\"unpublish\">Unpublish</Menu.Item>\n        <Menu.Item id=\"delete\">Delete</Menu.Item>\n      </Menu.Section>\n      <Separator />\n      <Menu.Section label=\"Import\">\n        <Menu.Item id=\"import-csv\">Import via CSV</Menu.Item>\n        <Menu.Item id=\"bulk-unpublish\">Bulk unpublish via CSV</Menu.Item>\n        <Menu.Item id=\"bulk-delete\">Bulk delete via CSV</Menu.Item>\n        <Menu.Item id=\"import-inventories\">Import inventories</Menu.Item>\n      </Menu.Section>\n      <Separator />\n      <Menu.Section label=\"Export\">\n        <Menu.Item id=\"export-products\">Export products</Menu.Item>\n        <Menu.Item id=\"export-inventories\">Export Inventories</Menu.Item>\n      </Menu.Section>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n\n> [!CAUTION]\\\n> **Don't**\n>\n> - Don't bury frequently used actions within a dropdown or menu; instead,\n>   prioritize them at the top and group related actions together to facilitate\n>   quick user selection.\n\n```jsx live\nconst App = () => (\n  <Menu.Root>\n    <Menu.Trigger asChild>\n      <Button variant=\"outline\" colorPalette=\"neutral\">\n        Actions\n        <Icons.KeyboardArrowDown />\n      </Button>\n    </Menu.Trigger>\n    <Menu.Content>\n      <Menu.Item id=\"bulk-delete\">Bulk delete via CSV</Menu.Item>\n      <Menu.Item id=\"bulk-unpublish\">Bulk unpublish via CSV</Menu.Item>\n      <Menu.Item id=\"delete\">Delete</Menu.Item>\n      <Menu.Item id=\"export-inventories\">Export Inventories</Menu.Item>\n      <Menu.Item id=\"export-products\">Export products</Menu.Item>\n      <Menu.Item id=\"import-inventories\">Import inventories</Menu.Item>\n      <Menu.Item id=\"import-csv\">Import via CSV</Menu.Item>\n      <Menu.Item id=\"publish\">Publish</Menu.Item>\n      <Menu.Item id=\"unpublish\">Unpublish</Menu.Item>\n    </Menu.Content>\n  </Menu.Root>\n);\n```\n",
+      "toc": [
+        {
+          "value": "Guidelines",
+          "href": "#guidelines",
+          "depth": 2,
+          "numbering": [
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Best practices",
+          "href": "#best-practices",
+          "depth": 3,
+          "numbering": [
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Common popover content",
+          "href": "#common-popover-content",
+          "depth": 4,
+          "numbering": [
+            1,
+            1,
+            1,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Usage",
+          "href": "#usage",
+          "depth": 2,
+          "numbering": [
+            1,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Solid-styled widths",
+          "href": "#solid-styled-widths",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            1
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Icons within action lists",
+          "href": "#icons-within-action-lists",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            2
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Keep menu items concise",
+          "href": "#keep-menu-items-concise",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            3
+          ],
+          "parent": "root"
+        },
+        {
+          "value": "Organize dropdown content when possible",
+          "href": "#organize-dropdown-content-when-possible",
+          "depth": 3,
+          "numbering": [
+            1,
+            2,
+            4
+          ],
+          "parent": "root"
+        }
+      ]
+    }
+  }
+}