@hexclave/dashboard-ui-components 1.0.0

package/dist/components/data-grid/use-data-source.d.ts

@@ -0,0 +1,85 @@
+import { DataGridColumnDef, DataGridDataPaginationMode, DataGridDataSource, DataGridPaginationModel, DataGridSortModel, RowId } from "./types.js";
+
+//#region src/components/data-grid/use-data-source.d.ts
+type UseDataSourceResult<TRow> = {
+  /** All rows currently loaded (for infinite mode, the accumulated set). */rows: readonly TRow[]; /** Total row count if known. */
+  totalRowCount: number | undefined; /** Whether the initial load is in progress (no data at all yet). */
+  isLoading: boolean; /** Whether a background refetch is happening (data already shown). */
+  isRefetching: boolean; /** Whether more rows are being fetched (infinite scroll). */
+  isLoadingMore: boolean; /** Request the next page (infinite scroll). */
+  loadMore: () => void; /** Whether there are more pages to load. */
+  hasMore: boolean; /** Reload from scratch. */
+  reload: () => void;
+  /**
+   * Error from the most recent async fetch, if any. Consumers should render
+   * an error UI and offer a `reload()` button when this is non-null. Client
+   * mode never sets this (no fetching). Cleared on next successful fetch.
+   */
+  error: Error | null;
+};
+/**
+ * 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.
+ */
+declare function useDataSource<TRow>(opts: {
+  data?: readonly TRow[];
+  dataSource?: DataGridDataSource<TRow>;
+  columns: readonly DataGridColumnDef<TRow>[];
+  getRowId: (row: TRow) => RowId;
+  sorting: DataGridSortModel; /** Current quick-search text, typically `gridState.quickSearch`. */
+  quickSearch: string;
+  /** Override the default client-mode matcher. Ignored in async mode
+   * (there the generator is the matcher). */
+  matchRow?: (row: TRow, query: string, columns: readonly DataGridColumnDef<TRow>[]) => boolean;
+  pagination: DataGridPaginationModel;
+  paginationMode: DataGridDataPaginationMode;
+}): UseDataSourceResult<TRow>;
+//#endregion
+export { UseDataSourceResult, useDataSource };
+//# sourceMappingURL=use-data-source.d.ts.map

package/dist/components/data-grid/use-data-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-data-source.d.ts","names":[],"sources":["../../../src/components/data-grid/use-data-source.ts"],"mappings":";;;KAiBY,mBAAA;4EAEV,IAAA,WAAe,IAAA,IAFc;EAI7B,aAAA,sBAkBY;EAhBZ,SAAA,WAJA;EAMA,YAAA,WAJA;EAMA,aAAA,WAFA;EAIA,QAAA;EAEA,OAAA,WAEA;EAAA,MAAA;EAMO;;;AAkST;;EAlSE,KAAA,EAAO,KAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkSO,aAAA,MAAA,CAAoB,IAAA;EAClC,IAAA,YAAgB,IAAA;EAChB,UAAA,GAAa,kBAAA,CAAmB,IAAA;EAChC,OAAA,WAAkB,iBAAA,CAAkB,IAAA;EACpC,QAAA,GAAW,GAAA,EAAK,IAAA,KAAS,KAAA;EACzB,OAAA,EAAS,iBAAA;EAET,WAAA;;;EAGA,QAAA,IACE,GAAA,EAAK,IAAA,EACL,KAAA,UACA,OAAA,WAAkB,iBAAA,CAAkB,IAAA;EAEtC,UAAA,EAAY,uBAAA;EACZ,cAAA,EAAgB,0BAAA;AAAA,IACd,mBAAA,CAAoB,IAAA"}

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

@@ -0,0 +1,244 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_chunk = require('../../chunk-BE-pF4vm.js');
+let react = require("react");
+let __state_js = require("./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 = (0, react.useMemo)(() => {
+		const searched = (0, __state_js.applyQuickSearch)(data, quickSearch, columns, matchRow);
+		const comparator = (0, __state_js.buildRowComparator)(sorting, columns);
+		const sorted = comparator ? [...searched].sort(comparator) : searched;
+		const totalRowCount = sorted.length;
+		return {
+			rows: paginationMode === "client" ? (0, __state_js.paginateRows)(sorted, pagination) : sorted,
+			totalRowCount
+		};
+	}, [
+		data,
+		JSON.stringify(sorting),
+		quickSearch,
+		matchRow,
+		pagination.pageIndex,
+		pagination.pageSize,
+		paginationMode,
+		columns
+	]);
+	return (0, react.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] = (0, react.useState)([]);
+	const [totalRowCount, setTotalRowCount] = (0, react.useState)(void 0);
+	const [isLoading, setIsLoading] = (0, react.useState)(true);
+	const [isRefetching, setIsRefetching] = (0, react.useState)(false);
+	const [isLoadingMore, setIsLoadingMore] = (0, react.useState)(false);
+	const [hasMore, setHasMore] = (0, react.useState)(true);
+	const [error, setError] = (0, react.useState)(null);
+	const cursorRef = (0, react.useRef)(void 0);
+	const abortRef = (0, react.useRef)(null);
+	const pageIndexRef = (0, react.useRef)(0);
+	const hasDataRef = (0, react.useRef)(false);
+	const hasMountedServerPaginationRef = (0, react.useRef)(false);
+	const latestArgsRef = (0, react.useRef)({
+		dataSource,
+		getRowId,
+		sorting,
+		quickSearch,
+		pagination
+	});
+	latestArgsRef.current = {
+		dataSource,
+		getRowId,
+		sorting,
+		quickSearch,
+		pagination
+	};
+	const sortingKey = JSON.stringify(sorting);
+	const quickSearchKey = quickSearch;
+	const fetchPage = (0, react.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);
+			}
+		}
+	}, []);
+	(0, react.useEffect)(() => {
+		fetchPage(false).catch(() => {});
+		return () => abortRef.current?.abort();
+	}, [
+		fetchPage,
+		dataSource,
+		sortingKey,
+		quickSearchKey,
+		pagination.pageSize
+	]);
+	(0, react.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: (0, react.useCallback)(() => {
+			if (!isLoadingMore && hasMore && paginationMode === "infinite") fetchPage(true).catch(() => {});
+		}, [
+			isLoadingMore,
+			hasMore,
+			paginationMode,
+			fetchPage
+		]),
+		hasMore,
+		reload: (0, react.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 = __state_js.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
+exports.useDataSource = useDataSource;
+//# sourceMappingURL=use-data-source.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-data-source.js","names":["defaultMatchRow"],"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/components/data-grid/use-url-state.d.ts

@@ -0,0 +1,38 @@
+import { DataGridColumnDef, DataGridState } from "./types.js";
+
+//#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/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/components/data-grid/use-url-state.js

@@ -0,0 +1,214 @@
+"use client";
+
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_chunk = require('../../chunk-BE-pF4vm.js');
+let react = require("react");
+let __state_js = require("./state.js");
+let __data_grid_sizing_js = require("./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 = (0, __data_grid_sizing_js.clampColumnWidth)(col, col.width ?? __data_grid_sizing_js.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] = (0, __data_grid_sizing_js.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 = (0, react.useRef)(columns);
+	columnsRef.current = columns;
+	const initialRef = (0, react.useRef)(opts?.initial);
+	const [state, setState] = (0, react.useState)(() => {
+		const base = (0, __state_js.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)
+		};
+	});
+	(0, react.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
+	]);
+	(0, react.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 = (0, __state_js.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
+exports.useDataGridUrlState = useDataGridUrlState;
+//# sourceMappingURL=use-url-state.js.map