@hexclave/dashboard-ui-components 1.0.40 → 1.0.42

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

@@ -1,308 +1,2 @@
-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[];
-  /** How cell content handles overflow.
-   * - `"truncate"` (default): single-line with text-overflow ellipsis.
-   * - `"wrap"`: content wraps naturally. When combined with
-   *   `rowHeight="auto"` on the grid, the row grows to fit. With a
-   *   fixed `rowHeight`, wrapped content is clipped at the row boundary. */
-  cellOverflow?: "truncate" | "wrap";
-  /** 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 DataGridExportFormat = "csv" | "json";
-type DataGridExportScope = "all" | "filtered";
-type DataGridExportField<TRow> = {
-  key: string;
-  label: string;
-  enabled: boolean;
-  getValue: (row: TRow) => unknown;
-};
-type DataGridExportRowsOptions = {
-  scope: DataGridExportScope;
-  onProgress: (fetched: number) => void;
-};
-type DataGridExportOptions<TRow> = {
-  title?: string;
-  description?: ReactNode;
-  entityName?: string;
-  entityNamePlural?: string;
-  filenamePrefix?: string;
-  fields?: readonly DataGridExportField<TRow>[];
-  fetchRows?: (options: DataGridExportRowsOptions) => Promise<readonly TRow[]>;
-  emptyExportTitle?: string;
-  emptyExportDescription?: string;
-  allScopeLabel?: ReactNode;
-  filteredScopeLabel?: ReactNode;
-  progressSubjectLabel?: string; /** Which export scope is selected by default when the dialog opens. Defaults to `"all"`. */
-  defaultScope?: DataGridExportScope;
-};
-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;
-  /**
-   * Fires when the selection set changes. **Page-scoped:** the header "select
-   * all" checkbox and `selectedRows` only cover the rows currently rendered
-   * (the visible page in paginated mode, or the loaded prefix in infinite
-   * mode). The grid does not load other pages to satisfy the selection — if
-   * you need cross-page selection, drive `selectedIds` from your own state
-   * and load all rows you care about up-front.
-   */
-  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, or `"auto"` for dynamic measurement.
-   *
-   * - **number** (default `44`): every row is exactly this tall.
-   *   Fast and predictable; content that overflows is clipped.
-   * - **`"auto"`**: each row is measured by the browser after render
-   *   and the virtualizer adjusts positions accordingly. Columns
-   *   with `cellOverflow: "wrap"` will push the row taller; columns
-   *   with `cellOverflow: "truncate"` (or the default) stay
-   *   single-line. Use `estimatedRowHeight` to reduce scroll-jank
-   *   when rows haven't been measured yet. */
-  rowHeight?: number | "auto";
-  /** Estimated row height used by the virtualizer when
-   *  `rowHeight="auto"`. Better estimates = less scroll-position
-   *  jank before rows are measured. Defaults to 44. Ignored when
-   *  `rowHeight` is a number. */
-  estimatedRowHeight?: 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 (when `fillHeight`). */
-  maxHeight?: number | string;
-  /**
-   * When `true` (default), the grid uses `h-full` and the row area scrolls inside the grid.
-   * When `false`, the grid is only as tall as toolbar + header + rows (`h-auto`), so sibling
-   * content (e.g. metadata) sits directly under the table without a large empty gap.
-   */
-  fillHeight?: boolean; /** Top offset for the sticky toolbar + header (px or CSS string). */
-  stickyTop?: 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;
-  /** Full export dialog configuration. If omitted, the dialog exports the
-   * currently loaded rows using the grid's visible columns. */
-  exportOptions?: DataGridExportOptions<TRow>; /** 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, DataGridExportField, DataGridExportFormat, DataGridExportOptions, DataGridExportRowsOptions, DataGridExportScope, DataGridFetchParams, DataGridFetchResult, DataGridFooterContext, DataGridHeaderContext, DataGridPaginationMode, DataGridPaginationModel, DataGridProps, DataGridSelectOption, DataGridSelectionMode, DataGridSelectionModel, DataGridSortItem, DataGridSortModel, DataGridState, DataGridStrings, DataGridToolbarContext, RowId };
-//# sourceMappingURL=types.d.ts.map
+import { A as DataGridState, C as DataGridPaginationModel, D as DataGridSelectionModel, E as DataGridSelectionMode, M as DataGridToolbarContext, N as RowId, O as DataGridSortItem, S as DataGridPaginationMode, T as DataGridSelectOption, _ as DataGridExportScope, a as DataGridColumnPin, b as DataGridFooterContext, c as DataGridColumnVisibility, d as DataGridDateDisplay, f as DataGridDateFormat, g as DataGridExportRowsOptions, h as DataGridExportOptions, i as DataGridColumnDef, j as DataGridStrings, k as DataGridSortModel, l as DataGridDataPaginationMode, m as DataGridExportFormat, n as DataGridCellContext, o as DataGridColumnPinning, p as DataGridExportField, r as DataGridColumnAlign, s as DataGridColumnType, t as DataGridCallbacks, u as DataGridDataSource, v as DataGridFetchParams, w as DataGridProps, x as DataGridHeaderContext, y as DataGridFetchResult } from "../../types-1-eOd1JF.js";
+export { DataGridCallbacks, DataGridCellContext, DataGridColumnAlign, DataGridColumnDef, DataGridColumnPin, DataGridColumnPinning, DataGridColumnType, DataGridColumnVisibility, DataGridDataPaginationMode, DataGridDataSource, DataGridDateDisplay, DataGridDateFormat, DataGridExportField, DataGridExportFormat, DataGridExportOptions, DataGridExportRowsOptions, DataGridExportScope, DataGridFetchParams, DataGridFetchResult, DataGridFooterContext, DataGridHeaderContext, DataGridPaginationMode, DataGridPaginationModel, DataGridProps, DataGridSelectOption, DataGridSelectionMode, DataGridSelectionModel, DataGridSortItem, DataGridSortModel, DataGridState, DataGridStrings, DataGridToolbarContext, RowId };

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

@@ -1,85 +1,2 @@
-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
+import { n as useDataSource, t as UseDataSourceResult } from "../../use-data-source-BVFynerX.js";
+export { UseDataSourceResult, useDataSource };

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

@@ -1,8 +1,6 @@
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_chunk = require('../../chunk-BE-pF4vm.js');
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 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;
@@ -238,7 +236,7 @@ function useDataSource(opts) {
 	});
 	return isClientMode ? clientResult : asyncResult;
 }
-
 //#endregion
 exports.useDataSource = useDataSource;
+
 //# sourceMappingURL=use-data-source.js.map

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

@@ -1 +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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"}
+{"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":";;;;AA8CA,SAAS,oBAA0B,MAYL;CAC5B,MAAM,EAAE,MAAM,SAAS,SAAS,aAAa,UAAU,YAAY,mBAAmB;CAKtF,MAAM,aAAA,GAAA,MAAA,QAAA,OAA0B;EAK9B,MAAM,YAAA,GAAA,WAAA,iBAAA,CAA4B,MAAM,aAAa,SAAS,QAAQ;EACtE,MAAM,cAAA,GAAA,WAAA,mBAAA,CAAgC,SAAS,OAAO;EACtD,MAAM,SAAS,aAAa,CAAC,GAAG,QAAQ,CAAC,CAAC,KAAK,UAAU,IAAI;EAC7D,MAAM,gBAAgB,OAAO;EAK7B,OAAO;GAAE,MAHP,mBAAmB,YAAA,GAAA,WAAA,aAAA,CACF,QAA2B,UAAU,IAClD;GACgB;EAAc;CACtC,GAAG;EAAC;EAhBe,KAAK,UAAU,OAgBf;EAAG;EAAa;EAAU,WAAW;EAAW,WAAW;EAAU;EAAgB;CAAO,CAAC;CAEhH,QAAA,GAAA,MAAA,QAAA,QAAsB;EACpB,MAAM,UAAU;EAChB,eAAe,UAAU;EACzB,WAAW;EACX,cAAc;EACd,eAAe;EACf,gBAAgB,CAAC;EACjB,SAAS;EACT,cAAc,CAAC;EACf,OAAO;CACT,IAAI,CAAC,SAAS,CAAC;AACjB;AAOA,SAAS,mBAAyB,MAOJ;CAC5B,MAAM,EACJ,YACA,UACA,SACA,aACA,YACA,mBACE;CAEJ,MAAM,CAAC,MAAM,YAAA,GAAA,MAAA,SAAA,CAA4B,CAAC,CAAC;CAC3C,MAAM,CAAC,eAAe,qBAAA,GAAA,MAAA,SAAA,CAAiD,KAAA,CAAS;CAChF,MAAM,CAAC,WAAW,iBAAA,GAAA,MAAA,SAAA,CAAyB,IAAI;CAC/C,MAAM,CAAC,cAAc,oBAAA,GAAA,MAAA,SAAA,CAA4B,KAAK;CACtD,MAAM,CAAC,eAAe,qBAAA,GAAA,MAAA,SAAA,CAA6B,KAAK;CACxD,MAAM,CAAC,SAAS,eAAA,GAAA,MAAA,SAAA,CAAuB,IAAI;CAC3C,MAAM,CAAC,OAAO,aAAA,GAAA,MAAA,SAAA,CAAmC,IAAI;CAErD,MAAM,aAAA,GAAA,MAAA,OAAA,CAA4B,KAAA,CAAS;CAC3C,MAAM,YAAA,GAAA,MAAA,OAAA,CAA0C,IAAI;CACpD,MAAM,gBAAA,GAAA,MAAA,OAAA,CAAsB,CAAC;CAC7B,MAAM,cAAA,GAAA,MAAA,OAAA,CAAoB,KAAK;CAC/B,MAAM,iCAAA,GAAA,MAAA,OAAA,CAAuC,KAAK;CAElD,MAAM,iBAAA,GAAA,MAAA,OAAA,CAAuB;EAC3B;EACA;EACA;EACA;EACA;CACF,CAAC;CACD,cAAc,UAAU;EAAE;EAAY;EAAU;EAAS;EAAa;CAAW;CAEjF,MAAM,aAAa,KAAK,UAAU,OAAO;CACzC,MAAM,iBAAiB;CAEvB,MAAM,aAAA,GAAA,MAAA,YAAA,CACJ,OAAO,WAAoB;EACzB,MAAM,EACJ,YAAY,mBACZ,UAAU,iBACV,SAAS,gBACT,aAAa,oBACb,YAAY,sBACV,cAAc;EAElB,SAAS,SAAS,MAAM;EACxB,MAAM,aAAa,IAAI,gBAAgB;EACvC,SAAS,UAAU;EAEnB,IAAI,QACF,iBAAiB,IAAI;OAChB;GAEL,IAAI,WAAW,SACb,gBAAgB,IAAI;QAEpB,aAAa,IAAI;GAEnB,UAAU,UAAU,KAAA;GACpB,aAAa,UAAU;EACzB;EAGA,SAAS,IAAI;EAEb,IAAI;GAUF,MAAM,MAAM,kBAAkB;IAR5B,SAAS;IACT,aAAa;IACb,YAAY,SACR;KAAE,WAAW,aAAa;KAAS,UAAU,kBAAkB;IAAS,IACxE;IACJ,QAAQ,UAAU;GAGe,CAAC;GAEpC,WAAW,MAAM,UAAU,KAAK;IAC9B,IAAI,WAAW,OAAO,SAAS;IAE/B,IAAI,OAAO,iBAAiB,MAC1B,iBAAiB,OAAO,aAAa;IAEvC,IAAI,OAAO,eAAe,KAAA,GACxB,UAAU,UAAU,OAAO;IAE7B,WAAW,OAAO,YAAY,KAAK;IAEnC,IAAI,QACF,SAAS,SAAS;KAChB,MAAM,cAAc,IAAI,IAAI,KAAK,IAAI,eAAe,CAAC;KACrD,MAAM,UAAU,OAAO,KAAK,QACzB,MAAM,CAAC,YAAY,IAAI,gBAAgB,CAAC,CAAC,CAC5C;KACA,OAAO,CAAC,GAAG,MAAM,GAAG,OAAO;IAC7B,CAAC;SAED,QAAQ,OAAO,IAAI;IAGrB,WAAW,UAAU;IACrB,aAAa;GACf;EACF,SAAS,KAAK;GACZ,IAAI,WAAW,OAAO,SAAS;GAK/B,QAAQ,MAAM,iCAAiC,GAAG;GAClD,SAAS,eAAe,QAAQ,MAAM,IAAI,MAAM,OAAO,GAAG,CAAC,CAAC;EAC9D,UAAU;GACR,IAAI,CAAC,WAAW,OAAO,SAAS;IAC9B,aAAa,KAAK;IAClB,gBAAgB,KAAK;IACrB,iBAAiB,KAAK;GACxB;EACF;CACF,GACA,CAAC,CACH;CAEA,CAAA,GAAA,MAAA,UAAA,OAAgB;EACd,UAAU,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC;EAC/B,aAAa,SAAS,SAAS,MAAM;CAIvC,GAAG;EAAC;EAAW;EAAY;EAAY;EAAgB,WAAW;CAAQ,CAAC;CAE3E,CAAA,GAAA,MAAA,UAAA,OAAgB;EACd,IAAI,mBAAmB,UAAU;GAC/B,8BAA8B,UAAU;GACxC;EACF;EACA,IAAI,CAAC,8BAA8B,SAAS;GAC1C,8BAA8B,UAAU;GACxC;EACF;EACA,UAAU,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC;CACjC,GAAG;EAAC;EAAW;EAAgB,WAAW;CAAS,CAAC;CAYpD,OAAO;EACL;EACA;EACA;EACA;EACA;EACA,WAAA,GAAA,MAAA,YAAA,OAhBiC;GACjC,IAAI,CAAC,iBAAiB,WAAW,mBAAmB,YAClD,UAAU,IAAI,CAAC,CAAC,YAAY,CAAC,CAAC;EAElC,GAAG;GAAC;GAAe;GAAS;GAAgB;EAAS,CAY5C;EACP;EACA,SAAA,GAAA,MAAA,YAAA,OAZ+B;GAC/B,UAAU,KAAK,CAAC,CAAC,YAAY,CAAC,CAAC;EACjC,GAAG,CAAC,SAAS,CAUN;EACL;CACF;AACF;AAGA,MAAM,mBAA4C,mBAAmB,CAAC;AACtE,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwD9B,SAAgB,cAAoB,MAiBN;CAC5B,MAAM,EACJ,MACA,YACA,SACA,UACA,SACA,aACA,WAAWA,WAAAA,iBACX,YACA,mBACE;CAEJ,MAAM,eAAe,QAAQ,QAAQ,CAAC;CAEtC,IAAI,QAAQ,IAAI,aAAa,gBAAgB,QAAQ,QAAQ,cAAc,MAEzE,QAAQ,KACN,gIAEF;CAYF,IACE,QAAQ,IAAI,aAAa,gBACtB,gBACA,mBAAmB,cACnB,KAAK,SAAS,GAGjB,QAAQ,KACN,mMAGF;CAGF,MAAM,eAAe,oBAAoB;EACvC,MAAM,QAAQ,CAAC;EACf;EACA;EACA;EACA;EACA;EACA;CACF,CAAC;CAED,MAAM,cAAc,mBAAmB;EACrC,YAAY,cAAc;EAC1B,UAAU,aAAa,WAAW;EAClC;EACA;EACA;EACA;CACF,CAAC;CAED,OAAO,eAAe,eAAe;AACvC"}

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

@@ -1,38 +1,2 @@
-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
+import { t as useDataGridUrlState } from "../../use-url-state-B4_wnBjm.js";
+export { useDataGridUrlState };

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

@@ -1,11 +1,8 @@
 "use client";
-
-Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_chunk = require('../../chunk-BE-pF4vm.js');
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 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 = [];
@@ -208,7 +205,7 @@ function useDataGridUrlState(columns, opts) {
 	]);
 	return [state, setState];
 }
-
 //#endregion
 exports.useDataGridUrlState = useDataGridUrlState;
+
 //# sourceMappingURL=use-url-state.js.map