@hexclave/dashboard-ui-components 1.0.0

package/dist/esm/components/data-grid/use-data-source.js

@@ -0,0 +1,242 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { applyQuickSearch, buildRowComparator, defaultMatchRow, paginateRows } from "./state.js";
+
+//#region src/components/data-grid/use-data-source.ts
+function useClientDataSource(opts) {
+	const { data, columns, sorting, quickSearch, matchRow, pagination, paginationMode } = opts;
+	const processed = useMemo(() => {
+		const searched = applyQuickSearch(data, quickSearch, columns, matchRow);
+		const comparator = buildRowComparator(sorting, columns);
+		const sorted = comparator ? [...searched].sort(comparator) : searched;
+		const totalRowCount = sorted.length;
+		return {
+			rows: paginationMode === "client" ? paginateRows(sorted, pagination) : sorted,
+			totalRowCount
+		};
+	}, [
+		data,
+		JSON.stringify(sorting),
+		quickSearch,
+		matchRow,
+		pagination.pageIndex,
+		pagination.pageSize,
+		paginationMode,
+		columns
+	]);
+	return useMemo(() => ({
+		rows: processed.rows,
+		totalRowCount: processed.totalRowCount,
+		isLoading: false,
+		isRefetching: false,
+		isLoadingMore: false,
+		loadMore: () => {},
+		hasMore: false,
+		reload: () => {},
+		error: null
+	}), [processed]);
+}
+function useAsyncDataSource(opts) {
+	const { dataSource, getRowId, sorting, quickSearch, pagination, paginationMode } = opts;
+	const [rows, setRows] = useState([]);
+	const [totalRowCount, setTotalRowCount] = useState(void 0);
+	const [isLoading, setIsLoading] = useState(true);
+	const [isRefetching, setIsRefetching] = useState(false);
+	const [isLoadingMore, setIsLoadingMore] = useState(false);
+	const [hasMore, setHasMore] = useState(true);
+	const [error, setError] = useState(null);
+	const cursorRef = useRef(void 0);
+	const abortRef = useRef(null);
+	const pageIndexRef = useRef(0);
+	const hasDataRef = useRef(false);
+	const hasMountedServerPaginationRef = useRef(false);
+	const latestArgsRef = useRef({
+		dataSource,
+		getRowId,
+		sorting,
+		quickSearch,
+		pagination
+	});
+	latestArgsRef.current = {
+		dataSource,
+		getRowId,
+		sorting,
+		quickSearch,
+		pagination
+	};
+	const sortingKey = JSON.stringify(sorting);
+	const quickSearchKey = quickSearch;
+	const fetchPage = useCallback(async (append) => {
+		const { dataSource: currentDataSource, getRowId: currentGetRowId, sorting: currentSorting, quickSearch: currentQuickSearch, pagination: currentPagination } = latestArgsRef.current;
+		abortRef.current?.abort();
+		const controller = new AbortController();
+		abortRef.current = controller;
+		if (append) setIsLoadingMore(true);
+		else {
+			if (hasDataRef.current) setIsRefetching(true);
+			else setIsLoading(true);
+			cursorRef.current = void 0;
+			pageIndexRef.current = 0;
+		}
+		setError(null);
+		try {
+			const gen = currentDataSource({
+				sorting: currentSorting,
+				quickSearch: currentQuickSearch,
+				pagination: append ? {
+					pageIndex: pageIndexRef.current,
+					pageSize: currentPagination.pageSize
+				} : currentPagination,
+				cursor: cursorRef.current
+			});
+			for await (const result of gen) {
+				if (controller.signal.aborted) return;
+				if (result.totalRowCount != null) setTotalRowCount(result.totalRowCount);
+				if (result.nextCursor !== void 0) cursorRef.current = result.nextCursor;
+				setHasMore(result.hasMore !== false);
+				if (append) setRows((prev) => {
+					const existingIds = new Set(prev.map(currentGetRowId));
+					const newRows = result.rows.filter((r) => !existingIds.has(currentGetRowId(r)));
+					return [...prev, ...newRows];
+				});
+				else setRows(result.rows);
+				hasDataRef.current = true;
+				pageIndexRef.current++;
+			}
+		} catch (err) {
+			if (controller.signal.aborted) return;
+			console.error("[DataGrid] Data source error:", err);
+			setError(err instanceof Error ? err : new Error(String(err)));
+		} finally {
+			if (!controller.signal.aborted) {
+				setIsLoading(false);
+				setIsRefetching(false);
+				setIsLoadingMore(false);
+			}
+		}
+	}, []);
+	useEffect(() => {
+		fetchPage(false).catch(() => {});
+		return () => abortRef.current?.abort();
+	}, [
+		fetchPage,
+		dataSource,
+		sortingKey,
+		quickSearchKey,
+		pagination.pageSize
+	]);
+	useEffect(() => {
+		if (paginationMode !== "server") {
+			hasMountedServerPaginationRef.current = false;
+			return;
+		}
+		if (!hasMountedServerPaginationRef.current) {
+			hasMountedServerPaginationRef.current = true;
+			return;
+		}
+		fetchPage(false).catch(() => {});
+	}, [
+		fetchPage,
+		paginationMode,
+		pagination.pageIndex
+	]);
+	return {
+		rows,
+		totalRowCount,
+		isLoading,
+		isRefetching,
+		isLoadingMore,
+		loadMore: useCallback(() => {
+			if (!isLoadingMore && hasMore && paginationMode === "infinite") fetchPage(true).catch(() => {});
+		}, [
+			isLoadingMore,
+			hasMore,
+			paginationMode,
+			fetchPage
+		]),
+		hasMore,
+		reload: useCallback(() => {
+			fetchPage(false).catch(() => {});
+		}, [fetchPage]),
+		error
+	};
+}
+const NOOP_DATA_SOURCE = async function* () {};
+const NOOP_GET_ROW_ID = () => "";
+/**
+* Hook that processes raw data through the grid's sort/pagination state
+* and returns the `rows` slice ready to pass to `DataGrid`. This is the
+* only correct way to feed client-side data into a grid.
+*
+* Two modes, picked by which prop you pass:
+* - `data: TRow[]` → client-side mode. In-memory sort + paginate.
+* - `dataSource: (params) => AsyncGenerator` → server / infinite mode.
+*   The generator yields pages as you scroll or change pages.
+*
+* ```tsx
+* // Client-side (most common):
+* const gridData = useDataSource({
+*   data: users,
+*   columns,
+*   getRowId: (row) => row.id,
+*   sorting: gridState.sorting,
+*   quickSearch: gridState.quickSearch,
+*   pagination: gridState.pagination,
+*   paginationMode: "client",
+* });
+*
+* <DataGrid
+*   columns={columns}
+*   rows={gridData.rows}
+*   totalRowCount={gridData.totalRowCount}
+*   isLoading={gridData.isLoading}
+*   state={gridState}
+*   onChange={setGridState}
+*   getRowId={(row) => row.id}
+* />
+* ```
+*
+* Rules:
+* - Call this hook unconditionally at the top level, before any early return.
+* - `rows` on `DataGrid` must ALWAYS be `gridData.rows`, never your raw array.
+* - For server or infinite pagination, use `dataSource` — see the
+*   `DataGridDataSource` type for the generator signature.
+*
+* Quick search:
+* - Client mode (`data` prop): the hook auto-filters rows via
+*   `applyQuickSearch` using a default case-insensitive substring match
+*   across every column. Override with `matchRow` for custom matching
+*   (fuzzy, weighted, field-specific, etc.).
+* - Async mode (`dataSource` prop): the hook passes `quickSearch` into
+*   `params.quickSearch` and re-runs the generator whenever the search
+*   string changes. The consumer owns the matching logic (typically by
+*   folding it into a backend query). The grid performs NO client-side
+*   filtering in async mode.
+*/
+function useDataSource(opts) {
+	const { data, dataSource, columns, getRowId, sorting, quickSearch, matchRow = defaultMatchRow, pagination, paginationMode } = opts;
+	const isClientMode = data != null && !dataSource;
+	if (process.env.NODE_ENV !== "production" && data == null && dataSource == null) console.warn("[useDataSource] neither `data` nor `dataSource` was provided — the grid will render empty indefinitely. Pass one or the other.");
+	if (process.env.NODE_ENV !== "production" && isClientMode && paginationMode === "infinite" && data.length > 0) console.warn("[useDataSource] `paginationMode: \"infinite\"` with a `data` array skips pagination entirely. Prefer `\"client\"` for in-memory lists or `\"server\"` + a `dataSource` generator for real paging.");
+	const clientResult = useClientDataSource({
+		data: data ?? [],
+		columns,
+		sorting,
+		quickSearch,
+		matchRow,
+		pagination,
+		paginationMode
+	});
+	const asyncResult = useAsyncDataSource({
+		dataSource: dataSource ?? NOOP_DATA_SOURCE,
+		getRowId: dataSource ? getRowId : NOOP_GET_ROW_ID,
+		sorting,
+		quickSearch,
+		pagination,
+		paginationMode
+	});
+	return isClientMode ? clientResult : asyncResult;
+}
+
+//#endregion
+export { useDataSource };
+//# sourceMappingURL=use-data-source.js.map

