@stackframe/dashboard-ui-components 2.8.84 → 2.8.86

package/dist/components/data-grid/types.d.ts

@@ -0,0 +1,242 @@
+import { ReactNode } from "react";
+
+//#region src/components/data-grid/types.d.ts
+/** Every row must be uniquely identifiable. The grid resolves identity
+ * through the top-level `getRowId` prop. */
+type RowId = string;
+type DataGridColumnType = "string" | "number" | "date" | "dateTime" | "boolean" | "singleSelect" | "custom";
+type DataGridColumnAlign = "left" | "center" | "right";
+type DataGridColumnPin = "left" | "right" | false;
+/** How `date` / `dateTime` cells render their value. `"relative"` shows
+ * "1 day ago"–style text with the full datetime in a tooltip; `"absolute"`
+ * shows the full datetime inline. */
+type DataGridDateDisplay = "relative" | "absolute";
+/** Per-column overrides for how a `date` / `dateTime` cell is formatted.
+ * If either function is omitted the grid falls back to its default
+ * (Intl.RelativeTimeFormat + `toLocaleString()`). */
+type DataGridDateFormat = {
+  relative?: (date: Date) => string;
+  absolute?: (date: Date) => string;
+};
+/** Context passed to `renderCell`. */
+type DataGridCellContext<TRow> = {
+  row: TRow;
+  rowId: RowId;
+  rowIndex: number;
+  value: unknown;
+  columnId: string;
+  isSelected: boolean;
+  /** Current date display mode — consumers writing custom `renderCell`
+   * for `date` / `dateTime` columns should branch on this to match the
+   * grid's built-in behaviour. */
+  dateDisplay: DataGridDateDisplay;
+};
+/** Context passed to `renderHeader`. */
+type DataGridHeaderContext<TRow> = {
+  columnId: string;
+  columnDef: DataGridColumnDef<TRow>;
+  isSorted: false | "asc" | "desc";
+  sortIndex: number | null;
+};
+/** A single column's full configuration. Generic over the row type. */
+type DataGridColumnDef<TRow> = {
+  /** Unique identifier for this column. */id: string; /** Display label. If a function is given it receives the header context. */
+  header: string | ((ctx: DataGridHeaderContext<TRow>) => ReactNode);
+  /** Accessor — either a key of TRow or a function. If omitted, `id` is
+   * used as the key. */
+  accessor?: keyof TRow | ((row: TRow) => unknown); /** Custom cell renderer. Falls back to plain text of the resolved value. */
+  renderCell?: (ctx: DataGridCellContext<TRow>) => ReactNode; /** Initial width in pixels. Defaults to 150. */
+  width?: number; /** Minimum width during resize. Defaults to 50. */
+  minWidth?: number; /** Maximum width during resize. Defaults to 800. */
+  maxWidth?: number;
+  /** Flex grow factor. When set, remaining space is distributed among flex
+   * columns proportionally. */
+  flex?: number;
+  sortable?: boolean;
+  resizable?: boolean;
+  hideable?: boolean; /** Pin position. Defaults to `false` (unpinned). */
+  pin?: DataGridColumnPin;
+  align?: DataGridColumnAlign; /** Column type affects default sorting. */
+  type?: DataGridColumnType; /** For `singleSelect` type — available value options. */
+  valueOptions?: readonly DataGridSelectOption[];
+  /** Custom sort comparator. Receives two resolved cell values.
+   * Return negative if a < b, positive if a > b, 0 if equal. */
+  sortComparator?: (a: unknown, b: unknown) => number;
+  /** Format a cell value to a plain string — used for export and
+   * clipboard copy. Defaults to `String(value)`. */
+  formatValue?: (value: unknown, row: TRow) => string;
+  /** Parse a raw cell value into a `Date`. Only consulted when `type` is
+   * `"date"` or `"dateTime"`. Defaults to `new Date(value)` with graceful
+   * handling of `null` / `undefined` / invalid dates. Override for
+   * non-standard formats (e.g. ClickHouse's space-separated UTC strings). */
+  parseValue?: (value: unknown) => Date | null; /** Per-column override for the relative / absolute date formatters. */
+  dateFormat?: DataGridDateFormat; /** Fired when a cell in this column is clicked. */
+  onCellClick?: (ctx: DataGridCellContext<TRow>, event: React.MouseEvent) => void; /** Fired when a cell in this column is double-clicked. */
+  onCellDoubleClick?: (ctx: DataGridCellContext<TRow>, event: React.MouseEvent) => void;
+};
+type DataGridSelectOption = {
+  value: string;
+  label: string;
+};
+type DataGridSortItem = {
+  columnId: string;
+  direction: "asc" | "desc";
+};
+type DataGridSortModel = readonly DataGridSortItem[];
+type DataGridSelectionMode = "none" | "single" | "multiple";
+type DataGridSelectionModel = {
+  selectedIds: ReadonlySet<RowId>; /** Tracks the last-clicked row for shift-range selection. */
+  anchorId: RowId | null;
+};
+type DataGridColumnVisibility = Record<string, boolean>;
+type DataGridColumnPinning = {
+  left: readonly string[];
+  right: readonly string[];
+};
+/** UI display mode — "paginated" shows page controls, "infinite" shows scroll sentinel. */
+type DataGridPaginationMode = "paginated" | "infinite";
+/** Data-fetching strategy used by `useDataSource`. */
+type DataGridDataPaginationMode = "client" | "server" | "infinite";
+type DataGridPaginationModel = {
+  pageIndex: number;
+  pageSize: number;
+};
+type DataGridState = {
+  sorting: DataGridSortModel;
+  columnVisibility: DataGridColumnVisibility;
+  columnWidths: Record<string, number>;
+  columnPinning: DataGridColumnPinning;
+  columnOrder: readonly string[];
+  pagination: DataGridPaginationModel;
+  selection: DataGridSelectionModel;
+  /** How `date` / `dateTime` columns render. Defaults to `"relative"`
+   * via `createDefaultDataGridState`. Toggled from the Columns popover
+   * whenever the grid has at least one date column. */
+  dateDisplay: DataGridDateDisplay;
+  /** Current quick-search text. Written by the built-in search input in
+   * the toolbar. `useDataSource` in client mode auto-filters by this
+   * value (via `applyQuickSearch`); in async mode it's passed through
+   * to the generator as `params.quickSearch`, where the consumer owns
+   * the "how do I match?" decision (typically by modifying the backend
+   * query). Defaults to `""`. */
+  quickSearch: string;
+};
+/** Params sent to the async data source on each fetch. */
+type DataGridFetchParams = {
+  sorting: DataGridSortModel;
+  pagination: DataGridPaginationModel;
+  /** Current quick-search text. Passed through from `state.quickSearch`
+   * so the async generator can fold it into its query (e.g. a SQL WHERE
+   * clause). Empty string when the search box is empty. A change in
+   * this value triggers a refetch, same mechanism as sorting. */
+  quickSearch: string; /** For cursor-based: the last row of the previous page. */
+  cursor: unknown;
+};
+/** Return type from a data source fetch. */
+type DataGridFetchResult<TRow> = {
+  rows: TRow[]; /** Total row count if known. `-1` or `undefined` for unknown (infinite). */
+  totalRowCount?: number; /** Cursor for the next page (for cursor-based pagination). */
+  nextCursor?: unknown; /** If `false`, there are no more pages. */
+  hasMore?: boolean;
+};
+/** An async-generator data source yields pages of rows. The generator
+ * receives fetch params as its argument and yields pages. Yielding
+ * allows the grid to display partial results during loading. */
+type DataGridDataSource<TRow> = (params: DataGridFetchParams) => AsyncGenerator<DataGridFetchResult<TRow>, void, undefined>;
+type DataGridCallbacks<TRow> = {
+  onRowClick?: (row: TRow, rowId: RowId, event: React.MouseEvent) => void;
+  onRowDoubleClick?: (row: TRow, rowId: RowId, event: React.MouseEvent) => void;
+  onCellClick?: (row: TRow, columnId: string, value: unknown, event: React.MouseEvent) => void;
+  onSelectionChange?: (selectedIds: ReadonlySet<RowId>, selectedRows: TRow[]) => void;
+  onSortChange?: (model: DataGridSortModel) => void;
+  onColumnResize?: (columnId: string, width: number) => void;
+  onColumnVisibilityChange?: (model: DataGridColumnVisibility) => void;
+};
+type DataGridProps<TRow> = {
+  /** Column definitions. */columns: readonly DataGridColumnDef<TRow>[];
+  /** The rows to display. The consumer is responsible for sorting
+   *  and paginating before passing them in. */
+  rows: readonly TRow[]; /** Extract a unique identifier from each row. */
+  getRowId: (row: TRow) => RowId; /** Total row count across all pages (used for pagination UI). */
+  totalRowCount?: number; /** True while the initial data load is in progress (shows skeleton). */
+  isLoading?: boolean; /** True during a background refetch (shows subtle indicator, keeps rows). */
+  isRefetching?: boolean; /** Whether more rows can be loaded (shows infinite scroll sentinel). */
+  hasMore?: boolean; /** True while loading the next page of infinite scroll. */
+  isLoadingMore?: boolean; /** Called when the infinite scroll sentinel becomes visible. */
+  onLoadMore?: () => void;
+  state: DataGridState;
+  onChange: React.Dispatch<React.SetStateAction<DataGridState>>;
+  /** UI mode for pagination. "paginated" shows page controls in the
+   *  footer. "infinite" shows a scroll sentinel instead. Defaults to
+   *  "paginated". */
+  paginationMode?: "paginated" | "infinite"; /** Selection behaviour. Defaults to "none". */
+  selectionMode?: DataGridSelectionMode; /** Whether columns can be resized by dragging. Defaults to true. */
+  resizable?: boolean; /** Row height in pixels. Defaults to 44. */
+  rowHeight?: number; /** Header row height in pixels. Defaults to 44. */
+  headerHeight?: number; /** Number of rows to render outside the visible area. Defaults to 5. */
+  overscan?: number; /** Grid max height. If omitted, grid takes available space. */
+  maxHeight?: number | string;
+} & DataGridCallbacks<TRow> & {
+  /** Custom toolbar renderer. When `false`, toolbar is hidden entirely. */toolbar?: false | ((ctx: DataGridToolbarContext<TRow>) => ReactNode);
+  /** Extra content rendered inside the default toolbar row, to the left of
+   *  the built-in columns / export actions. Use this to slot in
+   *  refresh buttons, custom toggles, row counts, etc. without giving up
+   *  the built-in actions. Ignored if a custom `toolbar` render function
+   *  is provided — that function owns the entire row. */
+  toolbarExtra?: ReactNode | ((ctx: DataGridToolbarContext<TRow>) => ReactNode); /** Custom empty state. Defaults to a centered "No data" message. */
+  emptyState?: ReactNode; /** Custom loading state. Defaults to skeleton rows. */
+  loadingState?: ReactNode; /** Custom footer. When `false`, footer is hidden. */
+  footer?: false | ((ctx: DataGridFooterContext<TRow>) => ReactNode); /** Extra content rendered to the right of the default footer info. */
+  footerExtra?: ReactNode | ((ctx: DataGridFooterContext<TRow>) => ReactNode); /** Filename stem for CSV export (without extension). */
+  exportFilename?: string; /** i18n overrides. */
+  strings?: Partial<DataGridStrings>;
+  className?: string;
+};
+type DataGridToolbarContext<TRow> = {
+  state: DataGridState;
+  onChange: React.Dispatch<React.SetStateAction<DataGridState>>;
+  columns: readonly DataGridColumnDef<TRow>[];
+  visibleColumns: readonly DataGridColumnDef<TRow>[];
+  totalRowCount: number | undefined;
+  selectedRowCount: number;
+  strings: DataGridStrings; /** Trigger a CSV export. */
+  exportCsv: () => void;
+};
+type DataGridFooterContext<TRow> = {
+  state: DataGridState;
+  totalRowCount: number | undefined;
+  visibleRowCount: number;
+  selectedRowCount: number;
+  paginationMode: DataGridPaginationMode;
+  strings: DataGridStrings;
+};
+type DataGridStrings = {
+  searchPlaceholder: string;
+  columns: string;
+  export: string;
+  density: string;
+  showAll: string;
+  hideAll: string;
+  resetColumns: string;
+  dateFormat: string;
+  dateFormatRelative: string;
+  dateFormatAbsolute: string;
+  rowsSelected: (count: number) => string;
+  rowsPerPage: string;
+  pageOf: (page: number, total: number) => string;
+  noData: string;
+  loading: string;
+  loadingMore: string;
+  exportCsv: string;
+  exportCopied: string;
+  sortAsc: string;
+  sortDesc: string;
+  unsort: string;
+  pinLeft: string;
+  pinRight: string;
+  unpin: string;
+  hideColumn: string;
+};
+//#endregion
+export { DataGridCallbacks, DataGridCellContext, DataGridColumnAlign, DataGridColumnDef, DataGridColumnPin, DataGridColumnPinning, DataGridColumnType, DataGridColumnVisibility, DataGridDataPaginationMode, DataGridDataSource, DataGridDateDisplay, DataGridDateFormat, DataGridFetchParams, DataGridFetchResult, DataGridFooterContext, DataGridHeaderContext, DataGridPaginationMode, DataGridPaginationModel, DataGridProps, DataGridSelectOption, DataGridSelectionMode, DataGridSelectionModel, DataGridSortItem, DataGridSortModel, DataGridState, DataGridStrings, DataGridToolbarContext, RowId };
+//# sourceMappingURL=types.d.ts.map

