@svgrid/grid 3.0.4 → 3.0.5

package/dist/gantt-view.svelte.d.ts

@@ -0,0 +1,24 @@
+/**
+ * gantt-view registry - the injection seam for the *Gantt view of the grid*.
+ * Setting the `gantt` prop on `<SvGrid>` switches the table for a task table
+ * beside a time chart (bars by start / end, a work-breakdown tree, dependency
+ * arrows), but the renderer itself ships in `@svgrid/enterprise` (a paid
+ * feature). This tiny reactive holder lets enterprise register that renderer at
+ * import time; the grid looks it up and mounts it, or shows an upsell
+ * placeholder when it is absent. Mirrors the `scheduler-view` / `board-view`
+ * pattern.
+ *
+ * ```ts
+ * // in @svgrid/enterprise, at module load:
+ * import { registerGanttView } from '@svgrid/grid'
+ * import SvGridGantt from './gantt/SvGridGantt.svelte'
+ * registerGanttView(SvGridGantt)
+ * ```
+ */
+import type { Component } from 'svelte';
+/** Register the component that renders `gantt` mode. Enterprise calls this. */
+export declare function registerGanttView(component: Component<any>): void;
+/** The registered Gantt renderer, or null when enterprise is not installed. */
+export declare function getGanttView(): Component<any> | null;
+/** Whether a Gantt renderer has been registered. */
+export declare function hasGanttView(): boolean;

package/dist/gantt-view.svelte.js

@@ -0,0 +1,13 @@
+let renderer = $state(null);
+/** Register the component that renders `gantt` mode. Enterprise calls this. */
+export function registerGanttView(component) {
+    renderer = component;
+}
+/** The registered Gantt renderer, or null when enterprise is not installed. */
+export function getGanttView() {
+    return renderer;
+}
+/** Whether a Gantt renderer has been registered. */
+export function hasGanttView() {
+    return renderer != null;
+}

package/dist/grid-icons.d.ts

@@ -35,8 +35,8 @@ export type GridIconName = 'sort' | 'sort-asc' | 'sort-desc' | 'filter' | 'menu'
 export type GridIcons = Partial<Record<GridIconName, Snippet>>;
 /**
  * Icons whose built-in form is a character rather than an SVG path. Kept as
- * data so `<SvGrid>`, its footer and the standalone `SvRowGroupPanel` render
- * the same defaults instead of three copies drifting apart.
+ * data so `<SvGrid>`, its footer and the row-group panel in @svgrid/enterprise
+ * render the same defaults instead of three copies drifting apart.
  *
  * Each is the exact character that shipped inline before, so a grid that sets
  * no `icons` renders byte-for-byte what it always did.

package/dist/grid-icons.js

@@ -1,7 +1,7 @@
 /**
  * Icons whose built-in form is a character rather than an SVG path. Kept as
- * data so `<SvGrid>`, its footer and the standalone `SvRowGroupPanel` render
- * the same defaults instead of three copies drifting apart.
+ * data so `<SvGrid>`, its footer and the row-group panel in @svgrid/enterprise
+ * render the same defaults instead of three copies drifting apart.
  *
  * Each is the exact character that shipped inline before, so a grid that sets
  * no `icons` renders byte-for-byte what it always did.

package/dist/grid-messages.d.ts

@@ -74,8 +74,14 @@ export type GridChromeMessages = {
     bulkEditCancel: string;
     bulkEditNoFields: string;
     chartRange: string;
+    rowLoadFailed: string;
+    rowLoadRetry: string;
     pivotUpsellTitle: string;
     pivotUpsellBody: string;
+    ganttUpsellTitle: string;
+    ganttUpsellBody: string;
+    /** Placeholder in the Gantt view's search box. */
+    ganttSearchPlaceholder: string;
     /** Shared licensing line under every Enterprise upsell note. */
     upsellLicense: string;
     upsellLicenseLink: string;