package/dist/esm/components/data-grid/use-data-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-data-source.js","names":[],"sources":["../../../../src/components/data-grid/use-data-source.ts"],"sourcesContent":["import { useCallback, useEffect, useMemo, useRef, useState } from \"react\";\nimport type {\n  DataGridColumnDef,\n  DataGridDataSource,\n  DataGridFetchParams,\n  DataGridDataPaginationMode,\n  DataGridPaginationModel,\n  DataGridSortModel,\n  RowId,\n} from \"./types\";\nimport {\n  applyQuickSearch,\n  buildRowComparator,\n  defaultMatchRow,\n  paginateRows,\n} from \"./state\";\n\nexport type UseDataSourceResult<TRow> = {\n  /** All rows currently loaded (for infinite mode, the accumulated set). */\n  rows: readonly TRow[];\n  /** Total row count if known. */\n  totalRowCount: number | undefined;\n  /** Whether the initial load is in progress (no data at all yet). */\n  isLoading: boolean;\n  /** Whether a background refetch is happening (data already shown). */\n  isRefetching: boolean;\n  /** Whether more rows are being fetched (infinite scroll). */\n  isLoadingMore: boolean;\n  /** Request the next page (infinite scroll). */\n  loadMore: () => void;\n  /** Whether there are more pages to load. */\n  hasMore: boolean;\n  /** Reload from scratch. */\n  reload: () => void;\n  /**\n   * Error from the most recent async fetch, if any. Consumers should render\n   * an error UI and offer a `reload()` button when this is non-null. Client\n   * mode never sets this (no fetching). Cleared on next successful fetch.\n   */\n  error: Error | null;\n};\n\n// ─── Client-side hook ────────────────────────────────────────────────\n// Memoised so resize / selection / other unrelated state changes\n// don't recompute or create new array references.\n\nfunction useClientDataSource<TRow>(opts: {\n  data: readonly TRow[];\n  columns: readonly DataGridColumnDef<TRow>[];\n  sorting: DataGridSortModel;\n  quickSearch: string;\n  matchRow: (\n    row: TRow,\n    query: string,\n    columns: readonly DataGridColumnDef<TRow>[],\n  ) => boolean;\n  pagination: DataGridPaginationModel;\n  paginationMode: DataGridDataPaginationMode;\n}): UseDataSourceResult<TRow> {\n  const { data, columns, sorting, quickSearch, matchRow, pagination, paginationMode } = opts;\n\n  // Stable serialised keys so useMemo only fires on real changes\n  const sortingKey = JSON.stringify(sorting);\n\n  const processed = useMemo(() => {\n    // Quick search is applied FIRST, on the full input. If nothing is\n    // typed this is a zero-cost no-op (applyQuickSearch returns the\n    // original array reference). Sort and paginate operate on the\n    // already-filtered set so the result counts are search-aware.\n    const searched = applyQuickSearch(data, quickSearch, columns, matchRow);\n    const comparator = buildRowComparator(sorting, columns);\n    const sorted = comparator ? [...searched].sort(comparator) : searched;\n    const totalRowCount = sorted.length;\n    const paged =\n      paginationMode === \"client\"\n        ? paginateRows(sorted as readonly TRow[], pagination)\n        : sorted;\n    return { rows: paged, totalRowCount };\n  }, [data, sortingKey, quickSearch, matchRow, pagination.pageIndex, pagination.pageSize, paginationMode, columns]);\n\n  return useMemo(() => ({\n    rows: processed.rows,\n    totalRowCount: processed.totalRowCount,\n    isLoading: false,\n    isRefetching: false,\n    isLoadingMore: false,\n    loadMore: () => {},\n    hasMore: false,\n    reload: () => {},\n    error: null,\n  }), [processed]);\n}\n\n// ─── Async data source hook ──────────────────────────────────────────\n// Key behaviour: when refetching (sort change), we keep showing the old\n// rows and set `isRefetching` instead of `isLoading`. This avoids the\n// jarring flash-to-skeleton on every sort toggle.\n\nfunction useAsyncDataSource<TRow>(opts: {\n  dataSource: DataGridDataSource<TRow>;\n  getRowId: (row: TRow) => RowId;\n  sorting: DataGridSortModel;\n  quickSearch: string;\n  pagination: DataGridPaginationModel;\n  paginationMode: DataGridDataPaginationMode;\n}): UseDataSourceResult<TRow> {\n  const {\n    dataSource,\n    getRowId,\n    sorting,\n    quickSearch,\n    pagination,\n    paginationMode,\n  } = opts;\n\n  const [rows, setRows] = useState<TRow[]>([]);\n  const [totalRowCount, setTotalRowCount] = useState<number | undefined>(undefined);\n  const [isLoading, setIsLoading] = useState(true);\n  const [isRefetching, setIsRefetching] = useState(false);\n  const [isLoadingMore, setIsLoadingMore] = useState(false);\n  const [hasMore, setHasMore] = useState(true);\n  const [error, setError] = useState<Error | null>(null);\n\n  const cursorRef = useRef<unknown>(undefined);\n  const abortRef = useRef<AbortController | null>(null);\n  const pageIndexRef = useRef(0);\n  const hasDataRef = useRef(false);\n  const hasMountedServerPaginationRef = useRef(false);\n\n  const latestArgsRef = useRef({\n    dataSource,\n    getRowId,\n    sorting,\n    quickSearch,\n    pagination,\n  });\n  latestArgsRef.current = { dataSource, getRowId, sorting, quickSearch, pagination };\n\n  const sortingKey = JSON.stringify(sorting);\n  const quickSearchKey = quickSearch;\n\n  const fetchPage = useCallback(\n    async (append: boolean) => {\n      const {\n        dataSource: currentDataSource,\n        getRowId: currentGetRowId,\n        sorting: currentSorting,\n        quickSearch: currentQuickSearch,\n        pagination: currentPagination,\n      } = latestArgsRef.current;\n\n      abortRef.current?.abort();\n      const controller = new AbortController();\n      abortRef.current = controller;\n\n      if (append) {\n        setIsLoadingMore(true);\n      } else {\n        // First load → skeleton. Subsequent → subtle refetch indicator.\n        if (hasDataRef.current) {\n          setIsRefetching(true);\n        } else {\n          setIsLoading(true);\n        }\n        cursorRef.current = undefined;\n        pageIndexRef.current = 0;\n      }\n      // Clear previous error at the start of a new attempt; we'll set it\n      // again if this attempt fails.\n      setError(null);\n\n      try {\n        const params: DataGridFetchParams = {\n          sorting: currentSorting,\n          quickSearch: currentQuickSearch,\n          pagination: append\n            ? { pageIndex: pageIndexRef.current, pageSize: currentPagination.pageSize }\n            : currentPagination,\n          cursor: cursorRef.current,\n        };\n\n        const gen = currentDataSource(params);\n\n        for await (const result of gen) {\n          if (controller.signal.aborted) return;\n\n          if (result.totalRowCount != null) {\n            setTotalRowCount(result.totalRowCount);\n          }\n          if (result.nextCursor !== undefined) {\n            cursorRef.current = result.nextCursor;\n          }\n          setHasMore(result.hasMore !== false);\n\n          if (append) {\n            setRows((prev) => {\n              const existingIds = new Set(prev.map(currentGetRowId));\n              const newRows = result.rows.filter(\n                (r) => !existingIds.has(currentGetRowId(r)),\n              );\n              return [...prev, ...newRows];\n            });\n          } else {\n            setRows(result.rows);\n          }\n\n          hasDataRef.current = true;\n          pageIndexRef.current++;\n        }\n      } catch (err) {\n        if (controller.signal.aborted) return;\n        // Surface the error on the result so consumers can render retry UI.\n        // Still log to console so it's visible in dev without forcing every\n        // consumer to wire up error rendering.\n        // eslint-disable-next-line no-console\n        console.error(\"[DataGrid] Data source error:\", err);\n        setError(err instanceof Error ? err : new Error(String(err)));\n      } finally {\n        if (!controller.signal.aborted) {\n          setIsLoading(false);\n          setIsRefetching(false);\n          setIsLoadingMore(false);\n        }\n      }\n    },\n    [],\n  );\n\n  useEffect(() => {\n    fetchPage(false).catch(() => {});\n    return () => abortRef.current?.abort();\n    // Also refetches when `dataSource` identity changes — consumers encode\n    // external filter state into the generator's closure, so a new\n    // generator reference is the signal that the query changed.\n  }, [fetchPage, dataSource, sortingKey, quickSearchKey, pagination.pageSize]);\n\n  useEffect(() => {\n    if (paginationMode !== \"server\") {\n      hasMountedServerPaginationRef.current = false;\n      return;\n    }\n    if (!hasMountedServerPaginationRef.current) {\n      hasMountedServerPaginationRef.current = true;\n      return;\n    }\n    fetchPage(false).catch(() => {});\n  }, [fetchPage, paginationMode, pagination.pageIndex]);\n\n  const loadMore = useCallback(() => {\n    if (!isLoadingMore && hasMore && paginationMode === \"infinite\") {\n      fetchPage(true).catch(() => {});\n    }\n  }, [isLoadingMore, hasMore, paginationMode, fetchPage]);\n\n  const reload = useCallback(() => {\n    fetchPage(false).catch(() => {});\n  }, [fetchPage]);\n\n  return {\n    rows,\n    totalRowCount,\n    isLoading,\n    isRefetching,\n    isLoadingMore,\n    loadMore,\n    hasMore,\n    reload,\n    error,\n  };\n}\n\n// ─── Noop data source (stable reference) ─────────────────────────────\nconst NOOP_DATA_SOURCE: DataGridDataSource<any> = async function* () {};\nconst NOOP_GET_ROW_ID = () => \"\";\n\n// ─── Public hook ─────────────────────────────────────────────────────\n// Both inner hooks are always called (React rules-of-hooks) but only\n// one provides the returned result.\n\n/**\n * Hook that processes raw data through the grid's sort/pagination state\n * and returns the `rows` slice ready to pass to `DataGrid`. This is the\n * only correct way to feed client-side data into a grid.\n *\n * Two modes, picked by which prop you pass:\n * - `data: TRow[]` → client-side mode. In-memory sort + paginate.\n * - `dataSource: (params) => AsyncGenerator` → server / infinite mode.\n *   The generator yields pages as you scroll or change pages.\n *\n * ```tsx\n * // Client-side (most common):\n * const gridData = useDataSource({\n *   data: users,\n *   columns,\n *   getRowId: (row) => row.id,\n *   sorting: gridState.sorting,\n *   quickSearch: gridState.quickSearch,\n *   pagination: gridState.pagination,\n *   paginationMode: \"client\",\n * });\n *\n * <DataGrid\n *   columns={columns}\n *   rows={gridData.rows}\n *   totalRowCount={gridData.totalRowCount}\n *   isLoading={gridData.isLoading}\n *   state={gridState}\n *   onChange={setGridState}\n *   getRowId={(row) => row.id}\n * />\n * ```\n *\n * Rules:\n * - Call this hook unconditionally at the top level, before any early return.\n * - `rows` on `DataGrid` must ALWAYS be `gridData.rows`, never your raw array.\n * - For server or infinite pagination, use `dataSource` — see the\n *   `DataGridDataSource` type for the generator signature.\n *\n * Quick search:\n * - Client mode (`data` prop): the hook auto-filters rows via\n *   `applyQuickSearch` using a default case-insensitive substring match\n *   across every column. Override with `matchRow` for custom matching\n *   (fuzzy, weighted, field-specific, etc.).\n * - Async mode (`dataSource` prop): the hook passes `quickSearch` into\n *   `params.quickSearch` and re-runs the generator whenever the search\n *   string changes. The consumer owns the matching logic (typically by\n *   folding it into a backend query). The grid performs NO client-side\n *   filtering in async mode.\n */\nexport function useDataSource<TRow>(opts: {\n  data?: readonly TRow[];\n  dataSource?: DataGridDataSource<TRow>;\n  columns: readonly DataGridColumnDef<TRow>[];\n  getRowId: (row: TRow) => RowId;\n  sorting: DataGridSortModel;\n  /** Current quick-search text, typically `gridState.quickSearch`. */\n  quickSearch: string;\n  /** Override the default client-mode matcher. Ignored in async mode\n   * (there the generator is the matcher). */\n  matchRow?: (\n    row: TRow,\n    query: string,\n    columns: readonly DataGridColumnDef<TRow>[],\n  ) => boolean;\n  pagination: DataGridPaginationModel;\n  paginationMode: DataGridDataPaginationMode;\n}): UseDataSourceResult<TRow> {\n  const {\n    data,\n    dataSource,\n    columns,\n    getRowId,\n    sorting,\n    quickSearch,\n    matchRow = defaultMatchRow,\n    pagination,\n    paginationMode,\n  } = opts;\n\n  const isClientMode = data != null && !dataSource;\n\n  if (process.env.NODE_ENV !== \"production\" && data == null && dataSource == null) {\n    // eslint-disable-next-line no-console\n    console.warn(\n      \"[useDataSource] neither `data` nor `dataSource` was provided — \"\n      + \"the grid will render empty indefinitely. Pass one or the other.\"\n    );\n  }\n\n  // Common footgun: consumers pass `data` as a fully-materialized array and\n  // set `paginationMode: \"infinite\"` expecting the grid to page through it.\n  // In client mode \"infinite\" skips `paginateRows` and returns every row;\n  // `hasMore` / `loadMore` on the result are always false/no-ops. If you\n  // want real paging, switch to `paginationMode: \"server\"` with a\n  // `dataSource` generator. If you want in-memory slicing, use `\"client\"`.\n  // If you're manually accumulating rows into `data` and driving the grid's\n  // sentinel via your own `hasMore`/`onLoadMore`, this warning is a hint —\n  // but current behavior (full list + external sentinel) is intentional.\n  if (\n    process.env.NODE_ENV !== \"production\"\n    && isClientMode\n    && paginationMode === \"infinite\"\n    && data.length > 0\n  ) {\n    // eslint-disable-next-line no-console\n    console.warn(\n      \"[useDataSource] `paginationMode: \\\"infinite\\\"` with a `data` array \"\n      + \"skips pagination entirely. Prefer `\\\"client\\\"` for in-memory lists \"\n      + \"or `\\\"server\\\"` + a `dataSource` generator for real paging.\"\n    );\n  }\n\n  const clientResult = useClientDataSource({\n    data: data ?? [],\n    columns,\n    sorting,\n    quickSearch,\n    matchRow,\n    pagination,\n    paginationMode,\n  });\n\n  const asyncResult = useAsyncDataSource({\n    dataSource: dataSource ?? NOOP_DATA_SOURCE,\n    getRowId: dataSource ? getRowId : NOOP_GET_ROW_ID,\n    sorting,\n    quickSearch,\n    pagination,\n    paginationMode,\n  });\n\n  return isClientMode ? clientResult : asyncResult;\n}\n"],"mappings":"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"}