package/dist/components/data-grid/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/components/data-grid/types.ts"],"mappings":"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"}

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

@@ -0,0 +1,79 @@
+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;
+};
+/**
+ * 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,sBAFmB;EAInB,SAAA,WAJA;EAMA,YAAA,WAJA;EAMA,aAAA,WAFA;EAIA,QAAA;EAEA,OAAA,WAEA;EAAA,MAAA;AAAA;AAoRF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,iBAAgB,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,236 @@
+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: () => {}
+	}), [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 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;
+		}
+		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);
+		} finally {
+			if (!controller.signal.aborted) {
+				setIsLoading(false);
+				setIsRefetching(false);
+				setIsLoadingMore(false);
+			}
+		}
+	}, []);
+	(0, react.useEffect)(() => {
+		fetchPage(false).catch(() => {});
+		return () => abortRef.current?.abort();
+	}, [
+		fetchPage,
+		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])
+	};
+}
+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;
+	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\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  }), [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\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\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        console.error(\"[DataGrid] Data source error:\", 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  }, [fetchPage, 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  };\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  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/empty-state.d.ts

@@ -9,6 +9,22 @@ type DesignEmptyStateProps = {
   children?: React.ReactNode;
   className?: string;
 };
+/**
+ * Centered "no data" placeholder. Show this inside a `DataGrid` via the
+ * `emptyState` prop, inside a chart when a query returns zero rows, or
+ * inside a card when a section has nothing to display.
+ *
+ * ```tsx
+ * <DesignEmptyState
+ *   icon={SearchIcon}
+ *   title="No results"
+ *   description="Try adjusting your filters."
+ * />
+ * ```
+ *
+ * Prefer this over a raw "No data" div — it handles spacing, typography,
+ * and the optional icon for you. `icon` is a component type, not a rendered node.
+ */
 declare function DesignEmptyState({
   icon: Icon,
   title,

package/dist/components/empty-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"empty-state.d.ts","names":[],"sources":["../../src/components/empty-state.tsx"],"mappings":";;;;KAKY,qBAAA;EACV,IAAA,GAAO,KAAA,CAAM,WAAA;EACb,KAAA;EACA,WAAA;EACA,QAAA,GAAW,KAAA,CAAM,SAAA;EACjB,SAAA;AAAA;AAAA,iBAGc,gBAAA,CAAA;EACd,IAAA,EAAM,IAAA;EACN,KAAA;EACA,WAAA;EACA,QAAA;EACA;AAAA,GACC,qBAAA,GAAqB,kBAAA,CAAA,GAAA,CAAA,OAAA"}
+{"version":3,"file":"empty-state.d.ts","names":[],"sources":["../../src/components/empty-state.tsx"],"mappings":";;;;KAKY,qBAAA;EACV,IAAA,GAAO,KAAA,CAAM,WAAA;EACb,KAAA;EACA,WAAA;EACA,QAAA,GAAW,KAAA,CAAM,SAAA;EACjB,SAAA;AAAA;;;;;;;;;;;;AAmBF;;;;;iBAAgB,gBAAA,CAAA;EACd,IAAA,EAAM,IAAA;EACN,KAAA;EACA,WAAA;EACA,QAAA;EACA;AAAA,GACC,qBAAA,GAAqB,kBAAA,CAAA,GAAA,CAAA,OAAA"}

package/dist/components/empty-state.js

@@ -8,6 +8,22 @@ let react = require("react");
 react = require_chunk.__toESM(react);
 
 //#region src/components/empty-state.tsx
+/**
+* Centered "no data" placeholder. Show this inside a `DataGrid` via the
+* `emptyState` prop, inside a chart when a query returns zero rows, or
+* inside a card when a section has nothing to display.
+*
+* ```tsx
+* <DesignEmptyState
+*   icon={SearchIcon}
+*   title="No results"
+*   description="Try adjusting your filters."
+* />
+* ```
+*
+* Prefer this over a raw "No data" div — it handles spacing, typography,
+* and the optional icon for you. `icon` is a component type, not a rendered node.
+*/
 function DesignEmptyState({ icon: Icon, title = "No data available", description, children, className }) {
 	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 		className: (0, _stackframe_stack_ui.cn)("flex flex-col items-center justify-center py-12 px-6 text-center", className),