@cdx-ui/components 0.3.11 → 0.3.13

package/docs/components/data-grid/content.md

@@ -15,14 +15,14 @@ import {
   Text,
   VStack,
 } from '@cdx-ui/components';
-import { DataGrid } from '@cdx-ui/data-grid';
+import { DataGrid, gridDeltaNumberColDef, gridPolarityNumberColDef } from '@cdx-ui/data-grid';
 ```
 
 ## Basic
 
 Pass `rows` and `columns`. This account grid starts with the features most applications need: formatted values, status `Chip` cells, search, header filters, selection, sorting, and pagination.
 
-Search is **not** always on. Set `showToolbar` to show the search field (same opt-in as MUI Community’s toolbar / quick filter). Set `headerFilters` to show per-column filter inputs in a second header row.
+Search and the filter button are **not** always on. Set `showToolbar` to show both (same opt-in as MUI Community’s toolbar). Set `headerFilters` to show per-column filter inputs in a second header row.
 
 The grid is a fixed viewport like MUI Data Grid Community: **300px** tall by default. Column headers stay visible while rows scroll; pagination stays at the bottom. Override height with a `className` such as `h-full` or a spacing-scale height (`h-130`).
 
@@ -65,7 +65,7 @@ const columns: GridColDef<Account>[] = [
     field: 'balance',
     headerName: 'Balance',
     width: 140,
-    align: 'end',
+    type: 'number',
     valueFormatter: (_, row) => currencyFormatter.format(row.balance),
   },
 ];
@@ -87,6 +87,174 @@ export default function DataGridBasicDemo() {
 }
 ```
 
+## Column types
+
+Set `type` on a column for MUI Community defaults: alignment, display formatting, and client sort. `number` right-aligns and formats with the locale (no forced decimals). `date` and `dateTime` expect a `Date` — convert strings with `valueGetter`. `boolean` renders a check or close icon with accessible Yes / No text. `singleSelect` shows the matching `valueOptions` label. Explicit `align`, `headerAlign`, `valueFormatter`, and `renderCell` override the defaults.
+
+```tsx
+import { DataGrid, type GridColDef } from '@cdx-ui/data-grid';
+
+// GridValidRowModel's index signature rejects otherwise equivalent interfaces.
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  listed: Date;
+  updated: Date;
+  active: boolean;
+  status: string;
+};
+
+const columns: GridColDef<Product>[] = [
+  { field: 'name', headerName: 'Name', type: 'string', flex: 1, minWidth: 160 },
+  { field: 'price', headerName: 'Price', type: 'number', width: 120 },
+  { field: 'listed', headerName: 'Listed', type: 'date', width: 140 },
+  { field: 'updated', headerName: 'Updated', type: 'dateTime', width: 200 },
+  { field: 'active', headerName: 'Active', type: 'boolean', width: 100 },
+  {
+    field: 'status',
+    headerName: 'Status',
+    type: 'singleSelect',
+    width: 140,
+    valueOptions: [
+      { value: 'open', label: 'Open' },
+      { value: 'pending', label: 'Pending review' },
+      { value: 'closed', label: 'Closed' },
+    ],
+  },
+];
+
+const rows: Product[] = [
+  {
+    id: '1',
+    name: 'Operating reserve',
+    price: 1234.5,
+    listed: new Date(2026, 0, 5),
+    updated: new Date(2026, 0, 5, 14, 30, 0),
+    active: true,
+    status: 'open',
+  },
+  {
+    id: '2',
+    name: 'Payroll sweep',
+    price: 80,
+    listed: new Date(2026, 2, 12),
+    updated: new Date(2026, 2, 12, 9, 0, 0),
+    active: false,
+    status: 'pending',
+  },
+  {
+    id: '3',
+    name: 'Merchant hold',
+    price: 10450,
+    listed: new Date(2025, 10, 2),
+    updated: new Date(2025, 11, 18, 16, 45, 0),
+    active: true,
+    status: 'closed',
+  },
+];
+
+export default function DataGridColumnTypesDemo() {
+  return (
+    <DataGrid
+      rows={rows}
+      columns={columns}
+      hideFooter
+      headerFilters
+      aria-label="Column types"
+      className="h-80"
+    />
+  );
+}
+```
+
+## Filters
+
+`showToolbar` shows the search field and a filter button. The panel has one row per condition: column, an operator for that column's type, and a value. And or Or on the second row applies to the whole model, not to a single row.
+
+Text columns use contains, does not contain, equals, starts with, ends with, is empty, is not empty, and is any of. Number columns use `=`, `!=`, `>`, `>=`, `<`, `<=`, plus the empty and is any of operators. Date columns use is, is not, is after, is on or after, is before, and is on or before. Boolean columns use is, and the value is any, true, or false. `singleSelect` columns use is, is not, and is any of.
+
+An item with no `operator` still means contains, which is what each header filter input writes. `isEmpty` and `isNotEmpty` need no value. `isAnyOf` takes a list. Type numbers without grouping (`10450`, not `10,450`). Date and date time values use the date field, and a date time filter matches that calendar day. Pass `filterLogicOperator` beside `filterModel`. In server mode the grid sends the operator and the typed value and does not filter `rows`.
+
+```tsx
+import { DataGrid, type GridColDef } from '@cdx-ui/data-grid';
+
+// GridValidRowModel's index signature rejects otherwise equivalent interfaces.
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  listed: Date;
+  updated: Date;
+  active: boolean;
+  status: string;
+};
+
+const columns: GridColDef<Product>[] = [
+  { field: 'name', headerName: 'Name', type: 'string', flex: 1, minWidth: 160 },
+  { field: 'price', headerName: 'Price', type: 'number', width: 120 },
+  { field: 'listed', headerName: 'Listed', type: 'date', width: 140 },
+  { field: 'updated', headerName: 'Updated', type: 'dateTime', width: 200 },
+  { field: 'active', headerName: 'Active', type: 'boolean', width: 100 },
+  {
+    field: 'status',
+    headerName: 'Status',
+    type: 'singleSelect',
+    width: 140,
+    valueOptions: [
+      { value: 'open', label: 'Open' },
+      { value: 'pending', label: 'Pending review' },
+      { value: 'closed', label: 'Closed' },
+    ],
+  },
+];
+
+const rows: Product[] = [
+  {
+    id: '1',
+    name: 'Operating reserve',
+    price: 1234.5,
+    listed: new Date(2026, 0, 5),
+    updated: new Date(2026, 0, 5, 14, 30, 0),
+    active: true,
+    status: 'open',
+  },
+  {
+    id: '2',
+    name: 'Payroll sweep',
+    price: 80,
+    listed: new Date(2026, 2, 12),
+    updated: new Date(2026, 2, 12, 9, 0, 0),
+    active: false,
+    status: 'pending',
+  },
+  {
+    id: '3',
+    name: 'Merchant hold',
+    price: 10450,
+    listed: new Date(2025, 10, 2),
+    updated: new Date(2025, 11, 18, 16, 45, 0),
+    active: true,
+    status: 'closed',
+  },
+];
+
+export default function DataGridFiltersDemo() {
+  return (
+    <DataGrid
+      rows={rows}
+      columns={columns}
+      showToolbar
+      hideFooter
+      autoHeight
+      aria-label="Filters"
+    />
+  );
+}
+```
+
 ## Rich cells
 
 Use `renderCell` to compose Forge UI components inside a cell. This operations view combines `Avatar`, `Chip`, `ProgressBar`, and an action `Menu`, while `valueFormatter` keeps sortable numeric data separate from its display value.