package/dist/grid-messages.js

@@ -84,8 +84,13 @@ export const defaultGridMessages = {
     opBefore: 'Before',
     opAfter: 'After',
     chartRange: 'Chart selected range',
+    rowLoadFailed: 'Could not load these rows.',
+    rowLoadRetry: 'Retry',
     pivotUpsellTitle: 'Pivot mode',
     pivotUpsellBody: 'Pivot mode is an Enterprise feature. Install @svgrid/enterprise and call enablePivot() to use it.',
+    ganttUpsellTitle: 'Gantt view',
+    ganttUpsellBody: 'The Gantt view is an Enterprise feature. Install @svgrid/enterprise and call enableGanttView() to render it.',
+    ganttSearchPlaceholder: 'Search tasks...',
     upsellLicense: 'A license key is required for production use. Without one the feature still works, but the grid renders an unlicensed watermark.',
     upsellLicenseLink: 'View licensing',
 };

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export * from './ai.js';
 export { registerExportProvider, getExportProvider, type GridExportProvider, type GridExportRunOptions, } from './export-provider.js';
 export type { SchedulerConfig, SchedulerDrawerConfig, SchedulerEventMoveEvent, SchedulerEventResizeEvent, SchedulerEventCommitEvent, SchedulerRangeSelection, SchedulerView, SchedulerResource, SchedulerCollisionMode, SchedulerException, SchedulerEditScope, SchedulerOccurrenceChangeEvent, } from './SvGrid.types.js';
 export { registerSchedulerView, getSchedulerView, hasSchedulerView } from './scheduler-view.svelte.js';
+export type { GanttConfig, GanttDrawerConfig, GanttTaskMoveEvent, GanttTaskResizeEvent, GanttProgressChangeEvent, GanttTaskCommitEvent, GanttDependency, GanttDependencyType, GanttZoom, } from './SvGrid.types.js';
+export { registerGanttView, getGanttView, hasGanttView } from './gantt-view.svelte.js';
 export { registerSelectionBarView, getSelectionBarView, hasSelectionBarView } from './selection-bar-view.svelte.js';
 export type { ChartViewConfig } from './SvGrid.types.js';
 export { registerChartView, getChartView, hasChartView } from './chart-view.svelte.js';
@@ -211,10 +213,9 @@ export { resolveColumnTypes, inferCellDataType, type CellDataType } from './colu
 export { computeColumnGroupMeta, hiddenLeavesForCollapse, type ColumnGroupMeta, type ColumnGroupShow, } from './column-groups.js';
 export { createHyperFormulaSheet, type HyperFormulaSheet, type HyperFormulaSheetConfig, type HyperFormulaInstance, } from './hyperformula-adapter.js';
 export { createCollaboration, broadcastChannelTransport, type CollabUser, type CollabCell, type CollabPresence, type CollabMessage, type CollabTransport, type Collaboration, } from './collaboration.js';
