@redsift/ds-mcp-server 12.4.0 → 12.5.0-muiv6

package/data/demos/patterns/_shared/story-helpers.ts

@@ -1,4 +1,5 @@
-import { within, waitFor, userEvent } from '@storybook/testing-library';
+import { useRef, useState } from 'react';
+import { within, waitFor, userEvent, fireEvent } from '@storybook/testing-library';
 import { expect } from '@storybook/jest';
 
 // ---------------------------------------------------------------------------
@@ -284,12 +285,15 @@ export const getRetryButton = (canvas: ReturnType<typeof within>): HTMLElement =
 
 /** Assert the bulk action bar is visible and shows the expected count. */
 export const assertBulkActionBarVisible = async (canvasElement: HTMLElement, expectedCount: number) => {
-  await waitFor(() => {
-    const pills = Array.from(canvasElement.querySelectorAll('.redsift-pill'));
-    const selectionPill = pills.find((p) => p.textContent?.includes('selected'));
-    expect(selectionPill).toBeTruthy();
-    expect(selectionPill!.textContent).toContain(`${expectedCount} selected`);
-  });
+  await waitFor(
+    () => {
+      const pills = Array.from(canvasElement.querySelectorAll('.redsift-pill'));
+      const selectionPill = pills.find((p) => p.textContent?.includes('selected'));
+      expect(selectionPill).toBeTruthy();
+      expect(selectionPill!.textContent).toContain(`${expectedCount} selected`);
+    },
+    { timeout: 5000 }
+  );
 };
 
 /** Assert the bulk action bar is hidden (no selection pill visible). */