@@ -163,13 +331,13 @@ const columns: GridColDef<Account>[] = [
     field: 'balance',
     headerName: 'Balance',
     width: 140,
-    align: 'end',
+    type: 'number',
     valueFormatter: (_, row) => currencyFormatter.format(row.balance),
   },
   {
     field: 'actions',
     headerName: 'Actions',
-    width: 72,
+    width: 100,
     align: 'center',
     headerAlign: 'center',
     sortable: false,
@@ -262,9 +430,144 @@ export default function DataGridNumericColumnsDemo() {
 }
 ```
 
+## Polarity and delta numbers
+
+`gridPolarityNumberColDef` colors a number by its sign. A positive value uses success, a negative value uses danger and a minus sign (−), and zero stays primary.
+
+`gridDeltaNumberColDef` shows a change. The symbol follows the direction of the value, and the color follows `increaseIsGood`: an increase is success when an increase is favorable and danger when it is not, and a decrease does the opposite. Zero stays primary. `symbol` is `arrow` (no icon at zero), `trendline` (including a flat icon at zero), or `sign` (+ or − before the value). Arrow and trendline hide the minus sign.
+
+Spread the preset into the column. It sets `type` to `number`, so sorting compares the raw number and empty values sort last. The header filter matches that number's locale text, not the colored cell. A `valueFormatter` passed to the preset, or set on the column after it, formats the visible number. `density` selects body-md or body-sm.
+
+Pass `increaseIsGood: false` when a rising number is unfavorable, such as contract terminations. The screen reader hears the direction, for example "Decrease 2.5%".
+
+```tsx
+import {
+  DataGrid,
+  gridDeltaNumberColDef,
+  gridPolarityNumberColDef,
+  type GridColDef,
+} from '@cdx-ui/data-grid';
+
+// GridValidRowModel's index signature rejects otherwise equivalent interfaces.
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+type PerformanceRow = {
+  id: string;
+  metric: string;
+  amount: number;
+  change: number;
+  terminations: number;
+};
+
+const currency = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+});
+
+const points = new Intl.NumberFormat('en-US', {
+  minimumFractionDigits: 1,
+  maximumFractionDigits: 1,
+});
+
+const formatPoints = (value: number) => `${points.format(value)}%`;
+
+const rows: PerformanceRow[] = [
+  { id: 'interest', metric: 'Interest income', amount: 1280.5, change: 2.5, terminations: -3.1 },
+  { id: 'fees', metric: 'Fee income', amount: -640, change: -1.2, terminations: 4.2 },
+  { id: 'transfers', metric: 'Transfers', amount: 0, change: 0, terminations: 0 },
+];
+
+const columns: GridColDef<PerformanceRow>[] = [
+  { field: 'metric', headerName: 'Metric', flex: 1, minWidth: 160 },
+  {
+    field: 'amount',
+    headerName: 'Amount',
+    width: 140,
+    ...gridPolarityNumberColDef<PerformanceRow>({
+      valueFormatter: (value) => currency.format(value),
+    }),
+  },
+  {
+    field: 'change',
+    headerName: 'Change',
+    width: 120,
+    ...gridDeltaNumberColDef<PerformanceRow>({
+      increaseIsGood: true,
+      symbol: 'arrow',
+      valueFormatter: formatPoints,
+    }),
+  },
+  {
+    field: 'terminations',
+    headerName: 'Terminations',
+    width: 150,
+    ...gridDeltaNumberColDef<PerformanceRow>({
+      increaseIsGood: false,
+      symbol: 'arrow',
+      valueFormatter: formatPoints,
+    }),
+  },
+  {
+    field: 'trend',
+    headerName: 'Trend',
+    width: 120,
+    ...gridDeltaNumberColDef<PerformanceRow>({
+      increaseIsGood: true,
+      symbol: 'trendline',
+      valueFormatter: formatPoints,
+    }),
+    valueGetter: (_value, row) => row.change,
+  },
+  {
+    field: 'signed',
+    headerName: 'Signed change',
+    width: 150,
+    ...gridDeltaNumberColDef<PerformanceRow>({
+      increaseIsGood: true,
+      symbol: 'sign',
+      valueFormatter: formatPoints,
+    }),
+    valueGetter: (_value, row) => row.change,
+  },
+  {
+    field: 'terminationsTrend',
+    headerName: 'Terminations trend',
+    width: 170,
+    ...gridDeltaNumberColDef<PerformanceRow>({
+      increaseIsGood: false,
+      symbol: 'trendline',
+      valueFormatter: formatPoints,
+    }),
+    valueGetter: (_value, row) => row.terminations,
+  },
+  {
+    field: 'terminationsSigned',
+    headerName: 'Terminations sign',
+    width: 170,
+    ...gridDeltaNumberColDef<PerformanceRow>({
+      increaseIsGood: false,
+      symbol: 'sign',
+      valueFormatter: formatPoints,
+    }),
+    valueGetter: (_value, row) => row.terminations,
+  },
+];
+
+export default function DataGridNumberCellsDemo() {
+  return (
+    <DataGrid
+      rows={rows}
+      columns={columns}
+      hideFooter
+      autoHeight
+      aria-label="Performance with polarity and delta numbers"
+    />
+  );
+}
+```
+
 ## Toolbar actions
 
-`toolbarActions` is an extension slot for your own toolbar controls beside search — export, density, view toggles, and so on. DataGrid does not ship toolbar buttons; you compose them and wire `onPress` to state that drives grid props.
+`toolbarActions` is an extension slot for your own controls beside search and the filter button — export, density, view toggles, and so on. Wire `onPress` to state that drives grid props.
 
 A common pattern is a **Filters** button that toggles the `headerFilters` row on demand instead of leaving filter inputs always visible:
 
@@ -505,13 +808,657 @@ export default function DataGridCheckboxCellsDemo() {
 }
 ```
 