package/dist/esm/components/data-grid/use-url-state.d.ts

@@ -0,0 +1,38 @@
+import { DataGridColumnDef, DataGridState } from "./types";
+
+//#region src/components/data-grid/use-url-state.d.ts
+type UrlStateOptions = {
+  /** Disambiguates URL params when multiple grids share a page. Defaults
+   * to `"grid"`. Use unique prefixes per-grid (e.g. `"users"`, `"teams"`). */
+  paramPrefix?: string;
+  /** Overrides for default state used when the URL has no value for a
+   * given key. Useful for things like a sensible initial sort (e.g.
+   * "newest signups first") that should appear on first load but be
+   * overridden when the user navigates to a bookmarked URL. */
+  initial?: Partial<Pick<DataGridState, "sorting" | "quickSearch" | "columnVisibility">>;
+};
+/**
+ * Drop-in replacement for `useState(() => createDefaultDataGridState(columns))`
+ * that persists user view preferences to URL search params, so a view
+ * can be bookmarked / shared / restored on reload.
+ *
+ * **Persisted:** column widths, hidden columns, sort model, quick-search.
+ * **Not persisted** (deliberately): pagination scroll position, selection,
+ * column pinning/order, date display mode — these are session-scoped.
+ *
+ * ```tsx
+ * const [gridState, setGridState] = useDataGridUrlState(columns, {
+ *   paramPrefix: "users",
+ *   initial: { sorting: [{ columnId: "signedUpAt", direction: "desc" }] },
+ * });
+ * ```
+ *
+ * URL encoding: `?{prefix}_w=...&{prefix}_h=...&{prefix}_s=...&{prefix}_q=...`.
+ * Default values are omitted so URLs stay clean. Updates use
+ * `history.replaceState` (not pushState) so back/forward isn't polluted,
+ * and `popstate` is observed so external URL changes flow back into state.
+ */
+declare function useDataGridUrlState<TRow>(columns: readonly DataGridColumnDef<TRow>[], opts?: UrlStateOptions): [DataGridState, React.Dispatch<React.SetStateAction<DataGridState>>];
+//#endregion
+export { useDataGridUrlState };
+//# sourceMappingURL=use-url-state.d.ts.map

