@redsift/table 12.6.1 → 12.6.2

package/_internal/StatefulDataGrid2.js

@@ -804,16 +804,40 @@ const clearAllVersionStorage = (id, maxVersion) => {
   clearPreviousVersionStorage(id, versions);
 };
 
+/** Options for `resetStatefulDataGridState` and `resetColumnVisibility`. */
+
+/**
+ * The query string a reset strips: `getSearch()` when given, otherwise the
+ * browser's live URL, otherwise the `search` fallback.
+ */
+const readLiveSearch = _ref2 => {
+  let {
+    search,
+    getSearch
+  } = _ref2;
+  if (getSearch) {
+    return getSearch();
+  }
+  if (typeof window !== 'undefined' && window.location) {
+    return window.location.search;
+  }
+  return search !== null && search !== void 0 ? search : '';
+};
+
 /**
  * Fully reset a `StatefulDataGrid` — clear localStorage for the given versions
  * and strip all grid-owned URL params (`_*` and `v=`), preserving any non-grid params.
  *
- * The function reads `window.location.search` directly so the strip always
- * operates on the live URL. This matters because consumers typically call this
- * from a component whose captured `search` snapshot may be stale — for example
- * when the grid has just written its own keys to the URL via the router adapter
- * but the parent hasn't re-rendered yet. Falling back to the supplied `search`
- * is only used in non-browser environments (SSR, unit tests without jsdom).
+ * The strip always operates on the live URL, because consumers typically call
+ * this from a component whose captured `search` snapshot may be stale — for
+ * example when the grid has just written its own keys to the URL via the
+ * router adapter but the parent hasn't re-rendered yet. The live URL is
+ * `getSearch()` when given, otherwise `window.location.search`. The supplied
+ * `search` is only used in non-browser environments (SSR, unit tests without
+ * jsdom).
+ *
+ * Under a browser router `window.location` is the router's URL. Under a memory
+ * history it is not, so pass `getSearch` (see `StatefulDataGridResetOptions`).
  *
  * The write is performed via `historyReplace(newSearch, { authoritative: true })`.
  * Adapters with delta/coalescing logic (e.g. `createReactRouterV5Adapter`)
@@ -826,17 +850,26 @@ const clearAllVersionStorage = (id, maxVersion) => {
  * const { search, historyReplace } = useMyRouter();
  * resetStatefulDataGridState({ id: 'myGrid', versions: [0, 1, 2], search, historyReplace });
  * ```
+ *
+ * Under a memory history, with `createReactRouterV5Adapter`:
+ * ```ts
+ * const { pathname, getSearch, historyReplace } = useRouter();
+ * resetStatefulDataGridState({ id: pathname, versions: [0, 1], getSearch, historyReplace });
+ * ```
  */
