@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,258 @@
+# useDataTable
+
+Hook that manages tabular data with sort, filter, pagination, selection, expansion, editing, column/row reorder, resize, and tree-mode flattening.
+
+```tsx
+'use client';
+import { ProductService, type Product } from '@/shared/services/product.service';
+import { useDataTable, useDataTableRow } from '@primereact/headless/datatable';
+import * as React from 'react';
+
+interface RowProps {
+    item: Record<string, unknown>;
+    index: number;
+    context: ReturnType<typeof useDataTable>;
+}
+
+function Row({ item, index, context }: RowProps) {
+    const { rowProps } = useDataTableRow({ item, index, context });
+    const product = item as unknown as Product;
+
+    return (
+        <tr {...rowProps} style={{ borderBottom: '1px solid var(--p-content-border-color)' }}>
+            <td style={cellStyle}>{product.code}</td>
+            <td style={cellStyle}>{product.name}</td>
+            <td style={cellStyle}>{product.category}</td>
+            <td style={cellStyle}>${product.price}</td>
+        </tr>
+    );
+}
+
+const cellStyle: React.CSSProperties = { padding: '0.5rem 0.75rem' };
+const headStyle: React.CSSProperties = { ...cellStyle, textAlign: 'left', fontWeight: 600, borderBottom: '1px solid var(--p-content-border-color)' };
+
+export default function BasicDemo() {
+    const [products, setProducts] = React.useState<Product[]>([]);
+
+    React.useEffect(() => {
+        setProducts(ProductService.getProductsData().slice(0, 6));
+    }, []);
+
+    const dt = useDataTable({ data: products as unknown as Record<string, unknown>[], dataKey: 'id' });
+    const rows = dt.state.paginatedData ?? dt.state.processedData ?? [];
+
+    return (
+        <div {...dt.rootProps} style={{ width: '100%' }}>
+            <div {...dt.tableContainerProps}>
+                <table {...dt.tableProps} style={{ width: '100%', borderCollapse: 'collapse' }}>
+                    <thead>
+                        <tr>
+                            <th style={headStyle}>Code</th>
+                            <th style={headStyle}>Name</th>
+                            <th style={headStyle}>Category</th>
+                            <th style={headStyle}>Price</th>
+                        </tr>
+                    </thead>
+                    <tbody>
+                        {rows.map((item, index) => (
+                            <Row key={dt.getRowKey(item, index)} item={item} index={index} context={dt} />
+                        ))}
+                    </tbody>
+                </table>
+            </div>
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useDataTable } from '@primereact/headless/datatable';
+```
+
+```tsx
+const dt = useDataTable({ data, dataKey: 'id' });
+const { state, rootProps, tableContainerProps, tableProps, getRowKey, sort, selection, pagination, expansion, filter, editing, columnReorder, columnResize, rowReorder, exportData, keyboard } = dt;
+```
+
+`useDataTable` is a single composite hook: every feature (sort, filter, pagination, selection, expansion, editing, etc.) is composed inside it and exposed under a namespaced key. See [Primitive](/docs/primitive/components/datatable) for a component-based API.
+
+## Features
+
+- **Sort**, single, multi, and removable tri-state via `sortField`, `sortOrder`, and `multiSortMeta`
+- **Filter**, row and menu filters per column with multiple constraints and AND/OR operators, plus a global filter across selected fields
+- **Pagination**, built-in slicing or lazy mode with `totalRecords` and `onLazyLoad`
+- **Selection**, single, multiple (checkbox or row), radio, Shift-range, Ctrl/Meta additive, and indeterminate parents in tree mode
+- **Expansion**, flat row expanders or tree-mode flattening; rows are stamped with `_treeLevel`, `_treeHasChildren`, `_treePosInSet`, `_treeSetSize`
+- **Editing**, `cell` and `row` modes; `editingKeys` and `editingCell` can be controlled, save and cancel events fire as expected
+- **Column reorder & resize**, drag-and-drop reorder, `fit` or `expand` resize, with hooks for both indicators
+- **Row reorder**, drag-and-drop driven from a row handle
+- **Grouping**, group metadata map keyed by row index for grouped headers and row spans
+- **Tree mode**, the same API works on hierarchical data; sort, filter, pagination, and selection all operate tree-aware
+- **CSV export**, export visible, selected, or all rows with custom fields and headers
+- **Keyboard navigation**, arrows (with Shift to extend selection), Home / End, Arrow Left / Right to collapse / expand a tree row, Enter or Space to select, Enter on a row to open the first editable cell
+
+## Working with callbacks
+
+### Controlled selection
+
+Pass `selectionKeys` and `onSelectionChange` to drive the selection from outside state.
+
+```tsx
+const [selectionKeys, setSelectionKeys] = React.useState({});
+
+const dt = useDataTable({
+    data,
+    dataKey: 'id',
+    selectionMode: 'multiple',
+    selectionKeys,
+    onSelectionChange: (e) => setSelectionKeys(e.value)
+});
+```
+
+### Controlled sort
+
+Mix single and multi-sort by reading both `sortField` / `sortOrder` and `multiSortMeta` from state.
+
+```tsx
+const [sortField, setSortField] = React.useState<string>();
+const [sortOrder, setSortOrder] = React.useState<1 | -1 | 0>();
+
+const dt = useDataTable({
+    data,
+    sortField,
+    sortOrder,
+    onSortChange: (e) => {
+        setSortField(e.field);
+        setSortOrder(e.order);
+    }
+});
+```
+
+### Controlled filter
+
+Filters are a record of `{ value, matchMode, constraints?, operator? }`. Both the per-column metadata and the global filter are debounceable via `filterDelay`.
+
+```tsx
+const [filters, setFilters] = React.useState({
+    name: { value: null, matchMode: 'contains' },
+    price: { value: null, matchMode: 'gte' }
+});
+const [globalFilter, setGlobalFilter] = React.useState('');
+
+const dt = useDataTable({
+    data,
+    filters,
+    onFilter: (e) => setFilters(e.filters),
+    globalFilter,
+    globalFilterFields: ['name', 'category'],
+    filterDelay: 200
+});
+```
+
+### Lazy loading
+
+In lazy mode the consumer drives data fetching. The hook returns the data as-is and emits `onLazyLoad` whenever page, sort, or filter state changes.
+
+```tsx
+const dt = useDataTable({
+    data,
+    lazy: true,
+    paginator: true,
+    totalRecords,
+    onLazyLoad: (e) => fetchPage(e)
+});
+```
+
+### Tree mode
+
+Pass nodes with `key`, `data`, and optional `children`; flip `treeMode`. The hook flattens visible nodes (respecting `expandedKeys`), and stamps each row with `_treeLevel`, `_treeHasChildren`, `_treePosInSet`, `_treeSetSize` so the renderer can draw indentation, expanders, and ARIA `aria-level` / `aria-posinset`.
+
+```tsx
+const dt = useDataTable({
+    data: nodes,
+    treeMode: true,
+    dataKey: 'key',
+    expandedKeys,
+    onExpandedChange: (e) => setExpandedKeys(e.value)
+});
+```
+
+### Cell and row editing
+
+```tsx
+const dt = useDataTable({
+    data,
+    editMode: 'cell',
+    onCellEditComplete: (e) => {
+        // mutate `data` based on `e.rowData`, `e.field`, `e.newValue`, and call `e.preventDefault()` to keep the cell open
+    }
+});
+```
+
+Switch to `editMode="row"` and use `onRowEditSave` / `onRowEditCancel` for whole-row commits.
+
+## Per-row state with useDataTableRow
+
+For hooking up a single `<tr>` to selection / expansion / reorder / editing, pair `useDataTable` with `useDataTableRow`. It returns a single `rowProps` getter pre-wired with `role`, `aria-rowindex`, click / key handlers, drag handlers when reorder is active, plus tree-mode ARIA (`aria-level`, `aria-expanded`, `aria-posinset`, `aria-setsize`).
+
+```tsx
+import { useDataTable, useDataTableRow } from '@primereact/headless/datatable';
+
+const dt = useDataTable({ data, dataKey: 'id', selectionMode: 'multiple' });
+
+function Row({ item, index }) {
+    const row = useDataTableRow({ item, index, context: dt });
+
+    return <tr {...row.rowProps}>{/* cells */}</tr>;
+}
+```
+
+## Styling with data attributes
+
+Every part exposes its state through `data-*` attributes, drive your CSS from those instead of class toggles.
+
+| Scope       | Part              | States                                                                                                                                       |
+| ----------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `datatable` | `root`            | `data-loading`, `data-row-hover`, `data-highlight-on-select`, `data-selection-mode`, `data-size`, `data-striped-rows`, `data-show-gridlines` |
+| `datatable` | `table-container` |                                                                                                                                              |
+| `datatable` | `table`           |                                                                                                                                              |
+| `datatable` | `row`             | `data-index`, `data-selected`, `data-drag-source`, `data-dragpoint-top`, `data-dragpoint-bottom`                                             |
+| `datatable` | `sort`            | `data-sorted`, `data-unsorted`, `data-sort-order` (`asc` / `desc`)                                                                           |
+| `datatable` | `filter`          | `data-display` (`row` / `menu`), `data-active`                                                                                               |
+| `datatable` | `cell-editor`     | `data-row-index`, `data-field`, `data-row-key`, `data-editing`                                                                               |
+| `datatable` | `row-toggle`      | `data-tree-level`, `aria-expanded`                                                                                                           |
+| `datatable` | `column-resizer`  |                                                                                                                                              |
+
+```css
+[data-scope='datatable'][data-part='row'][data-selected] {
+    background: var(--p-primary-50);
+}
+
+[data-scope='datatable'][data-part='sort'][data-sort-order='asc']::after {
+    content: '↑';
+}
+
+[data-scope='datatable'][data-part='cell-editor'][data-editing] {
+    outline: 2px solid var(--p-primary-color);
+}
+
+[data-scope='datatable'][data-part='row'][data-dragpoint-top] {
+    box-shadow: 0 -2px 0 var(--p-primary-color) inset;
+}
+```
+
+## API
+
+### useDataTable
+
+<DocTable name="useDataTable" category="api" />
+
+### useDataTableRow
+
+<DocTable name="useDataTableRow" category="api" />
+
+## Accessibility
+
+`role="table"` is applied for flat data and `role="treegrid"` when `treeMode` is enabled. Each row exposes `aria-rowindex` (1-based) and, in tree mode, `aria-level`, `aria-expanded`, `aria-posinset`, and `aria-setsize`. Sort triggers expose `role="button"`, `aria-sort`, and a descriptive `aria-label`. Cell-edit wrappers tag their `<td>` with `data-editable-cell` so Tab traversal can find and focus the next editable cell. See [Primitive](/docs/primitive/components/datatable#accessibility) for full WAI-ARIA compliance details.

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

@@ -0,0 +1,199 @@
+[
+  {
+    "name": "useDataView",
+    "source": "apps/showcase/assets/apidoc/usedataview.json",
+    "data": {
+      "description": "The useDataView manages the state and functionality of a dataview component.",
+      "interfaces": {
+        "UseDataViewLayoutChangeEvent": {
+          "description": "Defines the event object for layout change events.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "originalEvent",
+              "type": "SyntheticEvent<Element, Event>",
+              "default": "",
+              "description": "Browser event that triggered the layout change."
+            },
+            {
+              "name": "value",
+              "type": "string",
+              "default": "",
+              "description": "The new layout value."
+            }
+          ],
+          "methods": []
+        },
+        "UseDataViewProps": {
+          "description": "Defines valid properties in useDataView.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "layout",
+              "type": "string",
+              "default": "",
+              "description": "The controlled layout value."
+            },
+            {
+              "name": "defaultLayout",
+              "type": "string",
+              "default": "",
+              "description": "The default layout value for uncontrolled mode."
+            },
+            {
+              "name": "onLayoutChange",
+              "type": "(event: UseDataViewLayoutChangeEvent) => void",
+              "default": "",
+              "description": "Callback invoked when the layout changes."
+            }
+          ],
+          "methods": []
+        },
+        "UseDataViewState": {
+          "description": "Defines valid state in useDataView.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "layout",
+              "type": "string",
+              "default": "",
+              "description": "The current layout value."
+            }
+          ],
+          "methods": []
+        },
+        "UseDataViewRootProps": {
+          "description": "Data attribute props for the DataView root element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-layout",
+              "type": "string",
+              "default": "",
+              "description": "The current layout mode of the data view."
+            }
+          ],
+          "methods": []
+        },
+        "UseDataViewContentProps": {
+          "description": "Data attribute props for the DataView content element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "\"dataview\"",
+              "default": ""
+            },
+            {
+              "name": "data-part",
+              "type": "\"content\"",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseDataViewHeaderProps": {
+          "description": "Data attribute props for the DataView header element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "\"dataview\"",
+              "default": ""
+            },
+            {
+              "name": "data-part",
+              "type": "\"header\"",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseDataViewFooterProps": {
+          "description": "Data attribute props for the DataView footer element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "\"dataview\"",
+              "default": ""
+            },
+            {
+              "name": "data-part",
+              "type": "\"footer\"",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseDataViewEmptyProps": {
+          "description": "Data attribute props for the DataView empty element.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "data-scope",
+              "type": "\"dataview\"",
+              "default": ""
+            },
+            {
+              "name": "data-part",
+              "type": "\"empty\"",
+              "default": ""
+            }
+          ],
+          "methods": []
+        },
+        "UseDataViewExposes": {
+          "description": "Defines the methods and properties exposed by useDataView.",
+          "relatedProp": "",
+          "props": [
+            {
+              "name": "sort",
+              "type": "(value: unknown[], sortField: string, sortOrder: number) => unknown[]",
+              "default": "",
+              "description": "Sorts the data based on the specified field and order."
+            },
+            {
+              "name": "rootProps",
+              "type": "UseDataViewRootProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the root element.\nIncludes data-scope, data-part, and data-layout."
+            },
+            {
+              "name": "contentProps",
+              "type": "UseDataViewContentProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the content element."
+            },
+            {
+              "name": "headerProps",
+              "type": "UseDataViewHeaderProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the header element."
+            },
+            {
+              "name": "footerProps",
+              "type": "UseDataViewFooterProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the footer element."
+            },
+            {
+              "name": "emptyProps",
+              "type": "UseDataViewEmptyProps",
+              "default": "",
+              "description": "Pre-built data attribute props for the empty element."
+            }
+          ],
+          "methods": []
+        }
+      },
+      "types": {
+        "UseDataViewInstance": {
+          "description": "Instance of useDataView headless.",
+          "values": "HeadlessInstance<UseDataViewProps, UseDataViewState, UseDataViewExposes>"
+        }
+      },
+      "variables": {}
+    }
+  }
+]

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