package/dist/esm/components/data-grid/use-url-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-url-state.d.ts","names":[],"sources":["../../../../src/components/data-grid/use-url-state.ts"],"mappings":";;;KAqJK,eAAA;;AA3IY;EA8If,WAAA;;;;;EAKA,OAAA,GAAU,OAAA,CAAQ,IAAA,CAAK,aAAA;AAAA;;;;;;;;AAwBzB;;;;;;;;;;;;;;iBAAgB,mBAAA,MAAA,CACd,OAAA,WAAkB,iBAAA,CAAkB,IAAA,KACpC,IAAA,GAAO,eAAA,IACL,aAAA,EAAe,KAAA,CAAM,QAAA,CAAS,KAAA,CAAM,cAAA,CAAe,aAAA"}

package/dist/esm/components/data-grid/use-url-state.js

@@ -0,0 +1,212 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { createDefaultDataGridState } from "./state.js";
+import { DEFAULT_COL_WIDTH, clampColumnWidth } from "./data-grid-sizing.js";
+
+//#region src/components/data-grid/use-url-state.ts
+function serializeWidths(widths, columns) {
+	const parts = [];
+	for (const col of columns) {
+		const w = widths[col.id];
+		if (typeof w !== "number" || !Number.isFinite(w)) continue;
+		const defaultW = clampColumnWidth(col, col.width ?? DEFAULT_COL_WIDTH);
+		if (Math.round(w) === Math.round(defaultW)) continue;
+		parts.push(`${encodeURIComponent(col.id)}:${Math.round(w)}`);
+	}
+	return parts.join(",");
+}
+function parseWidths(raw, fallback, columns) {
+	if (!raw) return fallback;
+	const colMap = new Map(columns.map((c) => [c.id, c]));
+	const out = { ...fallback };
+	for (const part of raw.split(",")) {
+		const colonIdx = part.indexOf(":");
+		if (colonIdx <= 0) continue;
+		const encodedId = part.slice(0, colonIdx);
+		const num = part.slice(colonIdx + 1);
+		let id;
+		try {
+			id = decodeURIComponent(encodedId);
+		} catch {
+			continue;
+		}
+		if (!id || !num) continue;
+		const col = colMap.get(id);
+		if (!col) continue;
+		const n = Number(num);
+		if (!Number.isFinite(n)) continue;
+		out[id] = clampColumnWidth(col, n);
+	}
+	return out;
+}
+function serializeHidden(visibility) {
+	return Object.entries(visibility).filter(([, v]) => v === false).map(([id]) => encodeURIComponent(id)).join(",");
+}
+function parseHidden(raw, columns) {
+	if (!raw) return {};
+	const known = new Set(columns.map((c) => c.id));
+	const out = {};
+	for (const encodedId of raw.split(",")) {
+		let id;
+		try {
+			id = decodeURIComponent(encodedId);
+		} catch {
+			continue;
+		}
+		if (id && known.has(id)) out[id] = false;
+	}
+	return out;
+}
+function serializeSort(sort) {
+	return sort.map((s) => `${encodeURIComponent(s.columnId)}:${s.direction === "desc" ? "desc" : "asc"}`).join(",");
+}
+function sortEqual(a, b) {
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i].columnId !== b[i].columnId || a[i].direction !== b[i].direction) return false;
+	return true;
+}
+function parseSort(raw, fallback, columns) {
+	if (raw == null) return fallback;
+	if (raw === "") return [];
+	const known = new Set(columns.map((c) => c.id));
+	const out = [];
+	for (const part of raw.split(",")) {
+		const colonIdx = part.indexOf(":");
+		if (colonIdx <= 0) continue;
+		const encodedId = part.slice(0, colonIdx);
+		const dir = part.slice(colonIdx + 1);
+		if (dir !== "asc" && dir !== "desc") continue;
+		let id;
+		try {
+			id = decodeURIComponent(encodedId);
+		} catch {
+			continue;
+		}
+		if (!id || !known.has(id)) continue;
+		out.push({
+			columnId: id,
+			direction: dir
+		});
+	}
+	return out;
+}
+function parseQuickSearch(raw, fallback) {
+	if (raw == null) return fallback;
+	return raw;
+}
+/**
+* Drop-in replacement for `useState(() => createDefaultDataGridState(columns))`
+* that persists user view preferences to URL search params, so a view
+* can be bookmarked / shared / restored on reload.
+*
+* **Persisted:** column widths, hidden columns, sort model, quick-search.
+* **Not persisted** (deliberately): pagination scroll position, selection,
+* column pinning/order, date display mode — these are session-scoped.
+*
+* ```tsx
+* const [gridState, setGridState] = useDataGridUrlState(columns, {
+*   paramPrefix: "users",
+*   initial: { sorting: [{ columnId: "signedUpAt", direction: "desc" }] },
+* });
+* ```
+*
+* URL encoding: `?{prefix}_w=...&{prefix}_h=...&{prefix}_s=...&{prefix}_q=...`.
+* Default values are omitted so URLs stay clean. Updates use
+* `history.replaceState` (not pushState) so back/forward isn't polluted,
+* and `popstate` is observed so external URL changes flow back into state.
+*/
+function useDataGridUrlState(columns, opts) {
+	const prefix = opts?.paramPrefix ?? "grid";
+	const widthsKey = `${prefix}_w`;
+	const hiddenKey = `${prefix}_h`;
+	const sortKey = `${prefix}_s`;
+	const searchKey = `${prefix}_q`;
+	const columnsRef = useRef(columns);
+	columnsRef.current = columns;
+	const initialRef = useRef(opts?.initial);
+	const [state, setState] = useState(() => {
+		const base = createDefaultDataGridState(columns);
+		const initial = initialRef.current ?? {};
+		const baseWithInitial = {
+			...base,
+			sorting: initial.sorting ?? base.sorting,
+			quickSearch: initial.quickSearch ?? base.quickSearch,
+			columnVisibility: initial.columnVisibility ?? base.columnVisibility
+		};
+		if (typeof window === "undefined") return baseWithInitial;
+		const params = new URLSearchParams(window.location.search);
+		return {
+			...baseWithInitial,
+			columnWidths: parseWidths(params.get(widthsKey), base.columnWidths, columns),
+			columnVisibility: params.get(hiddenKey) != null ? parseHidden(params.get(hiddenKey), columns) : baseWithInitial.columnVisibility,
+			sorting: parseSort(params.get(sortKey), baseWithInitial.sorting, columns),
+			quickSearch: parseQuickSearch(params.get(searchKey), baseWithInitial.quickSearch)
+		};
+	});
+	useEffect(() => {
+		if (typeof window === "undefined") return;
+		const timer = setTimeout(() => {
+			const params = new URLSearchParams(window.location.search);
+			const before = params.toString();
+			const cols = columnsRef.current;
+			const initial = initialRef.current ?? {};
+			const widthsStr = serializeWidths(state.columnWidths, cols);
+			if (widthsStr) params.set(widthsKey, widthsStr);
+			else params.delete(widthsKey);
+			const hiddenStr = serializeHidden(state.columnVisibility);
+			const initialHidden = initial.columnVisibility ? serializeHidden(initial.columnVisibility) : "";
+			if (hiddenStr) params.set(hiddenKey, hiddenStr);
+			else if (initialHidden) params.set(hiddenKey, "");
+			else params.delete(hiddenKey);
+			const initialSort = initial.sorting ?? [];
+			if (sortEqual(state.sorting, initialSort)) params.delete(sortKey);
+			else params.set(sortKey, serializeSort(state.sorting));
+			const initialSearch = initial.quickSearch ?? "";
+			if (state.quickSearch === initialSearch) params.delete(searchKey);
+			else params.set(searchKey, state.quickSearch);
+			const after = params.toString();
+			if (before === after) return;
+			const url = `${window.location.pathname}${after ? `?${after}` : ""}${window.location.hash}`;
+			window.history.replaceState(window.history.state, "", url);
+		}, 100);
+		return () => clearTimeout(timer);
+	}, [
+		state.columnWidths,
+		state.columnVisibility,
+		state.sorting,
+		state.quickSearch,
+		widthsKey,
+		hiddenKey,
+		sortKey,
+		searchKey
+	]);
+	useEffect(() => {
+		if (typeof window === "undefined") return;
+		const onPop = () => {
+			const params = new URLSearchParams(window.location.search);
+			const cols = columnsRef.current;
+			const initial = initialRef.current ?? {};
+			const defaults = createDefaultDataGridState(cols);
+			setState((prev) => ({
+				...prev,
+				columnWidths: parseWidths(params.get(widthsKey), defaults.columnWidths, cols),
+				columnVisibility: params.get(hiddenKey) != null ? parseHidden(params.get(hiddenKey), cols) : initial.columnVisibility ?? defaults.columnVisibility,
+				sorting: parseSort(params.get(sortKey), initial.sorting ?? defaults.sorting, cols),
+				quickSearch: parseQuickSearch(params.get(searchKey), initial.quickSearch ?? defaults.quickSearch)
+			}));
+		};
+		window.addEventListener("popstate", onPop);
+		return () => window.removeEventListener("popstate", onPop);
+	}, [
+		widthsKey,
+		hiddenKey,
+		sortKey,
+		searchKey
+	]);
+	return [state, setState];
+}
+
+//#endregion
+export { useDataGridUrlState };
+//# sourceMappingURL=use-url-state.js.map

