@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,425 @@
+[
+  {
+    "name": "useDrawer",
+    "source": "apps/showcase/assets/apidoc/usedrawer.json",
+    "data": {
+      "description": "The useDrawer manages the state and functionality of a drawer component.",
+      "interfaces": {
+        "UseDrawerChangeEvent": {
+          "description": "Event fired when the drawer's open state changes.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "boolean",
+              "default": "",
+              "description": "The value of the drawer."
+            }
+          ],
+          "methods": []
+        },
+        "UseDrawerProps": {
+          "description": "Defines valid properties in useDrawer.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "open",
+              "type": "boolean",
+              "default": "",
+              "description": "Specifies the visibility of the drawer."
+            },
+            {
+              "name": "defaultOpen",
+              "type": "boolean",
+              "default": "",
+              "description": "Specifies the default visibility of the drawer."
+            },
+            {
+              "name": "blockScroll",
+              "type": "boolean",
+              "default": "false",
+              "description": "Whether to block scrolling when the drawer is open."
+            },
+            {
+              "name": "dismissable",
+              "type": "boolean",
+              "default": "true",
+              "description": "Whether clicking outside closes the drawer."
+            },
+            {
+              "name": "baseZIndex",
+              "type": "number",
+              "default": "0",
+              "description": "Base zIndex value to use in layering."
+            },
+            {
+              "name": "autoZIndex",
+              "type": "boolean",
+              "default": "true",
+              "description": "Whether to automatically manage layering."
+            },
+            {
+              "name": "trapped",
+              "type": "boolean",
+              "default": "true",
+              "description": "When enabled, focus is trapped within the drawer (modal behavior)."
+            },
+            {
+              "name": "position",
+              "type": "\"top\" | \"bottom\" | \"left\" | \"right\" | \"full\"",
+              "default": "left",
+              "description": "Position of the drawer."
+            },
+            {
+              "name": "onOpenChange",
+              "type": "(event: UseDrawerChangeEvent) => void",
+              "default": "",
+              "description": "Callback function that is called when the trigger is clicked."
+            },
+            {
+              "name": "onExitComplete",
+              "type": "() => void",
+              "default": "",
+              "description": "Callback fired after the leave (exit) transition completes."
+            }
+          ],
+          "methods": []
+        },
+        "UseDrawerState": {
+          "description": "Defines valid state in useDrawer.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "open",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the drawer is currently open."
+            },
+            {
+              "name": "trapped",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether focus is trapped within the drawer."
+            },
+            {
+              "name": "popupElement",
+              "type": "HTMLElement",
+              "default": "",
+              "description": "Reference to the popup element."
+            },
+            {
+              "name": "backdropElement",
+              "type": "HTMLElement",
+              "default": "",
+              "description": "Reference to the backdrop element."
+            }
+          ],
+          "methods": []
+        },
+        "UseDrawerTriggerProps": {
+          "description": "Props for the trigger element of the drawer.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "type",
+              "type": "\"button\"",
+              "default": "",
+              "description": "The button type."
+            },
+            {
+              "name": "aria-expanded",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the drawer is currently expanded/open."
+            },
+            {
+              "name": "aria-controls",
+              "type": "string",
+              "default": "",
+              "description": "The id of the drawer element this trigger controls."
+            },
+            {
+              "name": "onClick",
+              "type": "() => void",
+              "default": "",
+              "description": "Click handler to toggle the drawer open state."
+            }
+          ],
+          "methods": []
+        },
+        "UseDrawerRootProps": {
+          "description": "Props for the root element of the drawer.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "id",
+              "type": "string",
+              "default": "",
+              "description": "The id of the drawer root element."
+            },
+            {
+              "name": "data-open",
+              "type": "\"\"",
+              "default": "",
+              "description": "Present when the drawer is open."
+            },
+            {
+              "name": "data-closed",
+              "type": "\"\"",
+              "default": "",
+              "description": "Present when the drawer is closed."
+            }
+          ],
+          "methods": []
+        },
+        "UseDrawerBackdropProps": {
+          "description": "Props for the backdrop element of the drawer (HTML-safe, spreadable on native elements).",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "onMouseDown",
+              "type": "(event: MouseEvent) => void",
+              "default": "",
+              "description": "Handler for mouse down events on the backdrop."
+            },
+            {
+              "name": "onMouseUp",
+              "type": "() => void",
+              "default": "",
+              "description": "Handler for mouse up events on the backdrop."
+            }
+          ],
+          "methods": []
+        },
+        "UseDrawerbackdropMotionProps": {
+          "description": "Component-only props for the backdrop element of the drawer (not safe for native HTML elements).",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "visible",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the backdrop is visible."
+            },
+            {
+              "name": "motionProps",
+              "type": "{ name: string; appear: boolean }",
+              "default": "",
+              "description": "Motion transition properties."
+            }
+          ],
+          "methods": []
+        },
+        "UseDrawerCloseProps": {
+          "description": "Props for the close button element of the drawer.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "type",
+              "type": "\"button\"",
+              "default": "",
+              "description": "The button type."
+            },
+            {
+              "name": "ref",
+              "type": "(node: HTMLButtonElement | { elementRef: RefObject<HTMLButtonElement> }) => void",
+              "default": "",
+              "description": "Callback ref for the close button element. Accepts both native DOM elements and component instances with elementRef."
+            },
+            {
+              "name": "onClick",
+              "type": "() => void",
+              "default": "",
+              "description": "Click handler to close the drawer."
+            }
+          ],
+          "methods": []
+        },
+        "UseDrawerHeaderProps": {
+          "description": "Props for the header element of the drawer.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "id",
+              "type": "string",
+              "default": "",
+              "description": "The id for the header element (used for aria-labelledby)."
+            }
+          ],
+          "methods": []
+        },
+        "UseDrawerPopupProps": {
+          "description": "Props for the popup element of the drawer.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "id",
+              "type": "string",
+              "default": "",
+              "description": "The id of the drawer element."
+            },
+            {
+              "name": "ref",
+              "type": "(node: HTMLDivElement | { elementRef: RefObject<HTMLDivElement> }) => void",
+              "default": "",
+              "description": "Callback ref setter for the popup element. Accepts both native DOM elements and component instances with elementRef."
+            },
+            {
+              "name": "role",
+              "type": "\"complementary\"",
+              "default": "",
+              "description": "The ARIA role for the drawer."
+            },
+            {
+              "name": "aria-modal",
+              "type": "true",
+              "default": "",
+              "description": "Whether the drawer is modal."
+            },
+            {
+              "name": "data-position",
+              "type": "string",
+              "default": "",
+              "description": "The position of the drawer."
+            },
+            {
+              "name": "data-open",
+              "type": "\"\"",
+              "default": "",
+              "description": "Present when the drawer is open."
+            }
+          ],
+          "methods": []
+        },
+        "UseDrawerExposes": {
+          "description": "Defines the methods and properties exposed by useDrawer.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseDrawerState",
+              "default": "",
+              "description": "Current state of the drawer."
+            },
+            {
+              "name": "maskRef",
+              "type": "RefObject<HTMLDivElement | { elementRef: RefObject<HTMLDivElement> }>",
+              "default": "",
+              "description": "Reference to the mask element."
+            },
+            {
+              "name": "setMaskRef",
+              "type": "(node: HTMLDivElement | { elementRef: RefObject<HTMLDivElement> }) => void",
+              "default": "",
+              "description": "Callback ref setter for the mask element. Accepts both native DOM elements and component instances with elementRef."
+            },
+            {
+              "name": "popupRef",
+              "type": "RefObject<HTMLDivElement | { elementRef: RefObject<HTMLDivElement> }>",
+              "default": "",
+              "description": "Reference to the popup element."
+            },
+            {
+              "name": "closeButtonRef",
+              "type": "RefObject<HTMLButtonElement | { elementRef: RefObject<HTMLButtonElement> }>",
+              "default": "",
+              "description": "Reference to the close button element."
+            },
+            {
+              "name": "triggerProps",
+              "type": "UseDrawerTriggerProps",
+              "default": "",
+              "description": "Props for the trigger element."
+            },
+            {
+              "name": "rootProps",
+              "type": "UseDrawerRootProps",
+              "default": "",
+              "description": "Props for the root element."
+            },
+            {
+              "name": "backdropProps",
+              "type": "UseDrawerBackdropProps",
+              "default": "",
+              "description": "Props for the backdrop element (HTML-safe)."
+            },
+            {
+              "name": "backdropMotionProps",
+              "type": "UseDrawerbackdropMotionProps",
+              "default": "",
+              "description": "Component-only props for the backdrop element."
+            },
+            {
+              "name": "closeProps",
+              "type": "UseDrawerCloseProps",
+              "default": "",
+              "description": "Props for the close button element."
+            },
+            {
+              "name": "headerProps",
+              "type": "UseDrawerHeaderProps",
+              "default": "",
+              "description": "Props for the header element."
+            },
+            {
+              "name": "popupProps",
+              "type": "UseDrawerPopupProps",
+              "default": "",
+              "description": "Props for the popup element."
+            },
+            {
+              "name": "onOpenStateChange",
+              "type": "() => void",
+              "default": "",
+              "description": "Method to change the open state of the drawer."
+            },
+            {
+              "name": "close",
+              "type": "() => void",
+              "default": "",
+              "description": "Method to close the drawer."
+            },
+            {
+              "name": "onMaskMouseDown",
+              "type": "(event: MouseEvent) => void",
+              "default": "",
+              "description": "Handler for mask mouse down events."
+            },
+            {
+              "name": "onMaskMouseUp",
+              "type": "() => void",
+              "default": "",
+              "description": "Handler for mask mouse up events."
+            },
+            {
+              "name": "focusTrap",
+              "type": "UseFocusTrapExposes",
+              "default": "",
+              "description": "Focus trap exposes for sentinel rendering when trapped is true."
+            },
+            {
+              "name": "onOpenComplete",
+              "type": "() => void",
+              "default": "",
+              "description": "Callback to invoke after the drawer open animation completes.\nHandles focus behavior internally."
+            },
+            {
+              "name": "onCloseComplete",
+              "type": "() => void",
+              "default": "",
+              "description": "Callback to invoke after the drawer close animation completes."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseDrawerInstance": {
+          "description": "Instance of useDrawer headless.",
+          "values": "HeadlessInstance<UseDrawerProps, UseDrawerState, UseDrawerExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

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

@@ -0,0 +1,220 @@
+# useDrawer
+
+Hook that manages slide-in panel overlays with focus trap, scroll lock, and dismissable backdrop.
+
+```tsx
+'use client';
+import { Bars } from '@primeicons/react/bars';
+import { Times } from '@primeicons/react/times';
+import { useMotion } from '@primereact/core/motion';
+import { useDrawer } from '@primereact/headless/drawer';
+import { usePortal } from '@primereact/headless/portal';
+import { createPortal } from 'react-dom';
+
+const navItems = [
+    { icon: 'pi pi-objects-column', label: 'Dashboard' },
+    { icon: 'pi pi-inbox', label: 'Inbox' },
+    { icon: 'pi pi-calendar', label: 'Calendar' },
+    { icon: 'pi pi-chart-bar', label: 'Analytics' }
+];
+
+export default function BasicDemo() {
+    const { triggerProps, backdropProps, popupProps, closeProps, headerProps, rootProps, state } = useDrawer();
+    const portal = usePortal();
+
+    const popupMotion = useMotion({
+        name: 'p-drawer',
+        appear: true,
+        elementRef: state.popupElement,
+        visible: state.open,
+        enterFromClassName: '-translate-x-full',
+        enterActiveClassName: 'transition-transform duration-200',
+        enterToClassName: 'translate-x-0',
+        leaveFromClassName: 'translate-x-0',
+        leaveActiveClassName: 'transition-transform duration-200',
+        leaveToClassName: '-translate-x-full'
+    });
+
+    const backdropMotion = useMotion({
+        elementRef: state.backdropElement,
+        visible: state.open,
+        enterFromClassName: 'opacity-0',
+        enterActiveClassName: 'transition-opacity duration-200',
+        enterToClassName: 'opacity-100',
+        leaveFromClassName: 'opacity-100',
+        leaveActiveClassName: 'transition-opacity duration-200',
+        leaveToClassName: 'opacity-0'
+    });
+
+    return (
+        <div {...rootProps} className="flex justify-center">
+            <button
+                {...triggerProps}
+                className="inline-flex items-center justify-center w-10 h-10 rounded-lg border border-surface bg-surface-0 dark:bg-surface-950 hover:bg-surface-100 dark:hover:bg-surface-900 cursor-pointer focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-2 focus-visible:outline-primary transition"
+            >
+                <Bars />
+            </button>
+
+            {portal.state.mounted &&
+                popupMotion.state.rendered &&
+                createPortal(
+                    <>
+                        {backdropMotion.state.rendered && <div {...backdropProps} className="fixed inset-0 bg-black/50" />}
+                        {popupMotion.state.rendered && (
+                            <>
+                                <div
+                                    {...popupProps}
+                                    className="fixed top-0 left-0 h-full w-80 bg-surface-0 dark:bg-surface-900 shadow-2xl flex flex-col"
+                                >
+                                    <div {...headerProps} className="flex items-center justify-between p-4 border-b border-surface">
+                                        <span className="text-lg font-semibold">Navigation</span>
+                                        <button
+                                            {...closeProps}
+                                            className="inline-flex items-center justify-center w-8 h-8 rounded-full cursor-pointer bg-surface-50 dark:bg-surface-900 hover:bg-surface-100 dark:hover:bg-surface-800 focus-visible:outline focus-visible:outline-1 focus-visible:outline-offset-2 focus-visible:outline-primary transition"
+                                        >
+                                            <Times />
+                                        </button>
+                                    </div>
+                                    <nav className="flex-1 p-3">
+                                        <ul className="list-none m-0 p-0">
+                                            {navItems.map((item) => (
+                                                <li key={item.label}>
+                                                    <a className="flex items-center gap-3 px-3 py-2.5 rounded-lg cursor-pointer hover:bg-surface-50 dark:hover:bg-surface-800 transition text-sm font-medium">
+                                                        <i className={`${item.icon} text-base`} />
+                                                        {item.label}
+                                                    </a>
+                                                </li>
+                                            ))}
+                                        </ul>
+                                    </nav>
+                                </div>
+                            </>
+                        )}
+                    </>,
+                    document.body
+                )}
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useMotion } from '@primereact/core/motion';
+import { useDrawer } from '@primereact/headless/drawer';
+import { usePortal } from '@primereact/headless/portal';
+import * as React from 'react';
+import { createPortal } from 'react-dom';
+```
+
+```tsx
+const { rootProps, triggerProps, backdropProps, popupProps, closeProps, headerProps, state } = useDrawer();
+const portal = usePortal();
+
+<div {...rootProps}>
+    <button {...triggerProps}></button>
+    {portal.state.mounted &&
+        createPortal(
+            <>
+                <div {...backdropProps} />
+                <div {...popupProps}>
+                    <div {...headerProps}>
+                        <button {...closeProps}></button>
+                    </div>
+                    ...
+                </div>
+            </>,
+            document.body
+```
+
+`useDrawer` manages open/close state, focus trapping, scroll locking, and dismissable backdrop behavior. See [Primitive](/docs/primitive/components/drawer) for a component-based API.
+
+## Features
+
+- **Open/close lifecycle**, controlled or uncontrolled visibility with dismissable backdrop and escape handling
+- **Focus management**, focus trap inside the panel while open, with automatic return-focus to the trigger on close
+- **Positioning**, slides in from left, right, top, or bottom, exposed as a `data-position` attribute on the root
+- **Scroll and layering**, body scroll lock plus `baseZIndex`/`autoZIndex` to stack with other overlays
+- **Portal-ready**, designed to pair with `usePortal` and `createPortal` for SSR-safe body portaling
+- **Imperative controls**, `close()` method and `state.open` flag for programmatic control and conditional rendering
+
+## Working with callbacks
+
+### Controlled open state
+
+Pass `open` and `onOpenChange` to drive visibility from external state.
+
+```tsx
+const [isOpen, setIsOpen] = React.useState(false);
+
+const drawer = useDrawer({
+    open: isOpen,
+    onOpenChange: (e) => setIsOpen(e.value)
+});
+```
+
+### Animated transitions
+
+Combine with `useMotion` so the drawer and backdrop stay mounted through their exit transition before unmounting.
+
+```tsx
+const drawer = useDrawer();
+const motion = useMotion({ open: drawer.state.open });
+
+{
+    motion.present && (
+        <div {...drawer.popupProps} ref={motion.ref}>
+            ...
+        </div>
+    );
+}
+```
+
+### Non-dismissable drawer
+
+Force an explicit close action by disabling backdrop dismissal, useful during unsaved work.
+
+```tsx
+const drawer = useDrawer({ dismissable: false });
+```
+
+### Stacking with other overlays
+
+Use `autoZIndex` with a `baseZIndex` when the drawer must layer above dialogs or dropdowns.
+
+```tsx
+const drawer = useDrawer({ baseZIndex: 1100, autoZIndex: true });
+```
+
+## Styling with data attributes
+
+The hook exposes state through `data-*` attributes on each part. Use them as CSS selectors, no className juggling.
+
+| Scope    | Part    | States                                      |
+| -------- | ------- | ------------------------------------------- |
+| `drawer` | `root`  | `data-open`, `data-closed`, `data-position` |
+| `drawer` | `popup` | `data-open`, `data-closed`                  |
+
+```css
+[data-scope='drawer'][data-part='root'][data-open] {
+    opacity: 1;
+}
+[data-scope='drawer'][data-part='root'][data-closed] {
+    opacity: 0;
+}
+[data-scope='drawer'][data-part='root'][data-position='right'] {
+    right: 0;
+    left: auto;
+}
+```
+
+## API
+
+### useDrawer
+
+<DocTable name="useDrawer" category="api" />
+
+## Accessibility
+
+Escape closes the drawer, focus is trapped inside while open, and focus returns to the trigger on dismiss. See [Primitive](/docs/primitive/components/drawer#accessibility) for full WAI-ARIA compliance details.