@redsift/table-pro 12.6.0 → 12.6.2

package/index.d.ts

@@ -359,16 +359,53 @@ declare const clearPreviousVersionStorage: (id: string, previousLocalStorageVers
  * Useful when the consumer wants to wipe all persisted grid state regardless of which version is active.
  */
 declare const clearAllVersionStorage: (id: string, maxVersion: number) => void;
+/** Options for `resetStatefulDataGridState` and `resetColumnVisibility`. */
+interface StatefulDataGridResetOptions {
+    /** The grid's localStorage id: the `pathname` its `useRouter` returns. */
+    id: string;
+    /** The localStorage versions to clear. */
+    versions: number[];
+    /**
+     * The router's query string, as the caller captured it. Under a browser
+     * router this is only a fallback: `window.location.search` is read instead,
+     * because a snapshot captured at render can be stale. It is used as given
+     * only when `window.location` is unavailable (SSR, tests without jsdom), and
+     * it is ignored when `getSearch` is given.
+     */
+    search?: string;
+    /**
+     * Returns the router's live query string, with or without the leading `?`.
+     * Called once, at reset time, and used instead of both
+     * `window.location.search` and `search`.
+     *
+     * Pass it under a memory history (`createMemoryHistory`, `MemoryRouter`),
+     * for example in a sift rendered in an iframe. There `window.location` is
+     * the document's URL, not the router's, so without it the reset would
+     * rebuild the router's query string from the wrong URL: it would drop the
+     * router's non-grid params and add the document's. Use
+     * `() => history.location.search`, or the `getSearch` of a
+     * `createReactRouterV5Adapter` router.
+     */
+    getSearch?: () => string;
+    /** Writes the new query string. Called once, with `{ authoritative: true }`. */
+    historyReplace: (newSearch: string, options?: {
+        authoritative?: boolean;
+    }) => void;
+}
 /**
  * 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`)
@@ -381,20 +418,14 @@ declare const clearAllVersionStorage: (id: string, maxVersion: number) => void;
  * 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 });
+ * ```
  */
-declare const resetStatefulDataGridState: ({ id, versions, search, historyReplace, }: {
-    id: string;
-    versions: number[];
-    /**
-     * Fallback search string used only when `window.location.search` is
-     * unavailable (SSR, non-jsdom tests). In a browser the live URL is used
-     * regardless of this value.
-     */
-    search: string;
-    historyReplace: (newSearch: string, options?: {
-        authoritative?: boolean;
-    }) => void;
-}) => void;
+declare const resetStatefulDataGridState: ({ id, versions, search, getSearch, historyReplace, }: StatefulDataGridResetOptions) => void;
 /**
  * Reset only the column-visibility state of a `StatefulDataGrid` back to its
  * default (all columns visible). Clears the persisted `visibilityModel`
@@ -408,9 +439,10 @@ declare const resetStatefulDataGridState: ({ id, versions, search, historyReplac
  * 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:
@@ -419,19 +451,7 @@ declare const resetStatefulDataGridState: ({ id, versions, search, historyReplac
  * apiRef.current?.setColumnVisibilityModel?.({});
  * ```
  */
-declare const resetColumnVisibility: ({ id, versions, search, historyReplace, }: {
-    id: string;
-    versions: number[];
-    /**
-     * Fallback search string used only when `window.location.search` is
-     * unavailable (SSR, non-jsdom tests). In a browser the live URL is used
-     * regardless of this value.
-     */
-    search: string;
-    historyReplace: (newSearch: string, options?: {
-        authoritative?: boolean;
-    }) => void;
-}) => void;
+declare const resetColumnVisibility: ({ id, versions, search, getSearch, historyReplace, }: StatefulDataGridResetOptions) => void;
 
 /**
  * Type for legacy array-based row selection (v7 and earlier)
@@ -811,16 +831,25 @@ interface StatefulDataGridProps extends DataGridProps {
 }
 
 /**
- * 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 and density 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
@@ -829,34 +858,24 @@ interface StatefulDataGridProps extends DataGridProps {
  * @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
  * />
  */
@@ -1060,6 +1079,14 @@ declare const areFilterModelsEquivalent: (filterModel: GridFilterModel, filterMo
  * `historyReplace`. Authoritative writes bypass the delta logic and write
  * synchronously to the live URL.
  *
+ * The router also returns `getSearch`, which reads `history.location.search`
+ * when it is called rather than when `useRouter()` ran. Pass it to
+ * `resetStatefulDataGridState` and `resetColumnVisibility` so that they strip
+ * the router's live URL. Under a memory history (`createMemoryHistory`, e.g.
+ * a sift rendered in an iframe) this is required: without it they read
+ * `window.location.search`, which is the document's URL and not the router's.
+ * Its identity is stable for the adapter's lifetime.
+ *
  * @example
  * ```tsx
  * import { createReactRouterV5Adapter } from '@redsift/table-pro';
@@ -1067,6 +1094,10 @@ declare const areFilterModelsEquivalent: (filterModel: GridFilterModel, filterMo
  * const useRouter = createReactRouterV5Adapter(history);
  *
  * <StatefulDataGrid useRouter={useRouter} … />
+ *
+ * // Reset, reading the router's URL (required under a memory history):
+ * const { pathname, getSearch, historyReplace } = useRouter();
+ * resetStatefulDataGridState({ id: pathname, versions: [0, 1], getSearch, historyReplace });
  * ```
  */
 /** Minimal subset of React Router v5 `history` used by the adapter. */
@@ -1087,6 +1118,8 @@ interface ReactRouterV5History {
 declare const createReactRouterV5Adapter: (history: ReactRouterV5History) => (() => {
     pathname: string;
     search: string;
+    /** Reads the router's live query string, without the leading `?`. */
+    getSearch: () => string;
     historyReplace: (newSearch: string, options?: {
         authoritative?: boolean;
     }) => void;
@@ -1370,4 +1403,4 @@ type ToolbarWrapperProps = {
  */
 declare const ToolbarWrapper: React$1.FC<ToolbarWrapperProps>;
 
-export { ARRAY_IS_EMPTY, ARRAY_IS_NOT_EMPTY, BaseButton, BaseCheckbox, BaseIcon, BaseIconButton, BaseTextField, CATEGORIES, COLUMN_ORDER_MODEL_KEY, CONTAINS_ANY_OF, Category, ColumnOptions, ColumnOrderModel, ColumnType, CompletionResponse, ControlledPagination, ControlledPaginationProps, DATE_IS_BETWEEN, DEFAULT_OPERATORS, DENSITY_MODEL_KEY, DETAIL_PANEL_TOGGLE_COL_DEF, DIMENSION_MODEL_KEY, DOES_NOT_CONTAIN, DOES_NOT_CONTAIN_ANY_OF, DOES_NOT_END_WITH, DOES_NOT_END_WITH_ANY_OF, DOES_NOT_EQUAL, DOES_NOT_HAVE, DOES_NOT_HAVE_ANY_OF, DOES_NOT_HAVE_ANY_OF_WITH_SELECT, DOES_NOT_HAVE_WITH_SELECT, DOES_NOT_START_WITH, DOES_NOT_START_WITH_ANY_OF, DataGrid, DataGridModel, DataGridProps, DateOperatorName, EMPTY_ROW_SELECTION_MODEL, ENDS_WITH_ANY_OF, FILTER_MODEL_KEY, FILTER_SEARCH_KEY, FilterConfig, FilterConfigColumn, GridDensityValue, GridToolbarFilterSemanticField, GridToolbarFilterSemanticFieldProps, HAS, HAS_ALL_OF, HAS_ALL_OF_WITH_SELECT, HAS_ANY_OF, HAS_ANY_OF_WITH_SELECT, HAS_ONLY, HAS_ONLY_WITH_SELECT, HAS_WITH_SELECT, IS, IS_ANY_OF, IS_ANY_OF_I, IS_ANY_OF_I_WITH_SELECT, IS_ANY_OF_WITH_SELECT, IS_BETWEEN, IS_NOT, IS_NOT_ANY_OF, IS_NOT_ANY_OF_WITH_SELECT, IS_NOT_WITH_SELECT, IS_WITH_SELECT, LegacyRowSelectionModel, MultiSelectOperatorName, NumberOperatorName, PAGINATION_MODEL_KEY, PINNED_COLUMNS, PinnedColumns, ReactRouterV5History, RowSelectionModelInput, SORT_MODEL_KEY, STARTS_WITH_ANY_OF, SelectionStatus, ServerSideControlledPagination, ServerSideControlledPaginationProps, SingleSelectOperatorName, StatefulDataGrid, StatefulDataGridProps, StringOperatorName, StyledDataGridProps, TagsOperatorName, TextCell, Toolbar, ToolbarWrapper, ToolbarWrapperProps, UseLinkedFilterModelOptions, UseLinkedFilterModelReturn, VISIBILITY_MODEL_KEY, areFilterModelsEquivalent, areSearchStringsEqual, buildQueryParamsString, buildStorageKey, clearAllVersionStorage, clearPreviousVersionStorage, convertFromDisplayFormat, convertToDisplayFormat, createColumn, createReactRouterV5Adapter, createRowSelectionModel, customColumnTypes, decodeValue, encodeValue, fixServerSideHeaderCheckboxSelection, getColumnOrderFromString, getColumnVisibilityFromString, getCompletion, getDecodedSearchFromUrl, getDensityFromString, getDensityModel, getFilterModelFromString, getFinalSearch, getGridDateOperatorsExtended, getGridNumericOperators, getGridStringArrayOperators, getGridStringArrayOperatorsWithSelect, getGridStringArrayOperatorsWithSelectOnStringArrayColumns, getGridStringOperators, getModelsParsedOrUpdateLocalStorage, getPaginationFromString, getPinnedColumnsFromString, getRsMultipleSelectColumnType, getRsMultipleSelectWithShortOperatorListColumnType, getRsNumberColumnType, getRsSingleSelectColumnType, getRsSingleSelectWithShortOperatorListColumnType, getRsStringColumnType, getSearchParamsFromColumnOrder, getSearchParamsFromColumnVisibility, getSearchParamsFromDensity, getSearchParamsFromFilterModel, getSearchParamsFromPagination, getSearchParamsFromPinnedColumns, getSearchParamsFromSorting, getSearchParamsFromTab, getSearchParamsFromVersion, getSelectableRowIdsInPage, getSelectedIds, getSelectionCount, getSortingFromString, isOperatorValueValid, isRowSelected, isValueValid, makeCaseInsensitive, muiIconToDSIcon, normalizeDateValue, normalizeRowSelectionModel, numberOperatorDecoder, numberOperatorEncoder, onServerSideSelectionStatusChange, operatorList, resetColumnVisibility, resetStatefulDataGridState, updateUrl, urlSearchParamsToString, useLinkedFilterModel, wrapCaseInsensitive };
+export { ARRAY_IS_EMPTY, ARRAY_IS_NOT_EMPTY, BaseButton, BaseCheckbox, BaseIcon, BaseIconButton, BaseTextField, CATEGORIES, COLUMN_ORDER_MODEL_KEY, CONTAINS_ANY_OF, Category, ColumnOptions, ColumnOrderModel, ColumnType, CompletionResponse, ControlledPagination, ControlledPaginationProps, DATE_IS_BETWEEN, DEFAULT_OPERATORS, DENSITY_MODEL_KEY, DETAIL_PANEL_TOGGLE_COL_DEF, DIMENSION_MODEL_KEY, DOES_NOT_CONTAIN, DOES_NOT_CONTAIN_ANY_OF, DOES_NOT_END_WITH, DOES_NOT_END_WITH_ANY_OF, DOES_NOT_EQUAL, DOES_NOT_HAVE, DOES_NOT_HAVE_ANY_OF, DOES_NOT_HAVE_ANY_OF_WITH_SELECT, DOES_NOT_HAVE_WITH_SELECT, DOES_NOT_START_WITH, DOES_NOT_START_WITH_ANY_OF, DataGrid, DataGridModel, DataGridProps, DateOperatorName, EMPTY_ROW_SELECTION_MODEL, ENDS_WITH_ANY_OF, FILTER_MODEL_KEY, FILTER_SEARCH_KEY, FilterConfig, FilterConfigColumn, GridDensityValue, GridToolbarFilterSemanticField, GridToolbarFilterSemanticFieldProps, HAS, HAS_ALL_OF, HAS_ALL_OF_WITH_SELECT, HAS_ANY_OF, HAS_ANY_OF_WITH_SELECT, HAS_ONLY, HAS_ONLY_WITH_SELECT, HAS_WITH_SELECT, IS, IS_ANY_OF, IS_ANY_OF_I, IS_ANY_OF_I_WITH_SELECT, IS_ANY_OF_WITH_SELECT, IS_BETWEEN, IS_NOT, IS_NOT_ANY_OF, IS_NOT_ANY_OF_WITH_SELECT, IS_NOT_WITH_SELECT, IS_WITH_SELECT, LegacyRowSelectionModel, MultiSelectOperatorName, NumberOperatorName, PAGINATION_MODEL_KEY, PINNED_COLUMNS, PinnedColumns, ReactRouterV5History, RowSelectionModelInput, SORT_MODEL_KEY, STARTS_WITH_ANY_OF, SelectionStatus, ServerSideControlledPagination, ServerSideControlledPaginationProps, SingleSelectOperatorName, StatefulDataGrid, StatefulDataGridProps, StatefulDataGridResetOptions, StringOperatorName, StyledDataGridProps, TagsOperatorName, TextCell, Toolbar, ToolbarWrapper, ToolbarWrapperProps, UseLinkedFilterModelOptions, UseLinkedFilterModelReturn, VISIBILITY_MODEL_KEY, areFilterModelsEquivalent, areSearchStringsEqual, buildQueryParamsString, buildStorageKey, clearAllVersionStorage, clearPreviousVersionStorage, convertFromDisplayFormat, convertToDisplayFormat, createColumn, createReactRouterV5Adapter, createRowSelectionModel, customColumnTypes, decodeValue, encodeValue, fixServerSideHeaderCheckboxSelection, getColumnOrderFromString, getColumnVisibilityFromString, getCompletion, getDecodedSearchFromUrl, getDensityFromString, getDensityModel, getFilterModelFromString, getFinalSearch, getGridDateOperatorsExtended, getGridNumericOperators, getGridStringArrayOperators, getGridStringArrayOperatorsWithSelect, getGridStringArrayOperatorsWithSelectOnStringArrayColumns, getGridStringOperators, getModelsParsedOrUpdateLocalStorage, getPaginationFromString, getPinnedColumnsFromString, getRsMultipleSelectColumnType, getRsMultipleSelectWithShortOperatorListColumnType, getRsNumberColumnType, getRsSingleSelectColumnType, getRsSingleSelectWithShortOperatorListColumnType, getRsStringColumnType, getSearchParamsFromColumnOrder, getSearchParamsFromColumnVisibility, getSearchParamsFromDensity, getSearchParamsFromFilterModel, getSearchParamsFromPagination, getSearchParamsFromPinnedColumns, getSearchParamsFromSorting, getSearchParamsFromTab, getSearchParamsFromVersion, getSelectableRowIdsInPage, getSelectedIds, getSelectionCount, getSortingFromString, isOperatorValueValid, isRowSelected, isValueValid, makeCaseInsensitive, muiIconToDSIcon, normalizeDateValue, normalizeRowSelectionModel, numberOperatorDecoder, numberOperatorEncoder, onServerSideSelectionStatusChange, operatorList, resetColumnVisibility, resetStatefulDataGridState, updateUrl, urlSearchParamsToString, useLinkedFilterModel, wrapCaseInsensitive };

package/index.js

@@ -441,6 +441,14 @@ function getOperatorsForType(type, compact) {
  * `historyReplace`. Authoritative writes bypass the delta logic and write
  * synchronously to the live URL.
  *
+ * The router also returns `getSearch`, which reads `history.location.search`
+ * when it is called rather than when `useRouter()` ran. Pass it to
+ * `resetStatefulDataGridState` and `resetColumnVisibility` so that they strip
+ * the router's live URL. Under a memory history (`createMemoryHistory`, e.g.
+ * a sift rendered in an iframe) this is required: without it they read
+ * `window.location.search`, which is the document's URL and not the router's.
+ * Its identity is stable for the adapter's lifetime.
+ *
  * @example
  * ```tsx
  * import { createReactRouterV5Adapter } from '@redsift/table-pro';
@@ -448,6 +456,10 @@ function getOperatorsForType(type, compact) {
  * const useRouter = createReactRouterV5Adapter(history);
  *
  * <StatefulDataGrid useRouter={useRouter} … />
+ *
+ * // Reset, reading the router's URL (required under a memory history):
+ * const { pathname, getSearch, historyReplace } = useRouter();
+ * resetStatefulDataGridState({ id: pathname, versions: [0, 1], getSearch, historyReplace });
  * ```
  */
 
@@ -481,18 +493,23 @@ const createReactRouterV5Adapter = history => {
       });
     });
   };
+
+  // Read at call time, unlike the `search` snapshot below. Defined once so its
+  // identity is stable across renders.
+  const getSearch = () => history.location.search.replace(/^\?/, '');
   return () => {
     // Capture the search snapshot AT THE TIME useRouter() is called. The
     // grid hands this string to its change handlers, which build a complete
     // new search string from it. Diffing the handler's `newSearch` against
     // this captured snapshot tells us which keys the handler intentionally
     // changed (vs. which are stale passthrough from sibling handlers' models).
-    const captured = history.location.search.replace(/^\?/, '');
+    const captured = getSearch();
     const capturedParams = new URLSearchParams(captured);
     const capturedKeys = new Set(capturedParams.keys());
     return {
       pathname: history.location.pathname,
       search: captured,
+      getSearch,
       historyReplace: (newSearch, options) => {
         // Authoritative writes (e.g. `resetStatefulDataGridState`) bypass the
         // delta-vs-captured-snapshot logic. The caller asserts that `newSearch`