package/dist/esm/components/data-grid/use-url-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-url-state.js","names":[],"sources":["../../../../src/components/data-grid/use-url-state.ts"],"sourcesContent":["\"use client\";\n\nimport { useEffect, useRef, useState } from \"react\";\nimport { DEFAULT_COL_WIDTH, clampColumnWidth } from \"./data-grid-sizing\";\nimport { createDefaultDataGridState } from \"./state\";\nimport type {\n  DataGridColumnDef,\n  DataGridSortItem,\n  DataGridSortModel,\n  DataGridState,\n} from \"./types\";\n\n// ─── URL <-> state encoding ──────────────────────────────────────────\n// Compact, human-readable formats so URLs stay short. Each piece of\n// state gets its own param so unrelated changes don't churn shared keys:\n//\n//   ?{prefix}_w=name:200,email:300       column widths (only non-defaults)\n//   ?{prefix}_h=createdAt,role           hidden column ids\n//   ?{prefix}_s=signedUpAt:desc,name:asc multi-column sort\n//   ?{prefix}_q=alice                    quick-search text\n//\n// Column ids are URL-encoded so ids containing `,` `:` or other reserved\n// characters round-trip safely. Without encoding, an id like \"user:name\"\n// would silently break the parser.\n\n// ── widths ─────────────────────────────────────────────────────────\nfunction serializeWidths(\n  widths: Record<string, number>,\n  columns: readonly DataGridColumnDef<any>[],\n): string {\n  const parts: string[] = [];\n  for (const col of columns) {\n    const w = widths[col.id];\n    if (typeof w !== \"number\" || !Number.isFinite(w)) continue;\n    const defaultW = clampColumnWidth(col, col.width ?? DEFAULT_COL_WIDTH);\n    if (Math.round(w) === Math.round(defaultW)) continue;\n    parts.push(`${encodeURIComponent(col.id)}:${Math.round(w)}`);\n  }\n  return parts.join(\",\");\n}\n\nfunction parseWidths(\n  raw: string | null,\n  fallback: Record<string, number>,\n  columns: readonly DataGridColumnDef<any>[],\n): Record<string, number> {\n  if (!raw) return fallback;\n  const colMap = new Map(columns.map((c) => [c.id, c]));\n  const out: Record<string, number> = { ...fallback };\n  for (const part of raw.split(\",\")) {\n    // Only split on the FIRST colon — id-side is always pre-encoded so it\n    // can't contain a literal `:`, but width-side is always numeric.\n    const colonIdx = part.indexOf(\":\");\n    if (colonIdx <= 0) continue;\n    const encodedId = part.slice(0, colonIdx);\n    const num = part.slice(colonIdx + 1);\n    let id: string;\n    try {\n      id = decodeURIComponent(encodedId);\n    } catch {\n      continue;\n    }\n    if (!id || !num) continue;\n    const col = colMap.get(id);\n    if (!col) continue;\n    const n = Number(num);\n    if (!Number.isFinite(n)) continue;\n    out[id] = clampColumnWidth(col, n);\n  }\n  return out;\n}\n\n// ── hidden columns ─────────────────────────────────────────────────\nfunction serializeHidden(visibility: Record<string, boolean>): string {\n  return Object.entries(visibility)\n    .filter(([, v]) => v === false)\n    .map(([id]) => encodeURIComponent(id))\n    .join(\",\");\n}\n\nfunction parseHidden(\n  raw: string | null,\n  columns: readonly DataGridColumnDef<any>[],\n): Record<string, boolean> {\n  if (!raw) return {};\n  const known = new Set(columns.map((c) => c.id));\n  const out: Record<string, boolean> = {};\n  for (const encodedId of raw.split(\",\")) {\n    let id: string;\n    try {\n      id = decodeURIComponent(encodedId);\n    } catch {\n      continue;\n    }\n    if (id && known.has(id)) out[id] = false;\n  }\n  return out;\n}\n\n// ── sort model ─────────────────────────────────────────────────────\nfunction serializeSort(sort: DataGridSortModel): string {\n  return sort\n    .map((s) => `${encodeURIComponent(s.columnId)}:${s.direction === \"desc\" ? \"desc\" : \"asc\"}`)\n    .join(\",\");\n}\n\nfunction sortEqual(a: DataGridSortModel, b: DataGridSortModel): boolean {\n  if (a.length !== b.length) return false;\n  for (let i = 0; i < a.length; i++) {\n    if (a[i].columnId !== b[i].columnId || a[i].direction !== b[i].direction) return false;\n  }\n  return true;\n}\n\nfunction parseSort(\n  raw: string | null,\n  fallback: DataGridSortModel,\n  columns: readonly DataGridColumnDef<any>[],\n): DataGridSortModel {\n  if (raw == null) return fallback;\n  if (raw === \"\") return [];\n  const known = new Set(columns.map((c) => c.id));\n  const out: DataGridSortItem[] = [];\n  for (const part of raw.split(\",\")) {\n    const colonIdx = part.indexOf(\":\");\n    if (colonIdx <= 0) continue;\n    const encodedId = part.slice(0, colonIdx);\n    const dir = part.slice(colonIdx + 1);\n    if (dir !== \"asc\" && dir !== \"desc\") continue;\n    let id: string;\n    try {\n      id = decodeURIComponent(encodedId);\n    } catch {\n      continue;\n    }\n    if (!id || !known.has(id)) continue;\n    out.push({ columnId: id, direction: dir });\n  }\n  return out;\n}\n\n// ── quick search ───────────────────────────────────────────────────\nfunction parseQuickSearch(raw: string | null, fallback: string): string {\n  if (raw == null) return fallback;\n  return raw;\n}\n\n// ─── Hook ────────────────────────────────────────────────────────────\n\ntype UrlStateOptions = {\n  /** Disambiguates URL params when multiple grids share a page. Defaults\n   * to `\"grid\"`. Use unique prefixes per-grid (e.g. `\"users\"`, `\"teams\"`). */\n  paramPrefix?: string,\n  /** Overrides for default state used when the URL has no value for a\n   * given key. Useful for things like a sensible initial sort (e.g.\n   * \"newest signups first\") that should appear on first load but be\n   * overridden when the user navigates to a bookmarked URL. */\n  initial?: Partial<Pick<DataGridState, \"sorting\" | \"quickSearch\" | \"columnVisibility\">>,\n};\n\n/**\n * Drop-in replacement for `useState(() => createDefaultDataGridState(columns))`\n * that persists user view preferences to URL search params, so a view\n * can be bookmarked / shared / restored on reload.\n *\n * **Persisted:** column widths, hidden columns, sort model, quick-search.\n * **Not persisted** (deliberately): pagination scroll position, selection,\n * column pinning/order, date display mode — these are session-scoped.\n *\n * ```tsx\n * const [gridState, setGridState] = useDataGridUrlState(columns, {\n *   paramPrefix: \"users\",\n *   initial: { sorting: [{ columnId: \"signedUpAt\", direction: \"desc\" }] },\n * });\n * ```\n *\n * URL encoding: `?{prefix}_w=...&{prefix}_h=...&{prefix}_s=...&{prefix}_q=...`.\n * Default values are omitted so URLs stay clean. Updates use\n * `history.replaceState` (not pushState) so back/forward isn't polluted,\n * and `popstate` is observed so external URL changes flow back into state.\n */\nexport function useDataGridUrlState<TRow>(\n  columns: readonly DataGridColumnDef<TRow>[],\n  opts?: UrlStateOptions,\n): [DataGridState, React.Dispatch<React.SetStateAction<DataGridState>>] {\n  const prefix = opts?.paramPrefix ?? \"grid\";\n  const widthsKey = `${prefix}_w`;\n  const hiddenKey = `${prefix}_h`;\n  const sortKey = `${prefix}_s`;\n  const searchKey = `${prefix}_q`;\n\n  const columnsRef = useRef(columns);\n  columnsRef.current = columns;\n\n  // `initial` snapshots are captured once on first render. Re-running them\n  // each render would clobber the user's interactions.\n  const initialRef = useRef(opts?.initial);\n\n  const [state, setState] = useState<DataGridState>(() => {\n    const base = createDefaultDataGridState(columns);\n    const initial = initialRef.current ?? {};\n    const baseWithInitial: DataGridState = {\n      ...base,\n      sorting: initial.sorting ?? base.sorting,\n      quickSearch: initial.quickSearch ?? base.quickSearch,\n      columnVisibility: initial.columnVisibility ?? base.columnVisibility,\n    };\n    if (typeof window === \"undefined\") return baseWithInitial;\n    const params = new URLSearchParams(window.location.search);\n    return {\n      ...baseWithInitial,\n      columnWidths: parseWidths(params.get(widthsKey), base.columnWidths, columns),\n      columnVisibility: params.get(hiddenKey) != null\n        ? parseHidden(params.get(hiddenKey), columns)\n        : baseWithInitial.columnVisibility,\n      sorting: parseSort(params.get(sortKey), baseWithInitial.sorting, columns),\n      quickSearch: parseQuickSearch(params.get(searchKey), baseWithInitial.quickSearch),\n    };\n  });\n\n  // Sync state -> URL. Debounced so that high-frequency state changes\n  // (e.g. dragging a column resize handle, typing in the search box)\n  // don't fire a URL write per pixel / per keystroke.\n  useEffect(() => {\n    if (typeof window === \"undefined\") return;\n    const timer = setTimeout(() => {\n      const params = new URLSearchParams(window.location.search);\n      const before = params.toString();\n      const cols = columnsRef.current;\n      const initial = initialRef.current ?? {};\n\n      const widthsStr = serializeWidths(state.columnWidths, cols);\n      if (widthsStr) params.set(widthsKey, widthsStr);\n      else params.delete(widthsKey);\n\n      const hiddenStr = serializeHidden(state.columnVisibility);\n      // If the consumer supplied initial visibility, \"no hidden cols\" must\n      // be encoded explicitly (empty string) so a bookmark with no `_h=`\n      // doesn't silently re-hide a column the user just un-hid.\n      const initialHidden = initial.columnVisibility\n        ? serializeHidden(initial.columnVisibility)\n        : \"\";\n      if (hiddenStr) params.set(hiddenKey, hiddenStr);\n      else if (initialHidden) params.set(hiddenKey, \"\");\n      else params.delete(hiddenKey);\n\n      const initialSort = initial.sorting ?? [];\n      if (sortEqual(state.sorting, initialSort)) params.delete(sortKey);\n      else params.set(sortKey, serializeSort(state.sorting));\n\n      const initialSearch = initial.quickSearch ?? \"\";\n      if (state.quickSearch === initialSearch) params.delete(searchKey);\n      else params.set(searchKey, state.quickSearch);\n\n      const after = params.toString();\n      if (before === after) return;\n      const url = `${window.location.pathname}${after ? `?${after}` : \"\"}${window.location.hash}`;\n      window.history.replaceState(window.history.state, \"\", url);\n    }, 100);\n    return () => clearTimeout(timer);\n  }, [\n    state.columnWidths,\n    state.columnVisibility,\n    state.sorting,\n    state.quickSearch,\n    widthsKey,\n    hiddenKey,\n    sortKey,\n    searchKey,\n  ]);\n\n  // React to back/forward navigation.\n  useEffect(() => {\n    if (typeof window === \"undefined\") return;\n    const onPop = () => {\n      const params = new URLSearchParams(window.location.search);\n      const cols = columnsRef.current;\n      const initial = initialRef.current ?? {};\n      // When the URL no longer has a value for a key, reset to defaults\n      // rather than preserving the previous in-memory state — otherwise\n      // navigating back to a clean URL leaves stale state.\n      const defaults = createDefaultDataGridState(cols);\n      setState((prev) => ({\n        ...prev,\n        columnWidths: parseWidths(params.get(widthsKey), defaults.columnWidths, cols),\n        columnVisibility: params.get(hiddenKey) != null\n          ? parseHidden(params.get(hiddenKey), cols)\n          : (initial.columnVisibility ?? defaults.columnVisibility),\n        sorting: parseSort(params.get(sortKey), initial.sorting ?? defaults.sorting, cols),\n        quickSearch: parseQuickSearch(params.get(searchKey), initial.quickSearch ?? defaults.quickSearch),\n      }));\n    };\n    window.addEventListener(\"popstate\", onPop);\n    return () => window.removeEventListener(\"popstate\", onPop);\n  }, [widthsKey, hiddenKey, sortKey, searchKey]);\n\n  return [state, setState];\n}\n"],"mappings":"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"}

