@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,301 @@
+# usePopover
+
+Hook that manages popover open state, outside click dismissal, escape key handling, and focus management.
+
+```tsx
+'use client';
+import { Check } from '@primeicons/react/check';
+import { Times } from '@primeicons/react/times';
+import { usePopover } from '@primereact/headless/popover';
+import { usePortal } from '@primereact/headless/portal';
+import { usePositioner } from '@primereact/headless/positioner';
+import * as React from 'react';
+import { createPortal } from 'react-dom';
+
+const arrowPositionStyles: Record<string, React.CSSProperties> = {
+    top: { bottom: '-0.25rem', left: 'var(--px-placer-arrow-x)', transform: 'translateX(-50%) rotate(225deg)' },
+    bottom: { top: '-0.25rem', left: 'var(--px-placer-arrow-x)', transform: 'translateX(-50%) rotate(45deg)' },
+    left: { right: '-0.25rem', top: 'var(--px-placer-arrow-y)', transform: 'translateY(-50%) rotate(315deg)' },
+    right: { left: '-0.25rem', top: 'var(--px-placer-arrow-y)', transform: 'translateY(-50%) rotate(135deg)' }
+};
+
+const team = [
+    { initials: 'AK', name: 'Alex Kim' },
+    { initials: 'MR', name: 'Maya Ross' },
+    { initials: 'SL', name: 'Sam Lee' }
+];
+
+export default function BasicDemo() {
+    const { triggerProps, popupProps, positionerProps, arrowProps, closeProps, state } = usePopover();
+    const portal = usePortal();
+    const [copied, setCopied] = React.useState(false);
+
+    const positioner = usePositioner({
+        anchor: state.anchorElement,
+        content: state.positionerElement,
+        arrow: state.arrowElement,
+        side: 'bottom',
+        sideOffset: 12,
+        flip: true,
+        shift: true
+    });
+
+    const side = positioner.state.actualSide ?? 'bottom';
+
+    const handleCopy = () => {
+        navigator.clipboard.writeText('https://acme.io/project/design-system');
+        setCopied(true);
+        setTimeout(() => setCopied(false), 2000);
+    };
+
+    return (
+        <div className="flex justify-center min-h-48">
+            <button
+                {...triggerProps}
+                className="inline-flex items-center justify-center h-8 px-3 text-sm font-medium text-surface-700 dark:text-surface-0 bg-transparent border border-surface-200 dark:border-surface-700 rounded-lg cursor-pointer select-none transition-colors hover:bg-surface-50 dark:hover:bg-surface-800 focus-visible:outline-1 focus-visible:outline-primary focus-visible:outline-offset-2"
+            >
+                Share
+            </button>
+            {portal.state.mounted &&
+                state.open &&
+                createPortal(
+                    <div {...positionerProps}>
+                        <div
+                            {...popupProps}
+                            className="bg-surface-0 dark:bg-surface-900 rounded-xl shadow-lg border border-surface-200 dark:border-surface-700 w-80 outline-none relative"
+                        >
+                            <div
+                                {...arrowProps}
+                                className="absolute w-2 h-2 bg-surface-0 dark:bg-surface-900 border-l border-t border-surface-200 dark:border-surface-700"
+                                style={arrowPositionStyles[side]}
+                            />
+                            <div className="flex items-center justify-between px-4 pt-4 pb-2">
+                                <h3 className="text-sm font-semibold text-surface-900 dark:text-surface-0 m-0">Share Project</h3>
+                                <button
+                                    {...closeProps}
+                                    className="flex items-center justify-center w-7 h-7 rounded-md bg-transparent border-none text-surface-500 dark:text-surface-400 cursor-pointer transition-colors hover:bg-surface-100 dark:hover:bg-surface-800 focus-visible:outline-1 focus-visible:outline-primary focus-visible:-outline-offset-1"
+                                >
+                                    <Times className="w-3.5 h-3.5" />
+                                </button>
+                            </div>
+                            <div className="px-4 pb-3">
+                                <div className="flex gap-2">
+                                    <input
+                                        ref={(el) => {
+                                            if (el) {
+                                                el.focus({ preventScroll: true });
+                                                el.select();
+                                            }
+                                        }}
+                                        type="text"
+                                        readOnly
+                                        value="https://acme.io/project/design-system"
+                                        className="flex-1 min-w-0 px-3 py-1.5 text-sm bg-transparent text-surface-700 dark:text-surface-0 border border-surface-200 dark:border-surface-700 rounded-md outline-none focus:border-primary focus:ring-1 focus:ring-primary"
+                                    />
+                                    <button
+                                        onClick={handleCopy}
+                                        className="inline-flex items-center justify-center gap-1.5 min-w-24 px-3 py-1.5 text-sm font-medium rounded-md border-none cursor-pointer select-none transition-colors bg-primary text-primary-contrast hover:bg-primary-emphasis focus-visible:outline-1 focus-visible:outline-primary focus-visible:outline-offset-2"
+                                    >
+                                        {copied ? (
+                                            <>
+                                                <Check className="w-3.5 h-3.5" /> Copied!
+                                            </>
+                                        ) : (
+                                            'Copy'
+                                        )}
+                                    </button>
+                                </div>
+                            </div>
+                            <div className="px-4 pb-3">
+                                <p className="text-xs font-medium text-surface-500 dark:text-surface-400 mt-0 mb-2">Team Members</p>
+                                <div className="flex items-center gap-2">
+                                    {team.map((member) => (
+                                        <div
+                                            key={member.initials}
+                                            title={member.name}
+                                            className="w-8 h-8 rounded-full bg-primary/15 text-primary text-xs font-semibold flex items-center justify-center"
+                                        >
+                                            {member.initials}
+                                        </div>
+                                    ))}
+                                    <button className="w-8 h-8 rounded-full border border-dashed border-surface-300 dark:border-surface-600 bg-transparent text-surface-400 dark:text-surface-500 text-xs cursor-pointer flex items-center justify-center hover:border-primary hover:text-primary transition-colors">
+                                        +
+                                    </button>
+                                </div>
+                            </div>
+                            <div className="px-4 pb-4">
+                                <p className="text-xs text-surface-400 dark:text-surface-500 m-0">Anyone with the link can view this project.</p>
+                            </div>
+                        </div>
+                    </div>,
+                    document.body
+                )}
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { usePopover } from '@primereact/headless/popover';
+import { usePortal } from '@primereact/headless/portal';
+import { usePositioner } from '@primereact/headless/positioner';
+import { createPortal } from 'react-dom';
+```
+
+```tsx
+const { triggerProps, popupProps, positionerProps, arrowProps, closeProps, state } = usePopover();
+const portal = usePortal();
+
+usePositioner({
+    anchor: state.anchorElement,
+    content: state.positionerElement,
+    arrow: state.arrowElement,
+    side: 'bottom',
+    flip: true,
+    shift: true
+});
+```
+
+`usePopover` manages open/close state, outside click dismissal, escape key handling, and optional focus trapping. Use [usePositioner](/docs/headless/components/positioner) for anchor-relative positioning and [usePortal](/docs/headless/components/portal) with `createPortal` for body portaling. See [Primitive](/docs/primitive/components/popover) for a component-based API.
+
+## Features
+
+- **Open/close lifecycle**, controlled or uncontrolled state with outside-click dismissal and escape-key handling
+- **Focus management**, optional focus trap plus `autoFocus` control over initial focus when the popup mounts
+- **Anchor refs**, exposes `state.anchorElement`, `state.positionerElement`, and `state.arrowElement` for wiring into `usePositioner`
+- **Arrow support**, `arrowProps` pairs with the positioner's CSS custom properties for per-side arrow placement
+- **Portal-friendly**, `state.open` drives conditional rendering of portaled content without managing mount state yourself
+- **Imperative controls**, `setOpen(open, event)` for programmatic toggling tied to a source event
+
+## Working with callbacks
+
+### Controlled open state
+
+Pass `open` and `onOpenChange` to drive visibility from external state.
+
+```tsx
+const [isOpen, setIsOpen] = React.useState(false);
+
+const popover = usePopover({
+    open: isOpen,
+    onOpenChange: (e) => setIsOpen(e.open)
+});
+
+<>
+    <button {...triggerProps}></button>;
+    {
+        portal.state.mounted &&
+            state.open &&
+            createPortal(
+                <div {...positionerProps}>
+                    <div {...popupProps}>
+                        <div {...arrowProps} />
+                        <button {...closeProps}></button>
+                    </div>
+                </div>,
+                document.body
+```
+
+### Composing with usePositioner
+
+`usePopover` manages state and element refs but not positioning. Feed the element refs from `state` into `usePositioner` to place the popup relative to the trigger.
+
+```tsx
+const { triggerProps, popupProps, positionerProps, state } = usePopover();
+
+usePositioner({
+    anchor: state.anchorElement,
+    content: state.positionerElement,
+    side: 'bottom',
+    flip: true,
+    shift: true
+});
+```
+
+### Rendering into a portal
+
+Gate the portal content on both `portal.state.mounted` and `state.open` so the popup renders only on the client and only when visible.
+
+```tsx
+const portal = usePortal();
+
+{
+    portal.state.mounted &&
+        state.open &&
+        createPortal(
+            <div {...positionerProps}>
+                <div {...popupProps}>...</div>
+            </div>,
+            document.body
+        );
+}
+```
+
+### Arrow positioning
+
+Spread `arrowProps` on an arrow element and pass `state.arrowElement` to the positioner. The positioner writes `--placer-arrow-x` and `--placer-arrow-y` for you to consume in CSS.
+
+```tsx
+<div {...popupProps}>
+    <div {...arrowProps} />
+</div>
+```
+
+```css
+[data-scope='popover'][data-part='arrow'] {
+    position: absolute;
+    width: 0.5rem;
+    height: 0.5rem;
+    border-left: 1px solid var(--p-content-border-color);
+    border-top: 1px solid var(--p-content-border-color);
+}
+[data-part='arrow'][data-side='bottom'] {
+    top: -0.25rem;
+    left: var(--px-placer-arrow-x);
+    transform: translateX(-50%) rotate(45deg);
+}
+[data-part='arrow'][data-side='top'] {
+    bottom: -0.25rem;
+    left: var(--px-placer-arrow-x);
+    transform: translateX(-50%) rotate(225deg);
+}
+```
+
+### Modal-like focus trap
+
+Enable `trapped` for popovers that should behave like a mini-dialog, keeping keyboard focus inside until dismissed.
+
+```tsx
+const popover = usePopover({ trapped: 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                     |
+| --------- | --------- | -------------------------- |
+| `popover` | `trigger` | `data-positioner-open`     |
+| `popover` | `popup`   | `data-open`, `data-closed` |
+| `popover` | `arrow`   | `data-side`                |
+
+```css
+[data-scope='popover'][data-part='trigger'][data-positioner-open] {
+    background-color: light-dark(var(--p-surface-100), var(--p-surface-700));
+}
+[data-scope='popover'][data-part='popup'][data-open] {
+    opacity: 1;
+}
+```
+
+## API
+
+### usePopover
+
+<DocTable name="usePopover" category="api" />
+
+## Accessibility
+
+Escape dismisses the popover, focus moves into the content when opened, and Tab cycles focusable children. See [Primitive](/docs/primitive/components/popover#accessibility) for full WAI-ARIA compliance details.

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

@@ -0,0 +1,56 @@
+[
+  {
+    "name": "usePortal",
+    "source": "apps/showcase/assets/apidoc/useportal.json",
+    "data": {
+      "description": "The usePortal hook provides functionality to render content into a DOM node outside the component hierarchy.",
+      "interfaces": {
+        "UsePortalProps": {
+          "description": "Defines valid properties in usePortal.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "onMounted",
+              "type": "() => void",
+              "default": "",
+              "description": "Callback function to invoke when the portal is mounted."
+            },
+            {
+              "name": "onUnmounted",
+              "type": "() => void",
+              "default": "",
+              "description": "Callback function to invoke when the portal is unmounted."
+            }
+          ],
+          "methods": []
+        },
+        "UsePortalState": {
+          "description": "Defines valid state in usePortal.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "mounted",
+              "type": "boolean",
+              "default": "",
+              "description": "Current mount of the portal."
+            }
+          ],
+          "methods": []
+        },
+        "UsePortalExposes": {
+          "description": "Defines the methods and properties exposed by usePortal.",
+          "relatedProp": "",
+          "props": [],
+          "methods": []
+        }
+      },
+      "types": {
+        "UsePortalInstance": {
+          "description": "Instance of usePortal headless.",
+          "values": "HeadlessInstance<UsePortalProps, UsePortalState, UsePortalExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

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

@@ -0,0 +1,102 @@
+# usePortal
+
+Hook that tracks client-side mount state for SSR-safe portal rendering.
+
+```tsx
+'use client';
+import { usePortal } from '@primereact/headless/portal';
+import * as React from 'react';
+import { createPortal } from 'react-dom';
+
+export default function BasicDemo() {
+    const portal = usePortal();
+    const [container, setContainer] = React.useState<HTMLElement | null>(null);
+
+    return (
+        <div className="flex flex-col gap-4">
+            <div className="border border-surface-200 rounded-lg p-4 text-sm text-surface-600">
+                <p className="font-semibold text-surface-900 mb-2">Portal Target</p>
+                <div ref={setContainer} className="border border-dashed border-surface-300 rounded p-3 min-h-10" />
+            </div>
+            {portal.state.mounted &&
+                container &&
+                createPortal(
+                    <p className="text-sm text-primary-600 m-0">This content is rendered inside the target container via a portal.</p>,
+                    container
+                )}
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { usePortal } from '@primereact/headless/portal';
+import { createPortal } from 'react-dom';
+```
+
+```tsx
+const portal = usePortal();
+
+{
+    portal.state.mounted && createPortal(<div></div>, document.body);
+}
+```
+
+`usePortal` provides SSR-safe mount detection so portaled content renders only on the client. See [Primitive](/docs/primitive/components/portal) for a component-based API.
+
+## Features
+
+- **SSR-safe mount flag**, `state.mounted` stays `false` during server rendering and flips to `true` after client mount
+- **Lifecycle callbacks**, `onMounted` and `onUnmounted` fire on the corresponding mount boundaries
+- **Portal target agnostic**, pair the flag with any DOM node you want to render into
+
+## Working with callbacks
+
+### Guard `createPortal`
+
+Use `state.mounted` to skip portal rendering on the server, which avoids hydration mismatches.
+
+```tsx
+const portal = usePortal();
+
+{
+    portal.state.mounted && createPortal(<div>Portaled content</div>, document.body);
+}
+```
+
+### React to mount/unmount
+
+Pass `onMounted` and `onUnmounted` when you need to run a side effect tied to the portal's lifecycle, locking scroll, syncing analytics, or closing neighbouring UI.
+
+```tsx
+const portal = usePortal({
+    onMounted: () => lockScroll(),
+    onUnmounted: () => unlockScroll()
+});
+```
+
+### Portal into a custom container
+
+Combine `state.mounted` with a ref to a custom container for portaling into a specific element rather than `document.body`.
+
+```tsx
+const portal = usePortal();
+const [container, setContainer] = React.useState<HTMLElement | null>(null);
+
+<div ref={setContainer} />;
+{
+    portal.state.mounted && container && createPortal(<div>Content</div>, container);
+}
+```
+
+## API
+
+### usePortal
+
+<DocTable name="usePortal" category="api" />
+
+## Accessibility
+
+No direct keyboard behavior, focus management follows the portaled content. See [Primitive](/docs/primitive/components/portal#accessibility) for full WAI-ARIA compliance details.

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

@@ -0,0 +1,165 @@
+[
+  {
+    "name": "usePositioner",
+    "source": "apps/showcase/assets/apidoc/usepositioner.json",
+    "data": {
+      "description": "The usePositioner manages the state and functionality of a positioner component.",
+      "interfaces": {
+        "UsePositionerProps": {
+          "description": "Defines valid properties in usePositioner.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "side",
+              "type": "SideType",
+              "default": "",
+              "description": "The side of the positioner."
+            },
+            {
+              "name": "align",
+              "type": "AlignType",
+              "default": "",
+              "description": "The align of the positioner."
+            },
+            {
+              "name": "sideOffset",
+              "type": "number",
+              "default": "",
+              "description": "The side offset of the positioner."
+            },
+            {
+              "name": "alignOffset",
+              "type": "number",
+              "default": "",
+              "description": "The align offset of the positioner."
+            },
+            {
+              "name": "flip",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether to flip the positioner."
+            },
+            {
+              "name": "shift",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether to shift the positioner."
+            },
+            {
+              "name": "hideWhenDetached",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether to hide the positioner when detached."
+            },
+            {
+              "name": "strategy",
+              "type": "\"fixed\" | \"absolute\"",
+              "default": "'fixed'",
+              "description": "The positioning strategy."
+            },
+            {
+              "name": "boundary",
+              "type": "HTMLElement",
+              "default": "",
+              "description": "The boundary element that constrains the positioner placement.\nUsed in JS fallback mode only; CSS Anchor mode uses the containing block."
+            },
+            {
+              "name": "anchor",
+              "type": "HTMLElement",
+              "default": "",
+              "description": "The anchor element."
+            },
+            {
+              "name": "content",
+              "type": "HTMLDivElement",
+              "default": "",
+              "description": "The content element."
+            },
+            {
+              "name": "arrow",
+              "type": "HTMLDivElement",
+              "default": "",
+              "description": "The arrow element."
+            },
+            {
+              "name": "autoZIndex",
+              "type": "boolean",
+              "default": "true",
+              "description": "Whether to automatically manage layering."
+            },
+            {
+              "name": "baseZIndex",
+              "type": "number",
+              "default": "0",
+              "description": "Base zIndex value to use in layering."
+            },
+            {
+              "name": "onPlacementChange",
+              "type": "(placement: { side: SideType; align: AlignType }) => void",
+              "default": "",
+              "description": "Callback invoked when the actual placement changes due to flip or shift."
+            }
+          ],
+          "methods": []
+        },
+        "UsePositionerState": {
+          "description": "Defines valid state in usePositioner.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "actualSide",
+              "type": "SideType",
+              "default": "",
+              "description": "Actual side after placement."
+            },
+            {
+              "name": "actualAlign",
+              "type": "AlignType",
+              "default": "",
+              "description": "Actual align after placement."
+            }
+          ],
+          "methods": []
+        },
+        "UsePositionerExposes": {
+          "description": "Defines the methods and properties exposed by usePositioner.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UsePositionerState",
+              "default": "",
+              "description": "The state of the usePositioner."
+            },
+            {
+              "name": "getTransformOrigin",
+              "type": "() => string",
+              "default": "",
+              "description": "Computes the transform origin."
+            },
+            {
+              "name": "computePosition",
+              "type": "() => CSSProperties",
+              "default": "",
+              "description": "Computes the position."
+            },
+            {
+              "name": "updatePlacement",
+              "type": "() => void",
+              "default": "",
+              "description": "Updates the placement."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UsePositionerInstance": {
+          "description": "Instance of usePositioner headless.",
+          "values": "HeadlessInstance<UsePositionerProps, UsePositionerState, UsePositionerExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]