-export { createServerDataSource, type ServerDataSource, type ServerRequest, type ServerResult, type ServerController, type ServerState, type ServerSortModel, type ServerFilterModel, type ServerAggregation, type ServerGroupRow, type ServerLeafRow, type ServerMoreRow, type ServerFooterRow, type ServerSkeletonRow, type ServerDisplayRow, } from './server-data-source.js';
-export { createServerGroupModel, serverGroupRows, serverGroupNav, type ServerGroupController, type ServerGroupControllerOptions, type ServerGroupState, type ServerGroupGridRow, } from './server-group-model.js';
-export { default as SvGroupCell } from './SvGroupCell.svelte';
-export { default as SvRowGroupPanel } from './SvRowGroupPanel.svelte';
+export { createServerDataSource, type ServerDataSource, type ServerSelectionRule, type ServerRequest, type ServerResult, type ServerController, type ServerControllerOptions, type ServerState, type ServerSortModel, type ServerFilterModel, type ServerAggregation, type ServerGroupRow, type ServerLeafRow, type ServerMoreRow, type ServerFooterRow, type ServerSkeletonRow, type ServerGrandTotalRow, type ServerPlaceholderRow, type ServerDisplayRow, } from './server-data-source.js';
+export { createBlockCache, createRowPlaceholder, rowPlaceholderState, type BlockCache, type BlockCacheOptions, type BlockCacheState, type BlockFetchResult, type BlockState, } from './server-block-cache.js';
+export { toServerFilterColumns, type GridRowModel, type GridFilterState, type GridRowModelSort, } from './row-model.js';
 export { createNamedViews, memoryViews, localStorageViews, attachAutoSavedView, type SavedView, type ViewStorage, type NamedViews, type AutoSavedViewOptions, } from './named-views.js';
 export { resolveCellFormat, computeColumnStat, lerpColor, rgba, contrastText, formatNeedsStats, formatsNeedingStats, type ConditionalFormat, type ConditionalFormatSpec, type ColorScaleFormat, type ColorScaleStop, type ScaleBounds, type DataBarFormat, type IconSetFormat, type RuleFormat, type ResolvedCellFormat, } from './conditional-formatting.js';
 export { defaultGridMessages, resolveGridMessages, type GridMessages, type GridChromeMessages, } from './grid-messages.js';

package/dist/index.js

@@ -15,6 +15,7 @@ export { registerBoardView, getBoardView, hasBoardView } from './board-view.svel
 export * from './ai.js';
 export { registerExportProvider, getExportProvider, } from './export-provider.js';
 export { registerSchedulerView, getSchedulerView, hasSchedulerView } from './scheduler-view.svelte.js';
+export { registerGanttView, getGanttView, hasGanttView } from './gantt-view.svelte.js';
 // Bulk-action bar over the row selection. Prop + types free, renderer Pro.
 export { registerSelectionBarView, getSelectionBarView, hasSelectionBarView } from './selection-bar-view.svelte.js';
 export { registerChartView, getChartView, hasChartView } from './chart-view.svelte.js';
@@ -253,9 +254,8 @@ export { computeColumnGroupMeta, hiddenLeavesForCollapse, } from './column-group
 export { createHyperFormulaSheet, } from './hyperformula-adapter.js';
 export { createCollaboration, broadcastChannelTransport, } from './collaboration.js';
 export { createServerDataSource, } from './server-data-source.js';
-export { createServerGroupModel, serverGroupRows, serverGroupNav, } from './server-group-model.js';
-export { default as SvGroupCell } from './SvGroupCell.svelte';
-export { default as SvRowGroupPanel } from './SvRowGroupPanel.svelte';
+export { createBlockCache, createRowPlaceholder, rowPlaceholderState, } from './server-block-cache.js';
+export { toServerFilterColumns, } from './row-model.js';
 export { createNamedViews, memoryViews, localStorageViews, attachAutoSavedView, } from './named-views.js';
 export { resolveCellFormat, computeColumnStat, lerpColor, rgba, contrastText, formatNeedsStats, formatsNeedingStats, } from './conditional-formatting.js';
 export { defaultGridMessages, resolveGridMessages, } from './grid-messages.js';

package/dist/row-model.d.ts