package/dist/esm/components/data-grid/use-url-state.test.d.ts

@@ -0,0 +1 @@
+export { };

package/dist/esm/components/data-grid/use-url-state.test.js

@@ -0,0 +1,91 @@
+import { act, renderHook } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { useDataGridUrlState } from "./use-url-state.js";
+
+//#region src/components/data-grid/use-url-state.test.tsx
+// @vitest-environment jsdom
+const columns = [{
+	id: "name",
+	header: "Name",
+	accessor: () => "",
+	width: 160,
+	minWidth: 80,
+	type: "string"
+}, {
+	id: "email",
+	header: "Email",
+	accessor: () => "",
+	width: 200,
+	minWidth: 80,
+	type: "string"
+}];
+function setUrl(search) {
+	window.history.replaceState(null, "", `/${search ? `?${search}` : ""}`);
+}
+beforeEach(() => {
+	setUrl("");
+});
+afterEach(() => {
+	setUrl("");
+});
+describe("useDataGridUrlState", () => {
+	it("initializes from existing URL params", () => {
+		setUrl("grid_w=name:240&grid_h=email");
+		const { result } = renderHook(() => useDataGridUrlState(columns));
+		const [state] = result.current;
+		expect(state.columnWidths.name).toBe(240);
+		expect(state.columnVisibility.email).toBe(false);
+	});
+	it("writes width changes back to the URL (after debounce)", async () => {
+		const { result } = renderHook(() => useDataGridUrlState(columns));
+		act(() => {
+			const [, setState] = result.current;
+			setState((prev) => ({
+				...prev,
+				columnWidths: {
+					...prev.columnWidths,
+					name: 250
+				}
+			}));
+		});
+		await new Promise((resolve) => setTimeout(resolve, 150));
+		expect(new URLSearchParams(window.location.search).get("grid_w")).toBe("name:250");
+	});
+	it("resets column widths to defaults when a popstate clears the URL", () => {
+		setUrl("grid_w=name:300");
+		const { result } = renderHook(() => useDataGridUrlState(columns));
+		expect(result.current[0].columnWidths.name).toBe(300);
+		act(() => {
+			setUrl("");
+			window.dispatchEvent(new PopStateEvent("popstate"));
+		});
+		expect(result.current[0].columnWidths.name).toBe(160);
+	});
+	it("isolates two grids on the same page via paramPrefix", async () => {
+		const { result: a } = renderHook(() => useDataGridUrlState(columns, { paramPrefix: "users" }));
+		const { result: b } = renderHook(() => useDataGridUrlState(columns, { paramPrefix: "teams" }));
+		act(() => {
+			a.current[1]((prev) => ({
+				...prev,
+				columnWidths: {
+					...prev.columnWidths,
+					name: 222
+				}
+			}));
+		});
+		await new Promise((resolve) => setTimeout(resolve, 150));
+		const params = new URLSearchParams(window.location.search);
+		expect(params.get("users_w")).toBe("name:222");
+		expect(params.get("teams_w")).toBeNull();
+		expect(b.current[0].columnWidths.name).toBe(160);
+	});
+	it("ignores malformed entries in the URL param without throwing", () => {
+		setUrl("grid_w=:,name:abc,name:240,bogusid:99");
+		const { result } = renderHook(() => useDataGridUrlState(columns));
+		expect(result.current[0].columnWidths.name).toBe(240);
+	});
+});
+
+//#endregion
+export {  };
+//# sourceMappingURL=use-url-state.test.js.map