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

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

@@ -0,0 +1,291 @@
+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 Drilldown Datagrid Page extends the standard [Datagrid Page](/patterns/datagrid-page) with summary **DataCards** placed above the grid. Each DataCard contains **DrilldownItems** that display aggregate counts for a field (e.g. status, category). Clicking a DrilldownItem adds an `isAnyOf` filter to the DataGrid's filter panel — a one-click shortcut for filtering by that value.
+
+This is a **one-way** interaction: DrilldownItem clicks push filters into the grid, but the DataCard counts always reflect the **full** (unfiltered) dataset. If you need DataCard counts to recalculate as filters change, use the [Cross-filtered Datagrid Page](/patterns/crossfiltered-datagrid-page) instead.
+
+When the user sets an `is` or `isNot` filter via the DataGrid filter panel (instead of clicking a DrilldownItem), the DataCard selection **clears** — all DrilldownItems are deselected. Clicking a DrilldownItem after that overwrites the incompatible filter with a fresh `isAnyOf` item.
+
+## When to Use
+
+- 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)
+
+When **not** to use:
+
+- DataCard counts should **recalculate** when filters change — use [Cross-filtered Datagrid Page](/patterns/crossfiltered-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, each containing a `DataCard.Header` and either `DataCard.Listbox` (for multi-select fields) or `DataCard.Body` (for boolean toggles) with `DrilldownItem` children
+2. **Toolbar** — `Flexbox` wrapping MUI's `GridToolbarContainer` with `GridToolbarFilterButton`, `GridToolbarColumnsButton`, `GridToolbarDensitySelector`, `GridToolbarExport`, and `GridToolbarQuickFilter`
+3. **DataGrid** — the table itself with `filterModel` + `onFilterModelChange` controlled state
+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: 'DataCard aggregation',
+      required: true,
+      description: (
+        <>
+          <code>DataCard</code> components showing aggregate counts per field from the full dataset
+        </>
+      ),
+    },
+    {
+      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: '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 — controlled, shared between DataCards and DataGrid
+const [filterModel, setFilterModel] = useState<GridFilterModel>({ items: [] });
+
+// Selection state
+const [selectionModel, setSelectionModel] = useState<GridSelectionModel>([]);
+
+// Aggregate counts — always computed from the FULL dataset (one-way)
+const counts = useAggregateCounts(allRows);
+
+// Derive DataCard selections from filterModel (returns [] for is/isNot)
+const statusSelection = getSelectedFromFilterModel(filterModel, 'status');
+const categorySelection = getSelectedFromFilterModel(filterModel, 'category');
+
+// DataCard change handler — always writes isAnyOf filters
+const handleStatusChange = useCallback(
+(values: string[]) => setFilterModel((prev) => updateFilterModel(prev, 'status', values)),
+[],
+);
+`} />
+
+## 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 computed from the full dataset
+type AggregateCounts = {
+status: Record<string, number>;
+category: Record<string, number>;
+activeCount: number;
+inactiveCount: number;
+};
+`} />
+
+## Example
+
+The same 27-row dataset as the Datagrid Page, with three DataCards above: **Status** (5 DrilldownItems), **Category** (3 DrilldownItems), and **Active** (boolean toggle with 2 DrilldownItems). Clicking a DrilldownItem adds an `isAnyOf` filter to the grid. The Status and Category cards use `DataCard.Listbox` with controlled `values` for multi-select. The Active card uses `DataCard.Body` with `onClick` toggles. DataCard counts always show the full 27-row totals.
+
+<DemoBlock withThemeSwitcher path="patterns/drilldown-datagrid-page/example" />
+
+## Loading State
+
+DataCards with `isLoading={true}` (hides headers, shows skeleton placeholders) alongside a DataGrid with `loading={true}` and `rows={[]}`. Use this state while fetching initial data.
+
+<DemoBlock withThemeSwitcher path="patterns/drilldown-datagrid-page/with-loading" />
+
+## Empty State
+
+DataCards showing zero counts on all DrilldownItems, with the DataGrid displaying a custom `NoRowsOverlay` with "No results match your filters" and guidance to adjust filters.
+
+<DemoBlock withThemeSwitcher path="patterns/drilldown-datagrid-page/with-empty-state" />
+
+## Error State
+
+An error banner (`role="alert"`) 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/drilldown-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. **Compute aggregate counts** — Write a `useAggregateCounts(allRows)` hook that counts occurrences per field value from the full dataset. This never recalculates when filters change.
+3. **Build DataCards** — Create a `DataCard` for each summarized field with `DataCard.Header` (icon + title) and either `DataCard.Listbox` (multi-select) or `DataCard.Body` (boolean toggle) containing `DrilldownItem` children.
+4. **Write filter helpers** — Implement `getSelectedFromFilterModel` (reads `isAnyOf` values, returns `[]` for `is`/`isNot`) and `updateFilterModel` (always writes `isAnyOf`, removes when empty).
+5. **Wire DataCard handlers** — Connect `DataCard.Listbox` `onChange` to `updateFilterModel`. For boolean cards, connect `DrilldownItem` `onClick` to `updateBooleanFilter`.
+6. **Render the DataGrid** — Pass `filterModel` and `onFilterModelChange={setFilterModel}` so the filter panel stays synced with DataCard selections.
+7. **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
+
+## Related Patterns
+
+{/* prettier-ignore */}
+- <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)
+- <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/server-datagrid-page.mdx