@@ -0,0 +1,133 @@
+/**
+ * `GridRowModel` - one prop instead of eleven.
+ *
+ * A grid backed by a server needs the same wiring every time: hand it the
+ * rows, tell it not to sort or filter locally, forward the sort and the filter
+ * to the backend, report which rows are on screen, say which rows have not
+ * loaded, and delegate selection. Written out by hand that is a dozen props
+ * and a filter-shape conversion that every app gets slightly differently:
+ *
+ * ```svelte
+ * <SvGrid data={s.rows} externalSort externalFilter loading={s.loading}
+ *   onSortingChange={(x) => ctl.setSort(x)}
+ *   onFiltersChange={(f) => ctl.setFilter({ global: f.global,
+ *     columns: Object.fromEntries(f.columns.map((c) => [c.id, { ... }])) })}
+ *   onVisibleRangeChange={(r) => ctl.setViewport(r.startIndex, r.endIndex)}
+ *   ... />
+ * ```
+ *
+ * An object that implements this interface carries all of it, so the same grid
+ * becomes:
+ *
+ * ```svelte
+ * <SvGrid rowModel={ctl} {columns} />
+ * ```
+ *
+ * `createServerDataSource` returns one, and so does the Enterprise server row
+ * model - which is the point of the interface rather than a concrete type: the
+ * grid depends on the SHAPE, never on either implementation, and an app with
+ * its own fetching can satisfy it too.
+ *
+ * Every member except `subscribe` / `getRows` / `isLoading` is optional, and a
+ * prop written explicitly on `<SvGrid>` always wins over the model's answer -
+ * so adopting this is never all-or-nothing.
+ */
+import type { FilterOperator } from './SvGrid.types.js';
+/** The filter state as the grid reports it, straight from `onFiltersChange`. */
+export type GridFilterState = {
+    global: string;
+    columns: Array<{
+        id: string;
+        operator: FilterOperator;
+        value: string;
+        valueTo?: string;
+        selectedValues?: Array<string>;
+    }>;
+};
+/** The sort the grid hands a row model: column id and direction, in priority order. */
+export type GridRowModelSort = Array<{
+    id: string;
+    desc: boolean;
+}>;
+/**
+ * What `<SvGrid rowModel>` consumes: rows, a loading flag, a change
+ * subscription, and whichever optional parts the model implements - sort,
+ * filter, viewport, placeholders, group accessors, selection, filter
+ * values, paging, pinned rows and pivot columns. `createServerDataSource`
+ * and the Enterprise `createServerRowModel` both satisfy it.
+ */
+export type GridRowModel<TData> = {
+    /**
+     * Register a callback for "something changed, re-read me". Returns an
+     * unsubscribe function, which the grid calls on unmount.
+     */
+    subscribe(onChange: () => void): () => void;
+    /** The rows to render, including any placeholders for unloaded ones. */
+    getRows(): ReadonlyArray<TData>;
+    /** True while a fetch is in flight, for the loading overlay. */
+    isLoading(): boolean;
+    /** Stable row id. Required once selection or editing is involved. */
+    getRowId?(row: TData, index: number): string;
+    /** Sort on the server. Present means "do not sort locally". */
+    setSort?(sort: GridRowModelSort): void;
+    /** Filter on the server. Present means "do not filter locally". */
+    setFilter?(filters: GridFilterState): void;
+    /** Which rows are on screen, so a block-loading model knows what to fetch. */
+    setViewport?(startIndex: number, endIndex: number): void;
+    /** Why a row has no data yet, or null when it does. */
+    rowPlaceholder?(row: TData, rowIndex: number): 'loading' | 'failed' | null;
+    /** Retry the failed block a placeholder row belongs to. */
+    retryRow?(row: TData, rowIndex: number): void;
+    /** Group / tree accessors, for the grid's treegrid keyboard and ARIA. */
+    group?: {
+        isGroup: (row: TData) => boolean;
+        level: (row: TData) => number;
+        expanded?: (row: TData) => boolean;
+        onToggle: (row: TData) => void;
+    };
+    /** Selection the grid does not own - see the `rowSelectionModel` prop. */
+    selection?: {
+        isSelected: (rowId: string, row: TData) => boolean;
+        headerState: () => 'none' | 'some' | 'all';
+        toggle: (rowId: string, row: TData, next: boolean) => void;
+        toggleAll: (next: boolean) => void;
+        selectedCount?: () => number | null;
+        bulkUpdate?: (patch: Record<string, unknown>) => Promise<number>;
+    };
+    /** Distinct values for a column's set filter, fetched from the server. */
+    filterValues?(columnId: string): Promise<Array<string>>;
+    /** Server-side paging. Omit it for infinite scrolling. */
+    pagination?: {
+        pageIndex: number;
+        pageSize: number;
+        rowCount: number;
+        setPage(pageIndex: number): void;
+        setPageSize(pageSize: number): void;
+        /** Choices for the footer's page-size selector. */
+        pageSizes?: number[];
+        /**
+         * Ask the grid for as many rows as its body fits: it measures and calls
+         * `setPageSize` whenever the fit changes.
+         */
+        autoPageSize?: boolean;
+    };
+    /** Rows to pin above / below the scrolling body - a grand total, say. */
+    readonly pinnedTopRows?: ReadonlyArray<TData>;
+    readonly pinnedBottomRows?: ReadonlyArray<TData>;
+    /**
+     * Columns that replace the grid's `columns` while the model is in pivot
+     * mode, or null. Read after every change notification.
+     */
+    readonly pivotResultColumns?: ReadonlyArray<unknown> | null;
+};
+/**
+ * Turn the grid's filter payload into the column-keyed map a `ServerRequest`
+ * carries. Exported because a hand-written `GridRowModel` needs exactly this
+ * conversion, and copying it is how the two shapes drift apart.
+ */
+export declare function toServerFilterColumns(filters: GridFilterState): Record<string, {
+    operator: string;
+    value: string;
+    valueTo?: string;
+    selectedValues?: Array<string>;
+}>;