@@ -307,9 +311,23 @@ export const assertBulkActionBarHidden = async (canvasElement: HTMLElement) => {
 
 /** Click the header checkbox to select/deselect all visible rows. */
 export const clickHeaderCheckbox = async (canvasElement: HTMLElement) => {
-  const headerCheckbox = canvasElement.querySelector('.MuiDataGrid-columnHeaderCheckbox input[type="checkbox"]');
-  if (!headerCheckbox) throw new Error('Could not find header checkbox');
-  await userEvent.click(headerCheckbox);
+  // Wait for the grid to be stable: rows present, no loading, checkbox exists.
+  // This prevents clicking during a mid-render where the grid ignores the click.
+  await waitFor(
+    () => {
+      const rows = canvasElement.querySelectorAll('.MuiDataGrid-row');
+      expect(rows.length).toBeGreaterThan(0);
+      const headerCheckbox = canvasElement.querySelector('.MuiDataGrid-columnHeaderCheckbox input[type="checkbox"]');
+      expect(headerCheckbox).toBeTruthy();
+    },
+    { timeout: 3000 }
+  );
+  // Small yield to let React finish any pending microtask re-renders
+  await new Promise((resolve) => setTimeout(resolve, 200));
+  const headerCheckbox = canvasElement.querySelector('.MuiDataGrid-columnHeaderCheckbox input[type="checkbox"]')!;
+  fireEvent.click(headerCheckbox);
+  // Wait for React and MUI DataGrid to process the selection change
+  await new Promise((resolve) => setTimeout(resolve, 200));
 };
 
 /** Click a row checkbox by row index (0-based, within the visible page). */
@@ -322,6 +340,91 @@ export const clickRowCheckbox = async (canvasElement: HTMLElement, rowIndex: num
   const checkbox = rows[rowIndex].querySelector('input[type="checkbox"]');
   if (!checkbox) throw new Error(`Could not find checkbox in row ${rowIndex}`);
   await userEvent.click(checkbox);
+  // Wait for React and MUI DataGrid to process the selection change
+  await new Promise((resolve) => setTimeout(resolve, 200));
+};
+
+// ---------------------------------------------------------------------------
+// Checkbox state assertions
+// ---------------------------------------------------------------------------
+
+/** Get the header checkbox input element. */
+const getHeaderCheckboxInput = (canvasElement: HTMLElement): HTMLInputElement => {
+  const el = canvasElement.querySelector('.MuiDataGrid-columnHeaderCheckbox input[type="checkbox"]');
+  if (!el) throw new Error('Could not find header checkbox');
+  return el as HTMLInputElement;
+};
+
+/**
+ * Assert the header checkbox is in the expected state.
+ * The DS Checkbox component uses `aria-checked` to communicate state:
+ * - checked: aria-checked="true"
+ * - unchecked: aria-checked="false"
+ * - indeterminate: aria-checked="mixed"
+ * Note: `input.indeterminate` DOM property is NOT set by the DS Checkbox.
+ */
+export const assertHeaderCheckboxState = async (
+  canvasElement: HTMLElement,
+  expected: 'checked' | 'unchecked' | 'indeterminate'
+) => {
+  await waitFor(
+    () => {
+      const input = getHeaderCheckboxInput(canvasElement);
+      const ariaChecked = input.getAttribute('aria-checked');
+      switch (expected) {
+        case 'checked':
+          expect(ariaChecked).toBe('true');
+          break;
+        case 'unchecked':
+          expect(ariaChecked).toBe('false');
+          break;
+        case 'indeterminate':
+          expect(ariaChecked).toBe('mixed');
+          break;
+      }
+    },
+    { timeout: 5000 }
+  );
+};
+
+/**
+ * Assert a specific row's checkbox is checked or unchecked.
+ * Uses `aria-selected` on the MUI DataGrid row element, which is more reliable
+ * than checking `input.checked` on the custom DS Checkbox (whose native input
+ * is visually hidden and rendered asynchronously via React effects).
+ * @param rowIndex 0-based index within the visible page.
+ */
+export const assertRowCheckboxChecked = async (
+  canvasElement: HTMLElement,
+  rowIndex: number,
+  expectedChecked: boolean
+) => {
+  await waitFor(
+    () => {
+      const rows = canvasElement.querySelectorAll('.MuiDataGrid-row');
+      expect(rows.length).toBeGreaterThan(rowIndex);
+      const row = rows[rowIndex];
+      const isSelected = row.getAttribute('aria-selected') === 'true';
+      expect(isSelected).toBe(expectedChecked);
+    },
+    { timeout: 5000 }
+  );
+};
+
+/**
+ * Assert that the first data cell in a given row contains specific text.
+ * Useful to prove the page actually changed (different rows visible).
+ * Skips the checkbox column cell (first cell) and reads the second cell.
+ */
+export const assertFirstCellInRow = async (canvasElement: HTMLElement, rowIndex: number, expectedText: string) => {
+  await waitFor(() => {
+    const rows = canvasElement.querySelectorAll('.MuiDataGrid-row');
+    expect(rows.length).toBeGreaterThan(rowIndex);
+    const cells = rows[rowIndex].querySelectorAll('.MuiDataGrid-cell');
+    // cells[0] is checkbox column, cells[1] is first data column
+    const dataCell = cells[1] ?? cells[0];
+    expect(dataCell?.textContent).toContain(expectedText);
+  });
 };
 
 // ---------------------------------------------------------------------------
@@ -754,3 +857,450 @@ export const assertScreenReaderSequence = async (
     );
   }
 };
