@cdx-ui/components 0.3.12 → 0.3.14

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

@@ -107,10 +107,10 @@ type Product = {
 };
 
 const columns: GridColDef<Product>[] = [
-  { field: 'name', headerName: 'Name', type: 'string', flex: 1, minWidth: 140 },
+  { 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: 180 },
+  { field: 'updated', headerName: 'Updated', type: 'dateTime', width: 200 },
   { field: 'active', headerName: 'Active', type: 'boolean', width: 100 },
   {
     field: 'status',
@@ -193,10 +193,10 @@ type Product = {
 };
 
 const columns: GridColDef<Product>[] = [
-  { field: 'name', headerName: 'Name', type: 'string', flex: 1, minWidth: 140 },
+  { 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: 180 },
+  { field: 'updated', headerName: 'Updated', type: 'dateTime', width: 200 },
   { field: 'active', headerName: 'Active', type: 'boolean', width: 100 },
   {
     field: 'status',
@@ -808,6 +808,550 @@ 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.
@@ -1138,4 +1682,6 @@ sort. `valueOptions` is required when `type` is `singleSelect`.
 
 ## 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.