@primereact/mcp 11.0.0-rc.2

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

@@ -0,0 +1,561 @@
+# DataTable
+
+An unstyled data table with sort, filter, pagination, selection, expansion, editing, column reorder/resize, row reorder, grouping, frozen sections, CSV export, and tree mode.
+
+<DocPrimitiveIntro description="Compose a fully custom table with complete control over markup, layout, and styling. Every feature is opt-in and driven by data attributes." />
+
+```tsx
+'use client';
+import { ProductService, type Product } from '@/shared/services/product.service';
+import { DataTable } from 'primereact/datatable';
+import * as React from 'react';
+
+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)' };
+const rowStyle: React.CSSProperties = { 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));
+    }, []);
+
+    return (
+        <div style={{ width: '100%' }}>
+            <DataTable.Root data={products} dataKey="id">
+                <DataTable.TableContainer>
+                    <DataTable.Table style={{ width: '100%', borderCollapse: 'collapse' }}>
+                        <DataTable.THead>
+                            <DataTable.THeadRow>
+                                <DataTable.THeadCell style={headStyle}>Code</DataTable.THeadCell>
+                                <DataTable.THeadCell style={headStyle}>Name</DataTable.THeadCell>
+                                <DataTable.THeadCell style={headStyle}>Category</DataTable.THeadCell>
+                                <DataTable.THeadCell style={headStyle}>Price</DataTable.THeadCell>
+                            </DataTable.THeadRow>
+                        </DataTable.THead>
+                        <DataTable.TBody>
+                            {({ item }: { item: Record<string, unknown> }) => (
+                                <DataTable.Row style={rowStyle}>
+                                    <DataTable.Cell style={cellStyle}>{String(item.code)}</DataTable.Cell>
+                                    <DataTable.Cell style={cellStyle}>{String(item.name)}</DataTable.Cell>
+                                    <DataTable.Cell style={cellStyle}>{String(item.category)}</DataTable.Cell>
+                                    <DataTable.Cell style={cellStyle}>${String(item.price)}</DataTable.Cell>
+                                </DataTable.Row>
+                            )}
+                        </DataTable.TBody>
+                    </DataTable.Table>
+                </DataTable.TableContainer>
+            </DataTable.Root>
+        </div>
+    );
+}
+```
+
+<DocPrimitiveLinks name="DataTable" />
+
+## Features
+
+- Compound component API with sub-components: `Root`, `Header`, `TableContainer`, `Table`, `THead`, `THeadRow`, `THeadCell`, `TBody`, `FrozenTBody`, `Row`, `Cell`, `TFoot`, `TFootRow`, `TFootCell`, `Footer`, `Sort`, `SortIndicator`, `SortOrder`, `Filter`, `Pagination`, `Selection`, `RowToggle`, `RowToggleIndicator`, `RowExpansion`, `RowGroupHeader`, `RowGroupFooter`, `CellEditor`, `CellEditorDisplay`, `CellEditorContent`, `RowEditor`, `RowEditorInit`, `RowEditorSave`, `RowEditorCancel`, `ColumnToggle`, `ColumnReorder`, `ColumnReorderTarget`, `ColumnResizer`, `ColumnResizeIndicator`, `RowReorder`, `Export`, `Loading`, `EmptyTBody`
+- Sort (single, multi, removable), row and menu filters per column, plus a global filter across selected fields
+- Pagination with built-in slicing or lazy mode
+- Selection in single, multiple checkbox, multiple row, or radio modes; Shift for range, Ctrl/Meta to add or remove
+- Cell or row editing with Tab traversal, outside-click commit, and Escape cancel
+- Column reorder, column resize (`fit` or `expand`), and row reorder via drag handles
+- Frozen left and right columns via the `frozen` prop on `Cell` and `THeadCell`
+- Tree mode reuses the same components; flip `treeMode` on `Root` and feed it `{ key, data, children? }` nodes
+- CSV export with custom fields and headers
+
+## Usage
+
+```tsx
+import { DataTable } from 'primereact/datatable';
+```
+
+```tsx
+<DataTable.Root data={products} dataKey="id">
+    <DataTable.TableContainer>
+        <DataTable.Table>
+            <DataTable.THead>
+                <DataTable.THeadRow>
+                    <DataTable.THeadCell>Name</DataTable.THeadCell>
+                    <DataTable.THeadCell>Category</DataTable.THeadCell>
+                </DataTable.THeadRow>
+            </DataTable.THead>
+            <DataTable.TBody>
+                {({ item }) => (
+                    <DataTable.Row>
+                        <DataTable.Cell>{item.name}</DataTable.Cell>
+                        <DataTable.Cell>{item.category}</DataTable.Cell>
+                    </DataTable.Row>
+                )}
+            </DataTable.TBody>
+        </DataTable.Table>
+    </DataTable.TableContainer>
+</DataTable.Root>
+```
+
+## Behavior
+
+### Render Function Children
+
+`DataTable.TBody` accepts a render function that receives `{ item, index, groupMeta }` for each row. Stateful sub-components (`Selection`, `Pagination`, `Filter`, `Sort`, `RowToggle`, `CellEditor`) also expose render-prop slot context so you can read live state and call exposed methods.
+
+```tsx
+<DataTable.Sort field="price">{({ isSorted, sortOrder }) => <span>Price {isSorted ? (sortOrder === 1 ? '↑' : '↓') : ''}</span>}</DataTable.Sort>
+```
+
+### Polymorphic Rendering
+
+Use `as` on any sub-component to swap the underlying element or render through another component (e.g. a styled `Button` for `Sort` triggers).
+
+```tsx
+<DataTable.RowEditorInit as={Button} variant="text" />
+```
+
+### Sort
+
+Wrap header content in `DataTable.Sort` and provide `field`. Hold Ctrl / Cmd while clicking to multi-sort. Enable `removableSort` on `Root` for tri-state click cycles.
+
+```tsx
+<DataTable.THeadCell>
+    <DataTable.Sort field="price">
+        Price <DataTable.SortIndicator match="asc">↑</DataTable.SortIndicator>
+    </DataTable.Sort>
+</DataTable.THeadCell>
+```
+
+### Filter
+
+Render `DataTable.Filter` for each filterable column and a separate keyword input bound to `globalFilter`. Use `display="row"` for inline filters that apply on every change, or `display="menu"` for an overlay with multiple constraints, AND/OR operators, and explicit Apply / Clear.
+
+```tsx
+<DataTable.Filter field="name" display="row" dataType="text">
+    {({ value, onChange }) => <input value={value ?? ''} onChange={(e) => onChange(e, e.target.value)} />}
+</DataTable.Filter>
+```
+
+### Selection
+
+Set `selectionMode` on `Root` to `'single'` or `'multiple'` and wrap each cell or header trigger in `DataTable.Selection`. The slot context exposes `isSelected` / `toggle` for rows and `isAllSelected` / `isSomeSelected` / `toggleAll` for headers.
+
+```tsx
+<DataTable.Selection>{({ isSelected, toggle }) => <Checkbox checked={isSelected} onCheckedChange={toggle} />}</DataTable.Selection>
+```
+
+### Expansion & Tree Mode
+
+`DataTable.RowToggle` reads expansion state automatically and renders a leaf-spacer in tree mode when a row has no children, so indentation stays aligned. Setting `treeMode` on `Root` flips the table to `role="treegrid"` and stamps tree ARIA on every row.
+
+```tsx
+<DataTable.Root treeMode dataKey="key" data={nodes}>
+    {/* same Table / THead / TBody markup; rows now indent automatically */}
+</DataTable.Root>
+```
+
+### Cell and Row Editing
+
+Wrap each editable cell in `DataTable.CellEditor` with `field` / `rowIndex` / `rowData`, and supply two slots: `Display` (read mode) and `Content` (edit mode). When `editMode="row"`, replace the per-cell switch with `RowEditor.Init` / `Save` / `Cancel` triggers in a dedicated cell.
+
+```tsx
+<DataTable.CellEditor field="price" rowIndex={index} rowData={item}>
+    <DataTable.CellEditorDisplay>{item.price}</DataTable.CellEditorDisplay>
+    <DataTable.CellEditorContent>
+        <input defaultValue={item.price} />
+    </DataTable.CellEditorContent>
+</DataTable.CellEditor>
+```
+
+### Column Reorder & Resize
+
+Set `reorderableColumns` on `Root` and add a `DataTable.ColumnReorder` handle inside each `THeadCell`. For resizing, set `resizableColumns` and drop a `DataTable.ColumnResizer` inside the header, pair it with `ColumnResizeIndicator` for a live drag line.
+
+### Row Reorder
+
+Set `reorderableRows` on `Root` and add a `DataTable.RowReorder` handle in a row cell. The hook arms the surrounding `<tr>` as the drag source on pointer-down and emits `onRowReorder` with the new array.
+
+### Pagination
+
+Render `DataTable.Pagination` anywhere below the table; it acts as a render-prop wrapper that exposes `page`, `pageCount`, `rows`, `totalRecords`, `first`, `canPrev`, `canNext`, `onPageChange`, and `onRowsChange`.
+
+```tsx
+<DataTable.Pagination>{({ page, pageCount, onPageChange }) => <div>{/* custom paginator UI */}</div>}</DataTable.Pagination>
+```
+
+## Pass Through
+
+<DocPTViewer name="datatable-pt" components={['DataTableRoot']} />
+
+## API
+
+### DataTableRoot
+
+<DocTable name="DataTableRoot" category="api" />
+
+| Attribute                  | Value                                       |
+| -------------------------- | ------------------------------------------- |
+| `data-scope`               | `"datatable"`                               |
+| `data-part`                | `"root"`                                    |
+| `data-loading`             | Present while loading                       |
+| `data-row-hover`           | Present when `rowHover` is true             |
+| `data-highlight-on-select` | Present when selected rows should highlight |
+| `data-selection-mode`      | `"single"` \| `"multiple"`                  |
+| `data-size`                | `"small"` \| `"large"`                      |
+| `data-striped-rows`        | Present when `stripedRows` is true          |
+| `data-show-gridlines`      | Present when `showGridlines` is true        |
+
+<DocTable name="DataTableRoot" category="pt" />
+
+### DataTableHeader
+
+<DocTable name="DataTableHeader" category="api" />
+
+<DocTable name="DataTableHeader" category="pt" />
+
+### DataTableTableContainer
+
+<DocTable name="DataTableTableContainer" category="api" />
+
+| Attribute    | Value               |
+| ------------ | ------------------- |
+| `data-scope` | `"datatable"`       |
+| `data-part`  | `"table-container"` |
+
+<DocTable name="DataTableTableContainer" category="pt" />
+
+### DataTableTable
+
+<DocTable name="DataTableTable" category="api" />
+
+| Attribute    | Value                     |
+| ------------ | ------------------------- |
+| `data-scope` | `"datatable"`             |
+| `data-part`  | `"table"`                 |
+| `role`       | `"table"` or `"treegrid"` |
+
+<DocTable name="DataTableTable" category="pt" />
+
+### DataTableTHead
+
+<DocTable name="DataTableTHead" category="api" />
+
+<DocTable name="DataTableTHead" category="pt" />
+
+### DataTableTHeadRow
+
+<DocTable name="DataTableTHeadRow" category="api" />
+
+<DocTable name="DataTableTHeadRow" category="pt" />
+
+### DataTableTHeadCell
+
+<DocTable name="DataTableTHeadCell" category="api" />
+
+| Attribute           | Value                           |
+| ------------------- | ------------------------------- |
+| `data-frozen`       | Present when the cell is frozen |
+| `data-align-frozen` | `"left"` \| `"right"`           |
+
+<DocTable name="DataTableTHeadCell" category="pt" />
+
+### DataTableTBody
+
+<DocTable name="DataTableTBody" category="api" />
+
+<DocTable name="DataTableTBody" category="pt" />
+
+### DataTableFrozenTBody
+
+<DocTable name="DataTableFrozenTBody" category="api" />
+
+<DocTable name="DataTableFrozenTBody" category="pt" />
+
+### DataTableRow
+
+<DocTable name="DataTableRow" category="api" />
+
+| Attribute               | Value                                                  |
+| ----------------------- | ------------------------------------------------------ |
+| `data-scope`            | `"datatable"`                                          |
+| `data-part`             | `"row"`                                                |
+| `data-index`            | Zero-based row index in the rendered slice             |
+| `data-selected`         | Present when the row is selected                       |
+| `aria-selected`         | Reflects selection state when selection mode is active |
+| `aria-level`            | Tree depth (one-based) in tree mode                    |
+| `aria-expanded`         | Reflects expansion when the row has children           |
+| `aria-posinset`         | One-based position among siblings (tree mode)          |
+| `aria-setsize`          | Total siblings at the same depth (tree mode)           |
+| `data-drag-source`      | Present while dragging this row                        |
+| `data-dragpoint-top`    | Present when drop indicator targets the top edge       |
+| `data-dragpoint-bottom` | Present when drop indicator targets the bottom edge    |
+
+<DocTable name="DataTableRow" category="pt" />
+
+### DataTableCell
+
+<DocTable name="DataTableCell" category="api" />
+
+| Attribute            | Value                                  |
+| -------------------- | -------------------------------------- |
+| `data-scope`         | `"datatable"`                          |
+| `data-part`          | `"cell"`                               |
+| `role`               | `"gridcell"`                           |
+| `data-frozen`        | Present when the cell is frozen        |
+| `data-align-frozen`  | `"left"` \| `"right"`                  |
+| `data-editable-cell` | Present when wrapped by a `CellEditor` |
+
+<DocTable name="DataTableCell" category="pt" />
+
+### DataTableTFoot
+
+<DocTable name="DataTableTFoot" category="api" />
+
+<DocTable name="DataTableTFoot" category="pt" />
+
+### DataTableTFootRow
+
+<DocTable name="DataTableTFootRow" category="api" />
+
+<DocTable name="DataTableTFootRow" category="pt" />
+
+### DataTableTFootCell
+
+<DocTable name="DataTableTFootCell" category="api" />
+
+<DocTable name="DataTableTFootCell" category="pt" />
+
+### DataTableFooter
+
+<DocTable name="DataTableFooter" category="api" />
+
+<DocTable name="DataTableFooter" category="pt" />
+
+### DataTableSort
+
+<DocTable name="DataTableSort" category="api" />
+
+| Attribute         | Value                                               |
+| ----------------- | --------------------------------------------------- |
+| `data-scope`      | `"datatable"`                                       |
+| `data-part`       | `"sort"`                                            |
+| `role`            | `"button"`                                          |
+| `data-sorted`     | Present when this column is part of the active sort |
+| `data-unsorted`   | Present when this column is not part of the sort    |
+| `data-sort-order` | `"asc"` \| `"desc"` when sorted                     |
+| `aria-sort`       | `"ascending"` \| `"descending"` \| `"none"`         |
+
+<DocTable name="DataTableSort" category="pt" />
+
+### DataTableSortIndicator
+
+<DocTable name="DataTableSortIndicator" category="api" />
+
+<DocTable name="DataTableSortIndicator" category="pt" />
+
+### DataTableSortOrder
+
+<DocTable name="DataTableSortOrder" category="api" />
+
+<DocTable name="DataTableSortOrder" category="pt" />
+
+### DataTableFilter
+
+<DocTable name="DataTableFilter" category="api" />
+
+| Attribute      | Value                                        |
+| -------------- | -------------------------------------------- |
+| `data-scope`   | `"datatable"`                                |
+| `data-part`    | `"filter"`                                   |
+| `data-display` | `"row"` \| `"menu"`                          |
+| `data-active`  | Present when the column has an active filter |
+
+<DocTable name="DataTableFilter" category="pt" />
+
+### DataTablePagination
+
+<DocTable name="DataTablePagination" category="api" />
+
+<DocTable name="DataTablePagination" category="pt" />
+
+### DataTableSelection
+
+<DocTable name="DataTableSelection" category="api" />
+
+<DocTable name="DataTableSelection" category="pt" />
+
+### DataTableRowToggle
+
+<DocTable name="DataTableRowToggle" category="api" />
+
+| Attribute         | Value                                            |
+| ----------------- | ------------------------------------------------ |
+| `data-scope`      | `"datatable"`                                    |
+| `data-part`       | `"row-toggle"` (button) or `"row-toggle-spacer"` |
+| `data-tree-level` | Zero-based tree depth (tree mode only)           |
+| `aria-expanded`   | Reflects current expansion state                 |
+
+<DocTable name="DataTableRowToggle" category="pt" />
+
+### DataTableRowToggleIndicator
+
+<DocTable name="DataTableRowToggleIndicator" category="api" />
+
+<DocTable name="DataTableRowToggleIndicator" category="pt" />
+
+### DataTableRowExpansion
+
+<DocTable name="DataTableRowExpansion" category="api" />
+
+<DocTable name="DataTableRowExpansion" category="pt" />
+
+### DataTableRowGroupHeader / DataTableRowGroupFooter
+
+`<DataTable.RowGroupHeader>` and `<DataTable.RowGroupFooter>` render header / footer rows for grouped data when `groupField` is set on `Root`. They forward all props to a `<tr>` element and render the row only at the start (header) / end (footer) of each group as reported by the headless grouping metadata.
+
+```tsx
+<DataTable.TBody>
+    {({ item, index, groupMeta }) => (
+        <>
+            {groupMeta?.isGroupStart && (
+                <DataTable.RowGroupHeader>
+                    <DataTable.Cell colSpan={3}>{String(groupMeta.groupValue)}</DataTable.Cell>
+                </DataTable.RowGroupHeader>
+            )}
+            <DataTable.Row>{/* … */}</DataTable.Row>
+            {groupMeta?.isGroupEnd && (
+                <DataTable.RowGroupFooter>
+                    <DataTable.Cell colSpan={3}>Total: {groupMeta.groupCount}</DataTable.Cell>
+                </DataTable.RowGroupFooter>
+            )}
+        </>
+    )}
+</DataTable.TBody>
+```
+
+### DataTableCellEditor
+
+<DocTable name="DataTableCellEditor" category="api" />
+
+| Attribute        | Value                                         |
+| ---------------- | --------------------------------------------- |
+| `data-scope`     | `"datatable"`                                 |
+| `data-part`      | `"cell-editor"`                               |
+| `data-row-index` | The row index (used by Tab traversal)         |
+| `data-field`     | The field name (used by Tab traversal)        |
+| `data-row-key`   | The row key (used to track edits across sort) |
+| `data-editing`   | Present while the cell is in edit mode        |
+
+<DocTable name="DataTableCellEditor" category="pt" />
+
+### DataTableCellEditorDisplay
+
+<DocTable name="DataTableCellEditorDisplay" category="api" />
+
+<DocTable name="DataTableCellEditorDisplay" category="pt" />
+
+### DataTableCellEditorContent
+
+<DocTable name="DataTableCellEditorContent" category="api" />
+
+<DocTable name="DataTableCellEditorContent" category="pt" />
+
+### DataTableRowEditor
+
+<DocTable name="DataTableRowEditor" category="api" />
+
+<DocTable name="DataTableRowEditor" category="pt" />
+
+### DataTableRowEditorInit
+
+<DocTable name="DataTableRowEditorInit" category="api" />
+
+<DocTable name="DataTableRowEditorInit" category="pt" />
+
+### DataTableRowEditorSave
+
+<DocTable name="DataTableRowEditorSave" category="api" />
+
+<DocTable name="DataTableRowEditorSave" category="pt" />
+
+### DataTableRowEditorCancel
+
+<DocTable name="DataTableRowEditorCancel" category="api" />
+
+<DocTable name="DataTableRowEditorCancel" category="pt" />
+
+### DataTableColumnToggle
+
+<DocTable name="DataTableColumnToggle" category="api" />
+
+<DocTable name="DataTableColumnToggle" category="pt" />
+
+### DataTableColumnReorder
+
+<DocTable name="DataTableColumnReorder" category="api" />
+
+<DocTable name="DataTableColumnReorder" category="pt" />
+
+### DataTableColumnReorderTarget
+
+<DocTable name="DataTableColumnReorderTarget" category="api" />
+
+<DocTable name="DataTableColumnReorderTarget" category="pt" />
+
+### DataTableColumnResizer
+
+<DocTable name="DataTableColumnResizer" category="api" />
+
+<DocTable name="DataTableColumnResizer" category="pt" />
+
+### DataTableColumnResizeIndicator
+
+<DocTable name="DataTableColumnResizeIndicator" category="api" />
+
+<DocTable name="DataTableColumnResizeIndicator" category="pt" />
+
+### DataTableRowReorder
+
+<DocTable name="DataTableRowReorder" category="api" />
+
+<DocTable name="DataTableRowReorder" category="pt" />
+
+### DataTableExport
+
+<DocTable name="DataTableExport" category="api" />
+
+<DocTable name="DataTableExport" category="pt" />
+
+### DataTableLoading
+
+<DocTable name="DataTableLoading" category="api" />
+
+<DocTable name="DataTableLoading" category="pt" />
+
+### DataTableEmptyTBody
+
+<DocTable name="DataTableEmptyTBody" category="api" />
+
+<DocTable name="DataTableEmptyTBody" category="pt" />
+
+## Accessibility
+
+### Screen Reader
+
+`DataTable.Table` applies `role="table"` for flat data and `role="treegrid"` when `treeMode` is enabled. Each row exposes `role="row"` plus `aria-rowindex` (1-based) and, in tree mode, `aria-level`, `aria-expanded`, `aria-posinset`, and `aria-setsize`. Cells use `role="gridcell"`. Sort triggers expose `role="button"`, `aria-sort`, and a descriptive `aria-label`. Selection wrappers forward checkbox/radio semantics from the underlying input. Provide an accessible name on `Root` via `aria-label` or `aria-labelledby` when the table has no visible heading.
+
+### Keyboard Support
+
+| Key                               | Function                                                                                      |
+| --------------------------------- | --------------------------------------------------------------------------------------------- |
+| `tab`                             | Moves focus through interactive elements (sort triggers, filter inputs, rows).                |
+| `arrow up` / `arrow down`         | Moves focus between rows when a row is focused.                                               |
+| `shift + arrow up` / `arrow down` | Extends row selection while moving focus.                                                     |
+| `arrow left`                      | In tree mode, collapses the focused row, or moves focus to its parent if already collapsed.   |
+| `arrow right`                     | In tree mode, expands the focused row, or moves focus to its first child if already expanded. |
+| `home` / `end`                    | Moves focus to the first / last row.                                                          |
+| `space`                           | Toggles selection on the focused row.                                                         |
+| `enter`                           | Toggles selection on the focused row, or opens the first editable cell in `cell` edit mode.   |
+| `escape`                          | Cancels the active cell edit and returns focus to the row.                                    |
+| `tab` (in cell edit)              | Commits the edit and moves to the next editable cell, wrapping across rows.                   |
+| `shift + tab` (in cell edit)      | Commits the edit and moves to the previous editable cell.                                     |
+| `enter` (in cell edit)            | Commits the edit and stays in place.                                                          |