@redsift/ds-mcp-server 12.3.1-muiv6-alpha.2

package/data/docs/patterns.json

@@ -0,0 +1,712 @@
+[
+  {
+    "name": "Datagrid Page",
+    "slug": "datagrid-page",
+    "description": "Full-page MUI DataGrid with built-in Toolbar (columns, filters, density, export, quick search). Uses GridColDef[] with custom column types (rsString, rsNumber, rsSingleSelect), renderCell with TextCell and Pill, pagination, and checkboxSelection. All filtering, sorting, and pagination happen client-side — all rows are loaded into the DataGrid at once. Optionally includes bulk selection actions (rowSelectionModel + onRowSelectionModelChange). For server-side data handling, see the Server Datagrid Page pattern. Matches the table pattern used across OnDMARC, Certificates, and Brand Trust.",
+    "components": [
+      "DataGrid",
+      "TextCell",
+      "StatefulDataGrid",
+      "Pill",
+      "Button",
+      "Flexbox",
+      "Text",
+      "Badge",
+      "Icon",
+      "IconButton",
+      "IconButtonLink"
+    ],
+    "packages": ["@redsift/table", "@redsift/design-system", "@mui/x-data-grid-pro"],
+    "layout": "DataGrid with autoHeight, pagination, pageSize, built-in Toolbar via componentsProps.toolbar.showQuickFilter. Optional bulk actions bar when selectionModel.length > 0.",
+    "tags": [
+      "table",
+      "datagrid",
+      "list",
+      "pagination",
+      "filter",
+      "toolbar",
+      "bulk-actions",
+      "GridColDef",
+      "filterModel",
+      "checkboxSelection",
+      "client-side"
+    ],
+    "demoPath": "patterns/datagrid-page/example",
+    "whenToUse": [
+      "You need a filterable, sortable, paginated table of records",
+      "The full dataset can be loaded upfront (typically under ~1,000 rows)",
+      "All filtering, sorting, and pagination can happen client-side in the browser",
+      "You want built-in column visibility, density, export, and quick search with zero backend work",
+      "You need optional bulk selection with contextual action buttons"
+    ],
+    "whenNotToUse": [
+      "The dataset has thousands or millions of rows — use Server Datagrid Page instead",
+      "Sorting or filtering logic must live on the backend (e.g. ElasticSearch, SQL) — use Server Datagrid Page instead"
+    ],
+    "anatomy": [
+      "Toolbar — Flexbox wrapping GridToolbarContainer with filter, columns, density, export, quick search controls",
+      "DataGrid — the table itself, configured with autoHeight, pagination, checkboxSelection, and GridColDef[] columns",
+      "Bulk Action Bar — Flexbox row shown when selectionModel.length > 0, with Pill (count) and action Buttons"
+    ],
+    "features": [
+      {
+        "name": "Column definitions",
+        "required": true,
+        "description": "GridColDef[] with custom types: rsString, rsNumber, rsSingleSelect, rsMultipleSelect, boolean, date"
+      },
+      {
+        "name": "Toolbar",
+        "required": true,
+        "description": "Built-in toolbar with filter, columns, density, export, and quick search controls"
+      },
+      {
+        "name": "Pagination",
+        "required": true,
+        "description": "Client-side pagination with configurable page size (rowsPerPageOptions)"
+      },
+      { "name": "Sorting", "required": true, "description": "Client-side column sorting (built into DataGrid)" },
+      { "name": "Filtering", "required": true, "description": "Client-side column filtering (built into DataGrid)" },
+      {
+        "name": "Custom cell renderers",
+        "required": true,
+        "description": "renderCell returning TextCell, Pill, Icon, IconButtonLink"
+      },
+      {
+        "name": "Checkbox selection",
+        "required": false,
+        "description": "checkboxSelection + rowSelectionModel + onRowSelectionModelChange"
+      },
+      {
+        "name": "Bulk action bar",
+        "required": false,
+        "description": "Contextual buttons shown when rows are selected"
+      },
+      {
+        "name": "Actions column",
+        "required": false,
+        "description": "Column with IconButtonLink for row-level navigation"
+      },
+      {
+        "name": "Quick search",
+        "required": false,
+        "description": "GridToolbarQuickFilter for text search across all columns"
+      }
+    ],
+    "stateHooks": [
+      {
+        "name": "selectionModel",
+        "type": "GridSelectionModel",
+        "initial": "[]",
+        "description": "Tracks which rows are checked"
+      }
+    ],
+    "dataContract": "type Row = {\n  id: string;\n  label: string;\n  active: boolean;\n  status: 'active' | 'warning' | 'critical' | 'expired';\n  category: string;\n  score: number;\n  expiry: string;\n  tags: string[];\n};",
+    "implementationSteps": [
+      "Define your row type — Create a TypeScript type Row. Every row must have a unique id field.",
+      "Define column definitions — Create a GridColDef[] array with RS custom column types (rsString, rsNumber, rsSingleSelect, rsMultipleSelect). Add renderCell for rich content.",
+      "Create the toolbar — Build a CustomToolbar using GridToolbarContainer with filter, columns, density, export, and quick search controls.",
+      "Set up state — Add useState<GridSelectionModel>([]) for checkbox selection (if needed).",
+      "Render the DataGrid — Pass rows, columns, autoHeight, pagination, pageSize, rowsPerPageOptions, checkboxSelection, components={{ Toolbar: CustomToolbar }}.",
+      "Add bulk action bar — Conditionally render when selectionModel.length > 0.",
+      "Handle edge cases — Add loading state (loading prop), empty state (custom NoRowsOverlay), and error state (conditional render with retry).",
+      "Verify — Test pagination breakpoints, filter operators, column visibility toggle, density switching, and export."
+    ],
+    "variants": [
+      {
+        "name": "Loading State",
+        "slug": "with-loading",
+        "description": "DataGrid with loading={true} showing the built-in loading overlay"
+      },
+      {
+        "name": "Empty State",
+        "slug": "with-empty-state",
+        "description": "DataGrid with rows={[]} and a custom NoRowsOverlay"
+      },
+      {
+        "name": "Error State",
+        "slug": "with-error",
+        "description": "Error banner with retry button above the DataGrid"
+      }
+    ],
+    "accessibility": [
+      "Arrow keys navigate between cells",
+      "Page Up / Page Down move between pages",
+      "Space toggles checkbox selection on the focused row",
+      "Tab moves focus between the toolbar and the grid",
+      "Every IconButtonLink in actions column needs aria-label",
+      "Custom NoRowsOverlay content must be announced to screen readers"
+    ],
+    "relatedPatterns": [
+      {
+        "slug": "server-datagrid-page",
+        "relationship": "Use when the dataset is too large to load entirely, or when filtering/sorting must happen server-side"
+      },
+      {
+        "slug": "drilldown-datagrid-page",
+        "relationship": "Use when you want summary DataCards above the grid with one-way filter push"
+      },
+      {
+        "slug": "crossfiltered-datagrid-page",
+        "relationship": "Use when DataCard counts should recalculate as filters change (two-way sync)"
+      }
+    ]
+  },
+  {
+    "name": "Server Datagrid Page",
+    "slug": "server-datagrid-page",
+    "description": "Full-page MUI DataGrid where filtering, sorting, and pagination are all handled server-side. Uses paginationMode='server', sortingMode='server', filterMode='server' with controlled rowCount and loading props. The same column types and toolbar as the client-side Datagrid Page pattern, but only the current page of data is fetched per request. Filter changes are debounced to avoid excessive requests. Ideal for datasets too large to load entirely in the browser.",
+    "components": [
+      "DataGrid",
+      "TextCell",
+      "Pill",
+      "Button",
+      "Flexbox",
+      "Text",
+      "Badge",
+      "Icon",
+      "IconButton",
+      "IconButtonLink"
+    ],
+    "packages": ["@redsift/table", "@redsift/design-system", "@mui/x-data-grid-pro"],
+    "layout": "DataGrid with autoHeight, paginationMode='server', sortingMode='server', filterMode='server', rowCount, loading, built-in Toolbar. Optional bulk actions bar when selectionModel.length > 0.",
+    "tags": [
+      "table",
+      "datagrid",
+      "server-side",
+      "pagination",
+      "paginationMode",
+      "filterMode",
+      "sortingMode",
+      "loading",
+      "rowCount",
+      "filter",
+      "toolbar",
+      "bulk-actions",
+      "GridColDef",
+      "filterModel",
+      "sortModel",
+      "debounce"
+    ],
+    "demoPath": "patterns/server-datagrid-page/example",
+    "whenToUse": [
+      "The dataset has thousands or millions of records that cannot be loaded into the browser",
+      "Filtering, sorting, or pagination logic must live on the backend (ElasticSearch, SQL, API)",
+      "You need the server to return the total matching count alongside the current page of results",
+      "Filter changes should be debounced to avoid excessive requests during rapid typing"
+    ],
+    "whenNotToUse": [
+      "The dataset is small enough to load entirely (under ~1,000 rows) — use Datagrid Page instead",
+      "All data is available upfront and filtering can happen in the browser — use Datagrid Page instead"
+    ],
+    "anatomy": [
+      "Toolbar — Flexbox wrapping GridToolbarContainer with filter, columns, density, export, quick search controls",
+      "DataGrid — the table configured with paginationMode='server', sortingMode='server', filterMode='server', loading, and rowCount",
+      "Bulk Action Bar — Flexbox row shown when selectionModel.length > 0, with Pill (count) and action Buttons"
+    ],
+    "features": [
+      {
+        "name": "Server-side pagination",
+        "required": true,
+        "description": "paginationMode='server' with controlled page, pageSize, rowCount"
+      },
+      {
+        "name": "Server-side sorting",
+        "required": true,
+        "description": "sortingMode='server' with controlled sortModel + onSortModelChange"
+      },
+      {
+        "name": "Server-side filtering",
+        "required": true,
+        "description": "filterMode='server' with controlled filterModel + onFilterModelChange"
+      },
+      { "name": "Loading overlay", "required": true, "description": "loading prop set to true during fetches" },
+      {
+        "name": "Row count",
+        "required": true,
+        "description": "rowCount prop set to total matching records from server response"
+      },
+      {
+        "name": "Debounced filter changes",
+        "required": true,
+        "description": "300ms debounce on onFilterModelChange to avoid excessive requests"
+      },
+      {
+        "name": "Column definitions",
+        "required": true,
+        "description": "GridColDef[] with custom types: rsString, rsNumber, rsSingleSelect, rsMultipleSelect"
+      },
+      {
+        "name": "Toolbar",
+        "required": true,
+        "description": "Built-in toolbar with filter, columns, density, export, and quick search"
+      },
+      {
+        "name": "Custom cell renderers",
+        "required": true,
+        "description": "renderCell returning TextCell, Pill, Icon, IconButtonLink"
+      },
+      { "name": "Checkbox selection", "required": false, "description": "checkboxSelection + rowSelectionModel" },
+      {
+        "name": "Bulk action bar",
+        "required": false,
+        "description": "Contextual buttons shown when rows are selected"
+      },
+      {
+        "name": "Quick search",
+        "required": false,
+        "description": "GridToolbarQuickFilter with server-side text search"
+      }
+    ],
+    "stateHooks": [
+      {
+        "name": "rows",
+        "type": "Row[]",
+        "initial": "[]",
+        "description": "Rows returned from the server for the current page"
+      },
+      {
+        "name": "totalRows",
+        "type": "number",
+        "initial": "0",
+        "description": "Total matching records (for pagination)"
+      },
+      { "name": "loading", "type": "boolean", "initial": "true", "description": "Whether a fetch is in progress" },
+      { "name": "page", "type": "number", "initial": "0", "description": "0-based current page index" },
+      { "name": "pageSize", "type": "number", "initial": "10", "description": "Number of rows per page" },
+      { "name": "sortModel", "type": "GridSortModel", "initial": "[]", "description": "Current sort configuration" },
+      {
+        "name": "filterModel",
+        "type": "GridFilterModel",
+        "initial": "{ items: [] }",
+        "description": "Current filter configuration"
+      },
+      {
+        "name": "selectionModel",
+        "type": "GridSelectionModel",
+        "initial": "[]",
+        "description": "Tracks which rows are checked"
+      },
+      {
+        "name": "quickFilterText",
+        "type": "string",
+        "initial": "''",
+        "description": "Text for quick search across columns"
+      },
+      {
+        "name": "debounceRef",
+        "type": "useRef<ReturnType<typeof setTimeout>>",
+        "initial": "undefined",
+        "description": "Ref for debouncing filter changes"
+      }
+    ],
+    "dataContract": "type Row = {\n  id: string;\n  label: string;\n  active: boolean;\n  status: 'active' | 'warning' | 'critical' | 'expired';\n  category: string;\n  score: number;\n  expiry: string;\n  tags: string[];\n};\n\ntype FetchParams = {\n  page: number;\n  pageSize: number;\n  sortModel: GridSortModel;\n  filterModel: GridFilterModel;\n  quickFilterText: string;\n};\n\ntype FetchResult = {\n  rows: Row[];\n  totalRows: number;\n};",
+    "implementationSteps": [
+      "Define your row type — Create a TypeScript type Row. Every row must have a unique id field.",
+      "Create your fetch function — Implement an async function matching the FetchParams → FetchResult contract. If using React Query, wrap it in a useQuery hook.",
+      "Define column definitions — Create a GridColDef[] array with RS custom column types. Add renderCell for rich content.",
+      "Create the toolbar — Build a CustomToolbar using GridToolbarContainer with filter, columns, density, export, and quick search controls.",
+      "Set up state — Add all hooks: rows, totalRows, loading, page, pageSize, sortModel, filterModel, selectionModel, quickFilterText, debounce ref.",
+      "Wire the fetch effect — Use useEffect to call your fetch function whenever page, pageSize, sortModel, filterModel, or quickFilterText changes.",
+      "Configure the DataGrid — Pass paginationMode='server', sortingMode='server', filterMode='server', loading, rowCount={totalRows}, and all controlled state handlers.",
+      "Debounce filter changes — Use a 300ms setTimeout in onFilterModelChange. Reset to page 0 on filter change.",
+      "Add bulk action bar — Conditionally render when selectionModel.length > 0.",
+      "Handle edge cases — Add loading state, empty state (custom NoRowsOverlay), and error state (conditional render with retry).",
+      "Verify — Test page navigation, sort toggling, filter operators, debounced quick search, loading overlay, empty results, and error recovery."
+    ],
+    "variants": [
+      {
+        "name": "Loading State",
+        "slug": "with-loading",
+        "description": "Initial loading state before first fetch completes"
+      },
+      {
+        "name": "Empty State",
+        "slug": "with-empty-state",
+        "description": "Server returns zero results after filtering — shows custom NoRowsOverlay with clear filters button"
+      },
+      {
+        "name": "Error State",
+        "slug": "with-error",
+        "description": "Fetch rejects with error — shows error banner with retry button"
+      }
+    ],
+    "accessibility": [
+      "Arrow keys navigate between cells",
+      "Page Up / Page Down move between pages",
+      "Space toggles checkbox selection on the focused row",
+      "Tab moves focus between the toolbar and the grid",
+      "Every IconButtonLink in actions column needs aria-label",
+      "Loading state should set aria-busy='true' on the container",
+      "Error messages should use aria-live='polite' for screen reader announcement",
+      "Custom NoRowsOverlay content must be announced to screen readers"
+    ],
+    "relatedPatterns": [
+      {
+        "slug": "datagrid-page",
+        "relationship": "Use when all data can be loaded upfront and filtering/sorting can happen client-side"
+      },
+      {
+        "slug": "drilldown-datagrid-page",
+        "relationship": "Use when you want summary DataCards above the grid with one-way filter push"
+      },
+      {
+        "slug": "crossfiltered-datagrid-page",
+        "relationship": "Use when DataCard counts should recalculate as filters change (two-way sync)"
+      }
+    ]
+  },
+  {
+    "name": "Drilldown Datagrid Page",
+    "slug": "drilldown-datagrid-page",
+    "description": "Extends the Datagrid Page with summary DataCards placed above the grid. Each DataCard contains DrilldownItems showing aggregate counts for a field (status, category, active). Clicking a DrilldownItem adds an isAnyOf filter to the DataGrid — a one-click shortcut. This is a one-way interaction: DataCard counts always reflect the full (unfiltered) dataset. When the user sets an is or isNot filter via the filter panel, the DataCard selection clears and clicking a DrilldownItem overwrites with isAnyOf.",
+    "components": [
+      "DataGrid",
+      "TextCell",
+      "DataCard",
+      "DataCard.Header",
+      "DataCard.Body",
+      "DataCard.Listbox",
+      "DrilldownItem",
+      "Pill",
+      "Button",
+      "Flexbox",
+      "Text",
+      "Icon",
+      "IconButtonLink"
+    ],
+    "packages": ["@redsift/table", "@redsift/design-system", "@redsift/dashboard", "@mui/x-data-grid-pro"],
+    "layout": "Flexbox column: DataCard row (Flexbox gap=12px flexWrap=wrap with 1-N DataCards), then DataGrid with autoHeight, pagination, controlled filterModel + onFilterModelChange. Optional bulk actions bar when selectionModel.length > 0.",
+    "tags": [
+      "table",
+      "datagrid",
+      "datacard",
+      "drilldown",
+      "drilldown-item",
+      "filter",
+      "isAnyOf",
+      "summary-cards",
+      "kpi",
+      "one-way",
+      "filterModel",
+      "client-side"
+    ],
+    "demoPath": "patterns/drilldown-datagrid-page/example",
+    "whenToUse": [
+      "You want summary KPI cards above a filterable table",
+      "Clicking a card value should add a filter to the datagrid as a convenience shortcut",
+      "DataCard counts should always show totals from the full dataset, regardless of active filters",
+      "The dataset is small enough to load entirely (under ~1,000 rows)"
+    ],
+    "whenNotToUse": [
+      "DataCard counts should recalculate when filters change — use Cross-filtered Datagrid Page instead",
+      "No summary cards are needed — use Datagrid Page instead",
+      "The dataset is too large to load entirely — combine with Server Datagrid Page patterns"
+    ],
+    "anatomy": [
+      "DataCard Row — Flexbox with 1-N DataCards, each containing DataCard.Header and DataCard.Listbox or DataCard.Body with DrilldownItem children",
+      "Toolbar — Flexbox wrapping GridToolbarContainer with filter, columns, density, export, quick search controls",
+      "DataGrid — the table with controlled filterModel + onFilterModelChange",
+      "Bulk Action Bar — Flexbox row shown when selectionModel.length > 0, with Pill (count) and action Buttons"
+    ],
+    "features": [
+      {
+        "name": "DataCard aggregation",
+        "required": true,
+        "description": "DataCard components showing aggregate counts per field from the full dataset"
+      },
+      {
+        "name": "DrilldownItem filter push",
+        "required": true,
+        "description": "Clicking a DrilldownItem adds an isAnyOf filter to the DataGrid filterModel"
+      },
+      {
+        "name": "Listbox multi-select",
+        "required": true,
+        "description": "DataCard.Listbox with selectionMode=multiple and controlled values for multi-value fields"
+      },
+      {
+        "name": "is/isNot clearing",
+        "required": true,
+        "description": "When filter panel has is/isNot for a card's field, the DataCard selection clears"
+      },
+      {
+        "name": "Column definitions",
+        "required": true,
+        "description": "GridColDef[] with custom types: rsString, rsNumber, rsSingleSelect, rsMultipleSelect"
+      },
+      {
+        "name": "Toolbar",
+        "required": true,
+        "description": "Built-in toolbar with filter, columns, density, export, and quick search controls"
+      },
+      {
+        "name": "Custom cell renderers",
+        "required": true,
+        "description": "renderCell returning TextCell, Pill, Icon, IconButtonLink"
+      },
+      {
+        "name": "Boolean toggle",
+        "required": false,
+        "description": "DataCard.Body with DrilldownItem onClick for boolean fields (active/inactive)"
+      },
+      {
+        "name": "Checkbox selection",
+        "required": false,
+        "description": "checkboxSelection + rowSelectionModel"
+      },
+      {
+        "name": "Bulk action bar",
+        "required": false,
+        "description": "Contextual buttons shown when rows are selected"
+      }
+    ],
+    "stateHooks": [
+      {
+        "name": "filterModel",
+        "type": "GridFilterModel",
+        "initial": "{ items: [] }",
+        "description": "Controlled filter state shared between DataCards and DataGrid"
+      },
+      {
+        "name": "selectionModel",
+        "type": "GridSelectionModel",
+        "initial": "[]",
+        "description": "Tracks which rows are checked"
+      }
+    ],
+    "dataContract": "type Row = {\n  id: string;\n  label: string;\n  active: boolean;\n  status: 'active' | 'warning' | 'critical' | 'expired' | 'revoked';\n  category: 'primary' | 'secondary' | 'tertiary';\n  score: number;\n  expiry: string;\n  tags: string[];\n};\n\ntype AggregateCounts = {\n  status: Record<string, number>;\n  category: Record<string, number>;\n  activeCount: number;\n  inactiveCount: number;\n};",
+    "implementationSteps": [
+      "Define your row type — Create a TypeScript type Row. Every row must have a unique id field.",
+      "Compute aggregate counts — Write a useAggregateCounts(allRows) hook that counts occurrences per field value from the full dataset.",
+      "Build DataCards — Create a DataCard for each summarized field with DataCard.Header and DataCard.Listbox or DataCard.Body containing DrilldownItem children.",
+      "Write filter helpers — Implement getSelectedFromFilterModel (reads isAnyOf values, returns [] for is/isNot) and updateFilterModel (always writes isAnyOf).",
+      "Wire DataCard handlers — Connect DataCard.Listbox onChange to updateFilterModel. For boolean cards, connect DrilldownItem onClick to updateBooleanFilter.",
+      "Render the DataGrid — Pass filterModel and onFilterModelChange so the filter panel stays synced with DataCard selections.",
+      "Handle edge cases — Add loading, empty, and error states for both DataCards and DataGrid."
+    ],
+    "variants": [
+      {
+        "name": "Loading State",
+        "slug": "with-loading",
+        "description": "DataCards with isLoading={true} and DataGrid with loading={true}"
+      },
+      {
+        "name": "Empty State",
+        "slug": "with-empty-state",
+        "description": "DataCards with zero counts and DataGrid with custom NoRowsOverlay"
+      },
+      {
+        "name": "Error State",
+        "slug": "with-error",
+        "description": "Error banner above DataCards and DataGrid with retry button"
+      }
+    ],
+    "accessibility": [
+      "DrilldownItem renders as a button — focusable via Tab, activates with Enter or Space",
+      "DataCard.Listbox supports Arrow Up/Down to navigate and Space to toggle selection",
+      "Selected DrilldownItems receive aria-selected=true from the Listbox",
+      "DataGrid keyboard navigation works unchanged (arrows, Page Up/Down, Space for checkboxes)",
+      "Error banners use role=alert and aria-live=polite for screen reader announcement"
+    ],
+    "relatedPatterns": [
+      {
+        "slug": "crossfiltered-datagrid-page",
+        "relationship": "Use when DataCard counts should recalculate as filters change (two-way sync)"
+      },
+      {
+        "slug": "datagrid-page",
+        "relationship": "Use when no summary cards are needed"
+      },
+      {
+        "slug": "server-datagrid-page",
+        "relationship": "Use when the dataset is too large to load entirely"
+      }
+    ]
+  },
+  {
+    "name": "Cross-filtered Datagrid Page",
+    "slug": "crossfiltered-datagrid-page",
+    "description": "Extends the Drilldown Datagrid Page with two-way synchronization between DataCards and the DataGrid filter panel. DrilldownItem clicks add isAnyOf filters. Filter panel changes update DataCard selection state. DataCard counts recalculate against the cross-filtered dataset — each card computes counts by applying all filters except its own field, preventing a card from zeroing out its non-selected values. When the user sets is/isNot via the filter panel, the DataCard clears. Clicking a DrilldownItem overwrites with isAnyOf.",
+    "components": [
+      "DataGrid",
+      "TextCell",
+      "DataCard",
+      "DataCard.Header",
+      "DataCard.Body",
+      "DataCard.Listbox",
+      "DrilldownItem",
+      "Pill",
+      "Button",
+      "Flexbox",
+      "Text",
+      "Icon",
+      "IconButtonLink"
+    ],
+    "packages": ["@redsift/table", "@redsift/design-system", "@redsift/dashboard", "@mui/x-data-grid-pro"],
+    "layout": "Flexbox column: DataCard row (cross-filtered counts), then DataGrid with autoHeight, pagination, controlled filterModel + onFilterModelChange. Rows are pre-filtered client-side via applyFilters. Optional bulk actions bar.",
+    "tags": [
+      "table",
+      "datagrid",
+      "datacard",
+      "drilldown",
+      "drilldown-item",
+      "cross-filter",
+      "crossfilter",
+      "two-way",
+      "bidirectional",
+      "filter",
+      "isAnyOf",
+      "summary-cards",
+      "kpi",
+      "dashboard",
+      "filterModel",
+      "client-side"
+    ],
+    "demoPath": "patterns/crossfiltered-datagrid-page/example",
+    "whenToUse": [
+      "You want dashboard-style KPI cards that stay in sync with the table below",
+      "DataCard counts should recalculate as filters change — reflecting the current filter context",
+      "Clicking a card value should add a filter to the datagrid",
+      "Changing the filter panel should update the card selection (bidirectional)",
+      "The dataset is small enough to load entirely (under ~1,000 rows)"
+    ],
+    "whenNotToUse": [
+      "DataCard counts should always show full-dataset totals — use Drilldown Datagrid Page instead",
+      "No summary cards are needed — use Datagrid Page instead",
+      "The dataset is too large to load entirely — combine with Server Datagrid Page patterns"
+    ],
+    "anatomy": [
+      "DataCard Row — Flexbox with 1-N DataCards. Counts are cross-filtered: each card excludes its own field from the filter calculation",
+      "Toolbar — Flexbox wrapping GridToolbarContainer with filter, columns, density, export, quick search controls",
+      "DataGrid — the table with controlled filterModel + onFilterModelChange. Rows are pre-filtered client-side",
+      "Bulk Action Bar — Flexbox row shown when selectionModel.length > 0, with Pill (count) and action Buttons"
+    ],
+    "features": [
+      {
+        "name": "Cross-filtered aggregation",
+        "required": true,
+        "description": "DataCard counts recompute from rows filtered by all fields except the card's own field"
+      },
+      {
+        "name": "Two-way filter sync",
+        "required": true,
+        "description": "DataCard selections derive from filterModel; DataCard clicks update filterModel"
+      },
+      {
+        "name": "DrilldownItem filter push",
+        "required": true,
+        "description": "Clicking a DrilldownItem adds an isAnyOf filter to the DataGrid filterModel"
+      },
+      {
+        "name": "Listbox multi-select",
+        "required": true,
+        "description": "DataCard.Listbox with selectionMode=multiple and controlled values for multi-value fields"
+      },
+      {
+        "name": "is/isNot clearing",
+        "required": true,
+        "description": "When filter panel has is/isNot for a card's field, the DataCard selection clears"
+      },
+      {
+        "name": "Client-side row filtering",
+        "required": true,
+        "description": "applyFilters function filters the full row set by the current filterModel"
+      },
+      {
+        "name": "Column definitions",
+        "required": true,
+        "description": "GridColDef[] with custom types: rsString, rsNumber, rsSingleSelect, rsMultipleSelect"
+      },
+      {
+        "name": "Toolbar",
+        "required": true,
+        "description": "Built-in toolbar with filter, columns, density, export, and quick search controls"
+      },
+      {
+        "name": "Custom cell renderers",
+        "required": true,
+        "description": "renderCell returning TextCell, Pill, Icon, IconButtonLink"
+      },
+      {
+        "name": "Boolean toggle",
+        "required": false,
+        "description": "DataCard.Body with DrilldownItem onClick for boolean fields (active/inactive)"
+      },
+      {
+        "name": "Checkbox selection",
+        "required": false,
+        "description": "checkboxSelection + rowSelectionModel"
+      },
+      {
+        "name": "Bulk action bar",
+        "required": false,
+        "description": "Contextual buttons shown when rows are selected"
+      }
+    ],
+    "stateHooks": [
+      {
+        "name": "filterModel",
+        "type": "GridFilterModel",
+        "initial": "{ items: [] }",
+        "description": "Controlled filter state — single source of truth shared between DataCards and DataGrid"
+      },
+      {
+        "name": "selectionModel",
+        "type": "GridSelectionModel",
+        "initial": "[]",
+        "description": "Tracks which rows are checked"
+      }
+    ],
+    "dataContract": "type Row = {\n  id: string;\n  label: string;\n  active: boolean;\n  status: 'active' | 'warning' | 'critical' | 'expired' | 'revoked';\n  category: 'primary' | 'secondary' | 'tertiary';\n  score: number;\n  expiry: string;\n  tags: string[];\n};\n\ntype AggregateCounts = {\n  status: Record<string, number>;\n  category: Record<string, number>;\n  activeCount: number;\n  inactiveCount: number;\n};",
+    "implementationSteps": [
+      "Define your row type — Create a TypeScript type Row. Every row must have a unique id field.",
+      "Write the applyFilters function — Accepts (rows, filterModel, excludeField?). Supports isAnyOf, is, isNot operators. When excludeField is provided, skips filters for that field.",
+      "Write computeCounts — Accepts a row array and returns aggregate counts per field value.",
+      "Write filter helpers — Implement getSelectedFromFilterModel (reads isAnyOf values, returns [] for is/isNot) and updateFilterModel (always writes isAnyOf).",
+      "Compute cross-filtered counts — For each DataCard, call computeCounts(applyFilters(allRows, filterModel, cardField)).",
+      "Compute filtered rows for DataGrid — Call applyFilters(allRows, filterModel) without excluding any field.",
+      "Build DataCards — Create a DataCard for each field with DataCard.Listbox (multi-select with controlled values) or DataCard.Body (boolean toggle). Wire onChange/onClick to updateFilterModel/updateBooleanFilter.",
+      "Render the DataGrid — Pass rows={filteredRows}, filterModel, and onFilterModelChange={setFilterModel}.",
+      "Handle edge cases — Add loading, empty, and error states for both DataCards and DataGrid."
+    ],
+    "variants": [
+      {
+        "name": "Loading State",
+        "slug": "with-loading",
+        "description": "DataCards with isLoading={true} and DataGrid with loading={true}"
+      },
+      {
+        "name": "Empty State",
+        "slug": "with-empty-state",
+        "description": "DataCards with zero counts and DataGrid with custom NoRowsOverlay"
+      },
+      {
+        "name": "Error State",
+        "slug": "with-error",
+        "description": "Error banner above DataCards and DataGrid with retry button"
+      }
+    ],
+    "accessibility": [
+      "DrilldownItem renders as a button — focusable via Tab, activates with Enter or Space",
+      "DataCard.Listbox supports Arrow Up/Down to navigate and Space to toggle selection",
+      "Selected DrilldownItems receive aria-selected=true from the Listbox",
+      "DataGrid keyboard navigation works unchanged (arrows, Page Up/Down, Space for checkboxes)",
+      "Error banners use role=alert and aria-live=polite for screen reader announcement",
+      "As counts update in real-time, screen readers can query the updated values"
+    ],
+    "relatedPatterns": [
+      {
+        "slug": "drilldown-datagrid-page",
+        "relationship": "Use when DataCard counts should always show full-dataset totals (one-way)"
+      },
+      {
+        "slug": "datagrid-page",
+        "relationship": "Use when no summary cards are needed"
+      },
+      {
+        "slug": "server-datagrid-page",
+        "relationship": "Use when the dataset is too large to load entirely"
+      }
+    ]
+  }
+]