@@ -0,0 +1,301 @@
+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 Server Datagrid Page is a variant of the standard [Datagrid Page](/patterns/datagrid-page) where **all filtering, sorting, and pagination are handled server-side**. Instead of loading every row into the browser, only the current page of results is fetched from the server, and every user interaction (changing page, sorting a column, adding a filter) triggers a new request.
+
+Use this pattern when the dataset is too large to load entirely — thousands or millions of records — or when the canonical sort/filter logic must live on the backend (e.g. ElasticSearch queries, SQL `ORDER BY`).
+
+The DataGrid is configured with `paginationMode="server"`, `sortingMode="server"`, and `filterMode="server"`. A controlled `rowCount` tells the grid the total number of matching records so it can render the correct number of pagination pages. The `loading` prop activates the built-in loading overlay during fetches.
+
+## When to Use
+
+- 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
+
+When **not** to use:
+
+- The dataset is small enough to load entirely (under ~1,000 rows) — use [Datagrid Page](/patterns/datagrid-page) instead
+- All data is available upfront and filtering can happen in the browser — use [Datagrid Page](/patterns/datagrid-page) instead
+
+## Anatomy
+
+1. **Toolbar** — `Flexbox` wrapping MUI's `GridToolbarContainer` with `GridToolbarFilterButton`, `GridToolbarColumnsButton`, `GridToolbarDensitySelector`, `GridToolbarExport`, and `GridToolbarQuickFilter`
+2. **DataGrid** — the table configured with `paginationMode="server"`, `sortingMode="server"`, `filterMode="server"`, `loading`, and `rowCount`
+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: 'Server-side pagination',
+      required: true,
+      description: (
+        <>
+          <code>{'paginationMode="server"'}</code> with controlled <code>page</code>, <code>pageSize</code>,{' '}
+          <code>rowCount</code>
+        </>
+      ),
+    },
+    {
+      feature: 'Server-side sorting',
+      required: true,
+      description: (
+        <>
+          <code>{'sortingMode="server"'}</code> with controlled <code>sortModel</code> + <code>onSortModelChange</code>
+        </>
+      ),
+    },
+    {
+      feature: 'Server-side filtering',
+      required: true,
+      description: (
+        <>
+          <code>{'filterMode="server"'}</code> with controlled <code>filterModel</code> +{' '}
+          <code>onFilterModelChange</code>
+        </>
+      ),
+    },
+    {
+      feature: 'Loading overlay',
+      required: true,
+      description: (
+        <>
+          <code>loading</code> prop set to <code>true</code> during fetches
+        </>
+      ),
+    },
+    {
+      feature: 'Row count',
+      required: true,
+      description: (
+        <>
+          <code>rowCount</code> prop set to total matching records from the server response
+        </>
+      ),
+    },
+    {
+      feature: 'Debounced filter changes',
+      required: true,
+      description: (
+        <>
+          300ms debounce on <code>onFilterModelChange</code> to avoid excessive requests
+        </>
+      ),
+    },
+    {
+      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',
+    },
+    {
+      feature: 'Custom cell renderers',
+      required: true,
+      description: (
+        <>
+          <code>renderCell</code> returning <code>TextCell</code>, <code>Pill</code>, <code>Icon</code>,{' '}
+          <code>IconButtonLink</code>
+        </>
+      ),
+    },
+    {
+      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' },
+    {
+      feature: 'Quick search',
+      required: false,
+      description: (
+        <>
+          <code>GridToolbarQuickFilter</code> with server-side text search
+        </>
+      ),
+    },
+  ]}
+/>
+
+### 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 { useCallback, useEffect, useRef, useState } from 'react';
+import { GridFilterModel, GridSelectionModel, GridSortModel } from '@mui/x-data-grid-pro';
+
+// Data state — rows returned from the server for the current page
+const [rows, setRows] = useState<Row[]>([]);
+const [totalRows, setTotalRows] = useState(0);
+const [loading, setLoading] = useState(true);
+
+// Pagination state
+const [page, setPage] = useState(0);
+const [pageSize, setPageSize] = useState(10);
+
+// Sort & filter state (controlled — sent to server on change)
+const [sortModel, setSortModel] = useState<GridSortModel>([]);
+const [filterModel, setFilterModel] = useState<GridFilterModel>({ items: [] });
+
+// Selection state
+const [selectionModel, setSelectionModel] = useState<GridSelectionModel>([]);
+
+// Quick search
+const [quickFilterText, setQuickFilterText] = useState('');
+
+// Debounce ref for filter changes
+const debounceRef = useRef<ReturnType<typeof setTimeout>>();
+
+// Fetch data whenever page, pageSize, sortModel, or filterModel changes
+const fetchData = useCallback(async () => {
+setLoading(true);
+const result = await yourFetchFunction({ page, pageSize, sortModel, filterModel, quickFilterText });
+setRows(result.rows);
+setTotalRows(result.totalRows);
+setLoading(false);
+}, [page, pageSize, sortModel, filterModel, quickFilterText]);
+
+useEffect(() => { fetchData(); }, [fetchData]);
+
+// Debounced filter handler (300ms)
+const handleFilterChange = useCallback((model: GridFilterModel) => {
+clearTimeout(debounceRef.current);
+debounceRef.current = setTimeout(() => {
+setFilterModel(model);
+setPage(0); // Reset to first page on filter change
+}, 300);
+}, []);
+`} />
+
+## 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[];
+};
+
+// Fetch function parameters — sent to the server on every interaction
+type FetchParams = {
+page: number; // 0-based page index
+pageSize: number; // rows per page (10, 25, 50)
+sortModel: GridSortModel;
+filterModel: GridFilterModel;
+quickFilterText: string;
+};
+
+// Fetch function response — returned by the server
+type FetchResult = {
+rows: Row[]; // only the current page of results
+totalRows: number; // total matching records (for pagination)
+};
+
+// Fetch function signature
+async function fetchData(params: FetchParams): Promise<FetchResult> {
+// Implement: translate params to your API/ElasticSearch query
+// Return: { rows, totalRows }
+}
+`} />
+
+## Example
+
+The same 27-row dataset as the client-side Datagrid Page, but every interaction is routed through a mock `fakeFetch` function that simulates a 400 ms network round-trip. The mock applies filtering (string, number, date, single-select, multi-select, and boolean operators), sorting, and pagination server-side, then returns only the requested page slice alongside the total matching row count. Filter changes are debounced at 300 ms so rapid typing doesn't fire excessive requests.
+
+<DemoBlock withThemeSwitcher path="patterns/server-datagrid-page/example" />
+
+## Loading State
+
+The initial loading state before the first fetch completes — DataGrid rendered with `loading={true}` and `rows={[]}`. The built-in loading overlay displays a skeleton while the server responds.
+
+<DemoBlock withThemeSwitcher path="patterns/server-datagrid-page/with-loading" />
+
+## Empty State
+
+Server returns `{ rows: [], totalRows: 0 }` after filtering yields no results. The DataGrid shows a custom `NoRowsOverlay` with "No results match your filters" and a button to clear all filters.
+
+<DemoBlock withThemeSwitcher path="patterns/server-datagrid-page/with-empty-state" />
+
+## Error State
+
+The fetch function rejects with an error. The component shows an error banner above the DataGrid with a retry button, keeping the page layout intact.
+
+<DemoBlock withThemeSwitcher path="patterns/server-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. **Create your fetch function** — Implement an async function matching the `FetchParams → FetchResult` contract. This is where you call your API or ElasticSearch. If using React Query, wrap it in a `useQuery` hook with `[page, pageSize, sortModel, filterModel, quickFilterText]` as the query key.
+3. **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.
+4. **Create the toolbar** — Build a `CustomToolbar` component using `GridToolbarContainer` with filter, columns, density, export, and quick search controls.
+5. **Set up state** — Add all hooks from the State Management section: `rows`, `totalRows`, `loading`, `page`, `pageSize`, `sortModel`, `filterModel`, `selectionModel`, `quickFilterText`, and the debounce ref.
+6. **Wire the fetch effect** — Use `useEffect` to call your fetch function whenever `page`, `pageSize`, `sortModel`, `filterModel`, or `quickFilterText` changes.
+7. **Configure the DataGrid** — Pass `paginationMode="server"`, `sortingMode="server"`, `filterMode="server"`, `loading`, `rowCount={totalRows}`, and all controlled state handlers (`onPageChange`, `onPageSizeChange`, `onSortModelChange`, `onFilterModelChange`).
+8. **Debounce filter changes** — Use a 300ms `setTimeout` in `onFilterModelChange` to avoid excessive requests during rapid typing. Reset to page 0 on filter change.
+9. **Add bulk action bar** — Conditionally render when `selectionModel.length > 0`.
+10. **Handle edge cases** — Add loading state (`loading` prop), empty state (custom `NoRowsOverlay`), and error state (conditional render with retry).
+11. **Verify** — Test page navigation, sort toggling, filter operators, debounced quick search, loading overlay, empty results, and error recovery.
+
+## 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")
+- The loading state is announced to screen readers (`aria-busy="true"` on the container)
+- Error messages are in a live region (`aria-live="polite"`) so screen readers announce them
+- Custom `NoRowsOverlay` content is announced to screen readers
+
+## Related Patterns
+
+{/* prettier-ignore */}
+- <Link href="/patterns/datagrid-page" as={RouterLink}>Datagrid Page</Link> — use when all data can be loaded upfront and filtering/sorting can happen client-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)