@@ -0,0 +1,147 @@
+# useDataView
+
+Hook that manages layout state and provides a locale-aware sort utility for data presentation.
+
+```tsx
+'use client';
+import { useDataView } from '@primereact/headless/dataview';
+
+const products = [
+    { name: 'Bamboo Watch', category: 'Accessories', price: 65 },
+    { name: 'Black Watch', category: 'Accessories', price: 72 },
+    { name: 'Blue Band', category: 'Fitness', price: 79 },
+    { name: 'Blue T-Shirt', category: 'Clothing', price: 29 },
+    { name: 'Gaming Set', category: 'Electronics', price: 299 }
+];
+
+export default function BasicDemo() {
+    const { rootProps, contentProps, headerProps, emptyProps, state } = useDataView({ defaultLayout: 'list' });
+
+    return (
+        <div {...rootProps} className="border border-surface-200 dark:border-surface-700 rounded-lg overflow-hidden">
+            <div {...headerProps} className="px-4 py-3 bg-surface-50 dark:bg-surface-800 border-b border-surface-200 dark:border-surface-700">
+                <span className="text-sm font-medium text-surface-600 dark:text-surface-300">
+                    {products.length} products &middot; {state.layout} view
+                </span>
+            </div>
+            <div {...contentProps}>
+                {products.length > 0 ? (
+                    <div className="flex flex-col divide-y divide-surface-200 dark:divide-surface-700">
+                        {products.map((product) => (
+                            <div key={product.name} className="flex items-center justify-between px-4 py-3">
+                                <div>
+                                    <div className="text-sm font-medium text-surface-700 dark:text-surface-0">{product.name}</div>
+                                    <div className="text-xs text-surface-500 dark:text-surface-400 mt-0.5">{product.category}</div>
+                                </div>
+                                <span className="text-sm font-semibold text-surface-700 dark:text-surface-0">${product.price}</span>
+                            </div>
+                        ))}
+                    </div>
+                ) : (
+                    <div {...emptyProps} className="px-4 py-8 text-center text-sm text-surface-500 dark:text-surface-400">
+                        No products found.
+                    </div>
+                )}
+            </div>
+        </div>
+    );
+}
+```
+
+## Usage
+
+```tsx
+import { useDataView } from '@primereact/headless/dataview';
+```
+
+```tsx
+const { rootProps, contentProps, headerProps, footerProps, emptyProps, state, sort } = useDataView();
+
+<div {...rootProps}>
+    <div {...headerProps}></div>
+    <div {...contentProps}></div>
+    <div {...footerProps}></div>
+</div>;
+```
+
+`useDataView` manages layout switching and provides a locale-aware sort utility. See [Primitive](/docs/primitive/components/dataview) for a component-based API.
+
+## Features
+
+- **Layout state**, tracks the active layout (`list` or `grid`) and reflects it via `data-layout` on the root
+- **Controlled or uncontrolled**, drive layout from external state or let the hook manage it internally
+- **Locale-aware sort**, built-in `sort(data, field, order)` uses `localeCompare` for strings and numeric compare for numbers
+- **Section prop objects**, ready-to-spread props for root, content, header, footer, and empty sections with scoped data attributes
+
+## Working with callbacks
+
+### Reacting to layout changes
+
+Pass `onLayoutChange` to respond when the layout switches, useful for persisting preferences or re-rendering with a different item template.
+
+```tsx
+const { state } = useDataView({
+    defaultLayout: 'grid',
+    onLayoutChange: (e) => localStorage.setItem('dv-layout', e.value)
+});
+```
+
+### Controlled layout
+
+Pair `layout` with `onLayoutChange` when the layout must be driven by parent state or URL search params.
+
+```tsx
+const [layout, setLayout] = React.useState('list');
+
+const dataview = useDataView({
+    layout,
+    onLayoutChange: (e) => setLayout(e.value)
+});
+```
+
+### Sorting a dataset
+
+Use the returned `sort` method to get a new array without mutating the original. Order `1` is ascending, `-1` descending.
+
+```tsx
+const { sort } = useDataView();
+
+const asc = sort(products, 'price', 1);
+const desc = sort(products, 'price', -1);
+```
+
+### Rendering per layout
+
+Read `state.layout` to branch between list and grid templates in the content slot.
+
+```tsx
+const { state, contentProps } = useDataView({ defaultLayout: 'grid' });
+
+<div {...contentProps}>{state.layout === 'grid' ? products.map((p) => <Card key={p.id} product={p} />) : products.map((p) => <Row key={p.id} product={p} />)}</div>;
+```
+
+## Styling with data attributes
+
+The prop objects carry `data-scope="dataview"` and a `data-part` for each section. The root also exposes the active layout via `data-layout`.
+
+```css
+[data-scope='dataview'][data-part='root'] {
+    border: 1px solid #e5e7eb;
+    border-radius: 0.5rem;
+}
+
+[data-scope='dataview'][data-layout='grid'] [data-part='content'] {
+    display: grid;
+    grid-template-columns: repeat(3, 1fr);
+}
+```
+
+## API
+
+### useDataView
+
+<DocTable name="useDataView" category="api" />
+
+## Accessibility
+
+Arrow keys navigate items when selectable, and Enter activates the focused item. See [Primitive](/docs/primitive/components/dataview#accessibility) for full WAI-ARIA compliance details.