package/dist/row-model.js

@@ -0,0 +1,16 @@
+/**
+ * Turn the grid's filter payload into the column-keyed map a `ServerRequest`
+ * carries. Exported because a hand-written `GridRowModel` needs exactly this
+ * conversion, and copying it is how the two shapes drift apart.
+ */
+export function toServerFilterColumns(filters) {
+    return Object.fromEntries(filters.columns.map((c) => [
+        c.id,
+        {
+            operator: c.operator,
+            value: c.value,
+            ...(c.valueTo !== undefined ? { valueTo: c.valueTo } : {}),
+            ...(c.selectedValues !== undefined ? { selectedValues: c.selectedValues } : {}),
+        },
+    ]));
+}

package/dist/selection.d.ts

@@ -1,9 +1,10 @@
 import { type RowData, type TableFeatures } from "./index.js";
 import "./sv-grid-scrollbar.js";
 export declare function createSelection<TFeatures extends TableFeatures = TableFeatures, TData extends RowData = RowData>(ctx: any): {
-    isRowSelected: (rowId: string) => boolean;
+    isRowSelected: (rowId: string) => any;
     toggleRowSelectionById: (rowId: string) => void;
     toggleSelectAllRows: () => void;
+    setSelectAllRows: (select: boolean) => void;
     setActiveCell: (rowIndex: number, colIndex: number) => void;
     scrollActiveCellIntoView: (rowIndex: number, colIndex: number) => void;
     setSelection: (rowIndex: number, colIndex: number, additive?: boolean) => void;

package/dist/selection.js

@@ -7,14 +7,41 @@ import { getColumnBaseValue, isGroupRow, } from "./cell-values.js";
 import { expandRectToMerges, originOf, endOf } from "./merges.js";
 export function createSelection(ctx) {
     function isRowSelected(rowId) {
+        const model = ctx.props.rowSelectionModel;
+        if (model) {
+            const row = ctx.allRows.find((r) => r.id === rowId);
+            return row ? model.isSelected(rowId, row.original) : false;
+        }
         return Boolean(ctx.rowSelectionState[rowId]);
     }
     function toggleRowSelectionById(rowId) {
+        const model = ctx.props.rowSelectionModel;
+        if (model) {
+            const row = ctx.allRows.find((r) => r.id === rowId);
+            if (!row)
+                return;
+            model.toggle(rowId, row.original, !model.isSelected(rowId, row.original));
+            return;
+        }
         ctx.grid.setRowSelection((prev) => ({ ...prev, [rowId]: !prev[rowId] }));
     }
     function toggleSelectAllRows() {
-        const selectable = ctx.allRows.filter((row) => !isGroupRow(row));
-        const select = ctx.headerSelectionState !== "all";
+        setSelectAllRows(ctx.headerSelectionState !== "all");
+    }
+    /**
+     * Select or clear every row, for the header checkbox and for
+     * `api.selectAllRows()`.
+     */
+    function setSelectAllRows(select) {
+        // An external model decides what "all" means - possibly a million rows
+        // the grid has never seen - so it gets the intent, not a row list.
+        if (ctx.props.rowSelectionModel) {
+            ctx.props.rowSelectionModel.toggleAll(select);
+            return;
+        }
+        // Placeholder rows are excluded: there is no row there to select yet,
+        // and ticking one would leave a selected id that never resolves.
+        const selectable = ctx.allRows.filter((row) => !isGroupRow(row) && !ctx.placeholderStateOf(row));
         ctx.grid.setRowSelection((prev) => {
             const next = { ...prev };
             for (const row of selectable) {
@@ -646,6 +673,7 @@ export function createSelection(ctx) {
         isRowSelected,
         toggleRowSelectionById,
         toggleSelectAllRows,
+        setSelectAllRows,
         setActiveCell,
         scrollActiveCellIntoView,
         setSelection,

package/dist/server-block-cache.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Block cache for server-backed rows - the engine behind infinite scrolling.
+ *
+ * Paging asks for "page 3". Infinite scrolling asks a different question: the
+ * user is looking at rows 4,000 to 4,020 of a table with a million rows, so
+ * fetch the block that covers them, keep a bounded number of recently-seen
+ * blocks, and render something sensible for every row nobody has fetched yet.
+ * That is all this module does, in plain TypeScript with no Svelte and no DOM.
+ *
+ * The shape of the problem (and most of the vocabulary) is the same one every
+ * grid with a server row model solves, so the options here are deliberately
+ * recognisable: `blockSize`, `maxBlocksInCache`, `maxConcurrentRequests`,
+ * `blockLoadDebounceMs`, `initialRowCount`, `overflowRows`.
+ *
+ * Three things it takes seriously:
+ *
+ *   - **Unloaded rows still have to render.** `rows()` always returns a dense
+ *     array, with a shared sentinel object in every slot that has no data. The
+ *     grid recognises those (see {@link rowPlaceholderState}) and draws a
+ *     skeleton or a retry affordance instead of an empty row, so the scrollbar
+ *     never lies and scrolling never leaves a hole.
+ *   - **The row count may be unknown.** A backend that cannot cheaply count
+ *     says so (omit `rowCount`, or send `-1`) and the list grows by a block at
+ *     a time until a short block proves where the end is.
+ *   - **Requests are not free.** In-flight blocks are deduplicated, at most
+ *     `maxConcurrentRequests` are open at once, a fast scroll debounces rather
+ *     than firing a request per frame, and blocks abandoned by eviction or
+ *     purge are aborted.
+ *
+ * Enterprise's server row model runs one of these per group level; the free
+ * flat controller runs exactly one.
+ */
+/**
+ * The mark that says "this row is not data yet".
+ *
+ * A symbol, for two reasons. It cannot collide with a field in anyone's row
+ * data, which a string key like `__svPlaceholder` eventually would. And
+ * `Symbol.for` puts it in the global registry, so a placeholder still reads as
+ * one after it has crossed a module boundary - two copies of this file loaded
+ * through different specifiers would otherwise mint different symbols.
+ */
+declare const PLACEHOLDER: unique symbol;
+/** Rows the cache has not loaded. One shared object per state, not per row. */
+declare const LOADING_ROW: Readonly<{
+    [PLACEHOLDER]: "loading";
+}>;
+declare const FAILED_ROW: Readonly<{
+    [PLACEHOLDER]: "failed";
+}>;
+/**
+ * Why a row is not real data, or `null` when it is.
+ *
+ * Deliberately NOT an identity check. The sentinels are shared objects, so
+ * `row === LOADING_ROW` looks like the obvious test - but rows routinely
+ * arrive here through something that wrapped them. Svelte is the everyday
+ * case: assigning the controller state into `$state` makes the row array
+ * deeply reactive, and every row read back out is a proxy of the original.
+ * Identity fails, every placeholder reads as real data, and the grid renders
+ * a screen of blank rows instead of skeletons. Reading the mark works through
+ * any wrapper that forwards property access, which is all of them.
+ */
+export declare function rowPlaceholderState(row: unknown): 'loading' | 'failed' | null;
+/**
+ * Mint a frozen placeholder the grid will recognise, carrying whatever
+ * other fields the caller wants on it. The row model uses this to give its
+ * placeholders a `kind`, so code reading display rows and code reading grid
+ * rows agree on what they are looking at.
+ */
+export declare function createRowPlaceholder<T extends object>(state: 'loading' | 'failed', fields: T): Readonly<T & {
+    readonly [PLACEHOLDER]: 'loading' | 'failed';
+}>;
+/** What a block fetch has to answer with. `rowCount` is optional: see {@link BlockCacheOptions}. */
+export type BlockFetchResult<TData> = {
+    rows: ReadonlyArray<TData>;
+    /**
+     * Total rows after filtering. Omit it (or send `-1`) when the backend cannot
+     * count cheaply - the cache then discovers the end from the first short
+     * block, and `lastRowKnown()` stays false until it does.
+     */
+    rowCount?: number;
+};
+/** What a block cache is built from: block size, caps, debounce and the fetch. */
+export type BlockCacheOptions<TData> = {
+    /**
+     * Rows per request. Bigger blocks mean fewer round trips and more wasted
+     * rows when the user scrolls past; 100 is the usual compromise.
+     */
+    blockSize?: number;
+    /**
+     * Keep at most this many loaded blocks. Blocks outside the viewport are
+     * evicted least-recently-seen first, and scrolling back re-fetches them.
+     * Unlimited by default, which is right until the dataset is big enough that
+     * holding every visited block matters.
+     */
+    maxBlocksInCache?: number;
+    /** Requests open at once. Default 2. */
+    maxConcurrentRequests?: number;
+    /**
+     * Wait this long after the viewport settles before fetching. Non-zero values
+     * stop a drag of the scrollbar from requesting every block it flies past.
+     */
+    blockLoadDebounceMs?: number;
+    /**
+     * Rows to claim before anything is loaded, so the grid has a scrollbar (and
+     * `scrollToRow` has somewhere to land) on the first paint. Default 1.
+     */
+    initialRowCount?: number;
+    /**
+     * While the total is unknown, how many unloaded rows to keep past the last
+     * loaded one. Scrolling into them is what asks for the next block. Default 1.
+     */
+    overflowRows?: number;
+    /** Fetch one block. Reject, or throw, to mark it failed. */
+    fetch: (startRow: number, endRow: number, signal: AbortSignal) => Promise<BlockFetchResult<TData>>;
+    /** Called after any change to the rows, the count, or a block's state. */
+    onChange: (cache: BlockCacheState) => void;
+    /**
+     * How to coalesce `onChange`. Defaults to a microtask, so a burst of block
+     * arrivals rebuilds the row array once. Pass `(fn) => fn()` in tests to make
+     * every change synchronous.
+     */
+    schedule?: (flush: () => void) => void;
+};
+/** One block's place in the world, for diagnostics and for tests. */
+export type BlockState = {
+    blockIndex: number;
+    startRow: number;
+    endRow: number;
+    status: 'loading' | 'loaded' | 'failed';
+    /** Monotonic counter of when the viewport last covered this block. */
+    lastTouched: number;
+};
+/** One block as `getCacheState()` reports it. */
+export type BlockCacheState = {
+    /** Rows after filtering, or `null` while the backend has not said. */
+    rowCount: number | null;
+    /** False while the end of the data is still being discovered. */
+    lastRowKnown: boolean;
+    /** True while at least one block is in flight. */
+    loading: boolean;
+    /** Blocks whose fetch rejected. Empty unless something went wrong. */
+    failedBlocks: number[];
+};
+/**
+ * A block cache: rows arrive in blocks as the viewport reaches them,
+ * placeholders stand in until then, and blocks far from the viewport are
+ * evicted past the cap.
+ */
+export type BlockCache<TData> = {
+    /**
+     * Tell the cache which rows are on screen. Fetches what is missing (after
+     * `blockLoadDebounceMs`) and marks those blocks as recently seen so eviction
+     * spares them. Safe to call on every scroll frame.
+     */
+    setViewport(startIndex: number, endIndex: number): void;
+    /** The dense row array to hand the grid. Placeholders fill unloaded slots. */
+    rows(): ReadonlyArray<TData>;
+    /** One row, without building the array. Returns a placeholder when unloaded. */
+    getRow(index: number): TData | typeof LOADING_ROW | typeof FAILED_ROW;
+    rowCount(): number | null;
+    lastRowKnown(): boolean;
+    /** Re-fetch the blocks that failed. */
+    retryFailed(): void;
+    /**
+     * Re-fetch the loaded blocks in place, keeping the row count and scroll
+     * position. What you want after a mutation lands on the server.
+     */
+    refresh(): void;
+    /** Drop everything and start over from the current viewport. */
+    purge(): void;
+    /** Override the total, e.g. from a count endpoint that answered separately. */
+    setRowCount(count: number | null, known?: boolean): void;
+    /**
+     * Write rows straight into the cache from `startRow`, as if a fetch had
+     * returned them, bypassing the datasource, the debounce and the
+     * concurrency cap. `startRow` must sit on a block boundary. An explicit
+     * `rowCount` settles the total; without one a short final slice does.
+     */
+    applyRows(startRow: number, rows: ReadonlyArray<TData>, rowCount?: number): void;
+    /** Replace one loaded row. No-op when its block is not loaded. */
+    patch(index: number, row: TData): boolean;
+    /**
+     * The index of the first LOADED row matching `predicate`, or -1. Rows
+     * that are not loaded are not visited - a transaction addressed by id
+     * can only touch what is in the cache.
+     */
+    findIndex(predicate: (row: TData, index: number) => boolean): number;
+    /**
+     * Insert rows at an index and grow the count. Works within whichever
+     * run of loaded blocks contains `index`; loaded blocks AFTER that run
+     * are dropped, because their rows have shifted and will be re-fetched at
+     * their new offsets. An index in an unloaded region grows the count
+     * only (the rows exist; they arrive when scrolled to). Returns whether
+     * the rows were placed in the cache.
+     */
+    insert(index: number, rows: ReadonlyArray<TData>): boolean;
+    /**
+     * Remove `count` rows at an index and shrink the count, with the same
+     * run semantics as `insert`. Returns how many rows were actually
+     * removed from the cache.
+     */
+    remove(index: number, count?: number): number;
+    /** Every block the cache is holding, for `debug` output and tests. */
+    getCacheState(): BlockState[];
+    /** Abort what is in flight and stop emitting. Call on unmount. */
+    dispose(): void;
+};
+/**
+ * Build a block cache over a `fetch(startRow, endRow, signal)`. The free
+ * infinite row model and the Enterprise server-side row model both run on
+ * it, one per level.
+ */
+export declare function createBlockCache<TData>(options: BlockCacheOptions<TData>): BlockCache<TData>;
+export {};