@primereact/mcp 11.0.0-rc.2

package/data/llms/headless/components/motion.md

@@ -0,0 +1,160 @@
+# useMotion
+
+Hook that manages enter/leave animations with CSS class transitions and visibility control.
+
+## Usage
+
+```tsx
+import { useMotion } from '@primereact/core/motion';
+```
+
+```tsx
+const ref = React.useRef<HTMLDivElement>(undefined);
+const motion = useMotion({
+    elementRef: ref,
+    visible: isOpen,
+    name: 'fade'
+});
+
+return <>{motion.state.rendered && <div ref={ref} {...motion.rootProps}></div>}</>;
+```
+
+`useMotion` runs a CSS class-based enter/leave animation lifecycle against a single element, returning `rootProps` for hidden styles and `state.rendered` for conditional mounting.
+
+## Features
+
+- **CSS class lifecycle**, applies `{name}-enter-from`, `{name}-enter-active`, `{name}-enter-to` on enter and mirrored `-leave-*` classes on leave
+- **Mount management**, `state.rendered` combined with `mountOnEnter` / `unmountOnLeave` keeps the element in the DOM only while needed
+- **Hide strategies**, choose how closed content is hidden: `display: none`, `visibility: hidden`, or let CSS animations handle it entirely
+- **Dimension variables**, `cssVarPrefix` writes `--{prefix}-height` / `--{prefix}-width` on the element for collapsible transitions
+- **Full lifecycle callbacks**, eight hooks covering before/during/after/cancelled for both enter and leave phases
+- **Imperative control**, `enter()`, `leave()`, `cancel()`, and `update()` for programmatic transitions
+
+## Working with callbacks
+
+### Drive animations with a name prefix
+
+Pick a `name` and define six CSS classes against that prefix. The hook applies them in order across the enter and leave phases.
+
+```tsx
+const motion = useMotion({ elementRef: ref, visible, name: 'slide' });
+```
+
+```css
+.slide-enter-from {
+    opacity: 0;
+    transform: translateY(-10px);
+}
+.slide-enter-active {
+    transition: all 200ms ease-out;
+}
+.slide-enter-to {
+    opacity: 1;
+    transform: translateY(0);
+}
+
+.slide-leave-from {
+    opacity: 1;
+    transform: translateY(0);
+}
+.slide-leave-active {
+    transition: all 200ms ease-in;
+}
+.slide-leave-to {
+    opacity: 0;
+    transform: translateY(-10px);
+}
+```
+
+### Collapsible height transitions
+
+Set `cssVarPrefix` so the hook injects scroll-height into a CSS variable you can read from your transitions.
+
+```tsx
+const motion = useMotion({ elementRef: ref, visible, cssVarPrefix: 'panel-content' });
+```
+
+```css
+.collapsible-enter-active,
+.collapsible-leave-active {
+    transition: max-height 300ms ease;
+    overflow: hidden;
+}
+
+.collapsible-enter-to,
+.collapsible-leave-from {
+    max-height: var(--panel-content-height);
+}
+
+.collapsible-enter-from,
+.collapsible-leave-to {
+    max-height: 0;
+}
+```
+
+### Run the enter animation on mount
+
+Enable `appear` so the enter lifecycle plays the first time the element becomes visible, instead of jumping straight to its final state.
+
+```tsx
+const motion = useMotion({ elementRef: ref, visible: true, appear: true, name: 'fade' });
+```
+
+### React to phase transitions
+
+Use the lifecycle callbacks to coordinate side effects, trigger focus moves after enter, release listeners after leave, or clean up inline styles.
+
+```tsx
+const motion = useMotion({
+    elementRef: ref,
+    visible,
+    name: 'fade',
+    onBeforeEnter: (e) => e.el.style.setProperty('will-change', 'opacity'),
+    onAfterEnter: () => inputRef.current?.focus(),
+    onAfterLeave: () => releaseScrollLock()
+});
+```
+
+| Callback           | Phase                          |
+| ------------------ | ------------------------------ |
+| `onBeforeEnter`    | Before enter transition starts |
+| `onEnter`          | Enter transition starts        |
+| `onAfterEnter`     | Enter transition ends          |
+| `onEnterCancelled` | Enter transition cancelled     |
+| `onBeforeLeave`    | Before leave transition starts |
+| `onLeave`          | Leave transition starts        |
+| `onAfterLeave`     | Leave transition ends          |
+| `onLeaveCancelled` | Leave transition cancelled     |
+
+### Imperative control
+
+Call `enter()`, `leave()`, or `cancel()` to drive the animation from outside a visibility prop, and `update()` to reconfigure the instance on an existing element.
+
+```tsx
+const motion = useMotion({ elementRef: ref, visible, name: 'fade' });
+
+motion.enter();
+motion.leave();
+motion.cancel();
+motion.update(element, { name: 'slide', duration: 300 });
+```
+
+### Hide strategy reference
+
+Switch `hideStrategy` to match what your CSS expects. `display` is the default because it removes the element from layout entirely.
+
+| Value          | Behavior                                               |
+| -------------- | ------------------------------------------------------ |
+| `'display'`    | Applies `display: none` (default)                      |
+| `'visibility'` | Applies `visibility: hidden` and `max-height: 0`       |
+| `'none'`       | No automatic hiding, CSS animations handle it entirely |
+
+## API
+
+### useMotion
+
+<DocTable name="useMotion" category="api" />
+
+## Accessibility
+
+No keyboard behavior, a primitive for animation that does not affect accessibility. See [Primitive](/docs/primitive/components/motion#accessibility) for full WAI-ARIA compliance details.

package/data/llms/headless/components/navigationmenu/api.json

@@ -0,0 +1,220 @@
+[
+  {
+    "name": "useNavigationMenu",
+    "source": "apps/showcase/assets/apidoc/usenavigationmenu.json",
+    "data": {
+      "description": "The useNavigationMenu manages the state and functionality of a navigationmenu component.",
+      "interfaces": {
+        "UseNavigationMenuProps": {
+          "description": "Defines valid properties in useNavigationMenu.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "orientation",
+              "type": "NavigationMenuOrientation",
+              "default": "'horizontal'",
+              "description": "The orientation of the navigationmenu.\nDetermines which arrow keys move between triggers."
+            },
+            {
+              "name": "loopFocus",
+              "type": "boolean",
+              "default": "true",
+              "description": "Whether keyboard focus loops back to the first/last item at the end of the list."
+            },
+            {
+              "name": "modal",
+              "type": "boolean",
+              "default": "true",
+              "description": "Whether the navigationmenu is modal. When true, opening one menu prevents page interaction\noutside that menu."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "false",
+              "description": "Whether all menus in the navigationmenu are disabled."
+            }
+          ],
+          "methods": []
+        },
+        "UseNavigationMenuState": {
+          "description": "Defines valid state in useNavigationMenu.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "openMenuId",
+              "type": "string",
+              "default": "",
+              "description": "The id of the currently open menu, or null if none is open."
+            },
+            {
+              "name": "hasOpenMenu",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether any menu in the navigationmenu is currently open."
+            }
+          ],
+          "methods": []
+        },
+        "UseNavigationMenuRootProps": {
+          "description": "Pre-built props for the navigationmenu root element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "role",
+              "type": "\"menubar\"",
+              "default": "",
+              "description": "ARIA role for the navigationmenu element."
+            },
+            {
+              "name": "aria-orientation",
+              "type": "NavigationMenuOrientation",
+              "default": "",
+              "description": "The orientation of the navigationmenu."
+            },
+            {
+              "name": "data-scope",
+              "type": "\"navigationmenu\"",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "\"root\"",
+              "default": "",
+              "description": "Component part identifier."
+            },
+            {
+              "name": "data-orientation",
+              "type": "NavigationMenuOrientation",
+              "default": "",
+              "description": "The orientation of the navigationmenu."
+            },
+            {
+              "name": "data-has-open-menu",
+              "type": "\"\"",
+              "default": "",
+              "description": "Present when any menu in the navigationmenu is open."
+            },
+            {
+              "name": "data-modal",
+              "type": "\"\"",
+              "default": "",
+              "description": "Present when the navigationmenu is modal."
+            },
+            {
+              "name": "data-disabled",
+              "type": "\"\"",
+              "default": "",
+              "description": "Present when the navigationmenu is disabled."
+            }
+          ],
+          "methods": []
+        },
+        "UseNavigationMenuExposes": {
+          "description": "Defines the methods and properties exposed by useNavigationMenu.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseNavigationMenuState",
+              "default": "",
+              "description": "The state of the useNavigationMenu."
+            },
+            {
+              "name": "rootProps",
+              "type": "UseNavigationMenuRootProps",
+              "default": "",
+              "description": "Pre-built props for the navigationmenu root element."
+            },
+            {
+              "name": "registerTrigger",
+              "type": "(menuId: string, element: HTMLElement) => void",
+              "default": "",
+              "description": "Register or unregister a menu trigger element with the navigationmenu.\nPass null as element to unregister."
+            },
+            {
+              "name": "setOpenMenuId",
+              "type": "(menuId: string) => void",
+              "default": "",
+              "description": "Set which menu is currently open. Pass null to close all."
+            },
+            {
+              "name": "isMenuOpen",
+              "type": "(menuId: string) => boolean",
+              "default": "",
+              "description": "Whether the menu with the given id is the currently open one."
+            },
+            {
+              "name": "onTriggerKeyDown",
+              "type": "(menuId: string, event: KeyboardEvent) => void",
+              "default": "",
+              "description": "Handle keyboard event on a trigger. Manages ArrowLeft/Right (horizontal)\nor ArrowUp/Down (vertical), Home, End between sibling triggers."
+            },
+            {
+              "name": "onTriggerMouseEnter",
+              "type": "(menuId: string) => void",
+              "default": "",
+              "description": "Handle mouse enter on a trigger. When a menu is already open,\nhovering another trigger switches to it."
+            },
+            {
+              "name": "onMenuOpenChange",
+              "type": "(menuId: string, open: boolean) => void",
+              "default": "",
+              "description": "Notify the navigationmenu that a menu's open state has changed.\nCalled by child Menu.Root via its onOpenChange."
+            },
+            {
+              "name": "orientation",
+              "type": "NavigationMenuOrientation",
+              "default": "",
+              "description": "The orientation of the navigationmenu (echoed for child consumption)."
+            },
+            {
+              "name": "modal",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the navigationmenu is modal (echoed for child consumption)."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether all menus in the navigationmenu are disabled (echoed for child consumption)."
+            },
+            {
+              "name": "focusSibling",
+              "type": "(currentMenuId: string, direction: \"next\" | \"previous\") => void",
+              "default": "",
+              "description": "Move focus to the next or previous sibling trigger and (if a menu is\nalready open) switch the open menu accordingly. Used by the embedded\n `Menu`  to forward ArrowRight / ArrowLeft from list-level into the\nnavigationmenu when the focused item is not a submenu trigger."
+            },
+            {
+              "name": "setPendingFocus",
+              "type": "(target: \"first\" | \"last\") => void",
+              "default": "",
+              "description": "Set the focus target the next time a menu opens. Used by NavigationMenu's\ntrigger keyboard handler so ArrowDown opens the menu and lands on its\nfirst item, while ArrowUp opens it on the last item (WAI-ARIA NavigationMenu\nkeyboard pattern)."
+            },
+            {
+              "name": "consumePendingFocus",
+              "type": "() => \"first\" | \"last\"",
+              "default": "",
+              "description": "Read and clear any pending focus target queued by the navigationmenu. The\nembedded  `Menu`  calls this from  `onListFocus`  to decide whether to\nfocus the first or last item on open."
+            },
+            {
+              "name": "registerInstantSignal",
+              "type": "(menuId: string, handler: () => void) => () => void",
+              "default": "",
+              "description": "Register a callback fired when the navigationmenu is about to switch between\ntwo sibling menus involving this menu. The child  `Menu`  uses this to\nflip its own  `instantType`  and skip the open/close animation during\nfast traversal. Returns an unregister function."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseNavigationMenuInstance": {
+          "description": "Instance of useNavigationMenu headless.",
+          "values": "HeadlessInstance<UseNavigationMenuProps, UseNavigationMenuState, UseNavigationMenuExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

package/data/llms/headless/components/navigationmenu.md

@@ -0,0 +1,166 @@
+# useNavigationMenu
+
+Hook that coordinates multiple useMenu instances inside a horizontal navigation bar with sibling traversal and single-open-at-a-time behavior.
+
+```tsx
+'use client';
+import { useMenu } from '@primereact/headless/menu';
+import { useNavigationMenu } from '@primereact/headless/navigationmenu';
+import { usePortal } from '@primereact/headless/portal';
+import { usePositioner } from '@primereact/headless/positioner';
+import * as React from 'react';
+import { createPortal } from 'react-dom';
+
+function HeadlessMenu({
+    label,
+    items,
+    navigationmenu,
+    menuId
+}: {
+    label: string;
+    items: string[];
+    navigationmenu: ReturnType<typeof useNavigationMenu>;
+    menuId: string;
+}) {
+    const menu = useMenu({ navigationmenu, navigationmenuMenuId: menuId });
+    const { triggerProps, popupProps, positionerProps, getListProps, getItemProps, state, popover } = menu;
+    const portal = usePortal();
+
+    // Drive position via floating-ui through usePositioner — without it the
+    // popup would render at (0,0) since popover only tracks element refs.
+    usePositioner({
+        anchor: popover.state.anchorElement,
+        content: popover.state.positionerElement,
+        side: 'bottom',
+        align: 'start',
+        sideOffset: 4,
+        flip: true,
+        shift: true
+    });
+
+    // Compose the popover anchor ref from triggerProps with NavigationMenu's
+    // trigger registration so both popup positioning and sibling navigation
+    // work for the same button element.
+    const triggerRef = React.useCallback(
+        (node: HTMLButtonElement | null) => {
+            (triggerProps.ref as (n: HTMLElement | null) => void)?.(node);
+            navigationmenu.registerTrigger(menuId, node);
+        },
+        [triggerProps.ref, navigationmenu, menuId]
+    );
+
+    return (
+        <>
+            <button
+                {...triggerProps}
+                ref={triggerRef}
+                onKeyDown={(event) => navigationmenu.onTriggerKeyDown(menuId, event)}
+                onMouseEnter={() => navigationmenu.onTriggerMouseEnter(menuId)}
+                className="inline-flex items-center px-3 py-1.5 rounded-md text-sm font-medium text-surface-700 dark:text-surface-200 hover:bg-surface-100 dark:hover:bg-surface-800 data-open:bg-surface-100 dark:data-open:bg-surface-800 outline-none"
+            >
+                {label}
+            </button>
+            {portal.state.mounted &&
+                state.open &&
+                popover.state.rendered &&
+                createPortal(
+                    <div {...positionerProps}>
+                        <div
+                            {...popupProps}
+                            className="min-w-44 bg-surface-0 dark:bg-surface-900 border border-surface-200 dark:border-surface-700 rounded-lg shadow-md overflow-hidden"
+                        >
+                            <div {...getListProps()} className="list-none m-0 p-1 flex flex-col gap-0.5 outline-none">
+                                {items.map((item) => (
+                                    <div
+                                        key={item}
+                                        {...getItemProps({ value: item.toLowerCase().replace(/\s+/g, '-') })}
+                                        className="flex items-center gap-2 px-3 py-2 rounded-md cursor-pointer text-sm text-surface-700 dark:text-surface-200 hover:bg-surface-100 dark:hover:bg-surface-800 data-focused:bg-surface-100 dark:data-focused:bg-surface-700 select-none"
+                                    >
+                                        {item}
+                                    </div>
+                                ))}
+                            </div>
+                        </div>
+                    </div>,
+                    document.body
+                )}
+        </>
+    );
+}
+
+export default function BasicDemo() {
+    const navigationmenu = useNavigationMenu();
+
+    return (
+        <div className="flex justify-center">
+            <div
+                {...navigationmenu.rootProps}
+                className="inline-flex items-center gap-1 p-1 bg-surface-0 dark:bg-surface-900 border border-surface-200 dark:border-surface-700 rounded-lg"
+            >
+                <HeadlessMenu label="File" items={['New Document', 'Open', 'Save', 'Save As…']} navigationmenu={navigationmenu} menuId="file" />
+                <HeadlessMenu label="Edit" items={['Undo', 'Redo', 'Cut', 'Copy', 'Paste']} navigationmenu={navigationmenu} menuId="edit" />
+                <HeadlessMenu label="View" items={['Zoom In', 'Zoom Out', 'Reset Zoom']} navigationmenu={navigationmenu} menuId="view" />
+                <HeadlessMenu label="Help" items={['Documentation', 'Support', 'About']} navigationmenu={navigationmenu} menuId="help" />
+            </div>
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useMenu } from '@primereact/headless/menu';
+import { useNavigationMenu } from '@primereact/headless/navigationmenu';
+```
+
+```tsx
+const navigationmenu = useNavigationMenu();
+const fileMenu = useMenu({ navigationmenu, navigationmenuMenuId: 'file' });
+const editMenu = useMenu({ navigationmenu, navigationmenuMenuId: 'edit' });
+```
+
+`useNavigationMenu` tracks which child menu is currently open and switches between them on hover or arrow-key traversal. Each `useMenu` registered to the bar surrenders its open-state to the navigation menu via the `navigationmenu` / `navigationmenuMenuId` props.
+
+See [Primitive](/docs/primitive/components/navigationmenu) for a component-based API.
+
+## Features
+
+- **Single-open-at-a-time**, only one child menu may be open; opening another auto-closes the previous
+- **Hover-to-switch**, moving the pointer onto a sibling trigger while a menu is open transfers focus and open state
+- **Arrow-key traversal**, `focusSibling` lets child menus route arrow keys across triggers
+- **Instant transition signal**, `registerInstantSignal` enables animation-less hand-off when switching siblings
+- **Horizontal or vertical orientation**, exposed via `aria-orientation` and `data-orientation`
+
+## API
+
+### useNavigationMenu
+
+<DocTable name="useNavigationMenu" category="api" />
+
+### Returned values
+
+| Property            | Description                                                                        |
+| ------------------- | ---------------------------------------------------------------------------------- |
+| `rootProps`         | Props for the navigation menu container (`role="menubar"`, ARIA + data attributes) |
+| `state.openMenuId`  | Id of the currently open child menu, or `null`                                     |
+| `state.hasOpenMenu` | Whether any child menu is currently open                                           |
+| `isMenuOpen(id)`    | Returns `true` when the menu with the given id is the active one                   |
+| `onMenuOpenChange`  | Callback used by child `useMenu` to report open-state changes back to the bar      |
+| `focusSibling`      | `(currentMenuId, 'next' \| 'previous')`, moves focus to the adjacent trigger       |
+| `setPendingFocus`   | Marks a sibling for focus after the current menu closes                            |
+| `registerTrigger`   | Used by child menus to register their trigger DOM ref for keyboard navigation      |
+
+## Accessibility
+
+NavigationMenu exposes `role="menubar"` and reflects orientation via `aria-orientation`. Each child trigger participates in arrow-key navigation.
+
+### Keyboard Support
+
+| Key                          | Function                                                             |
+| ---------------------------- | -------------------------------------------------------------------- |
+| `left arrow` / `right arrow` | Moves focus to the previous / next trigger (horizontal orientation). |
+| `up arrow` / `down arrow`    | Moves focus to the previous / next trigger (vertical orientation).   |
+| `enter` / `space`            | Opens the focused menu.                                              |
+| `home` / `end`               | Moves focus to the first / last trigger.                             |
+| `escape`                     | Closes the open menu and returns focus to its trigger.               |