@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,283 @@
+# useMenu
+
+Hook that manages menu state, keyboard navigation, focus tracking, and submenu coordination.
+
+```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 { useMenu } from '@primereact/headless/menu';
+import { usePortal } from '@primereact/headless/portal';
+import { usePositioner } from '@primereact/headless/positioner';
+import * as React from 'react';
+import { createPortal } from 'react-dom';
+
+export default function BasicDemo() {
+    const menu = useMenu();
+    const { triggerProps, popupProps, positionerProps, getListProps, getItemProps, labelProps, separatorProps, state, popover } = menu;
+    const portal = usePortal();
+
+    const [notifications, setNotifications] = React.useState(true);
+    const [sound, setSound] = React.useState(false);
+    const [theme, setTheme] = React.useState('light');
+
+    usePositioner({
+        anchor: popover.state.anchorElement,
+        content: popover.state.positionerElement,
+        side: 'bottom',
+        align: 'start',
+        sideOffset: 4,
+        flip: true,
+        shift: true
+    });
+
+    const itemClass = `relative 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 data-checked:ps-8 data-unchecked:ps-8`;
+    const indicatorClass = 'absolute start-2.5 inline-flex items-center justify-center size-3.5 text-surface-500 dark:text-surface-400';
+
+    return (
+        <div className="flex justify-center">
+            <button
+                {...triggerProps}
+                className="inline-flex items-center px-3.5 py-2 rounded-md text-sm font-medium text-surface-700 dark:text-surface-200 border border-surface-200 dark:border-surface-700 hover:bg-surface-100 dark:hover:bg-surface-800 data-open:bg-surface-100 dark:data-open:bg-surface-800 outline-none"
+            >
+                Account
+            </button>
+            {portal.state.mounted &&
+                state.open &&
+                popover.state.rendered &&
+                createPortal(
+                    <div {...positionerProps}>
+                        <div
+                            {...popupProps}
+                            className="w-56 bg-surface-0 dark:bg-surface-900 border border-surface-200 dark:border-surface-700 rounded-lg shadow-md overflow-hidden"
+                        >
+                            <div {...getListProps()} className="m-0 p-1 flex flex-col gap-0.5 outline-none">
+                                <div
+                                    {...labelProps}
+                                    className="px-3 py-1.5 text-xs font-semibold text-surface-500 dark:text-surface-400 uppercase tracking-wide"
+                                >
+                                    My Account
+                                </div>
+                                <div {...getItemProps({ value: 'profile' })} className={itemClass}>
+                                    <User className="w-4! h-4! text-surface-500" />
+                                    Profile
+                                </div>
+                                <div {...getItemProps({ value: 'billing' })} className={itemClass}>
+                                    <CreditCard className="w-4! h-4! text-surface-500" />
+                                    Billing
+                                </div>
+                                <div {...getItemProps({ value: 'settings' })} className={itemClass}>
+                                    <Cog className="w-4! h-4! text-surface-500" />
+                                    Settings
+                                </div>
+
+                                <div {...separatorProps} className="border-t border-surface-200 dark:border-surface-700 my-1" />
+
+                                <div
+                                    {...labelProps}
+                                    className="px-3 py-1.5 text-xs font-semibold text-surface-500 dark:text-surface-400 uppercase tracking-wide"
+                                >
+                                    Notifications
+                                </div>
+                                <div
+                                    {...getItemProps({
+                                        value: 'notifications',
+                                        type: 'checkbox',
+                                        checked: notifications,
+                                        closeOnSelect: false,
+                                        onSelect: () => setNotifications((v) => !v)
+                                    })}
+                                    className={itemClass}
+                                >
+                                    {notifications && (
+                                        <span className={indicatorClass}>
+                                            <Check />
+                                        </span>
+                                    )}
+                                    Enable notifications
+                                </div>
+                                <div
+                                    {...getItemProps({
+                                        value: 'sound',
+                                        type: 'checkbox',
+                                        checked: sound,
+                                        closeOnSelect: false,
+                                        onSelect: () => setSound((v) => !v)
+                                    })}
+                                    className={itemClass}
+                                >
+                                    {sound && (
+                                        <span className={indicatorClass}>
+                                            <Check />
+                                        </span>
+                                    )}
+                                    Play sound
+                                </div>
+
+                                <div {...separatorProps} className="border-t border-surface-200 dark:border-surface-700 my-1" />
+
+                                <div
+                                    {...labelProps}
+                                    className="px-3 py-1.5 text-xs font-semibold text-surface-500 dark:text-surface-400 uppercase tracking-wide"
+                                >
+                                    Appearance
+                                </div>
+                                {(['light', 'dark', 'system'] as const).map((value) => (
+                                    <div
+                                        key={value}
+                                        {...getItemProps({
+                                            value,
+                                            type: 'radio',
+                                            checked: theme === value,
+                                            closeOnSelect: false,
+                                            onSelect: () => setTheme(value)
+                                        })}
+                                        className={itemClass}
+                                    >
+                                        {theme === value && (
+                                            <span className={indicatorClass}>
+                                                <Dot />
+                                            </span>
+                                        )}
+                                        {value.charAt(0).toUpperCase() + value.slice(1)}
+                                    </div>
+                                ))}
+                            </div>
+                        </div>
+                    </div>,
+                    document.body
+                )}
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useMenu } from '@primereact/headless/menu';
+import { useMenuSubmenu } from '@primereact/headless/menu/submenu';
+```
+
+```tsx
+const menu = useMenu();
+const sub = useMenuSubmenu({ defaultOpen: true });
+const subTriggerProps = menu.getSubTriggerProps({ value: 'projects', sub });
+```
+
+`useMenu` manages focus tracking, keyboard navigation, and submenu orchestration for menu structures. See [Primitive](/docs/primitive/components/menu) for a component-based API.
+
+## Features
+
+- **Inline or popup rendering**, spread `getListProps()` directly for an inline menu, or drive visibility with `triggerProps` and `state.open`
+- **Composite submenus**, `composite` mode enables hover-to-open nested menus with arrow-key navigation across levels
+- **Typed items**, `getItemProps({ type })` produces menuitem, checkbox, or radio behavior with proper ARIA semantics
+- **Dynamic prop getters**, `getItemProps`, `getSubTriggerProps`, `getListProps`, and `getIndicatorProps` emit props and data attributes per element
+- **Type-ahead search**, typing characters moves focus to the matching item label
+- **Popover integration**, built on `usePopover` so positioning, portal, and dismissal are configured through the same options
+
+## Working with callbacks
+
+### Controlled popup visibility
+
+Use `open` and `onOpenChange` to drive visibility externally, useful for coordinating with other overlays or toolbar state.
+
+```tsx
+const [open, setOpen] = React.useState(false);
+
+const menu = useMenu({
+    open,
+    onOpenChange: (e) => setOpen(e.value)
+});
+
+<div {...menu.rootProps}>
+    <ul {...menu.getListProps()}>
+        <li {...menu.getItemProps({ value: 'item1' })}></li>
+        <li {...sub.subProps}>
+            <div {...subTriggerProps}></div>
+            <ul {...menu.getListProps({ value: 'projects', sub })}></ul>
+        </li>
+    </ul>
+</div>;
+```
+
+### Submenus with `useMenuSubmenu`
+
+Create a separate `useMenuSubmenu` instance per submenu and wire it through `getSubTriggerProps` / `getListProps`.
+
+```tsx
+const menu = useMenu({ composite: true });
+const sub = useMenuSubmenu();
+const subTriggerProps = menu.getSubTriggerProps({ value: 'files', sub });
+const subListProps = menu.getListProps({ value: 'files', sub });
+```
+
+### Checkbox and radio items
+
+Pass `type` and `checked` to `getItemProps` and wrap radio items in an element carrying `radioGroupProps`.
+
+```tsx
+menu.getItemProps({ value: 'notifications', type: 'checkbox', checked: notificationsOn });
+menu.getItemProps({ value: 'light', type: 'radio', checked: theme === 'light' });
+```
+
+### Indicator visibility with `match`
+
+`getIndicatorProps` returns a `matchVisible` flag so you can render submenu arrows, checkmarks, or radio dots conditionally.
+
+```tsx
+const indicatorProps = menu.getIndicatorProps({ type: 'checkbox', checked: true, match: 'checked' });
+
+{
+    indicatorProps.matchVisible && <CheckIcon {...indicatorProps} />;
+}
+```
+
+## Styling with data attributes
+
+All prop getters attach `data-scope="menu"` and a `data-part` attribute for CSS targeting. Additional data attributes reflect runtime state:
+
+- **`getItemProps`**, `data-part="item"`, plus `data-value`, `data-focused`, `data-disabled`, `data-checked`
+- **`getSubTriggerProps`**, `data-part="subtrigger"`, plus `data-value`, `data-focused`, `data-disabled`, `data-open`
+- **`getIndicatorProps`**, `data-part="indicator"`, plus `data-open`/`data-closed` or `data-checked`/`data-unchecked`
+- **`getListProps`**, `data-part="list"`
+
+```css
+[data-scope='menu'][data-part='item'][data-focused] {
+    background-color: var(--surface-hover);
+}
+
+[data-scope='menu'][data-part='item'][data-checked] {
+    font-weight: 600;
+}
+
+[data-scope='menu'][data-part='subtrigger'][data-open] {
+    background-color: var(--surface-hover);
+}
+
+[data-scope='menu'][data-part='indicator'][data-checked] {
+    color: var(--primary);
+}
+
+[data-scope='menu'][data-part='item'][data-disabled] {
+    opacity: 0.6;
+    pointer-events: none;
+}
+```
+
+## API
+
+### useMenu
+
+<DocTable name="useMenu" category="api" />
+
+### useMenuSubmenu
+
+<DocTable name="useMenuSubmenu" category="api" />
+
+## Accessibility
+
+Arrow keys navigate items, Enter or Space activates the focused item, Escape closes, and type-ahead matches item labels. See [Primitive](/docs/primitive/components/menu#accessibility) for full WAI-ARIA compliance details.

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

@@ -0,0 +1,131 @@
+[
+  {
+    "name": "useMessage",
+    "source": "apps/showcase/assets/apidoc/usemessage.json",
+    "data": {
+      "description": "The useMessage manages the state and functionality of a message component.",
+      "interfaces": {
+        "UseMessageProps": {
+          "description": "Defines valid properties in useMessage.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "life",
+              "type": "number",
+              "default": "null",
+              "description": "Delay in milliseconds to close the message automatically."
+            },
+            {
+              "name": "onClose",
+              "type": "() => void",
+              "default": "",
+              "description": "Callback to invoke when the message is closed."
+            }
+          ],
+          "methods": []
+        },
+        "UseMessageState": {
+          "description": "Defines valid state in useMessage.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "visible",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the message is currently visible."
+            }
+          ],
+          "methods": []
+        },
+        "UseMessageRootProps": {
+          "description": "Data attribute props for the Message root element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "string",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "string",
+              "default": "",
+              "description": "Component part identifier."
+            },
+            {
+              "name": "style",
+              "type": "CSSProperties",
+              "default": "",
+              "description": "Inline style applied when message is not visible."
+            }
+          ],
+          "methods": []
+        },
+        "UseMessageCloseProps": {
+          "description": "Data attribute props for the Message close element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "string",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "string",
+              "default": "",
+              "description": "Component part identifier."
+            },
+            {
+              "name": "onClick",
+              "type": "() => void",
+              "default": "",
+              "description": "Click handler to close the message."
+            }
+          ],
+          "methods": []
+        },
+        "UseMessageExposes": {
+          "description": "Defines the methods and properties exposed by useMessage.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseMessageState",
+              "default": "",
+              "description": "Current state of the message."
+            },
+            {
+              "name": "rootProps",
+              "type": "UseMessageRootProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the root element."
+            },
+            {
+              "name": "closeProps",
+              "type": "UseMessageCloseProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the close element."
+            },
+            {
+              "name": "handleClose",
+              "type": "() => void",
+              "default": "",
+              "description": "Manually close the message."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseMessageInstance": {
+          "description": "Instance of useMessage headless.",
+          "values": "HeadlessInstance<UseMessageProps, UseMessageState, UseMessageExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

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

@@ -0,0 +1,143 @@
+# useMessage
+
+Hook that manages message visibility with auto-close timer and close callback.
+
+```tsx
+'use client';
+import { Sparkles } from '@primeicons/react/sparkles';
+import { Times } from '@primeicons/react/times';
+import { useMessage } from '@primereact/headless/message';
+
+export default function BasicDemo() {
+    const { rootProps, closeProps, state } = useMessage({});
+
+    return (
+        <div className="max-w-sm mx-auto">
+            {state.visible && (
+                <div
+                    {...rootProps}
+                    className="flex items-center gap-3 px-3 py-2 rounded-lg border border-surface-200 dark:border-surface-700 bg-surface-0 dark:bg-surface-900"
+                    role="alert"
+                >
+                    <Sparkles className="w-5 h-5 text-primary shrink-0" />
+                    <p className="flex-1 text-sm text-surface-700 dark:text-surface-0">Upgrade now and save 5%.</p>
+                    <button
+                        {...closeProps}
+                        className="shrink-0 w-7 h-7 inline-flex items-center justify-center rounded-full hover:bg-surface-100 dark:hover:bg-surface-800 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary text-surface-500 dark:text-surface-400 transition-colors cursor-pointer"
+                        aria-label="Close"
+                    >
+                        <Times className="w-3.5 h-3.5" />
+                    </button>
+                </div>
+            )}
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useMessage } from '@primereact/headless/message';
+```
+
+```tsx
+const { rootProps, closeProps, state } = useMessage({});
+
+<>
+    {
+        state.visible && (
+            <div {...rootProps} role="alert">
+                <p></p>
+                <button {...closeProps}></button>
+            </div>
+```
+
+`useMessage` manages visibility state with an optional auto-close timer, see [Primitive](/docs/primitive/components/message) for a component-based API.
+
+## Features
+
+- **Visibility lifecycle**, tracks `state.visible` and hides the root via `display: none` when dismissed
+- **Auto-close timer**, optional `life` in milliseconds for self-dismissing messages
+- **Imperative dismissal**, `handleClose()` for closing the message from custom logic
+- **Dismissal callback**, `onClose` fires whether the message is closed by user action or by the timer
+
+## Working with callbacks
+
+### Auto-closing after a delay
+
+Set `life` to dismiss the message automatically. Useful for transient confirmations that shouldn't require user action.
+
+```tsx
+const message = useMessage({ life: 3000 });
+```
+
+### Reacting to dismissal
+
+Pair `life` with `onClose` to run cleanup when the message leaves, regardless of whether the user closed it or the timer expired.
+
+```tsx
+const message = useMessage({
+    life: 5000,
+    onClose: () => analytics.track('message_dismissed')
+});
+```
+
+### Dismissing from custom logic
+
+Call `handleClose()` to dismiss the message from outside the rendered close button, for example after a form submission succeeds.
+
+```tsx
+const message = useMessage({});
+
+const onSubmit = async () => {
+    await save();
+    message.handleClose();
+};
+```
+
+### Gating render on visibility
+
+`state.visible` is reactive and safe to use as a mount guard so the message is fully removed from the DOM after dismissal.
+
+```tsx
+{
+    state.visible && <div {...rootProps}>...</div>;
+}
+```
+
+## Styling with data attributes
+
+Prop objects include `data-scope="message"` and a `data-part` attribute for CSS targeting.
+
+| Scope     | Part    |
+| --------- | ------- |
+| `message` | `root`  |
+| `message` | `close` |
+
+```css
+[data-scope='message'][data-part='root'] {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding: 0.75rem 1rem;
+    border: 1px solid #ccc;
+    border-radius: 0.5rem;
+}
+
+[data-scope='message'][data-part='close'] {
+    cursor: pointer;
+    border: none;
+    background: transparent;
+}
+```
+
+## API
+
+### useMessage
+
+<DocTable name="useMessage" category="api" />
+
+## Accessibility
+
+Announced via aria-live when shown; Tab reaches the close button if present. See [Primitive](/docs/primitive/components/message#accessibility) for full WAI-ARIA compliance details.