@primereact/mcp 11.0.0-rc.2

package/data/llms/primitive/components/menu.md

@@ -0,0 +1,479 @@
+# Menu
+
+An unstyled, accessible menu component with compound composition for inline and popup navigation.
+
+<DocPrimitiveIntro description="Build fully custom navigation menus with complete control over layout and styling." />
+
+```tsx
+'use client';
+import { Check } from '@primeicons/react/check';
+import { Cog } from '@primeicons/react/cog';
+import { CreditCard } from '@primeicons/react/credit-card';
+import { Dot } from '@primeicons/react/dot';
+import { User } from '@primeicons/react/user';
+import { Menu } from 'primereact/menu';
+import type { MenuCheckboxItemCheckedChangeEvent, MenuRadioItemGroupValueChangeEvent } from 'primereact/menu';
+import * as React from 'react';
+import styles from './basic-demo.module.css';
+
+export default function BasicDemo() {
+    const [notifications, setNotifications] = React.useState(true);
+    const [sound, setSound] = React.useState(false);
+    const [theme, setTheme] = React.useState('light');
+
+    return (
+        <div className={styles.container}>
+            <Menu.Root>
+                <Menu.Trigger className={styles.trigger}>Account</Menu.Trigger>
+                <Menu.Portal>
+                    <Menu.Positioner sideOffset={4}>
+                        <Menu.Popup className={styles.popup}>
+                            <Menu.List className={styles.list}>
+                                <Menu.Group>
+                                    <Menu.Label className={styles.label}>My Account</Menu.Label>
+                                    <Menu.Item className={styles.item}>
+                                        <User className={styles.icon} />
+                                        Profile
+                                    </Menu.Item>
+                                    <Menu.Item className={styles.item}>
+                                        <CreditCard className={styles.icon} />
+                                        Billing
+                                    </Menu.Item>
+                                    <Menu.Item className={styles.item}>
+                                        <Cog className={styles.icon} />
+                                        Settings
+                                    </Menu.Item>
+                                </Menu.Group>
+
+                                <Menu.Separator className={styles.separator} />
+
+                                <Menu.Group>
+                                    <Menu.Label className={styles.label}>Notifications</Menu.Label>
+                                    <Menu.CheckboxItem
+                                        className={styles.item}
+                                        checked={notifications}
+                                        onCheckedChange={(e: MenuCheckboxItemCheckedChangeEvent) => setNotifications(e.checked)}
+                                    >
+                                        <Menu.CheckboxItemIndicator className={styles.indicator}>
+                                            <Check />
+                                        </Menu.CheckboxItemIndicator>
+                                        Enable notifications
+                                    </Menu.CheckboxItem>
+                                    <Menu.CheckboxItem
+                                        className={styles.item}
+                                        checked={sound}
+                                        onCheckedChange={(e: MenuCheckboxItemCheckedChangeEvent) => setSound(e.checked)}
+                                    >
+                                        <Menu.CheckboxItemIndicator className={styles.indicator}>
+                                            <Check />
+                                        </Menu.CheckboxItemIndicator>
+                                        Play sound
+                                    </Menu.CheckboxItem>
+                                </Menu.Group>
+
+                                <Menu.Separator className={styles.separator} />
+
+                                <Menu.Group>
+                                    <Menu.Label className={styles.label}>Appearance</Menu.Label>
+                                    <Menu.RadioItemGroup
+                                        value={theme}
+                                        onValueChange={(e: MenuRadioItemGroupValueChangeEvent) => setTheme(e.value as string)}
+                                    >
+                                        <Menu.RadioItem className={styles.item} value="light">
+                                            <Menu.RadioItemIndicator className={styles.indicator}>
+                                                <Dot />
+                                            </Menu.RadioItemIndicator>
+                                            Light
+                                        </Menu.RadioItem>
+                                        <Menu.RadioItem className={styles.item} value="dark">
+                                            <Menu.RadioItemIndicator className={styles.indicator}>
+                                                <Dot />
+                                            </Menu.RadioItemIndicator>
+                                            Dark
+                                        </Menu.RadioItem>
+                                        <Menu.RadioItem className={styles.item} value="system">
+                                            <Menu.RadioItemIndicator className={styles.indicator}>
+                                                <Dot />
+                                            </Menu.RadioItemIndicator>
+                                            System
+                                        </Menu.RadioItem>
+                                    </Menu.RadioItemGroup>
+                                </Menu.Group>
+                            </Menu.List>
+                        </Menu.Popup>
+                    </Menu.Positioner>
+                </Menu.Portal>
+            </Menu.Root>
+        </div>
+    );
+}
+```
+
+<DocPrimitiveLinks name="Menu" />
+
+## Features
+
+- Compound component API with sub-components: `Root`, `List`, `Item`, `CheckboxItem`, `RadioItemGroup`, `RadioItem`, `Sub`, `SubTrigger`, `Indicator`, `Label`, `Separator`, `Trigger`, `Portal`, `Positioner`, `Popup`, `Arrow`. Submenus reuse `Portal`/`Positioner`/`Popup` inside `Menu.Submenu`; the same components automatically detect the sub context.
+- Inline and portal-based popup rendering modes
+- Nested submenus with open/close coordination
+- Checkbox and radio item types with indicator matching
+- Built-in character search to jump to items by typing
+- Composite mode for complex nested menus with hover-to-open behavior
+
+## Usage
+
+```tsx
+import { Menu } from 'primereact/menu';
+```
+
+```tsx
+<Menu.Root>
+    <Menu.Trigger />
+    <Menu.Portal>
+        <Menu.Positioner>
+            <Menu.Popup>
+                <Menu.List>
+                    <Menu.Item />
+                    <Menu.Submenu>
+                        <Menu.SubmenuTrigger>
+                            <Menu.Indicator />
+                        </Menu.SubmenuTrigger>
+                        <Menu.Portal>
+                            <Menu.Positioner>
+                                <Menu.Popup>
+                                    <Menu.List>
+                                        <Menu.Item />
+                                        <Menu.Item />
+                                    </Menu.List>
+                                </Menu.Popup>
+                            </Menu.Positioner>
+                        </Menu.Portal>
+                    </Menu.Submenu>
+                </Menu.List>
+            </Menu.Popup>
+        </Menu.Positioner>
+    </Menu.Portal>
+</Menu.Root>
+```
+
+## Behavior
+
+### Checkbox Items
+
+Use `Menu.CheckboxItem` to create a toggleable item managed by `useCheckbox`. Use `Menu.Indicator` with `match="checked"` to display a checkmark when the item is active.
+
+```tsx
+<Menu.CheckboxItem defaultChecked={true}>
+    <Menu.Indicator match="checked">
+        <Check />
+    </Menu.Indicator>
+    Enable Notifications
+</Menu.CheckboxItem>
+```
+
+### Radio Items
+
+Wrap `Menu.RadioItem` elements inside a `Menu.RadioItemGroup`. The group is managed by `useRadioButtonGroup` and each item by `useRadioButton`. Use `Menu.Indicator` with `match="checked"` to display a dot or icon for the selected option.
+
+```tsx
+<Menu.RadioItemGroup defaultValue="light">
+    <Menu.RadioItem value="light">
+        <Menu.Indicator match="checked">
+            <Dot />
+        </Menu.Indicator>
+        Light Mode
+    </Menu.RadioItem>
+    <Menu.RadioItem value="dark">
+        <Menu.Indicator match="checked">
+            <Dot />
+        </Menu.Indicator>
+        Dark Mode
+    </Menu.RadioItem>
+</Menu.RadioItemGroup>
+```
+
+### Motion Animation
+
+```tsx
+<Menu.Popup motionProps={{ name: 'p-popover' }}></Menu.Popup>
+```
+
+See [Motion](/docs/primitive/components/motion) for animation phases, CSS variables, and hide strategies.
+
+### Polymorphic Rendering
+
+Use `as` on any sub-component to change the rendered HTML element.
+
+```tsx
+<Menu.Item as="a" href="/dashboard">
+    Dashboard
+</Menu.Item>
+```
+
+Default elements: `Root`=`div`, `List`=`ul`, `Item`=`li`, `CheckboxItem`=`li`, `RadioItem`=`li`, `Sub`=`li`, `SubTrigger`=`div`, `Trigger`=`button`, `Label`=`li`, `Separator`=`li`, `Indicator`=`span`, `Popup`=`div`, `Positioner`=`div`, `Arrow`=`div`, `RadioItemGroup`=`div`, `Portal`=portal.
+
+### Render Function Children
+
+`Item` and `SubTrigger` accept a render function as children, providing access to the component instance.
+
+```tsx
+<Menu.Item>{(instance) => <span>{instance.focused ? 'Focused' : 'Idle'}</span>}</Menu.Item>
+```
+
+## Pass Through
+
+<DocPTViewer name="menu-pt" components={['MenuRoot']} />
+
+## API
+
+### MenuRoot
+
+<DocTable name="MenuRoot" category="api" />
+
+| Attribute    | Value    |
+| ------------ | -------- |
+| `data-scope` | `"menu"` |
+| `data-part`  | `"root"` |
+
+<DocTable name="MenuRoot" category="pt" />
+
+### MenuTrigger
+
+<DocTable name="MenuTrigger" category="api" />
+
+| Attribute    | Value                     |
+| ------------ | ------------------------- |
+| `data-scope` | `"menu"`                  |
+| `data-part`  | `"trigger"`               |
+| `data-open`  | Present when menu is open |
+
+<DocTable name="MenuTrigger" category="pt" />
+
+### MenuList
+
+<DocTable name="MenuList" category="api" />
+
+| Attribute    | Value    |
+| ------------ | -------- |
+| `data-scope` | `"menu"` |
+| `data-part`  | `"list"` |
+
+<DocTable name="MenuList" category="pt" />
+
+### MenuItem
+
+<DocTable name="MenuItem" category="api" />
+
+| Attribute       | Value                         |
+| --------------- | ----------------------------- |
+| `data-scope`    | `"menu"`                      |
+| `data-part`     | `"item"`                      |
+| `data-value`    | The item value                |
+| `data-focused`  | Present when item is focused  |
+| `data-disabled` | Present when item is disabled |
+| `data-checked`  | Present when item is checked  |
+
+<DocTable name="MenuItem" category="pt" />
+
+### MenuSubmenu
+
+<DocTable name="MenuSubmenu" category="api" />
+
+| Attribute    | Value                        |
+| ------------ | ---------------------------- |
+| `data-scope` | `"menu"`                     |
+| `data-part`  | `"sub"`                      |
+| `data-open`  | Present when submenu is open |
+
+<DocTable name="MenuSubmenu" category="pt" />
+
+### MenuSubmenuTrigger
+
+<DocTable name="MenuSubmenuTrigger" category="api" />
+
+| Attribute       | Value                               |
+| --------------- | ----------------------------------- |
+| `data-scope`    | `"menu"`                            |
+| `data-part`     | `"subtrigger"`                      |
+| `data-value`    | The subtrigger value                |
+| `data-focused`  | Present when subtrigger is focused  |
+| `data-disabled` | Present when subtrigger is disabled |
+| `data-open`     | Present when submenu is open        |
+
+<DocTable name="MenuSubmenuTrigger" category="pt" />
+
+### MenuIndicator
+
+<DocTable name="MenuIndicator" category="api" />
+
+| Attribute        | Value                          |
+| ---------------- | ------------------------------ |
+| `data-scope`     | `"menu"`                       |
+| `data-part`      | `"indicator"`                  |
+| `data-open`      | Present when submenu is open   |
+| `data-closed`    | Present when submenu is closed |
+| `data-checked`   | Present when item is checked   |
+| `data-unchecked` | Present when item is unchecked |
+
+<DocTable name="MenuIndicator" category="pt" />
+
+### MenuLabel
+
+<DocTable name="MenuLabel" category="api" />
+
+| Attribute    | Value     |
+| ------------ | --------- |
+| `data-scope` | `"menu"`  |
+| `data-part`  | `"label"` |
+
+<DocTable name="MenuLabel" category="pt" />
+
+### MenuSeparator
+
+<DocTable name="MenuSeparator" category="api" />
+
+| Attribute    | Value         |
+| ------------ | ------------- |
+| `data-scope` | `"menu"`      |
+| `data-part`  | `"separator"` |
+
+<DocTable name="MenuSeparator" category="pt" />
+
+### MenuCheckboxItem
+
+<DocTable name="MenuCheckboxItem" category="api" />
+
+| Attribute    | Value    |
+| ------------ | -------- |
+| `data-scope` | `"menu"` |
+| `data-part`  | `"item"` |
+
+<DocTable name="MenuCheckboxItem" category="pt" />
+
+### MenuRadioItemGroup
+
+<DocTable name="MenuRadioItemGroup" category="api" />
+
+| Attribute    | Value          |
+| ------------ | -------------- |
+| `data-scope` | `"menu"`       |
+| `data-part`  | `"radiogroup"` |
+
+<DocTable name="MenuRadioItemGroup" category="pt" />
+
+### MenuRadioItem
+
+<DocTable name="MenuRadioItem" category="api" />
+
+| Attribute    | Value    |
+| ------------ | -------- |
+| `data-scope` | `"menu"` |
+| `data-part`  | `"item"` |
+
+<DocTable name="MenuRadioItem" category="pt" />
+
+### MenuPopup
+
+<DocTable name="MenuPopup" category="api" />
+
+| Attribute    | Value     |
+| ------------ | --------- |
+| `data-scope` | `"menu"`  |
+| `data-part`  | `"popup"` |
+
+<DocTable name="MenuPopup" category="pt" />
+
+### MenuPositioner
+
+<DocTable name="MenuPositioner" category="api" />
+
+| Attribute    | Value          |
+| ------------ | -------------- |
+| `data-scope` | `"menu"`       |
+| `data-part`  | `"positioner"` |
+
+**CSS Custom Properties**
+
+The positioner element exposes CSS custom properties for layout and transform control.
+
+| CSS Variable                | Description                              |
+| --------------------------- | ---------------------------------------- |
+| `--available-height`        | Available vertical space in pixels       |
+| `--available-width`         | Available horizontal space in pixels     |
+| `--transform-origin`        | Computed transform origin for animations |
+| `--positioner-anchor-width` | Width of the anchor/trigger element      |
+
+<DocTable name="MenuPositioner" category="pt" />
+
+### MenuArrow
+
+<DocTable name="MenuArrow" category="api" />
+
+| Attribute    | Value     |
+| ------------ | --------- |
+| `data-scope` | `"menu"`  |
+| `data-part`  | `"arrow"` |
+
+**CSS Custom Properties**
+
+The arrow element exposes CSS custom properties for dynamic positioning:
+
+| CSS Variable          | Description                    |
+| --------------------- | ------------------------------ |
+| `--placer-arrow-x`    | Horizontal offset of arrow     |
+| `--placer-arrow-y`    | Vertical offset of arrow       |
+| `--placer-arrow-left` | Left position of arrow element |
+| `--placer-arrow-top`  | Top position of arrow element  |
+
+<DocTable name="MenuArrow" category="pt" />
+
+### MenuPortal
+
+<DocTable name="MenuPortal" category="api" />
+
+<DocTable name="MenuPortal" category="pt" />
+
+### MenuCheckboxItem
+
+<DocTable name="MenuCheckboxItem" category="pt" />
+
+### MenuRadioItem
+
+<DocTable name="MenuRadioItem" category="pt" />
+
+### MenuIcon
+
+<DocTable name="MenuIcon" category="pt" />
+
+### MenuCheckboxIcon
+
+<DocTable name="MenuCheckboxIcon" category="pt" />
+
+### MenuRadioIcon
+
+<DocTable name="MenuRadioIcon" category="pt" />
+
+## Accessibility
+
+### Screen Reader
+
+Menu component uses the `menu` role and the value to describe the menu can either be provided with `aria-labelledby` or `aria-label` props. Each list item has a `menuitem` role with `aria-label` referring to the label of the item and `aria-disabled` defined if the item is disabled. Checkbox items use `menuitemcheckbox` and radio items use `menuitemradio` roles with `aria-checked` to indicate selection state.
+
+In popup mode, the component implicitly manages the `aria-expanded`, `aria-haspopup` and `aria-controls` attributes of the target element to define the relation between the target and the popup.
+
+### Keyboard Support
+
+| Key              | Function                                                                                                                                                                 |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `tab`            | Add focus to the first item if focus moves in to the menu. If the focus is already within the menu, focus moves to the next focusable item in the page tab sequence.     |
+| `shift + tab`    | Add focus to the first item if focus moves in to the menu. If the focus is already within the menu, focus moves to the previous focusable item in the page tab sequence. |
+| `enter`          | Activates the focused menuitem. If menu is in overlay mode, popup gets closes and focus moves to target.                                                                 |
+| `space`          | Activates the focused menuitem. If menu is in overlay mode, popup gets closes and focus moves to target.                                                                 |
+| `escape`         | If menu is in overlay mode, popup gets closes and focus moves to target.                                                                                                 |
+| `down arrow`     | Moves focus to the next menuitem.                                                                                                                                        |
+| `up arrow`       | Moves focus to the previous menuitem.                                                                                                                                    |
+| `right arrow`    | Opens submenu if focused item has one. Moves focus to the first item of the submenu.                                                                                     |
+| `left arrow`     | Closes current submenu and moves focus to parent submenu trigger.                                                                                                        |
+| `alt + up arrow` | If menu is in overlay mode, popup gets closes and focus moves to the target.                                                                                             |
+| `home`           | Moves focus to the first menuitem.                                                                                                                                       |
+| `end`            | Moves focus to the last menuitem.                                                                                                                                        |