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

package/data/metadata.json

@@ -0,0 +1,4 @@
+{
+  "generatedAt": "2026-03-27T16:15:06.727Z",
+  "commitSha": "2c2f13c866eb3a49a10b4f0943ff599324f851b2"
+}

package/data/patterns/crossfiltered-datagrid-page.mdx

@@ -0,0 +1,386 @@
+import { Link } from '@redsift/design-system';
+import { DemoBlock } from '../../components/DemoBlock';
+import { CodeBlock } from '../../components/CodeBlock';
+import { FeatureTable } from '../../components/FeatureTable';
+import { RouterLink } from '../../components/RouterLink';
+
+## Introduction
+
+The Cross-filtered Datagrid Page extends the [Drilldown Datagrid Page](/patterns/drilldown-datagrid-page) with **two-way synchronization** between DataCards and the DataGrid filter panel. This means:
+
+- Clicking a **DrilldownItem** adds an `isAnyOf` filter to the DataGrid — just like the one-way pattern
+- Changing a filter in the **DataGrid filter panel** updates the DataCard selection state — the card highlights reflect the active filter
+- DataCard **counts recalculate** against the cross-filtered dataset — filtering by category changes the status counts, and vice versa
+
+Each DataCard's counts are computed by applying **all filters except the card's own field**. This prevents a card from filtering itself: selecting "active" in the Status card doesn't zero out the other status values — it only changes the Category and Active card counts.
+
+When the user sets an `is` or `isNot` filter via the filter panel, the corresponding DataCard **clears** — all DrilldownItems are deselected. Clicking a DrilldownItem after that overwrites the incompatible filter with a fresh `isAnyOf` item.
+
+## When to Use
+
+- 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)
+
+When **not** to use:
+
+- DataCard counts should always show full-dataset totals — use [Drilldown Datagrid Page](/patterns/drilldown-datagrid-page) instead
+- No summary cards are needed — use [Datagrid Page](/patterns/datagrid-page) instead
+- The dataset is too large to load entirely — combine with [Server Datagrid Page](/patterns/server-datagrid-page) patterns
+
+## Anatomy
+
+1. **DataCard Row** — `Flexbox` with 1–N `DataCard` components. Counts are cross-filtered: each card excludes its own field from the filter calculation
+2. **Toolbar** — `Flexbox` wrapping MUI's `GridToolbarContainer` with `GridToolbarFilterButton`, `GridToolbarColumnsButton`, `GridToolbarDensitySelector`, `GridToolbarExport`, and `GridToolbarQuickFilter`
+3. **DataGrid** — the table itself with controlled `filterModel` + `onFilterModelChange`. Rows are pre-filtered client-side
+4. **Bulk Action Bar** — a `Flexbox` row shown when `selectionModel.length > 0`, containing a `Pill` with the selection count and action `Button` components
+
+## Features
+
+<FeatureTable
+  features={[
+    {
+      feature: 'Cross-filtered aggregation',
+      required: true,
+      description: (
+        <>
+          DataCard counts recompute from rows filtered by all fields <strong>except</strong> the card's own field
+        </>
+      ),
+    },
+    {
+      feature: 'Two-way filter sync',
+      required: true,
+      description: (
+        <>
+          DataCard selections derive from <code>filterModel</code>; DataCard clicks update <code>filterModel</code>
+        </>
+      ),
+    },
+    {
+      feature: 'DrilldownItem filter push',
+      required: true,
+      description: (
+        <>
+          Clicking a <code>DrilldownItem</code> adds an <code>isAnyOf</code> filter to the DataGrid's{' '}
+          <code>filterModel</code>
+        </>
+      ),
+    },
+    {
+      feature: 'Listbox multi-select',
+      required: true,
+      description: (
+        <>
+          <code>DataCard.Listbox</code> with <code>{'selectionMode="multiple"'}</code> and controlled{' '}
+          <code>values</code> for multi-value fields
+        </>
+      ),
+    },
+    {
+      feature: (
+        <>
+          <code>is</code>/<code>isNot</code> clearing
+        </>
+      ),
+      required: true,
+      description: (
+        <>
+          When filter panel has <code>is</code>/<code>isNot</code> for a card's field, the DataCard selection clears
+        </>
+      ),
+    },
+    {
+      feature: 'Client-side row filtering',
+      required: true,
+      description: (
+        <>
+          <code>applyFilters</code> function filters the full row set by the current <code>filterModel</code>
+        </>
+      ),
+    },
+    {
+      feature: 'Column definitions',
+      required: true,
+      description: (
+        <>
+          <code>GridColDef[]</code> with custom types: <code>rsString</code>, <code>rsNumber</code>,{' '}
+          <code>rsSingleSelect</code>, <code>rsMultipleSelect</code>
+        </>
+      ),
+    },
+    {
+      feature: 'Toolbar',
+      required: true,
+      description: 'Built-in toolbar with filter, columns, density, export, and quick search controls',
+    },
+    {
+      feature: 'Custom cell renderers',
+      required: true,
+      description: (
+        <>
+          <code>renderCell</code> returning <code>TextCell</code>, <code>Pill</code>, <code>Icon</code>,{' '}
+          <code>IconButtonLink</code>
+        </>
+      ),
+    },
+    {
+      feature: 'Boolean toggle',
+      required: false,
+      description: (
+        <>
+          <code>DataCard.Body</code> with <code>DrilldownItem</code> <code>onClick</code> for boolean fields
+          (active/inactive)
+        </>
+      ),
+    },
+    {
+      feature: 'Checkbox selection',
+      required: false,
+      description: (
+        <>
+          <code>checkboxSelection</code> + <code>rowSelectionModel</code>
+        </>
+      ),
+    },
+    { feature: 'Bulk action bar', required: false, description: 'Contextual buttons shown when rows are selected' },
+  ]}
+/>
+
+### Components
+
+{/* prettier-ignore */}
+- <Link href="/table/datagrid" as={RouterLink}>DataGrid</Link> — the table itself (from `@redsift/table`)
+- <Link href="/dashboard/data-card" as={RouterLink}>DataCard</Link> — summary card container with colored border (from `@redsift/dashboard`)
+- <Link href="/dashboard/data-card" as={RouterLink}>DataCard.Header</Link> — card header with icon and title
+- <Link href="/dashboard/data-card" as={RouterLink}>DataCard.Body</Link> — static row container for DataRow or DrilldownItem
+- <Link href="/dashboard/data-card" as={RouterLink}>DataCard.Listbox</Link> — multi-select container synced with DataGrid filters
+- <Link href="/dashboard/drilldown-item" as={RouterLink}>DrilldownItem</Link> — numeric value with legend and filter icon (from `@redsift/dashboard`)
+- <Link href="/layout/flexbox" as={RouterLink}>Flexbox</Link> — page and toolbar layout
+- <Link href="/forms/button" as={RouterLink}>Button</Link> — toolbar and bulk action buttons
+- <Link href="/forms/icon-button-link" as={RouterLink}>IconButtonLink</Link> — action column navigation links
+- <Link href="/data-display/pill" as={RouterLink}>Pill</Link> — status badges in cells and count indicators
+- <Link href="/typography/text" as={RouterLink}>Text</Link> — cell content and labels
+- <Link href="/media-and-icons/icon" as={RouterLink}>Icon</Link> — toolbar icons and cell indicators
+
+## State Management
+
+<CodeBlock codeString={`import { useCallback, useMemo, useState } from 'react';
+import { GridFilterModel, GridSelectionModel } from '@mui/x-data-grid-pro';
+
+// Filter state — the single source of truth, shared between DataCards and DataGrid
+const [filterModel, setFilterModel] = useState<GridFilterModel>({ items: [] });
+
+// Selection state
+const [selectionModel, setSelectionModel] = useState<GridSelectionModel>([]);
+
+// Cross-filtered counts — each card excludes its own field from the filter
+const statusCounts = useMemo(
+() => computeCounts(applyFilters(allRows, filterModel, 'status')),
+[filterModel],
+);
+const categoryCounts = useMemo(
+() => computeCounts(applyFilters(allRows, filterModel, 'category')),
+[filterModel],
+);
+const activeCounts = useMemo(
+() => computeCounts(applyFilters(allRows, filterModel, 'active')),
+[filterModel],
+);
+
+// Rows displayed in the DataGrid — all filters applied (no exclusion)
+const filteredRows = useMemo(
+() => applyFilters(allRows, filterModel),
+[filterModel],
+);
+
+// Derive DataCard selections from filterModel (returns [] for is/isNot)
+const statusSelection = getSelectedFromFilterModel(filterModel, 'status');
+const categorySelection = getSelectedFromFilterModel(filterModel, 'category');
+`} />
+
+## Cross-filtering Logic
+
+<CodeBlock codeString={`// Apply filterModel to rows client-side.
+// When excludeField is provided, filters for that field are skipped —
+// this is how each DataCard gets counts that exclude its own field.
+function applyFilters(rows: Row[], filterModel: GridFilterModel, excludeField?: string): Row[] {
+  return rows.filter((row) => {
+    for (const item of filterModel.items) {
+      if (item.field === excludeField) continue;
+      if (!item.value || (Array.isArray(item.value) && item.value.length === 0)) continue;
+
+      const rowValue = row[item.field as keyof Row];
+
+      switch (item.operator) {
+        case 'isAnyOf': {
+          const values = Array.isArray(item.value) ? item.value : [item.value];
+          if (!values.includes(String(rowValue))) return false;
+          break;
+        }
+        case 'is': {
+          if (item.field === 'active') {
+            if (rowValue !== (item.value === 'true')) return false;
+          } else {
+            if (String(rowValue) !== String(item.value)) return false;
+          }
+          break;
+        }
+        case 'isNot': {
+          if (String(rowValue) === String(item.value)) return false;
+          break;
+        }
+        default:
+          break;
+      }
+    }
+    return true;
+
+});
+}
+
+// Compute aggregate counts from a row subset
+function computeCounts(rows: Row[]) {
+const status: Record<string, number> = {};
+const category: Record<string, number> = {};
+let activeCount = 0;
+let inactiveCount = 0;
+
+for (const row of rows) {
+status[row.status] = (status[row.status] || 0) + 1;
+category[row.category] = (category[row.category] || 0) + 1;
+if (row.active) activeCount++;
+else inactiveCount++;
+}
+
+return { status, category, activeCount, inactiveCount };
+}
+`} />
+
+## Filter Helpers
+
+<CodeBlock codeString={`// Read selected values for a field — only syncs with isAnyOf.
+// Returns [] for is/isNot operators (clears the DataCard).
+function getSelectedFromFilterModel(filterModel: GridFilterModel, fieldName: string): string[] {
+  const item = filterModel.items.find((i) => i.field === fieldName);
+  if (!item || item.value === undefined) return [];
+  if (item.operator === 'isAnyOf') {
+    return Array.isArray(item.value) ? item.value : [item.value];
+  }
+  return []; // is, isNot, or other → clear card
+}
+
+// Write an isAnyOf filter — always creates a fresh item, never preserves
+// an incompatible operator. Empty values removes the filter entirely.
+function updateFilterModel(
+filterModel: GridFilterModel,
+fieldName: string,
+values: string[],
+): GridFilterModel {
+const items = filterModel.items.filter((i) => i.field !== fieldName);
+if (values.length > 0) {
+items.push({
+field: fieldName,
+id: Math.floor(Math.random() \* 100000),
+operator: 'isAnyOf',
+value: values,
+});
+}
+return { ...filterModel, items };
+}
+
+// Boolean filter helper — uses the 'is' operator with 'true'/'false'.
+function updateBooleanFilter(
+filterModel: GridFilterModel,
+fieldName: string,
+value: boolean | null,
+): GridFilterModel {
+const items = filterModel.items.filter((i) => i.field !== fieldName);
+if (value !== null) {
+items.push({
+field: fieldName,
+id: Math.floor(Math.random() \* 100000),
+operator: 'is',
+value: String(value),
+});
+}
+return { ...filterModel, items };
+}
+`} />
+
+## Data Contract
+
+<CodeBlock codeString={`// Row type — same as Datagrid Page. Every row MUST have a unique 'id' field.
+type Row = {
+  id: string;
+  label: string;
+  active: boolean;
+  status: 'active' | 'warning' | 'critical' | 'expired' | 'revoked';
+  category: 'primary' | 'secondary' | 'tertiary';
+  score: number;
+  expiry: string;
+  tags: string[];
+};
+
+// Aggregate counts — recomputed from cross-filtered rows
+type AggregateCounts = {
+status: Record<string, number>;
+category: Record<string, number>;
+activeCount: number;
+inactiveCount: number;
+};
+`} />
+
+## Example
+
+The same 27-row dataset, with three cross-filtered DataCards. **Status card** counts are computed with status filters excluded (but category + active filters applied). **Category card** counts exclude category filters. **Active card** counts exclude active filters. This prevents a card from zeroing out its own non-selected values. Selecting "active" in the Status card changes the Category and Active counts, but all five status values still show their cross-filtered totals.
+
+<DemoBlock withThemeSwitcher path="patterns/crossfiltered-datagrid-page/example" />
+
+## Loading State
+
+DataCards with `isLoading={true}` alongside a DataGrid with `loading={true}` and `rows={[]}`. Use this state while fetching initial data.
+
+<DemoBlock withThemeSwitcher path="patterns/crossfiltered-datagrid-page/with-loading" />
+
+## Empty State
+
+DataCards showing zero counts on all DrilldownItems, with the DataGrid displaying a custom `NoRowsOverlay` indicating no results match the current filters.
+
+<DemoBlock withThemeSwitcher path="patterns/crossfiltered-datagrid-page/with-empty-state" />
+
+## Error State
+
+An error banner above the DataCards and DataGrid with a retry button. DataCards switch to loading state during retry. The page layout remains intact.
+
+<DemoBlock withThemeSwitcher path="patterns/crossfiltered-datagrid-page/with-error" />
+
+## Implementation Checklist
+
+1. **Define your row type** — Create a TypeScript `type Row` per the Data Contract section. Every row must have a unique `id` field.
+2. **Write the `applyFilters` function** — Accepts `(rows, filterModel, excludeField?)`. Supports `isAnyOf`, `is`, `isNot` operators. When `excludeField` is provided, skips filters for that field.
+3. **Write `computeCounts`** — Accepts a row array and returns aggregate counts per field value.
+4. **Write filter helpers** — Implement `getSelectedFromFilterModel` (reads `isAnyOf` values, returns `[]` for `is`/`isNot`) and `updateFilterModel` (always writes `isAnyOf`, removes when empty).
+5. **Compute cross-filtered counts** — For each DataCard, call `computeCounts(applyFilters(allRows, filterModel, cardField))`. This gives counts that exclude the card's own field.
+6. **Compute filtered rows for DataGrid** — Call `applyFilters(allRows, filterModel)` without excluding any field. Pass the result as the DataGrid's `rows` prop.
+7. **Build DataCards** — Create a `DataCard` for each field with `DataCard.Listbox` (multi-select with controlled `values` derived from `getSelectedFromFilterModel`) or `DataCard.Body` (boolean toggle). Wire `onChange` / `onClick` to `updateFilterModel` / `updateBooleanFilter`.
+8. **Render the DataGrid** — Pass `rows={filteredRows}`, `filterModel`, and `onFilterModelChange={setFilterModel}` so the filter panel stays synced.
+9. **Handle edge cases** — Add loading (DataCards `isLoading` + DataGrid `loading`), empty (zero counts + `NoRowsOverlay`), and error states (banner + retry).
+
+## Keyboard & Accessibility
+
+- **DrilldownItem** renders as a `<button>` — focusable via **Tab**, activates with **Enter** or **Space**
+- **DataCard.Listbox** supports **Arrow Up/Down** to navigate between items and **Space** to toggle selection
+- When a DrilldownItem is selected, it receives `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 should be able to query the updated values
+
+## Related Patterns
+
+{/* prettier-ignore */}
+- <Link href="/patterns/drilldown-datagrid-page" as={RouterLink}>Drilldown Datagrid Page</Link> — use when DataCard counts should always show full-dataset totals (one-way)
+- <Link href="/patterns/datagrid-page" as={RouterLink}>Datagrid Page</Link> — use when no summary cards are needed
+- <Link href="/patterns/server-datagrid-page" as={RouterLink}>Server Datagrid Page</Link> — use when the dataset is too large to load entirely

package/data/patterns/datagrid-page.mdx

@@ -0,0 +1,214 @@
+import { Link } from '@redsift/design-system';
+import { DemoBlock } from '../../components/DemoBlock';
+import { CodeBlock } from '../../components/CodeBlock';
+import { FeatureTable } from '../../components/FeatureTable';
+import { RouterLink } from '../../components/RouterLink';
+
+## Introduction
+
+The Datagrid Page is the most common layout across Red Sift products. It combines a full MUI DataGrid with a composable toolbar that includes columns, filters, density, export, reset, saved views, and quick search controls. This is the go-to pattern whenever you need to display a filterable, sortable, paginated collection of records — domains, certificates, email sources, or lookalikes.
+
+Optionally, the page can include bulk selection with contextual action buttons, Saved Views (full CRUD for named table state presets), and Quick Views (a dropdown to switch column visibility presets). All filtering, sorting, and pagination in this pattern happen **client-side** — all rows are loaded into the DataGrid at once. For server-side data handling, see the [Server Datagrid Page](/patterns/server-datagrid-page) pattern.
+
+## When to Use
+
+- 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
+
+When **not** to use:
+
+- The dataset has thousands or millions of rows — use [Server Datagrid Page](/patterns/server-datagrid-page) instead
+- Sorting or filtering logic must live on the backend (e.g. ElasticSearch, SQL) — use [Server Datagrid Page](/patterns/server-datagrid-page) instead
+
+## Anatomy
+
+1. **Toolbar** — `Flexbox` wrapping MUI's `GridToolbarContainer` with `GridToolbarFilterButton`, `GridToolbarColumnsButton`, `GridToolbarDensitySelector`, `GridToolbarExport`, and `GridToolbarQuickFilter`
+2. **DataGrid** — the table itself from `@redsift/table`, configured with `autoHeight`, `pagination`, `checkboxSelection`, and `GridColDef[]` columns
+3. **Bulk Action Bar** — a `Flexbox` row shown when `selectionModel.length > 0`, containing a `Pill` with the selection count and action `Button` components
+
+## Features
+
+<FeatureTable
+  features={[
+    {
+      feature: 'Column definitions',
+      required: true,
+      description: (
+        <>
+          <code>GridColDef[]</code> array with custom types: <code>rsString</code>, <code>rsNumber</code>,{' '}
+          <code>rsSingleSelect</code>, <code>rsMultipleSelect</code>, <code>boolean</code>, <code>date</code>
+        </>
+      ),
+    },
+    {
+      feature: 'Toolbar',
+      required: true,
+      description: 'Built-in toolbar with filter, columns, density, export, and quick search controls',
+    },
+    {
+      feature: 'Pagination',
+      required: true,
+      description: (
+        <>
+          Client-side pagination with configurable page size (<code>rowsPerPageOptions</code>)
+        </>
+      ),
+    },
+    { feature: 'Sorting', required: true, description: 'Client-side column sorting (built into DataGrid)' },
+    { feature: 'Filtering', required: true, description: 'Client-side column filtering (built into DataGrid)' },
+    {
+      feature: 'Custom cell renderers',
+      required: true,
+      description: (
+        <>
+          <code>renderCell</code> returning <code>TextCell</code>, <code>Pill</code>, <code>Icon</code>,{' '}
+          <code>IconButtonLink</code> for rich cell content
+        </>
+      ),
+    },
+    {
+      feature: 'Checkbox selection',
+      required: false,
+      description: (
+        <>
+          <code>checkboxSelection</code> + <code>rowSelectionModel</code> + <code>onRowSelectionModelChange</code> for
+          row selection
+        </>
+      ),
+    },
+    { feature: 'Bulk action bar', required: false, description: 'Contextual buttons shown when rows are selected' },
+    {
+      feature: 'Actions column',
+      required: false,
+      description: (
+        <>
+          Column with <code>IconButtonLink</code> for row-level navigation
+        </>
+      ),
+    },
+    {
+      feature: 'Quick search',
+      required: false,
+      description: (
+        <>
+          <code>GridToolbarQuickFilter</code> for text search across all columns
+        </>
+      ),
+    },
+  ]}
+/>
+
+### Components
+
+{/* prettier-ignore */}
+- <Link href="/table/datagrid" as={RouterLink}>DataGrid</Link> — the table itself (from `@redsift/table`)
+- <Link href="/layout/flexbox" as={RouterLink}>Flexbox</Link> — page and toolbar layout
+- <Link href="/forms/button" as={RouterLink}>Button</Link> — toolbar and bulk action buttons
+- <Link href="/forms/icon-button" as={RouterLink}>IconButton</Link> — toolbar icon controls (columns, filters, density, export, reset, save)
+- <Link href="/forms/icon-button-link" as={RouterLink}>IconButtonLink</Link> — action column navigation links
+- <Link href="/data-display/pill" as={RouterLink}>Pill</Link> — status badges in cells and count indicators
+- <Link href="/typography/text" as={RouterLink}>Text</Link> — cell content, labels, and search placeholder
+- <Link href="/media-and-icons/icon" as={RouterLink}>Icon</Link> — toolbar icons and cell indicators
+- <Link href="/data-display/badge" as={RouterLink}>Badge</Link> — active filter count on the filter button
+
+## State Management
+
+<CodeBlock codeString={`import { useState } from 'react';
+import { GridSelectionModel } from '@mui/x-data-grid-pro';
+
+// Selection state — tracks which rows are checked
+const [selectionModel, setSelectionModel] = useState<GridSelectionModel>([]);
+
+// Page size — controlled if you need to persist it
+// (DataGrid manages page/pageSize internally for client-side mode)
+`} />
+
+## Data Contract
+
+<CodeBlock codeString={`// Row type — adapt fields to your domain
+// Every row MUST have a unique 'id' field (string or number)
+type Row = {
+  id: string;
+  label: string;
+  active: boolean;
+  status: 'active' | 'warning' | 'critical' | 'expired';
+  category: string;
+  score: number;
+  expiry: string;        // ISO 8601 date string
+  tags: string[];
+};
+
+// Column definitions — use RS custom column types for built-in filter operators
+import { GridColDef } from '@mui/x-data-grid-pro';
+
+const columns: GridColDef[] = [
+{ field: 'label', headerName: 'Domain', type: 'rsString', flex: 1 },
+{ field: 'status', headerName: 'Status', type: 'rsSingleSelect', valueOptions: [...] },
+{ field: 'score', headerName: 'Score', type: 'rsNumber', width: 100 },
+{ field: 'expiry', headerName: 'Expiry', type: 'date', width: 140 },
+{ field: 'tags', headerName: 'Tags', type: 'rsMultipleSelect', valueOptions: [...] },
+];
+`} />
+
+## Example
+
+A complete datagrid page showcasing all common column types: string (`rsString`), number (`rsNumber`), boolean, date, single-select with status pills (`rsSingleSelect`), single-select with icons (`rsSingleSelect`), and multi-select tags (`rsMultipleSelect`). Includes checkbox selection with a bulk action bar, an actions column with navigation links, and pagination set to 10/25/50 rows per page with 27 rows to exercise all breakpoints.
+
+<DemoBlock withThemeSwitcher path="patterns/datagrid-page/example" />
+
+## Loading State
+
+DataGrid with `loading={true}` showing the built-in loading overlay. Use this state while fetching initial data or refreshing the dataset.
+
+<DemoBlock withThemeSwitcher path="patterns/datagrid-page/with-loading" />
+
+## Empty State
+
+DataGrid with `rows={[]}` and a custom `NoRowsOverlay` slot displaying an empty illustration with a descriptive message. Use this when the dataset has no records or a filter returns no results.
+
+<DemoBlock withThemeSwitcher path="patterns/datagrid-page/with-empty-state" />
+
+## Error State
+
+When data fetching fails, replace the DataGrid area with an error message and a retry button. This keeps the page layout intact while communicating the failure.
+
+<DemoBlock withThemeSwitcher path="patterns/datagrid-page/with-error" />
+
+## Implementation Checklist
+
+1. **Define your row type** — Create a TypeScript `type Row` per the Data Contract section. Every row must have a unique `id` field.
+2. **Define column definitions** — Create a `GridColDef[]` array. Use RS custom column types (`rsString`, `rsNumber`, `rsSingleSelect`, `rsMultipleSelect`) for built-in filter operators. Add `renderCell` for rich content (pills, icons, links).
+3. **Create the toolbar** — Build a `CustomToolbar` component using `GridToolbarContainer` with `GridToolbarFilterButton`, `GridToolbarColumnsButton`, `GridToolbarDensitySelector`, `GridToolbarExport`, and optionally `GridToolbarQuickFilter`.
+4. **Set up state** — Add `useState<GridSelectionModel>([])` for checkbox selection (if needed).
+5. **Render the DataGrid** — Pass `rows`, `columns`, `autoHeight`, `pagination`, `pageSize`, `rowsPerPageOptions`, `checkboxSelection`, `components={{ Toolbar: CustomToolbar }}`.
+6. **Add bulk action bar** — Conditionally render a `Flexbox` with a `Pill` (selection count) and action `Button` components when `selectionModel.length > 0`.
+7. **Handle edge cases** — Add loading state (`loading` prop), empty state (custom `NoRowsOverlay`), and error state (conditional render with retry).
+8. **Verify** — Test pagination breakpoints, filter operators, column visibility toggle, density switching, and export.
+
+## Keyboard & Accessibility
+
+The MUI DataGrid provides extensive built-in keyboard support:
+
+- **Arrow keys** navigate between cells
+- **Page Up / Page Down** move between pages
+- **Home / End** jump to first/last cell in a row
+- **Enter** activates cell editing or expands a row
+- **Space** toggles checkbox selection on the focused row
+- **Tab** moves focus between the toolbar and the grid
+
+As an implementor, ensure:
+
+- Every `IconButtonLink` in the actions column has an accessible `aria-label` (e.g. `aria-label="View details"`)
+- Status `Pill` components use meaningful color contrast — don't rely on color alone
+- Bulk action buttons have descriptive labels (e.g. "Delete 3 selected" instead of just "Delete")
+- Custom `NoRowsOverlay` content is announced to screen readers
+
+## Related Patterns
+
+{/* prettier-ignore */}
+- <Link href="/patterns/server-datagrid-page" as={RouterLink}>Server Datagrid Page</Link> — use when the dataset is too large to load entirely, or when filtering/sorting must happen server-side
+- <Link href="/patterns/drilldown-datagrid-page" as={RouterLink}>Drilldown Datagrid Page</Link> — use when you want summary DataCards above the grid with one-way filter push
+- <Link href="/patterns/crossfiltered-datagrid-page" as={RouterLink}>Cross-filtered Datagrid Page</Link> — use when DataCard counts should recalculate as filters change (two-way sync)