+
+// ---------------------------------------------------------------------------
+// Pagination — page navigation and page-size switching
+// ---------------------------------------------------------------------------
+
+/** Assert the displayed rows text matches (e.g. "1–10 of 14,075"). Ignores locale thousands separators. */
+export const assertDisplayedRowsText = async (canvasElement: HTMLElement, expected: string) => {
+  const strip = (s: string) => s.replace(/,/g, '');
+  await waitFor(() => {
+    const el = canvasElement.querySelector('.MuiTablePagination-displayedRows');
+    expect(el).toBeTruthy();
+    expect(strip(el!.textContent!)).toBe(strip(expected));
+  });
+};
+
+/** Click the "Go to next page" pagination button. */
+export const clickNextPage = async (canvasElement: HTMLElement) => {
+  const btn = canvasElement.querySelector(
+    '.MuiTablePagination-actions button[aria-label="Go to next page"]'
+  ) as HTMLElement | null;
+  if (!btn) throw new Error('Could not find next page button');
+  await userEvent.click(btn);
+};
+
+/** Click the "Go to previous page" pagination button. */
+export const clickPrevPage = async (canvasElement: HTMLElement) => {
+  const btn = canvasElement.querySelector(
+    '.MuiTablePagination-actions button[aria-label="Go to previous page"]'
+  ) as HTMLElement | null;
+  if (!btn) throw new Error('Could not find previous page button');
+  await userEvent.click(btn);
+};
+
+/** Wait for a pagination button to exist and be enabled. Use before clickPrevPage/clickNextPage in server-side stories. */
+export const waitForPaginationEnabled = async (canvasElement: HTMLElement, direction: 'next' | 'previous') => {
+  const label = direction === 'next' ? 'Go to next page' : 'Go to previous page';
+  await waitFor(
+    () => {
+      const btn = canvasElement.querySelector(
+        `.MuiTablePagination-actions button[aria-label="${label}"]`
+      ) as HTMLButtonElement | null;
+      expect(btn).toBeTruthy();
+      expect(btn!.disabled).toBe(false);
+    },
+    { timeout: 10000 }
+  );
+};
+
+/**
+ * Change the page size via the MUI pagination "Rows per page" select.
+ * The dropdown menu renders as a portal on document.body.
+ */
+export const changePageSize = async (canvasElement: HTMLElement, newSize: number) => {
+  const select = canvasElement.querySelector('.MuiTablePagination-select') as HTMLElement | null;
+  if (!select) throw new Error('Could not find page size select');
+  await userEvent.click(select);
+  // The menu renders as a MUI Popper on document.body
+  await waitFor(() => {
+    const options = document.querySelectorAll('li[role="option"]');
+    expect(options.length).toBeGreaterThan(0);
+  });
+  const options = document.querySelectorAll('li[role="option"]');
+  const target = Array.from(options).find((opt) => opt.textContent === String(newSize));
+  if (!target) throw new Error(`Could not find page size option "${newSize}"`);
+  await userEvent.click(target);
+};
+
+// ---------------------------------------------------------------------------
+// Column visibility — columns panel interaction
+// ---------------------------------------------------------------------------
+
+/** Open the columns panel via the toolbar button. */
+export const openColumnsPanel = async (canvasElement: HTMLElement) => {
+  const btn = canvasElement.querySelector(
+    '.MuiDataGrid-toolbarContainer button[aria-label="Select columns"]'
+  ) as HTMLElement | null;
+  if (!btn) throw new Error('Could not find columns toolbar button');
+  await userEvent.click(btn);
+  // Wait for the panel to appear on document.body
+  await waitFor(() => {
+    const panel = document.querySelector('.MuiDataGrid-columnsPanel');
+    expect(panel).toBeTruthy();
+  });
+};
+
+/** Toggle a column's visibility in the columns panel by its label text. */
+export const toggleColumnInPanel = async (fieldLabel: string) => {
+  const panel = document.querySelector('.MuiDataGrid-columnsPanel');
+  if (!panel) throw new Error('Columns panel is not open');
+  const labels = Array.from(panel.querySelectorAll('.MuiFormControlLabel-root'));
+  const target = labels.find((label) => label.textContent?.includes(fieldLabel));
+  if (!target) throw new Error(`Could not find column "${fieldLabel}" in columns panel`);
+  const checkbox = target.querySelector('input[type="checkbox"]') as HTMLElement | null;
+  if (!checkbox) throw new Error(`Could not find checkbox for column "${fieldLabel}"`);
+  await userEvent.click(checkbox);
+};
+
+/** Close the columns panel by clicking elsewhere. */
+export const closeColumnsPanel = async () => {
+  // Press Escape to close the panel
+  await userEvent.keyboard('{Escape}');
+  await waitFor(() => {
+    const panel = document.querySelector('.MuiDataGrid-columnsPanel');
+    expect(panel).toBeFalsy();
+  });
+};
+
+/** Assert a column header is visible in the grid. */
+export const assertColumnVisible = async (canvasElement: HTMLElement, headerName: string) => {
+  await waitFor(() => {
+    const headers = Array.from(canvasElement.querySelectorAll('.MuiDataGrid-columnHeaderTitle'));
+    const found = headers.some((h) => h.textContent === headerName);
+    expect(found).toBe(true);
+  });
+};
+
+/** Assert a column header is NOT visible in the grid. */
+export const assertColumnHidden = async (canvasElement: HTMLElement, headerName: string) => {
+  await waitFor(() => {
+    const headers = Array.from(canvasElement.querySelectorAll('.MuiDataGrid-columnHeaderTitle'));
+    const found = headers.some((h) => h.textContent === headerName);
+    expect(found).toBe(false);
+  });
+};
+
+// ---------------------------------------------------------------------------
+// Density — switch and assert grid density
+// ---------------------------------------------------------------------------
+
+/**
+ * Change the grid density via the toolbar density selector.
+ * The menu renders as a portal on document.body.
+ */
+export const changeDensity = async (canvasElement: HTMLElement, density: 'Compact' | 'Standard' | 'Comfortable') => {
+  const btn = canvasElement.querySelector(
+    '.MuiDataGrid-toolbarContainer button[aria-label="Density"]'
+  ) as HTMLElement | null;
+  if (!btn) throw new Error('Could not find density toolbar button');
+  await userEvent.click(btn);
+  // Wait for menu to appear
+  await waitFor(() => {
+    const menuItems = document.querySelectorAll('li[role="menuitem"]');
+    expect(menuItems.length).toBeGreaterThan(0);
+  });
+  const menuItems = document.querySelectorAll('li[role="menuitem"]');
+  const target = Array.from(menuItems).find((item) => item.textContent === density);
+  if (!target) throw new Error(`Could not find density option "${density}"`);
+  await userEvent.click(target);
+};
+
+/**
+ * Assert the grid root has the expected density CSS class.
+ * MUI DataGrid density classes: MuiDataGrid-root--densityCompact, densityStandard, densityComfortable.
+ */
+export const assertDensity = async (canvasElement: HTMLElement, density: 'Compact' | 'Standard' | 'Comfortable') => {
+  await waitFor(() => {
+    const grid = canvasElement.querySelector('.MuiDataGrid-root');
+    expect(grid).toBeTruthy();
+    expect(grid!.classList.contains(`MuiDataGrid-root--density${density}`)).toBe(true);
+  });
+};
+
+// ---------------------------------------------------------------------------
+// Mock router — isolated URL state for StatefulDataGrid stories
+// ---------------------------------------------------------------------------
+
+/**
+ * Create an isolated mock router for StatefulDataGrid interaction stories.
+ *
+ * Each story should create its own instance to prevent cross-story state leakage.
+ * The mock router stores URL search params in a closure — no `window.location` involved.
+ *
+ * @param initialSearch - Initial URL search string (default: '')
+ * @returns `{ useRouter, getSearch }` — pass `useRouter` to StatefulDataGrid; use `getSearch()` for assertions
+ */
+export const createMockRouter = (initialSearch = '') => {
+  const state = { search: initialSearch };
+
+  const useRouter = () => ({
+    pathname: '/test',
+    search: state.search,
+    historyReplace: (newSearch: string) => {
+      state.search = newSearch.startsWith('?') ? newSearch : `?${newSearch}`;
+    },
+  });
+
+  const getSearch = () => state.search;
+
+  return { useRouter, getSearch };
+};
+
+/**
+ * React hook wrapper around createMockRouter that persists the router instance
+ * across re-renders. Must be called inside a component or Storybook render function.
+ *
+ * Unlike createMockRouter(), this hook:
+ * 1. Persists the router state across re-renders (via useRef)
+ * 2. Triggers a parent re-render when historyReplace is called (via useState),
+ *    mimicking the real Next.js router's behavior where router.replace() causes
+ *    the consuming component to re-render with the updated search string.
+ *
+ * Without this, calling createMockRouter() inside a render function resets the
+ * URL state on every re-render, causing race conditions in interaction tests.
+ */
+export const usePersistentMockRouter = (initialSearch = '') => {
+  const searchRef = useRef(initialSearch);
+  const [, forceRerender] = useState(0);
+
+  const routerRef = useRef<ReturnType<typeof createMockRouter>>();
+  if (!routerRef.current) {
+    routerRef.current = {
+      useRouter: () => ({
+        pathname: '/test',
+        search: searchRef.current,
+        historyReplace: (newSearch: string) => {
+          searchRef.current = newSearch.startsWith('?') ? newSearch : `?${newSearch}`;
+          forceRerender((t) => t + 1);
+        },
+      }),
+      getSearch: () => searchRef.current,
+    };
+  }
+
+  return routerRef.current;
+};
+
+// ---------------------------------------------------------------------------
+// URL assertion helpers — for StatefulDataGrid stories
+// ---------------------------------------------------------------------------
+
+/** Assert the mock router's search string contains a substring. */
+export const assertSearchContains = async (getSearch: () => string, substring: string) => {
+  await waitFor(() => {
+    expect(getSearch()).toContain(substring);
+  });
+};
+
+/** Assert a specific URL search param equals the expected value. */
+export const assertSearchParam = async (getSearch: () => string, key: string, value: string) => {
+  await waitFor(() => {
+    const params = new URLSearchParams(getSearch());
+    expect(params.get(key)).toBe(value);
+  });
+};
+
+/** Assert a URL search param's value contains a substring. */
+export const assertSearchParamContains = async (getSearch: () => string, key: string, substring: string) => {
+  await waitFor(() => {
+    const params = new URLSearchParams(getSearch());
+    const val = params.get(key);
+    expect(val).toBeTruthy();
+    expect(val!).toContain(substring);
+  });
+};
+
+/** Assert a URL search param's value does NOT contain a substring. */
+export const assertSearchParamMissing = async (getSearch: () => string, key: string, substring: string) => {
+  await waitFor(() => {
+    const params = new URLSearchParams(getSearch());
+    const val = params.get(key) ?? '';
+    expect(val).not.toContain(substring);
+  });
+};
+
+// ---------------------------------------------------------------------------
+// State sync assertion — verify URL ↔ localStorage consistency
+// ---------------------------------------------------------------------------
+
+/**
+ * Normalizes the localStorage search-model string (internal bracket format)
+ * into display-format URL params for comparison.
+ * e.g. `_Items[contains,string]=e` → `Items.contains=e`
+ *
+ * Since localStorage stores the raw internal format and URL uses display format,
+ * we compare the *semantic content* rather than the raw strings.
+ */
+
+interface SyncAssertionOptions {
+  /** getSearch() from createMockRouter */
+  getSearch: () => string;
+  /** pathname used for localStorage keys (from createMockRouter, typically '/test') */
+  pathname?: string;
+  /** localStorage version */
+  localStorageVersion?: number;
+  /** Whether to check filter sync */
+  checkFilters?: boolean;
+  /** Whether to check sort sync */
+  checkSort?: boolean;
+  /** Whether to check pagination sync */
+  checkPagination?: boolean;
+  /** Whether to check density sync */
+  checkDensity?: boolean;
+}
+
+/**
+ * Assert that URL query params and localStorage are in sync.
+ *
+ * Compares the semantic content of each state dimension (filters, sort, pagination, density)
+ * between the URL and localStorage. Both are populated by the same `updateUrl` → `historyReplace`
+ * and `setLocalStorageX` calls, so they should always agree.
+ */
+export const assertAllStatesInSync = async ({
+  getSearch,
+  pathname = '/test',
+  localStorageVersion = 1,
+  checkFilters = true,
+  checkSort = true,
+  checkPagination = true,
+  checkDensity = true,
+}: SyncAssertionOptions) => {
+  await waitFor(
+    () => {
+      const search = getSearch();
+      const url = new URLSearchParams(search);
+
+      // --- Filters ---
+      if (checkFilters) {
+        const lsKey = `${pathname}:${localStorageVersion}:searchModel`;
+        const lsRaw = localStorage.getItem(lsKey);
+        const lsFilters = lsRaw ? JSON.parse(lsRaw) : '';
+
+        // URL has filter params in display format: `Items.contains=e`
+        // localStorage has internal format: `_Items[contains,string]=e&_logicOperator=and`
+        // Both should represent the same filters. We verify by checking that every
+        // filter field.operator from the URL also exists in localStorage (and vice versa).
+        if (lsFilters) {
+          const lsParams = new URLSearchParams(lsFilters);
+          // Check each internal filter key maps to a URL key
+          for (const [key] of lsParams) {
+            if (key === '_logicOperator' || key === '_quickFilterValues') continue;
+            // Internal: _Field[operator,type] → Display: Field.operator
+            const match = key.match(/^_([^[]+)\[([^,]+)/);
+            if (match) {
+              const [, field, operator] = match;
+              const displayKey = `${field}.${operator}`;
+              // The URL (display format) should contain this key
+              expect(search).toContain(displayKey);
+            }
+          }
+        }
+      }
+
+      // --- Sort ---
+      if (checkSort) {
+        const lsKey = `${pathname}:${localStorageVersion}:sortModel`;
+        const lsRaw = localStorage.getItem(lsKey);
+        const lsSorting = lsRaw ? JSON.parse(lsRaw) : '';
+
+        const urlSort = url.get('_sortColumn');
+        if (lsSorting) {
+          // localStorage: `_sortColumn=[DateTime,desc]`
+          // URL: `_sortColumn=DateTime.desc`
+          const lsParams = new URLSearchParams(lsSorting);
+          const lsSortValue = lsParams.get('_sortColumn') ?? '';
+          // Extract field and direction from both
+          const lsMatch = lsSortValue.match(/^\[(\w+),(\w+)\]$/);
+          if (lsMatch && urlSort) {
+            const [, lsField, lsDir] = lsMatch;
+            expect(urlSort).toBe(`${lsField}.${lsDir}`);
+          }
+        }
+      }
+
+      // --- Pagination ---
+      if (checkPagination) {
+        const lsKey = `${pathname}:${localStorageVersion}:paginationModel`;
+        const lsRaw = localStorage.getItem(lsKey);
+        const lsPagination = lsRaw ? JSON.parse(lsRaw) : '';
+
+        const urlPagination = url.get('_pagination');
+        if (lsPagination && urlPagination) {
+          // localStorage: `_pagination=[0,10,next]`
+          // URL: `_pagination=0.10.next`
+          const lsParams = new URLSearchParams(lsPagination);
+          const lsPaginationValue = lsParams.get('_pagination') ?? '';
+          const lsMatch = lsPaginationValue.match(/^\[(\d+),(\d+),(\w+)\]$/);
+          if (lsMatch) {
+            const [, page, size, dir] = lsMatch;
+            expect(urlPagination).toBe(`${page}.${size}.${dir}`);
+          }
+        }
+      }
+
+      // --- Density ---
+      if (checkDensity) {
+        const lsKey = `${pathname}:${localStorageVersion}:densityModel`;
+        const lsRaw = localStorage.getItem(lsKey);
+        const lsDensity = lsRaw ? JSON.parse(lsRaw) : '';
+
+        const urlDensity = url.get('_density');
+        if (lsDensity && urlDensity) {
+          // localStorage: `_density=compact`
+          // URL: `_density=compact`
+          const lsParams = new URLSearchParams(lsDensity);
+          const lsDensityValue = lsParams.get('_density') ?? '';
+          expect(urlDensity).toBe(lsDensityValue);
+        }
+      }
+    },
+    { timeout: 5000 }
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Sorting — click column header and assert sort direction
+// ---------------------------------------------------------------------------
+
+/**
+ * Click a column header to cycle its sort direction (unsorted → asc → desc → unsorted).
+ * Finds the header by its displayed title text.
+ */
+export const clickColumnHeader = async (canvasElement: HTMLElement, headerName: string) => {
+  const headers = Array.from(canvasElement.querySelectorAll('.MuiDataGrid-columnHeader'));
+  const target = headers.find((h) => {
+    const title = h.querySelector('.MuiDataGrid-columnHeaderTitle');
+    return title?.textContent === headerName;
+  });
+  if (!target) throw new Error(`Could not find column header "${headerName}"`);
+  const titleEl = target.querySelector('.MuiDataGrid-columnHeaderTitle') as HTMLElement;
+  await userEvent.click(titleEl);
+};
+
+/**
+ * Assert a column header has the expected sort direction.
+ * MUI DataGrid sets `aria-sort="ascending" | "descending"` on the column header element.
+ * When unsorted, the attribute is absent.
+ */
+export const assertColumnSorted = async (
+  canvasElement: HTMLElement,
+  headerName: string,
+  direction: 'ascending' | 'descending' | 'none'
+) => {
+  await waitFor(() => {
+    const headers = Array.from(canvasElement.querySelectorAll('.MuiDataGrid-columnHeader'));
+    const target = headers.find((h) => {
+      const title = h.querySelector('.MuiDataGrid-columnHeaderTitle');
+      return title?.textContent === headerName;
+    });
+    expect(target).toBeTruthy();
+    if (direction === 'none') {
+      const val = target!.getAttribute('aria-sort');
+      expect(val === null || val === 'none').toBe(true);
+    } else {
+      expect(target!.getAttribute('aria-sort')).toBe(direction);
+    }
+  });
+};

package/data/demos/patterns/_shared/use-router-adapter.ts

@@ -0,0 +1,51 @@
+/**
+ * Router adapter for StatefulDataGrid — plain browser API implementation.
+ *
+ * StatefulDataGrid requires a `useRouter` hook that returns:
+ *   - `pathname`       — current URL path (used as localStorage key)
+ *   - `search`         — current query string (URL state source)
+ *   - `historyReplace` — update the URL without triggering navigation
+ *
+ * This adapter uses `window.location` and `window.history.replaceState`
+ * directly. It works in any browser environment without a routing framework.
+ *
+ * In real products, replace this with your framework's router:
+ *
+ *   react-router:
+ *     import { useLocation, useNavigate } from 'react-router-dom';
+ *     export const useRouter = () => {
+ *       const { pathname, search } = useLocation();
+ *       const navigate = useNavigate();
+ *       return {
+ *         pathname,
+ *         search,
+ *         historyReplace: (newSearch: string) => {
+ *           navigate(`${pathname}?${newSearch}`, { replace: true });
+ *         },
+ *       };
+ *     };
+ *
+ *   Next.js:
+ *     import { useRouter as useNextRouter } from 'next/router';
+ *     export const useRouter = () => {
+ *       const router = useNextRouter();
+ *       return {
+ *         pathname: router.pathname,
+ *         search: typeof window !== 'undefined' ? window.location.search : '',
+ *         historyReplace: (newSearch: string) => {
+ *           router.replace(`${router.pathname}?${newSearch}`, undefined, { shallow: true });
+ *         },
+ *       };
+ *     };
+ */
+export const useRouterAdapter = () => ({
+  pathname: window.location.pathname,
+  search: window.location.search,
+  historyReplace: (newSearch: string) => {
+    window.history.replaceState(
+      {},
+      '',
+      decodeURIComponent(`${window.location.pathname}?${new URLSearchParams(newSearch)}`)
+    );
+  },
+});