@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,196 @@
+[
+  {
+    "name": "useOrderList",
+    "source": "apps/showcase/assets/apidoc/useorderlist.json",
+    "data": {
+      "description": "The useOrderList manages the state and functionality of an OrderList component.",
+      "interfaces": {
+        "UseOrderListValueChangeEvent": {
+          "description": "Event fired when the orderlist value changes.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "originalEvent",
+              "type": "Event | SyntheticEvent<Element, Event>",
+              "default": "",
+              "description": "The original event that triggered the change."
+            },
+            {
+              "name": "value",
+              "type": "unknown[]",
+              "default": "",
+              "description": "Updated list after the reorder."
+            }
+          ],
+          "methods": []
+        },
+        "UseOrderListProps": {
+          "description": "Defines valid properties in useOrderList.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "T[]",
+              "default": "",
+              "description": "An array of objects to display and reorder."
+            },
+            {
+              "name": "selection",
+              "type": "T[]",
+              "default": "",
+              "description": "An array of currently selected items."
+            },
+            {
+              "name": "disabled",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, it specifies that the component should be disabled."
+            },
+            {
+              "name": "draggable",
+              "type": "boolean",
+              "default": "false",
+              "description": "When present, items can be reordered via drag and drop."
+            },
+            {
+              "name": "placeholder",
+              "type": "\"empty\" | \"clone\"",
+              "default": "\"empty\"",
+              "description": "Controls the placeholder element left behind during drag.\n-  `\"clone\"`  creates a visual copy of the dragged item.\n-  `\"empty\"`  creates an empty element that only preserves the height."
+            },
+            {
+              "name": "onValueChange",
+              "type": "(event: UseOrderListValueChangeEvent) => void",
+              "default": "",
+              "description": "Callback fired when the list order changes."
+            }
+          ],
+          "methods": []
+        },
+        "UseOrderListState": {
+          "description": "Defines valid state in useOrderList.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "value",
+              "type": "T[]",
+              "default": "",
+              "description": "Current ordered list of items."
+            },
+            {
+              "name": "selection",
+              "type": "T[]",
+              "default": "",
+              "description": "Currently selected items."
+            },
+            {
+              "name": "dragging",
+              "type": "boolean",
+              "default": "",
+              "description": "Whether a drag operation is currently in progress."
+            }
+          ],
+          "methods": []
+        },
+        "UseOrderListExposes": {
+          "description": "Defines the methods and properties exposed by useOrderList.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "state",
+              "type": "UseOrderListState<T>",
+              "default": "",
+              "description": "The state of the useOrderList."
+            },
+            {
+              "name": "getOptionProps",
+              "type": "(item: unknown, index: number) => Record<string, unknown>",
+              "default": "",
+              "description": "Pre-built props for a list item element."
+            },
+            {
+              "name": "listRef",
+              "type": "RefObject<HTMLElement>",
+              "default": "",
+              "description": "Ref to attach to the element wrapping the option list. When set, moved items are scrolled\ninto view after a reorder."
+            },
+            {
+              "name": "moveUp",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": "",
+              "description": "Moves selected items one position up."
+            },
+            {
+              "name": "moveDown",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": "",
+              "description": "Moves selected items one position down."
+            },
+            {
+              "name": "moveTop",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": "",
+              "description": "Moves selected items to the top of the list."
+            },
+            {
+              "name": "moveBottom",
+              "type": "(event?: SyntheticEvent) => void",
+              "default": "",
+              "description": "Moves selected items to the bottom of the list."
+            },
+            {
+              "name": "rootProps",
+              "type": "Record<string, unknown>",
+              "default": "",
+              "description": "Pre-built data attribute props for the root element."
+            },
+            {
+              "name": "controlsProps",
+              "type": "Record<string, unknown>",
+              "default": "",
+              "description": "Pre-built data attribute props for the controls container element."
+            },
+            {
+              "name": "listProps",
+              "type": "Record<string, unknown>",
+              "default": "",
+              "description": "Pre-built data attribute props for the list element."
+            },
+            {
+              "name": "prevProps",
+              "type": "Record<string, unknown>",
+              "default": "",
+              "description": "Pre-built props for the \"move previous\" button element."
+            },
+            {
+              "name": "nextProps",
+              "type": "Record<string, unknown>",
+              "default": "",
+              "description": "Pre-built props for the \"move next\" button element."
+            },
+            {
+              "name": "firstProps",
+              "type": "Record<string, unknown>",
+              "default": "",
+              "description": "Pre-built props for the \"move first\" button element."
+            },
+            {
+              "name": "lastProps",
+              "type": "Record<string, unknown>",
+              "default": "",
+              "description": "Pre-built props for the \"move last\" button element."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseOrderListInstance": {
+          "description": "Instance of useOrderList headless.",
+          "values": "HeadlessInstance<UseOrderListProps<T>, UseOrderListState<T>, UseOrderListExposes<T>>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

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

@@ -0,0 +1,221 @@
+# useOrderList
+
+A headless hook that manages list ordering with selection-based controls and optional drag-and-drop support.
+
+```tsx
+'use client';
+import { useOrderList, type UseOrderListValueChangeEvent } from '@primereact/headless/orderlist';
+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 [items, setItems] = useState(cities);
+    const [selection, setSelection] = useState<City[]>([]);
+
+    const orderList = useOrderList({
+        value: items,
+        selection,
+        onValueChange: (e: UseOrderListValueChangeEvent) => setItems(e.value as typeof cities)
+    });
+
+    const toggleSelection = (item: City) => {
+        setSelection((prev) => (prev.includes(item) ? prev.filter((s) => s !== item) : [...prev, item]));
+    };
+
+    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 hasSelection = selection.length > 0;
+
+    return (
+        <div className="flex justify-center">
+            <div className="flex gap-2 w-full max-w-xs">
+                <div {...orderList.controlsProps} className="flex flex-col gap-1">
+                    <button
+                        onClick={orderList.firstProps.onClick as React.MouseEventHandler}
+                        disabled={!hasSelection || undefined}
+                        className={btnClassName}
+                    >
+                        ⇈
+                    </button>
+                    <button
+                        onClick={orderList.prevProps.onClick as React.MouseEventHandler}
+                        disabled={!hasSelection || undefined}
+                        className={btnClassName}
+                    >
+                        ↑
+                    </button>
+                    <button
+                        onClick={orderList.nextProps.onClick as React.MouseEventHandler}
+                        disabled={!hasSelection || undefined}
+                        className={btnClassName}
+                    >
+                        ↓
+                    </button>
+                    <button
+                        onClick={orderList.lastProps.onClick as React.MouseEventHandler}
+                        disabled={!hasSelection || undefined}
+                        className={btnClassName}
+                    >
+                        ⇊
+                    </button>
+                </div>
+                <div {...orderList.listProps} className="flex-1 border border-surface-200 dark:border-surface-700 rounded-lg overflow-hidden">
+                    {(orderList.state.value as typeof cities).map((item, i) => (
+                        <div
+                            key={item.code}
+                            {...orderList.getOptionProps(item, i)}
+                            onClick={() => toggleSelection(item)}
+                            className={`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'}`}
+                        >
+                            {item.name}
+                        </div>
+                    ))}
+                </div>
+            </div>
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useOrderList } from '@primereact/headless/orderlist';
+```
+
+```tsx
+const orderList = useOrderList({
+    value: items,
+    selection,
+    draggable: true,
+    onValueChange: (e) => setItems(e.value)
+});
+
+<div {...orderList.rootProps}>
+    <div {...orderList.controlsProps}>
+        <button {...orderList.firstProps}>Top</button>
+        <button {...orderList.prevProps}>Up</button>
+        <button {...orderList.nextProps}>Down</button>
+        <button {...orderList.lastProps}>Bottom</button>
+    </div>
+    <div {...orderList.listProps}>
+        {orderList.state.value.map((item, i) => (
+            <div key={i} {...orderList.getOptionProps(item, i)}>
+                {item.name}
+            </div>
+```
+
+`useOrderList` manages item ordering through move operations and drag-and-drop. Pair it with **Listbox** for built-in selection and keyboard navigation.
+
+## Features
+
+- **Selection-driven reorder**, move the current selection with `moveUp`, `moveDown`, `moveTop`, `moveBottom` or their pre-wired button props
+- **Drag-and-drop**, optional pointer-based reordering with configurable placeholder and cross-container restrictions
+- **Placeholder modes**, choose between an `empty` height-preserving gap or a full `clone` of the dragged item
+- **Per-option props**, `getOptionProps(item, index)` returns the ARIA, sortable, and data attributes each row needs
+- **Imperative controls**, call move methods programmatically for custom keyboard or gesture bindings
+
+## Working with callbacks
+
+### onValueChange, persist the new order
+
+`onValueChange` fires whenever the list changes. In controlled usage, feed `e.value` back into your state.
+
+```tsx
+const [items, setItems] = React.useState(['A', 'B', 'C']);
+
+const orderList = useOrderList({
+    value: items,
+    onValueChange: (e) => setItems(e.value)
+});
+```
+
+### Selection-based move buttons
+
+Track selection externally so the move controls know what to operate on. The button props already call the matching move operation.
+
+```tsx
+const [selection, setSelection] = React.useState([]);
+
+const orderList = useOrderList({
+    value: items,
+    selection,
+    onSelectionChange: (e) => setSelection(e.value),
+    onValueChange: (e) => setItems(e.value)
+});
+```
+
+### Enabling drag-and-drop with a clone placeholder
+
+Switch to `clone` when users need a visual anchor in the original position while dragging.
+
+```tsx
+const orderList = useOrderList({
+    value: items,
+    draggable: true,
+    placeholder: 'clone',
+    onValueChange: (e) => setItems(e.value)
+});
+```
+
+Target the ghost with the `[data-sortable-placeholder]` attribute.
+
+### Driving moves programmatically
+
+Use the returned imperative methods to bind moves to custom shortcuts or toolbars.
+
+```tsx
+const orderList = useOrderList({ value: items, selection, onValueChange: (e) => setItems(e.value) });
+
+useHotkey('alt+up', () => orderList.moveUp());
+useHotkey('alt+shift+up', () => orderList.moveTop());
+```
+
+## Styling with data attributes
+
+Every prop object includes `data-scope` and `data-part` attributes for CSS targeting.
+
+```css
+[data-scope='orderlist'][data-part='root'] {
+    display: flex;
+    gap: 1rem;
+}
+
+[data-scope='orderlist'][data-part='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
+
+### useOrderList
+
+<DocTable name="useOrderList" category="api" />
+
+## Accessibility
+
+Arrow keys navigate items, Shift+Arrow moves the selected item up or down, and Space toggles selection. See [Primitive](/docs/primitive/components/orderlist#accessibility) for full WAI-ARIA compliance details.