-const resetStatefulDataGridState = _ref2 => {
+const resetStatefulDataGridState = _ref3 => {
   let {
     id,
     versions,
     search,
+    getSearch,
     historyReplace
-  } = _ref2;
+  } = _ref3;
   clearPreviousVersionStorage(id, versions);
-  const liveSearch = typeof window !== 'undefined' && window.location ? window.location.search : search;
-  const params = new URLSearchParams(liveSearch);
+  const params = new URLSearchParams(readLiveSearch({
+    search,
+    getSearch
+  }));
   const keysToDelete = [];
   params.forEach((_value, key) => {
     if (key.startsWith('_') || key === 'v') {
@@ -865,9 +898,10 @@ const resetStatefulDataGridState = _ref2 => {
  * other params alone it will not clobber a filter the caller is writing in the
  * same transition.
  *
- * Like `resetStatefulDataGridState`, the URL strip reads `window.location.search`
- * directly so it operates on the live URL (the caller's captured snapshot may
- * be stale), and writes via `historyReplace(newSearch, { authoritative: true })`.
+ * Like `resetStatefulDataGridState`, the URL strip operates on the live URL
+ * (the caller's captured snapshot may be stale): `getSearch()` when given,
+ * otherwise `window.location.search`. Pass `getSearch` under a memory history.
+ * It writes via `historyReplace(newSearch, { authoritative: true })`.
  *
  * This clears the *persisted* state only. The caller is responsible for
  * resetting the *live* grid in the same tick:
@@ -876,13 +910,14 @@ const resetStatefulDataGridState = _ref2 => {
  * apiRef.current?.setColumnVisibilityModel?.({});
  * ```
  */
-const resetColumnVisibility = _ref3 => {
+const resetColumnVisibility = _ref4 => {
   let {
     id,
     versions,
     search,
+    getSearch,
     historyReplace
-  } = _ref3;
+  } = _ref4;
   for (const version of versions) {
     try {
       window.localStorage.removeItem(buildStorageKey({
@@ -894,8 +929,10 @@ const resetColumnVisibility = _ref3 => {
       // Ignore — storage may be unavailable (SSR, Safari private mode).
     }
   }
-  const liveSearch = typeof window !== 'undefined' && window.location ? window.location.search : search;
-  const params = new URLSearchParams(liveSearch);
+  const params = new URLSearchParams(readLiveSearch({
+    search,
+    getSearch
+  }));
   params.delete('_columnVisibility');
   historyReplace(params.toString(), {
     authoritative: true
@@ -3427,16 +3464,25 @@ const COMPONENT_NAME = 'DataGrid';
 const CLASSNAME = 'redsift-datagrid';
 
 /**
- * StatefulDataGrid extends DataGrid with automatic state persistence to localStorage.
- * Preserves filters, sorting, pagination, column visibility, and column widths
- * across page refreshes.
+ * StatefulDataGrid extends DataGrid with automatic state persistence to the URL and localStorage.
+ * Filters, sorting, pagination, column visibility, column order, pinned
+ * columns, density, row grouping, aggregation and pivot are written to the URL
+ * query string and to localStorage; column widths are kept in localStorage
+ * only. On load the URL wins, then localStorage, then `initialState`, so state
+ * survives page refreshes and a copied URL reopens the same view.
  *
- * Use when users need persistent table preferences. Requires unique `localStorageKey`.
+ * Use when users need persistent table preferences or shareable filtered views.
+ * Requires a `useRouter` hook returning `{ pathname, search, historyReplace }`
+ * (`createReactRouterV5Adapter` builds one from a React Router v5 `history`).
+ * State is stored in localStorage under the `pathname` it returns, and
+ * versioned by `localStorageVersion` (a number, default `1`).
  *
  * @example
- * // Basic stateful grid (persists to localStorage)
+ * // Basic stateful grid (URL + localStorage)
+ * const useRouter = createReactRouterV5Adapter(history);
+ *
  * <StatefulDataGrid
- *   localStorageKey="users-table"
+ *   useRouter={useRouter}
  *   columns={columns}
  *   rows={users}
  *   pagination
@@ -3445,34 +3491,24 @@ const CLASSNAME = 'redsift-datagrid';
  * @example
  * // With version migration (clears old preferences)
  * <StatefulDataGrid
- *   localStorageKey="reports-table"
- *   localStorageVersion="v2"
- *   previousLocalStorageVersions={['v1']}
+ *   useRouter={useRouter}
+ *   localStorageVersion={2}
+ *   previousLocalStorageVersions={[1]}
  *   columns={columns}
  *   rows={reports}
  * />
  *
  * @example
- * // With URL state sync (shareable filtered views)
- * <StatefulDataGrid
- *   localStorageKey="domains-table"
- *   useRouter={true}
- *   columns={columns}
- *   rows={domains}
- *   pagination
- * />
- *
- * @example
  * // All features combined
  * <StatefulDataGrid
- *   localStorageKey="audit-log"
- *   localStorageVersion="v3"
- *   previousLocalStorageVersions={['v1', 'v2']}
- *   useRouter={true}
+ *   useRouter={useRouter}
+ *   localStorageVersion={3}
+ *   previousLocalStorageVersions={[1, 2]}
  *   columns={columns}
  *   rows={logs}
  *   pagination
- *   pageSize={50}
+ *   pageSizeOptions={[25, 50, 100]}
+ *   initialState={{ pagination: { paginationModel: { page: 0, pageSize: 50 } } }}
  *   checkboxSelection
  * />
  */