@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,483 @@
+# ContextMenu
+
+An unstyled, accessible context menu component with compound composition for right-click actions.
+
+<DocPrimitiveIntro description="Build fully custom right-click menus with complete control over layout and styling." />
+
+```tsx
+'use client';
+import { ChevronRight } from '@primeicons/react/chevron-right';
+import { Clipboard } from '@primeicons/react/clipboard';
+import { Copy } from '@primeicons/react/copy';
+import { ExternalLink } from '@primeicons/react/external-link';
+import { Folder } from '@primeicons/react/folder';
+import { PenToSquare } from '@primeicons/react/pen-to-square';
+import { Refresh } from '@primeicons/react/refresh';
+import { Search } from '@primeicons/react/search';
+import { Trash } from '@primeicons/react/trash';
+import { ContextMenu } from 'primereact/contextmenu';
+import styles from './basic-demo.module.css';
+
+export default function BasicDemo() {
+    return (
+        <div className={styles.container}>
+            <ContextMenu.Root>
+                <ContextMenu.Trigger className={styles.trigger}>Right Click Here</ContextMenu.Trigger>
+                <ContextMenu.Portal>
+                    <ContextMenu.Positioner>
+                        <ContextMenu.Popup className={styles.popup}>
+                            <ContextMenu.List className={styles.list}>
+                                <ContextMenu.Item className={styles.item}>
+                                    <Copy className={styles.icon} />
+                                    Copy
+                                </ContextMenu.Item>
+                                <ContextMenu.Item className={styles.item}>
+                                    <Clipboard className={styles.icon} />
+                                    Paste
+                                </ContextMenu.Item>
+
+                                <ContextMenu.Separator className={styles.separator} />
+
+                                <ContextMenu.Submenu>
+                                    <ContextMenu.SubmenuTrigger className={styles.subtrigger}>
+                                        <Folder className={styles.icon} />
+                                        View
+                                        <ContextMenu.SubmenuIndicator className={styles.indicator}>
+                                            <ChevronRight />
+                                        </ContextMenu.SubmenuIndicator>
+                                    </ContextMenu.SubmenuTrigger>
+                                    <ContextMenu.Portal>
+                                        <ContextMenu.Positioner>
+                                            <ContextMenu.Popup className={styles.popup}>
+                                                <ContextMenu.List className={styles.list}>
+                                                    <ContextMenu.Item className={styles.item}>
+                                                        <Search className={styles.icon} />
+                                                        Zoom In
+                                                    </ContextMenu.Item>
+                                                    <ContextMenu.Item className={styles.item}>
+                                                        <Search className={styles.icon} />
+                                                        Zoom Out
+                                                    </ContextMenu.Item>
+                                                    <ContextMenu.Item className={styles.item}>
+                                                        <Refresh className={styles.icon} />
+                                                        Reload
+                                                    </ContextMenu.Item>
+                                                </ContextMenu.List>
+                                            </ContextMenu.Popup>
+                                        </ContextMenu.Positioner>
+                                    </ContextMenu.Portal>
+                                </ContextMenu.Submenu>
+
+                                <ContextMenu.Separator className={styles.separator} />
+
+                                <ContextMenu.Item className={styles.item}>
+                                    <PenToSquare className={styles.icon} />
+                                    Rename
+                                </ContextMenu.Item>
+                                <ContextMenu.Item className={styles.item}>
+                                    <ExternalLink className={styles.icon} />
+                                    Open Link
+                                </ContextMenu.Item>
+
+                                <ContextMenu.Separator className={styles.separator} />
+
+                                <ContextMenu.Item className={styles.itemDanger}>
+                                    <Trash className={styles.icon} />
+                                    Delete
+                                </ContextMenu.Item>
+                            </ContextMenu.List>
+                        </ContextMenu.Popup>
+                    </ContextMenu.Positioner>
+                </ContextMenu.Portal>
+            </ContextMenu.Root>
+        </div>
+    );
+}
+```
+
+<DocPrimitiveLinks name="ContextMenu" />
+
+## Features
+
+- Compound component API with sub-components: `Root`, `Trigger`, `Portal`, `Positioner`, `Popup`, `Arrow`, `List`, `Item`, `Sub`, `SubTrigger`, `SubPortal`, `SubPositioner`, `SubPopup`, `Indicator`, `Label`, `Separator`, `RadioGroup`
+- Right-click activation with automatic cursor-based popup positioning
+- Global mode to attach context menu to the entire document
+- Nested submenus with open/close coordination
+- Checkbox and radio item types with indicator matching
+- Built-in character search to jump to items by typing
+
+## Usage
+
+```tsx
+import { ContextMenu } from 'primereact/contextmenu';
+```
+
+```tsx
+<ContextMenu.Root>
+    <ContextMenu.Trigger></ContextMenu.Trigger>
+    <ContextMenu.Portal>
+        <ContextMenu.Positioner>
+            <ContextMenu.Popup>
+                <ContextMenu.Arrow />
+                <ContextMenu.List>
+                    <ContextMenu.Label></ContextMenu.Label>
+                    <ContextMenu.Item></ContextMenu.Item>
+                    <ContextMenu.Separator />
+                    <ContextMenu.Submenu>
+                        <ContextMenu.SubmenuTrigger>
+                            <ContextMenu.Indicator />
+                        </ContextMenu.SubmenuTrigger>
+                        <ContextMenu.SubmenuPortal>
+                            <ContextMenu.SubmenuPositioner>
+                                <ContextMenu.SubmenuPopup>
+                                    <ContextMenu.List>
+                                        <ContextMenu.Item></ContextMenu.Item>
+                                    </ContextMenu.List>
+                                </ContextMenu.SubmenuPopup>
+                            </ContextMenu.SubmenuPositioner>
+                        </ContextMenu.SubmenuPortal>
+                    </ContextMenu.Submenu>
+                </ContextMenu.List>
+            </ContextMenu.Popup>
+        </ContextMenu.Positioner>
+    </ContextMenu.Portal>
+</ContextMenu.Root>
+```
+
+## Behavior
+
+### Checkbox Items
+
+Set `type="checkbox"` on `ContextMenu.Item` to create a toggleable item. Use `ContextMenu.Indicator` with `match="checked"` to display a checkmark when the item is active.
+
+```tsx
+<ContextMenu.Item type="checkbox" defaultChecked={true}>
+    <ContextMenu.Indicator match="checked">
+        <Check />
+    </ContextMenu.Indicator>
+    Enable Notifications
+</ContextMenu.Item>
+```
+
+### Radio Items
+
+Wrap `ContextMenu.Item` elements with `type="radio"` inside a `ContextMenu.RadioGroup`. Use `ContextMenu.Indicator` with `match="checked"` to display a dot or icon for the selected option.
+
+```tsx
+<ContextMenu.RadioGroup defaultValue="light">
+    <ContextMenu.Item type="radio" value="light">
+        <ContextMenu.Indicator match="checked">
+            <Dot />
+        </ContextMenu.Indicator>
+        Light Mode
+    </ContextMenu.Item>
+    <ContextMenu.Item type="radio" value="dark">
+        <ContextMenu.Indicator match="checked">
+            <Dot />
+        </ContextMenu.Indicator>
+        Dark Mode
+    </ContextMenu.Item>
+</ContextMenu.RadioGroup>
+```
+
+### Motion Animation
+
+```tsx
+<ContextMenu.Popup motionProps={{ name: 'p-anchored-overlay' }}></ContextMenu.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
+<ContextMenu.Item as="a" href="/dashboard">
+    Dashboard
+</ContextMenu.Item>
+```
+
+Default elements: `Root`=`div`, `Trigger`=`div`, `List`=`ul`, `Item`=`li`, `Sub`=`li`, `SubTrigger`=`div`, `SubPositioner`=`div`, `SubPopup`=`div`, `Label`=`li`, `Separator`=`li`, `Indicator`=`span`, `Popup`=`div`, `Positioner`=`div`, `Arrow`=`div`, `RadioGroup`=`div`, `Portal`=portal, `SubPortal`=portal.
+
+### Render Function Children
+
+`Item` and `SubTrigger` accept a render function as children, providing access to the component instance.
+
+```tsx
+<ContextMenu.Item>{(instance) => <span>{instance.focused ? 'Focused' : 'Idle'}</span>}</ContextMenu.Item>
+```
+
+## Pass Through
+
+<DocPTViewer name="contextmenu-pt" components={['ContextMenuRoot']} />
+
+## API
+
+### ContextMenuRoot
+
+<DocTable name="ContextMenuRoot" category="api" />
+
+| Attribute    | Value           |
+| ------------ | --------------- |
+| `data-scope` | `"contextmenu"` |
+| `data-part`  | `"root"`        |
+
+<DocTable name="ContextMenuRoot" category="pt" />
+
+### ContextMenuTrigger
+
+<DocTable name="ContextMenuTrigger" category="api" />
+
+| Attribute    | Value           |
+| ------------ | --------------- |
+| `data-scope` | `"contextmenu"` |
+| `data-part`  | `"trigger"`     |
+
+<DocTable name="ContextMenuTrigger" category="pt" />
+
+### ContextMenuList
+
+<DocTable name="ContextMenuList" category="api" />
+
+| Attribute    | Value           |
+| ------------ | --------------- |
+| `data-scope` | `"contextmenu"` |
+| `data-part`  | `"list"`        |
+
+<DocTable name="ContextMenuList" category="pt" />
+
+### ContextMenuItem
+
+<DocTable name="ContextMenuItem" category="api" />
+
+| Attribute       | Value                         |
+| --------------- | ----------------------------- |
+| `data-scope`    | `"contextmenu"`               |
+| `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="ContextMenuItem" category="pt" />
+
+### ContextMenuSubmenu
+
+<DocTable name="ContextMenuSubmenu" category="api" />
+
+| Attribute    | Value                        |
+| ------------ | ---------------------------- |
+| `data-scope` | `"contextmenu"`              |
+| `data-part`  | `"sub"`                      |
+| `data-open`  | Present when submenu is open |
+
+<DocTable name="ContextMenuSubmenu" category="pt" />
+
+### ContextMenuSubmenuTrigger
+
+<DocTable name="ContextMenuSubmenuTrigger" category="api" />
+
+| Attribute       | Value                               |
+| --------------- | ----------------------------------- |
+| `data-scope`    | `"contextmenu"`                     |
+| `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="ContextMenuSubmenuTrigger" category="pt" />
+
+### ContextMenuSubmenuPositioner
+
+<DocTable name="ContextMenuSubmenuPositioner" category="api" />
+
+| Attribute    | Value             |
+| ------------ | ----------------- |
+| `data-scope` | `"contextmenu"`   |
+| `data-part`  | `"subpositioner"` |
+
+**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="ContextMenuSubmenuPositioner" category="pt" />
+
+### ContextMenuSubmenuPortal
+
+<DocTable name="ContextMenuSubmenuPortal" category="api" />
+
+<DocTable name="ContextMenuSubmenuPortal" category="pt" />
+
+### ContextMenuSubmenuPopup
+
+<DocTable name="ContextMenuSubmenuPopup" category="api" />
+
+| Attribute    | Value           |
+| ------------ | --------------- |
+| `data-scope` | `"contextmenu"` |
+| `data-part`  | `"subpopup"`    |
+
+<DocTable name="ContextMenuSubmenuPopup" category="pt" />
+
+### ContextMenuIndicator
+
+<DocTable name="ContextMenuIndicator" category="api" />
+
+| Attribute        | Value                          |
+| ---------------- | ------------------------------ |
+| `data-scope`     | `"contextmenu"`                |
+| `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="ContextMenuIndicator" category="pt" />
+
+### ContextMenuLabel
+
+<DocTable name="ContextMenuLabel" category="api" />
+
+| Attribute    | Value           |
+| ------------ | --------------- |
+| `data-scope` | `"contextmenu"` |
+| `data-part`  | `"label"`       |
+
+<DocTable name="ContextMenuLabel" category="pt" />
+
+### ContextMenuSeparator
+
+<DocTable name="ContextMenuSeparator" category="api" />
+
+| Attribute    | Value           |
+| ------------ | --------------- |
+| `data-scope` | `"contextmenu"` |
+| `data-part`  | `"separator"`   |
+
+<DocTable name="ContextMenuSeparator" category="pt" />
+
+### ContextMenuRadioGroup
+
+<DocTable name="ContextMenuRadioGroup" category="api" />
+
+| Attribute    | Value           |
+| ------------ | --------------- |
+| `data-scope` | `"contextmenu"` |
+| `data-part`  | `"radiogroup"`  |
+
+<DocTable name="ContextMenuRadioGroup" category="pt" />
+
+### ContextMenuPopup
+
+<DocTable name="ContextMenuPopup" category="api" />
+
+| Attribute    | Value           |
+| ------------ | --------------- |
+| `data-scope` | `"contextmenu"` |
+| `data-part`  | `"popup"`       |
+
+<DocTable name="ContextMenuPopup" category="pt" />
+
+### ContextMenuPositioner
+
+<DocTable name="ContextMenuPositioner" category="api" />
+
+| Attribute    | Value           |
+| ------------ | --------------- |
+| `data-scope` | `"contextmenu"` |
+| `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="ContextMenuPositioner" category="pt" />
+
+### ContextMenuArrow
+
+<DocTable name="ContextMenuArrow" category="api" />
+
+| Attribute    | Value           |
+| ------------ | --------------- |
+| `data-scope` | `"contextmenu"` |
+| `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="ContextMenuArrow" category="pt" />
+
+### ContextMenuPortal
+
+<DocTable name="ContextMenuPortal" category="api" />
+
+<DocTable name="ContextMenuPortal" category="pt" />
+
+### ContextMenuCheckboxItem
+
+<DocTable name="ContextMenuCheckboxItem" category="pt" />
+
+### ContextMenuRadioItem
+
+<DocTable name="ContextMenuRadioItem" category="pt" />
+
+### ContextMenuIcon
+
+<DocTable name="ContextMenuIcon" category="pt" />
+
+### ContextMenuCheckboxIcon
+
+<DocTable name="ContextMenuCheckboxIcon" category="pt" />
+
+### ContextMenuRadioIcon
+
+<DocTable name="ContextMenuRadioIcon" category="pt" />
+
+## Accessibility
+
+### Screen Reader
+
+ContextMenu 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.
+
+The component implicitly manages the `aria-expanded`, `aria-haspopup` and `aria-controls` attributes of the trigger element to define the relation between the trigger 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. Popup closes and focus moves to target.                                                                                                  |
+| `space`          | Activates the focused menuitem. Popup closes and focus moves to target.                                                                                                  |
+| `escape`         | Closes the popup 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` | Closes the popup and focus moves to the target.                                                                                                                          |
+| `home`           | Moves focus to the first menuitem.                                                                                                                                       |
+| `end`            | Moves focus to the last menuitem.                                                                                                                                        |