+## Column visibility
+
+Set a field to `false` in `columnVisibilityModel` to hide its column while keeping it in `columns`. A hidden column still sorts, filters, and matches search, and the filter panel still lists it, so a single visible column can show a rich cell while other fields drive the toolbar controls. With `treeData`, the first visible column becomes the tree column. The grid has no built-in control for showing or hiding columns, so keep the model in your own state. The API picker in [Tree data](#tree-data) uses it.
+
+## Tree data
+
+Set `treeData` and return each row's path from `getTreeDataPath`, such as `['Statements', '2026', 'Checking 4821 Oct.pdf']`. The first column becomes the tree column: an expand toggle, then the row content, indented by depth. Pass `groupingColDef` to override that column's header, width, or cell. A row attaches to its nearest ancestor that exists in `rows`, so a path does not need a row for every level.
+
+Every other column renders, sorts, and filters as it does in a flat grid, so parents and children share the same columns. Leave a value empty where it does not apply to a level, such as a folder's size. Sorting reorders siblings at every level and keeps children under their parent.
+
+Groups start collapsed. `defaultGroupingExpansionDepth` expands groups down to a depth (`-1` expands everything), and `isGroupExpandedByDefault` decides per row. While search, header filters, or the filter panel are active, a row stays visible when it or a descendant matches, and every group on the way to a match opens. Clearing the filter restores the groups the user had open.
+
+Pagination counts top-level rows, so a page never splits a group. Tree data sorts and filters on the client. It cannot be combined with server pagination, sorting, or filtering.
+
+This document library uses `groupingColDef` to draw a file-type icon and each folder's file count in the tree column, and opens the current year's statements with `isGroupExpandedByDefault`.
+
+```tsx
+import { HStack, Icon, type IconColor, Text } from '@cdx-ui/components';
+import {
+  DataGrid,
+  type DataGridProps,
+  type GridColDef,
+  type GridTreeNodeParams,
+} from '@cdx-ui/data-grid';
+import { Csv, Description, Folder, type ForgeIcon, PictureAsPdf, TableChart } from '@cdx-ui/icons';
+
+type DocumentType = 'Folder' | 'PDF' | 'CSV' | 'Spreadsheet' | 'Document';
+
+// GridValidRowModel's index signature rejects otherwise equivalent interfaces.
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+type BankDocument = {
+  id: string;
+  path: string[];
+  type: DocumentType;
+  modified: Date;
+  size?: number;
+};
+
+const typeIcons: Record<DocumentType, { icon: ForgeIcon; color: IconColor }> = {
+  Folder: { icon: Folder, color: 'action' },
+  PDF: { icon: PictureAsPdf, color: 'danger' },
+  CSV: { icon: Csv, color: 'success' },
+  Spreadsheet: { icon: TableChart, color: 'success' },
+  Document: { icon: Description, color: 'info' },
+};
+
+const documents: BankDocument[] = [
+  { id: 'statements', path: ['Statements'], type: 'Folder', modified: new Date(2026, 9, 31) },
+  {
+    id: 'statements-2026',
+    path: ['Statements', '2026'],
+    type: 'Folder',
+    modified: new Date(2026, 9, 31),
+  },
+  {
+    id: 'checking-2026-10',
+    path: ['Statements', '2026', 'Checking 4821 Oct.pdf'],
+    type: 'PDF',
+    modified: new Date(2026, 9, 31),
+    size: 184_320,
+  },
+  {
+    id: 'checking-2026-09',
+    path: ['Statements', '2026', 'Checking 4821 Sep.pdf'],
+    type: 'PDF',
+    modified: new Date(2026, 8, 30),
+    size: 176_128,
+  },
+  {
+    id: 'savings-2026-q3',
+    path: ['Statements', '2026', 'Savings 9310 Q3.pdf'],
+    type: 'PDF',
+    modified: new Date(2026, 8, 30),
+    size: 98_304,
+  },
+  {
+    id: 'statements-2025',
+    path: ['Statements', '2025'],
+    type: 'Folder',
+    modified: new Date(2025, 11, 31),
+  },
+  {
+    id: 'checking-2025-12',
+    path: ['Statements', '2025', 'Checking 4821 Dec.pdf'],
+    type: 'PDF',
+    modified: new Date(2025, 11, 31),
+    size: 192_512,
+  },
+  {
+    id: 'savings-2025-q4',
+    path: ['Statements', '2025', 'Savings 9310 Q4.pdf'],
+    type: 'PDF',
+    modified: new Date(2025, 11, 31),
+    size: 101_376,
+  },
+  { id: 'tax', path: ['Tax documents'], type: 'Folder', modified: new Date(2026, 0, 31) },
+  {
+    id: 'tax-1099-int',
+    path: ['Tax documents', '1099-INT 2025.pdf'],
+    type: 'PDF',
+    modified: new Date(2026, 0, 31),
+    size: 64_512,
+  },
+  {
+    id: 'tax-1098',
+    path: ['Tax documents', '1098 Mortgage 2025.pdf'],
+    type: 'PDF',
+    modified: new Date(2026, 0, 29),
+    size: 71_680,
+  },
+  { id: 'loans', path: ['Loans'], type: 'Folder', modified: new Date(2026, 8, 15) },
+  {
+    id: 'mortgage',
+    path: ['Loans', 'Home mortgage 7702'],
+    type: 'Folder',
+    modified: new Date(2026, 8, 15),
+  },
+  {
+    id: 'mortgage-closing',
+    path: ['Loans', 'Home mortgage 7702', 'Closing disclosure.pdf'],
+    type: 'PDF',
+    modified: new Date(2024, 4, 22),
+    size: 1_258_291,
+  },
+  {
+    id: 'mortgage-amortization',
+    path: ['Loans', 'Home mortgage 7702', 'Amortization.xlsx'],
+    type: 'Spreadsheet',
+    modified: new Date(2024, 4, 22),
+    size: 48_128,
+  },
+  {
+    id: 'mortgage-escrow',
+    path: ['Loans', 'Home mortgage 7702', 'Escrow analysis.pdf'],
+    type: 'PDF',
+    modified: new Date(2026, 8, 15),
+    size: 215_040,
+  },
+  {
+    id: 'auto-loan',
+    path: ['Loans', 'Auto loan 3318'],
+    type: 'Folder',
+    modified: new Date(2026, 6, 2),
+  },
+  {
+    id: 'auto-payoff',
+    path: ['Loans', 'Auto loan 3318', 'Payoff quote.pdf'],
+    type: 'PDF',
+    modified: new Date(2026, 6, 2),
+    size: 52_224,
+  },
+  {
+    id: 'transactions-export',
+    path: ['Transactions Oct 2026.csv'],
+    type: 'CSV',
+    modified: new Date(2026, 10, 2),
+    size: 23_552,
+  },
+  {
+    id: 'direct-deposit',
+    path: ['Direct deposit form.pdf'],
+    type: 'PDF',
+    modified: new Date(2026, 2, 9),
+    size: 88_064,
+  },
+  {
+    id: 'beneficiary',
+    path: ['Beneficiaries.docx'],
+    type: 'Document',
+    modified: new Date(2025, 10, 18),
+    size: 36_864,
+  },
+];
+
+const fileCountOf = new Map(
+  documents
+    .filter((folder) => folder.type === 'Folder')
+    .map((folder) => [
+      folder.id,
+      documents.filter(
+        (doc) =>
+          doc.type !== 'Folder' &&
+          folder.path.every((segment, index) => doc.path[index] === segment),
+      ).length,
+    ]),
+);
+
+const sizeFormatter = new Intl.NumberFormat('en-US', { maximumFractionDigits: 1 });
+
+function formatSize(bytes: number) {
+  if (bytes < 1024) {
+    return `${sizeFormatter.format(bytes)} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${sizeFormatter.format(bytes / 1024)} KB`;
+  }
+  return `${sizeFormatter.format(bytes / (1024 * 1024))} MB`;
+}
+
+const columns: GridColDef<BankDocument>[] = [
+  { field: 'name', headerName: 'Name', valueGetter: (_, row) => row.path.at(-1) },
+  { field: 'type', headerName: 'Type', width: 120 },
+  { field: 'modified', headerName: 'Modified', type: 'date', width: 130 },
+  {
+    field: 'size',
+    headerName: 'Size',
+    type: 'number',
+    width: 100,
+    valueFormatter: (value) => (typeof value === 'number' ? formatSize(value) : ''),
+  },
+];
+
+const groupingColDef: DataGridProps<BankDocument>['groupingColDef'] = {
+  flex: 1,
+  minWidth: 240,
+  renderCell: ({ row }) => {
+    const { icon, color } = typeIcons[row.type];
+    const isFolder = row.type === 'Folder';
+    return (
+      <HStack space="sm" className="min-w-0 flex-1 items-center">
+        <Icon as={icon} color={color} />
+        <Text numberOfLines={1} color={isFolder ? 'action' : 'primary'}>
+          {isFolder
+            ? `${String(row.path.at(-1))} (${String(fileCountOf.get(row.id) ?? 0)})`
+            : row.path.at(-1)}
+        </Text>
+      </HStack>
+    );
+  },
+};
+
+const getTreeDataPath = (row: BankDocument) => row.path;
+const isGroupExpandedByDefault = ({ id }: GridTreeNodeParams<BankDocument>) =>
+  id === 'statements' || id === 'statements-2026';
+
+export default function DataGridTreeDataColumnsDemo() {
+  return (
+    <DataGrid
+      rows={documents}
+      columns={columns}
+      treeData
+      getTreeDataPath={getTreeDataPath}
+      groupingColDef={groupingColDef}
+      isGroupExpandedByDefault={isGroupExpandedByDefault}
+      aria-label="Documents"
+      className="h-130"
+    />
+  );
+}
+```
+
+With `checkboxSelection`, the checkbox sits in the tree column. By default, selecting a group selects its descendants, and a group is checked when all of its children are and shows a mixed state when only some are. Set `rowSelectionPropagation` to `{ descendants: false, parents: false }` to select rows independently. Selection is kept for rows that a filter hides, unlike MUI X, and select-all applies to the rows that match the filter.
+
+This picker shows each API as one rich row. `description` and `method` are hidden with `columnVisibilityModel` (see [Column visibility](#column-visibility)), so search also matches descriptions. The filter panel still lists the hidden `method` column, so filtering by method uses the panel that already exists.
+
+```tsx
+import { useState } from 'react';
+import { Chip, HStack, Text, VStack } from '@cdx-ui/components';
+import { DataGrid, type GridColDef, type GridRowSelectionModel } from '@cdx-ui/data-grid';
+
+type Method = 'GET' | 'POST' | 'PUT' | 'DELETE';
+
+// GridValidRowModel's index signature rejects otherwise equivalent interfaces.
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+type Api = {
+  id: string;
+  path: string[];
+  description: string;
+  method?: Method;
+};
+
+const methodColors: Record<Method, 'info' | 'success' | 'warning' | 'danger'> = {
+  GET: 'info',
+  POST: 'success',
+  PUT: 'warning',
+  DELETE: 'danger',
+};
+
+const apis: Api[] = [
+  { id: 'accounts', path: ['Accounts'], description: 'Account information and balances' },
+  { id: 'oauth', path: ['Accounts', 'OAuth V1'], description: 'Token-scoped account APIs' },
+  {
+    id: 'list-accounts',
+    path: ['Accounts', 'OAuth V1', 'List customer accounts'],
+    description: 'Returns every account the customer can see',
+    method: 'GET',
+  },
+  {
+    id: 'close-account',
+    path: ['Accounts', 'OAuth V1', 'Close account'],
+    description: 'Closes an account with a zero balance',
+    method: 'DELETE',
+  },
+  {
+    id: 'open-account',
+    path: ['Accounts', 'OAuth V1', 'Open account'],
+    description: 'Opens a new deposit account',
+    method: 'POST',
+  },
+  { id: 'balances', path: ['Accounts', 'Balances'], description: 'Real-time balance APIs' },
+  {
+    id: 'get-balance',
+    path: ['Accounts', 'Balances', 'Get balance'],
+    description: 'Returns the available and ledger balance',
+    method: 'GET',
+  },
+  { id: 'payments', path: ['Payments'], description: 'Transfers and bill pay' },
+  {
+    id: 'create-transfer',
+    path: ['Payments', 'Create transfer'],
+    description: 'Moves money between two accounts',
+    method: 'POST',
+  },
+  {
+    id: 'update-payee',
+    path: ['Payments', 'Update payee'],
+    description: 'Changes a bill pay payee',
+    method: 'PUT',
+  },
+];
+
+const columns: GridColDef<Api>[] = [
+  {
+    field: 'name',
+    headerName: 'APIs',
+    flex: 1,
+    minWidth: 280,
+    valueGetter: (_, row) => row.path.at(-1),
+    renderCell: ({ row }) => (
+      <HStack space="sm" className="flex-1 items-center">
+        <VStack className="min-w-0 flex-1">
+          <Text numberOfLines={1} weight="medium">
+            {row.path.at(-1)}
+          </Text>
+          <Text numberOfLines={1} color="secondary" size="sm">
+            {row.description}
+          </Text>
+        </VStack>
+        {row.method ? (
+          <Chip color={methodColors[row.method]} size="small">
+            <Chip.Label>{row.method}</Chip.Label>
+          </Chip>
+        ) : null}
+      </HStack>
+    ),
+  },
+  { field: 'description', headerName: 'Description' },
+  { field: 'method', headerName: 'Method' },
+];
+
+const columnVisibilityModel = { description: false, method: false };
+const endpointCount = apis.filter((api) => api.method).length;
+
+export default function DataGridTreeDataSelectionDemo() {
+  const [selection, setSelection] = useState<GridRowSelectionModel>({
+    type: 'include',
+    ids: new Set(['list-accounts', 'create-transfer']),
+  });
+  const selectedEndpoints = apis.filter((api) => api.method && selection.ids.has(api.id)).length;
+
+  return (
+    <DataGrid
+      rows={apis}
+      columns={columns}
+      columnVisibilityModel={columnVisibilityModel}
+      treeData
+      getTreeDataPath={(row) => row.path}
+      defaultGroupingExpansionDepth={1}
+      checkboxSelection
+      rowSelectionModel={selection}
+      onRowSelectionModelChange={setSelection}
+      showToolbar
+      toolbarActions={
+        <Text color="secondary" size="sm">
+          {`${selectedEndpoints.toString()} of ${endpointCount.toString()} endpoints selected`}
+        </Text>
+      }
+      hideFooter
+      aria-label="APIs"
+      className="h-130"
+    />
+  );
+}
+```
+
+## Detail panel
+
+Return content from `getDetailPanelContent` to add a toggle column at the start of the grid. Opening a row shows a panel under it that spans every column. Return `null` for rows that have no details, and those rows get no toggle. Use `defaultDetailPanelExpandedRowIds`, or control `detailPanelExpandedRowIds` with `onDetailPanelExpandedRowIdsChange`, to choose which panels are open. The panel grows to fit its content.
+
+The panel scrolls with the grid when it is wider than the viewport, so keep its content narrow enough to read without horizontal scrolling. When any column is pinned to start, the toggle column pins after the selection column.
+
+```tsx
+import { Button, Chip, HStack, Text, VStack } from '@cdx-ui/components';
+import { DataGrid, type GridColDef } from '@cdx-ui/data-grid';
+import { Check, Close, ContentCopy } from '@cdx-ui/icons';
+
+// GridValidRowModel's index signature rejects otherwise equivalent interfaces.
+// eslint-disable-next-line @typescript-eslint/consistent-type-definitions
+type AuditEvent = {
+  id: string;
+  time: string;
+  user: string;
+  category: 'Access' | 'Change';
+  domain: string;
+  eventType: string;
+  status: 'Success' | 'Failed';
+  details: [label: string, value: string][];
+};
+
+const events: AuditEvent[] = [
+  {
+    id: 'evt_8f2a6c91',
+    time: 'Jan 12, 2026, 11:51:06 AM',
+    user: 'Mary Jane',
+    category: 'Change',
+    domain: 'Track and publish',
+    eventType: 'Login',
+    status: 'Failed',
+    details: [
+      ['Event ID', 'evt_8f2a6c91'],
+      ['Organisation ID', 'org_acme'],
+      ['Category', 'change'],
+      ['Environment ID', 'env_production'],
+      ['Occurred at', '2026-01-12T11:51:06Z'],
+      ['Target collection', 'articles'],
+      ['Actor type', 'user'],
+      ['Version before', '12'],
+      ['User ID', 'usr_10482'],
+      ['Version after', '13'],
+      ['User email', 'mary.jane@example.com'],
+      ['Patch path', '/title'],
+      ['Correlation ID', 'req_7d4b9e23'],
+      ['HTTP status code', '403'],
+    ],
+  },
+  {
+    id: 'evt_51ab07e4',
+    time: 'Jan 12, 2026, 10:05:41 AM',
+    user: 'Peter Parker',
+    category: 'Access',
+    domain: 'Branding and theming',
+    eventType: 'History',
+    status: 'Success',
+    details: [
+      ['Event ID', 'evt_51ab07e4'],
+      ['Organisation ID', 'org_acme'],
+      ['Category', 'access'],
+      ['Environment ID', 'env_production'],
+      ['User ID', 'usr_20311'],
+      ['HTTP status code', '200'],
+    ],
+  },
+  {
+    id: 'evt_c3d94f10',
+    time: 'Jan 11, 2026, 4:18:22 PM',
+    user: 'Jane Cooper',
+    category: 'Access',
+    domain: 'Track and publish',
+    eventType: 'Login',
+    status: 'Success',
+    details: [
+      ['Event ID', 'evt_c3d94f10'],
+      ['Organisation ID', 'org_acme'],
+      ['User ID', 'usr_10077'],
+      ['HTTP status code', '200'],
+    ],
+  },
+];
+
+const columns: GridColDef<AuditEvent>[] = [
+  { field: 'time', headerName: 'Time', width: 220 },
+  { field: 'user', headerName: 'User', width: 140 },
+  {
+    field: 'category',
+    headerName: 'Category',
+    width: 120,
+    renderCell: ({ row }) => (
+      <Chip size="small" color={row.category === 'Access' ? 'info' : 'neutral'}>
+        <Chip.Label>{row.category}</Chip.Label>
+      </Chip>
+    ),
+  },
+  { field: 'domain', headerName: 'Domain', flex: 1, minWidth: 180 },
+  { field: 'eventType', headerName: 'Event type', width: 130 },
+  {
+    field: 'status',
+    headerName: 'Status',
+    width: 120,
+    renderCell: ({ row }) => (
+      <Chip size="small" color={row.status === 'Success' ? 'success' : 'danger'}>
+        <Chip.Icon as={row.status === 'Success' ? Check : Close} />
+        <Chip.Label>{row.status}</Chip.Label>
+      </Chip>
+    ),
+  },
+];
+
+function AuditEventDetails({ event }: { event: AuditEvent }) {
+  return (
+    <VStack space="md" className="rounded-lg bg-surface-secondary p-4">
+      <HStack className="flex-wrap">
+        {event.details.map(([label, value]) => (
+          <HStack key={label} space="md" className="w-1/2 py-1">
+            <Text color="secondary" size="sm" className="w-40">
+              {label}:
+            </Text>
+            <Text size="sm" className="flex-1">
+              {value}
+            </Text>
+          </HStack>
+        ))}
+      </HStack>
+      <Button
+        variant="outline"
+        size="small"
+        className="self-end"
+        onPress={() => {
+          void navigator.clipboard.writeText(
+            JSON.stringify(Object.fromEntries(event.details), null, 2),
+          );
+        }}
+      >
+        <Button.Icon as={ContentCopy} position="leading" />
+        <Button.Label>Copy</Button.Label>
+      </Button>
+    </VStack>
+  );
+}
+
+export default function DataGridDetailPanelDemo() {
+  return (
+    <DataGrid
+      rows={events}
+      columns={columns}
+      getDetailPanelContent={({ row }) => <AuditEventDetails event={row} />}
+      defaultDetailPanelExpandedRowIds={new Set(['evt_8f2a6c91'])}
+      hideFooter
+      aria-label="Audit log"
+      className="h-130"
+    />
+  );
+}
+```
+
+## Column pinning
+
+Pass `pinnedColumns` with `start` and/or `end` field lists so key columns stay visible while the grid scrolls horizontally. Deprecated `left` / `right` keys are aliases for `start` / `end` (same mapping as `align`). MUI X `initialState.pinnedColumns` moves to the `pinnedColumns` prop.
+
+Pinned columns use a fixed pixel `width` (default 100) and ignore `flex`. When `checkboxSelection` is on and any column is pinned to start, the selection column pins first at the start edge. The MUI X checkbox field `__check__` is accepted as an alias for that column.
+
+```tsx
+import { Chip, IconButton, Menu } from '@cdx-ui/components';
+import { DataGrid, type GridColDef } from '@cdx-ui/data-grid';
+import { MoreHoriz } from '@cdx-ui/icons';
+import { accounts, type Account, type AccountStatus } from './_data';
+
+const currencyFormatter = new Intl.NumberFormat('en-US', {
+  style: 'currency',
+  currency: 'USD',
+});
+
+const statusColors: Record<AccountStatus, 'success' | 'warning' | 'info' | 'neutral'> = {
+  Active: 'success',
+  Pending: 'warning',
+  Frozen: 'info',
+  Closed: 'neutral',
+};
+
+const columns: GridColDef<Account>[] = [
+  { field: 'id', headerName: 'Account', width: 120 },
+  { field: 'name', headerName: 'Name', width: 180 },
+  { field: 'type', headerName: 'Type', width: 140 },
+  {
+    field: 'status',
+    headerName: 'Status',
+    width: 120,
+    renderCell: ({ row }) => (
+      <Chip color={statusColors[row.status]} size="small">
+        <Chip.Label>{row.status}</Chip.Label>
+      </Chip>
+    ),
+  },
+  { field: 'owner', headerName: 'Owner', width: 160 },
+  {
+    field: 'balance',
+    headerName: 'Balance',
+    width: 140,
+    align: 'end',
+    valueFormatter: (_, row) => currencyFormatter.format(row.balance),
+  },
+  {
+    field: 'automation',
+    headerName: 'Automated',
+    width: 140,
+    valueFormatter: (_, row) => `${row.automation.toString()}%`,
+  },
+  {
+    field: 'actions',
+    headerName: 'Actions',
+    width: 100,
+    align: 'center',
+    headerAlign: 'center',
+    sortable: false,
+    filterable: false,
+    renderCell: ({ row }) => (
+      <Menu placement="bottom-end">
+        <Menu.Trigger asChild>
+          <IconButton
+            as={MoreHoriz}
+            variant="ghost"
+            size="small"
+            accessibilityLabel={`Actions for ${row.name}`}
+          />
+        </Menu.Trigger>
+        <Menu.Popup>
+          <Menu.Content accessibilityLabel={`${row.name} actions`}>
+            <Menu.Item>
+              <Menu.ItemLabel>View account</Menu.ItemLabel>
+            </Menu.Item>
+            <Menu.Item>
+              <Menu.ItemLabel>Assign owner</Menu.ItemLabel>
+            </Menu.Item>
+          </Menu.Content>
+        </Menu.Popup>
+      </Menu>
+    ),
+  },
+];
+
+export default function DataGridColumnPinningDemo() {
+  return (
+    <DataGrid
+      rows={accounts}
+      columns={columns}
+      pinnedColumns={{ start: ['id'], end: ['actions'] }}
+      aria-label="Accounts with pinned columns"
+      defaultPaginationModel={{ page: 0, pageSize: 5 }}
+      pageSizeOptions={[5, 10, 25]}
+      className="h-105"
+    />
+  );
+}
+```
+
 ## Server data
 
 Set `paginationMode="server"` and `sortingMode="server"` to let your data source own those operations. `filterMode` follows `paginationMode` unless you set it, so server pagination also means server filtering. Keep the models controlled, pass the current page in `rows`, and provide the full `rowCount` of matching rows.
 
-With server filtering, search and header filters no longer filter `rows`. Send `quickFilter` and `filterModel` to your data source instead. Both change on every keystroke, so debounce the request and return to page 0 when the debounced query changes, as this demo does. Passing `filterMode="client"` with server pagination filters only the current page of `rows`.
+With server filtering, search, header filters, and the filter panel no longer filter `rows`. Send `quickFilter`, `filterModel`, and `filterLogicOperator` to your data source instead. Search and header filters change on every keystroke, so debounce the request and return to page 0 when the debounced query changes, as this demo does. Passing `filterMode="client"` with server pagination filters only the current page of `rows`.
 
-`GridFilterItem` will gain an optional `operator` field, defaulting to `'contains'`, in a future minor release. Existing `{ field, value }` items keep working, so server handlers should treat a missing `operator` as `'contains'`.
+A missing `operator` still means contains, so existing `{ field, value }` items keep working. When `operator` is set, `value` is typed: a string, a number, a `Date`, a boolean, a `singleSelect` value, or an array for `isAnyOf`. `filterLogicOperator` is a separate prop and defaults to `and`.
 
 ```tsx
 import { useEffect, useMemo, useState } from 'react';
@@ -702,7 +1649,7 @@ export default function DataGridEmptyDemo() {
 
 ### DataGrid
 
-Web-only. Inspired by MUI Data Grid Community props; not a wrap of `@mui/x-data-grid`.
+Web-only. MUI X–shaped `rows` / `columns` API; not a wrap of `@mui/x-data-grid`.
 
 | Attribute   | Values      | Description |
 | ----------- | ----------- | ----------- |
@@ -712,25 +1659,29 @@ Web-only. Inspired by MUI Data Grid Community props; not a wrap of `@mui/x-data-
 
 Column definition. `valueGetter`, `valueFormatter`, and `renderCell` take no `apiRef`.
 Use `start`, `center`, or `end` for `align` and `headerAlign`; the legacy `left` and `right`
-values are deprecated aliases.
+values are deprecated aliases. `type` selects built-in alignment, formatting, and client
+sort. `valueOptions` is required when `type` is `singleSelect`.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `field` | `string` | — | — |
+| `field?` | `string` | — | — |
 | `headerName?` | `string` | — | — |
 | `width?` | `number` | — | — |
 | `minWidth?` | `number` | — | — |
 | `flex?` | `number` | — | — |
-| `align?` | `'start' \| 'center' \| 'end' \| 'left' \| 'right'` | `'start'` | Logical cell-content alignment. `left` and `right` are deprecated compatibility aliases for `start` and `end`. |
-| `headerAlign?` | `'start' \| 'center' \| 'end' \| 'left' \| 'right'` | — | Logical header-content alignment. Defaults to `align`. `left` and `right` are deprecated compatibility aliases for `start` and `end`. |
+| `align?` | `'start' \| 'center' \| 'end' \| 'left' \| 'right'` | — | — |
+| `headerAlign?` | `'start' \| 'center' \| 'end' \| 'left' \| 'right'` | — | — |
 | `sortable?` | `boolean` | — | — |
 | `filterable?` | `boolean` | — | — |
-| `type?` | `'string'` | — | — |
+| `type?` | `'string' \| 'number' \| 'boolean' \| 'date' \| 'dateTime' \| 'singleSelect'` | — | — |
 | `valueGetter?` | `((value: unknown, row: GridValidRowModel, col: GridColDef<GridValidRowModel>) => unknown)` | — | — |
 | `valueFormatter?` | `((value: unknown, row: GridValidRowModel, col: GridColDef<GridValidRowModel>) => ReactNode \| string)` | — | — |
 | `renderCell?` | `((params: GridRenderCellParams<GridValidRowModel>) => ReactNode)` | — | — |
 | `renderHeader?` | `(() => ReactNode)` | — | — |
+| `valueOptions?` | `readonly GridValueOption[] \| ((params: { row?: GridValidRowModel; }) => readonly GridValueOption[])` | — | — |
 
 ## Accessibility
 
-The grid renders a semantic HTML table on web. Sortable headers expose `aria-sort`. Select-all and row checkboxes are labelled.
+The grid renders a semantic HTML table on web. Sortable headers expose `aria-sort`. Select-all and row checkboxes are labelled.
+
+Tree and detail panel toggles are buttons with `aria-expanded`, labelled with the row they open, such as "Expand OAuth V1, Accounts". A partly selected tree group exposes `aria-checked="mixed"`. Expanding or collapsing never moves focus. When a filter removes the row that had focus, focus moves to the toolbar search field if `showToolbar` is on. Closing the filter panel with Escape, Remove all, or by removing the last filter returns focus to the control that opened it. A press outside the panel closes it and leaves focus where it went. The grid keeps table semantics rather than `treegrid`, so screen readers do not announce the tree level; the toggle label names the row's ancestors instead.