@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,270 @@
+# usePickList
+
+A headless hook that manages two lists with transfer, reorder, and optional drag-and-drop between them.
+
+```tsx
+'use client';
+import { usePickList, type UsePickListValueChangeEvent, type UsePickListSelectionChangeEvent } from '@primereact/headless/picklist';
+import { useState } from 'react';
+
+const cities = [
+    { name: 'New York', code: 'NY' },
+    { name: 'Rome', code: 'RM' },
+    { name: 'London', code: 'LDN' },
+    { name: 'Istanbul', code: 'IST' },
+    { name: 'Paris', code: 'PRS' }
+];
+
+type City = (typeof cities)[0];
+
+export default function BasicDemo() {
+    const [source, setSource] = useState(cities);
+    const [target, setTarget] = useState<City[]>([]);
+    const [selection, setSelection] = useState<City[]>([]);
+
+    const pickList = usePickList({
+        source,
+        target,
+        selection,
+        onValueChange: (e: UsePickListValueChangeEvent) => {
+            setSource(e.source as typeof cities);
+            setTarget(e.target as typeof cities);
+        },
+        onSelectionChange: (e: UsePickListSelectionChangeEvent) => setSelection(e.value as City[])
+    });
+
+    const toggleSelection = (item: City) => {
+        setSelection((prev) => (prev.includes(item) ? prev.filter((s) => s !== item) : [...prev, item]));
+    };
+
+    const listClassName = 'flex-1 border border-surface-200 dark:border-surface-700 rounded-lg overflow-hidden min-h-48';
+    const itemClassName = (item: City) =>
+        `px-3 py-2 cursor-pointer select-none text-sm border-b border-surface-100 dark:border-surface-800 last:border-b-0 ${selection.includes(item) ? 'bg-primary/10 text-primary' : 'hover:bg-surface-50 dark:hover:bg-surface-900'}`;
+    const btnClassName =
+        'px-2 py-1 rounded bg-surface-100 dark:bg-surface-800 hover:bg-surface-200 dark:hover:bg-surface-700 text-sm disabled:opacity-50';
+
+    const hasSourceSelection = selection.some((s) => source.includes(s));
+    const hasTargetSelection = selection.some((s) => target.includes(s));
+
+    return (
+        <div className="flex justify-center">
+            <div {...pickList.rootProps} className="flex gap-3 items-center w-full max-w-lg">
+                <div {...pickList.sourceListProps} className={listClassName}>
+                    {(pickList.state.source as typeof cities).map((item, i) => (
+                        <div
+                            key={item.code}
+                            {...pickList.getOptionProps(item, i, 'source')}
+                            onClick={() => toggleSelection(item)}
+                            className={itemClassName(item)}
+                        >
+                            {item.name}
+                        </div>
+                    ))}
+                </div>
+                <div className="flex flex-col gap-1">
+                    <button
+                        onClick={pickList.moveToTargetProps.onClick as React.MouseEventHandler}
+                        disabled={!hasSourceSelection || undefined}
+                        className={btnClassName}
+                    >
+                        →
+                    </button>
+                    <button
+                        onClick={pickList.moveAllToTargetProps.onClick as React.MouseEventHandler}
+                        disabled={source.length === 0 || undefined}
+                        className={btnClassName}
+                    >
+                        ⇉
+                    </button>
+                    <button
+                        onClick={pickList.moveToSourceProps.onClick as React.MouseEventHandler}
+                        disabled={!hasTargetSelection || undefined}
+                        className={btnClassName}
+                    >
+                        ←
+                    </button>
+                    <button
+                        onClick={pickList.moveAllToSourceProps.onClick as React.MouseEventHandler}
+                        disabled={target.length === 0 || undefined}
+                        className={btnClassName}
+                    >
+                        ⇇
+                    </button>
+                </div>
+                <div {...pickList.targetListProps} className={listClassName}>
+                    {(pickList.state.target as typeof cities).map((item, i) => (
+                        <div
+                            key={item.code}
+                            {...pickList.getOptionProps(item, i, 'target')}
+                            onClick={() => toggleSelection(item)}
+                            className={itemClassName(item)}
+                        >
+                            {item.name}
+                        </div>
+                    ))}
+                </div>
+            </div>
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { usePickList } from '@primereact/headless/picklist';
+```
+
+```tsx
+const pickList = usePickList({
+    source,
+    target,
+    selection,
+    draggable: true,
+    onValueChange: (e) => {
+        setSource(e.source);
+        setTarget(e.target);
+    }
+});
+
+<div {...pickList.rootProps}>
+    <div {...pickList.sourceListProps}>
+        {pickList.state.source.map((item, i) => (
+            <div key={i} {...pickList.getOptionProps(item, i, 'source')}>
+                {item.name}
+            </div>
+        ))}
+    </div>
+    <div>
+        <button {...pickList.moveToTargetProps}>→</button>
+        <button {...pickList.moveAllToTargetProps}>⇉</button>
+        <button {...pickList.moveToSourceProps}>←</button>
+        <button {...pickList.moveAllToSourceProps}>⇇</button>
+    </div>
+    <div {...pickList.targetListProps}>
+        {pickList.state.target.map((item, i) => (
+            <div key={i} {...pickList.getOptionProps(item, i, 'target')}>
+                {item.name}
+            </div>
+        ))}
+    </div>
+</div>;
+```
+
+`usePickList` manages two lists with transfer and reorder operations. Pair it with **Listbox** for built-in selection and keyboard navigation.
+
+## Features
+
+- **Two-list state**, keeps `source` and `target` arrays in sync and emits a single `onValueChange` for any mutation
+- **Transfer operations**, `moveToTarget`, `moveToSource`, `moveAllToTarget`, `moveAllToSource` with pre-wired button props
+- **Per-side reorder controls**, independent prev/next/first/last props for each list plus matching imperative methods
+- **Drag-and-drop**, optional pointer reorder within a list and transfer across lists with scope validation
+- **Side-aware option props**, `getOptionProps(item, index, 'source' | 'target')` returns the attributes each row needs
+
+## Working with callbacks
+
+### onValueChange, keep both arrays in state
+
+Transfer and reorder both funnel through `onValueChange`. Apply `e.source` and `e.target` back to state in one step.
+
+```tsx
+const [source, setSource] = React.useState(initialSource);
+const [target, setTarget] = React.useState([]);
+
+const pickList = usePickList({
+    source,
+    target,
+    onValueChange: (e) => {
+        setSource(e.source);
+        setTarget(e.target);
+    }
+});
+```
+
+### Tracking selection per side
+
+Selection is shared across both lists. Mirror it externally so transfer buttons know which items to move.
+
+```tsx
+const [selection, setSelection] = React.useState([]);
+
+const pickList = usePickList({
+    source,
+    target,
+    selection,
+    onSelectionChange: (e) => setSelection(e.value),
+    onValueChange: (e) => {
+        setSource(e.source);
+        setTarget(e.target);
+    }
+});
+```
+
+### Cross-list drag with clone placeholder
+
+Enable `draggable` to allow reorder within a list and transfer across lists in one gesture. Switch the placeholder to `clone` when users benefit from seeing the original position.
+
+```tsx
+const pickList = usePickList({
+    source,
+    target,
+    draggable: true,
+    placeholder: 'clone',
+    onValueChange: (e) => {
+        setSource(e.source);
+        setTarget(e.target);
+    }
+});
+```
+
+### Driving transfers from custom UI
+
+Call the imperative methods directly when you want to trigger moves from keyboard shortcuts or a menu.
+
+```tsx
+const pickList = usePickList({ source, target, selection, onValueChange });
+
+useHotkey('alt+right', () => pickList.moveToTarget());
+useHotkey('alt+shift+right', () => pickList.moveAllToTarget());
+```
+
+## Styling with data attributes
+
+Every prop object includes `data-scope` and `data-part` attributes for CSS targeting.
+
+```css
+[data-scope='picklist'][data-part='root'] {
+    display: flex;
+    gap: 1rem;
+}
+
+[data-scope='picklist'][data-part='source-list'],
+[data-scope='picklist'][data-part='target-list'] {
+    min-height: 200px;
+}
+
+[data-sortable-placeholder] {
+    opacity: 0.4;
+}
+```
+
+#### Option Attributes
+
+| Attribute                   | Value                                                    |
+| --------------------------- | -------------------------------------------------------- |
+| `data-selected`             | Present when the item is selected                        |
+| `data-sortable-item`        | Present on every sortable item                           |
+| `data-sortable-container`   | Container id for the sortable group                      |
+| `data-dragging`             | Present on the item being dragged                        |
+| `data-dropping`             | Present briefly during the drop animation                |
+| `data-sortable-placeholder` | Present on the placeholder clone left behind during drag |
+
+## API
+
+### usePickList
+
+<DocTable name="usePickList" category="api" />
+
+## Accessibility
+
+Arrow keys navigate within each list, Tab moves between lists, and Enter moves selection across lists. See [Primitive](/docs/primitive/components/picklist#accessibility) for full WAI-ARIA compliance details.

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

@@ -0,0 +1,405 @@
+[
+  {
+    "name": "usePopover",
+    "source": "apps/showcase/assets/apidoc/usepopover.json",
+    "data": {
+      "description": "The usePopover manages the state and functionality of a popover component.",
+      "interfaces": {
+        "UsePopoverOpenChangeEvent": {
+          "description": "Event fired when the popover's open state changes.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "originalEvent",
+              "type": "Event",
+              "default": "",
+              "description": "The original browser event that triggered the change."
+            },
+            {
+              "name": "value",
+              "type": "boolean",
+              "default": "",
+              "description": "The open value of the popover."
+            }
+          ],
+          "methods": []
+        },
+        "UsePopoverProps": {
+          "description": "Defines valid properties in usePopover.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "anchor",
+              "type": "HTMLElement",
+              "default": "undefined",
+              "description": "External anchor element for positioning the popover programmatically.\nWhen provided, it is used instead of the trigger element."
+            },
+            {
+              "name": "defaultOpen",
+              "type": "boolean",
+              "default": "undefined",
+              "description": "Whether the popover is open by default."
+            },
+            {
+              "name": "open",
+              "type": "boolean",
+              "default": "undefined",
+              "description": "Whether the popover is open."
+            },
+            {
+              "name": "trapped",
+              "type": "boolean",
+              "default": "false",
+              "description": "When enabled, focus is trapped within the popover (modal behavior).\nWhen disabled, focus leaving the popover closes it (non-modal behavior)."
+            },
+            {
+              "name": "autoFocus",
+              "type": "boolean",
+              "default": "true",
+              "description": "Whether to focus the first focusable element when the popover is opened."
+            },
+            {
+              "name": "closeOnEscape",
+              "type": "boolean",
+              "default": "true",
+              "description": "Specifies if pressing escape key should hide the dialog."
+            },
+            {
+              "name": "onOpenChange",
+              "type": "(event: UsePopoverOpenChangeEvent) => void",
+              "default": "undefined",
+              "description": "Callback to invoke when the open state changes."
+            },
+            {
+              "name": "onExitComplete",
+              "type": "() => void",
+              "default": "undefined",
+              "description": "Callback fired after the leave (exit) transition completes."
+            },
+            {
+              "name": "appendTo",
+              "type": "\"body\" | HTMLElement | \"self\"",
+              "default": "'body'",
+              "description": "DOM element or CSS selector to append the overlay to."
+            }
+          ],
+          "methods": []
+        },
+        "UsePopoverState": {
+          "description": "Defines valid state in usePopover.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "open",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the popover is open."
+            },
+            {
+              "name": "rendered",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether the popover positioner is rendered (stays true during exit animation)."
+            },
+            {
+              "name": "trapped",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether focus is trapped within the popover."
+            },
+            {
+              "name": "anchorElement",
+              "type": "HTMLElement",
+              "default": "",
+              "description": "The anchor element."
+            },
+            {
+              "name": "positionerElement",
+              "type": "HTMLDivElement",
+              "default": "",
+              "description": "The positioner element."
+            },
+            {
+              "name": "popupElement",
+              "type": "HTMLElement",
+              "default": "",
+              "description": "The popup element."
+            },
+            {
+              "name": "arrowElement",
+              "type": "HTMLDivElement",
+              "default": "",
+              "description": "The arrow element."
+            }
+          ],
+          "methods": []
+        },
+        "UsePopoverTriggerProps": {
+          "description": "Pre-built props for the popover trigger element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "string",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "string",
+              "default": "",
+              "description": "Component part identifier."
+            },
+            {
+              "name": "ref",
+              "type": "(node: HTMLElement) => void",
+              "default": "",
+              "description": "Ref callback that registers the anchor element."
+            },
+            {
+              "name": "onClick",
+              "type": "(e: MouseEvent) => void",
+              "default": "",
+              "description": "Click handler that toggles the popover."
+            },
+            {
+              "name": "data-positioner-open",
+              "type": "string",
+              "default": "",
+              "description": "Data attribute when the positioner is open."
+            }
+          ],
+          "methods": []
+        },
+        "UsePopoverPopupProps": {
+          "description": "Pre-built props for the popover popup element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "string",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "string",
+              "default": "",
+              "description": "Component part identifier."
+            },
+            {
+              "name": "ref",
+              "type": "(node: HTMLElement) => void",
+              "default": "",
+              "description": "Ref callback that registers the popup element."
+            },
+            {
+              "name": "tabIndex",
+              "type": "number",
+              "default": "",
+              "description": "Tab index for programmatic focus support."
+            },
+            {
+              "name": "data-open",
+              "type": "string",
+              "default": "",
+              "description": "Data attribute when the popup is open."
+            }
+          ],
+          "methods": []
+        },
+        "UsePopoverCloseProps": {
+          "description": "Pre-built props for the popover close button.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "string",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "string",
+              "default": "",
+              "description": "Component part identifier."
+            },
+            {
+              "name": "type",
+              "type": "\"button\"",
+              "default": "",
+              "description": "The button type attribute."
+            },
+            {
+              "name": "onClick",
+              "type": "(e: MouseEvent<HTMLButtonElement>) => void",
+              "default": "",
+              "description": "Click handler that closes the popover."
+            }
+          ],
+          "methods": []
+        },
+        "UsePopoverPositionerProps": {
+          "description": "Pre-built props for the popover positioner element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "string",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "string",
+              "default": "",
+              "description": "Component part identifier."
+            },
+            {
+              "name": "ref",
+              "type": "(node: HTMLDivElement) => void",
+              "default": "",
+              "description": "Ref callback that registers the positioner element."
+            }
+          ],
+          "methods": []
+        },
+        "UsePopoverArrowProps": {
+          "description": "Pre-built props for the popover arrow element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "string",
+              "default": "",
+              "description": "Component scope identifier."
+            },
+            {
+              "name": "data-part",
+              "type": "string",
+              "default": "",
+              "description": "Component part identifier."
+            },
+            {
+              "name": "ref",
+              "type": "(node: HTMLDivElement) => void",
+              "default": "",
+              "description": "Ref callback that registers the arrow element."
+            }
+          ],
+          "methods": []
+        },
+        "UsePopoverExposes": {
+          "description": "Defines the methods and properties exposed by usePopover.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UsePopoverState",
+              "default": "",
+              "description": "The state of the usePopover."
+            },
+            {
+              "name": "setOpen",
+              "type": "(open: boolean, originalEvent?: Event) => void",
+              "default": "",
+              "description": "Sets the open state."
+            },
+            {
+              "name": "setArrowRef",
+              "type": "(node: HTMLDivElement) => void",
+              "default": "",
+              "description": "Sets the arrow element."
+            },
+            {
+              "name": "setAnchorRef",
+              "type": "(node: HTMLElement) => void",
+              "default": "",
+              "description": "Sets the anchor element."
+            },
+            {
+              "name": "setAnchorFallbackRef",
+              "type": "(node: HTMLElement) => void",
+              "default": "",
+              "description": "Sets the fallback anchor element, used when the primary anchor is not set."
+            },
+            {
+              "name": "setPositionerRef",
+              "type": "(node: HTMLDivElement) => void",
+              "default": "",
+              "description": "Sets the positioner element."
+            },
+            {
+              "name": "setPopupRef",
+              "type": "(node: HTMLElement) => void",
+              "default": "",
+              "description": "Sets the popup element."
+            },
+            {
+              "name": "setRendered",
+              "type": "(rendered: boolean) => void",
+              "default": "",
+              "description": "Sets the rendered state of the positioner."
+            },
+            {
+              "name": "triggerProps",
+              "type": "UsePopoverTriggerProps",
+              "default": "",
+              "description": "Pre-built props for the trigger element."
+            },
+            {
+              "name": "popupProps",
+              "type": "UsePopoverPopupProps",
+              "default": "",
+              "description": "Pre-built props for the popup element."
+            },
+            {
+              "name": "closeProps",
+              "type": "UsePopoverCloseProps",
+              "default": "",
+              "description": "Pre-built props for the close button."
+            },
+            {
+              "name": "positionerProps",
+              "type": "UsePopoverPositionerProps",
+              "default": "",
+              "description": "Pre-built props for the positioner element."
+            },
+            {
+              "name": "arrowProps",
+              "type": "UsePopoverArrowProps",
+              "default": "",
+              "description": "Pre-built props for the arrow element."
+            },
+            {
+              "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 popover open animation completes.\nHandles autoFocus behavior internally."
+            },
+            {
+              "name": "onCloseComplete",
+              "type": "() => void",
+              "default": "",
+              "description": "Callback to invoke after the popover close animation completes."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UsePopoverInstance": {
+          "description": "Instance of usePopover headless.",
+          "values": "HeadlessInstance<UsePopoverProps, UsePopoverState, UsePopoverExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]