@svgrid/grid 3.0.4 → 3.0.6

package/dist/server-data-source.d.ts

@@ -16,10 +16,17 @@
  * follow-up re-fetch of the current page lands.
  */
 import type { GridPredicateExpr } from './filtering/predicate-expr.js';
+import { type BlockState } from './server-block-cache.js';
+import { type GridFilterState, type GridRowModel } from './row-model.js';
+/** Sort clauses in priority order; `id` is the column id. */
 export type ServerSortModel = Array<{
     id: string;
     desc: boolean;
 }>;
+/**
+ * What a request carries for filtering: the global search, the per-column
+ * operator filters, and the advanced-filter expression.
+ */
 export type ServerFilterModel = {
     /** Free-text global search. */
     global?: string;
@@ -53,11 +60,24 @@ export type ServerFilterModel = {
      */
     expression?: GridPredicateExpr;
 };
-/** A value column to roll up per group. */
+/** The aggregate functions every backend helper understands. */
+export type ServerAggFn = 'sum' | 'avg' | 'min' | 'max' | 'count';
+/**
+ * One value column to roll up per group. `fn` is one of the five built-ins
+ * or any name your backend knows (`median`, `countDistinct`, a domain
+ * aggregate): the request carries it untouched. The SvelteKit planner emits
+ * only the built-ins plus the names it was told to allow, since `fn` ends
+ * up in SQL.
+ */
 export type ServerAggregation = {
     col: string;
-    fn: 'sum' | 'avg' | 'min' | 'max' | 'count';
+    fn: ServerAggFn | (string & {});
 };
+/**
+ * One range of rows as the grid asks for it. A flat request carries the
+ * range, the sort and the filter; a grouped request adds `groupBy`,
+ * `groupKeys` and `aggregations`; a pivoted one `pivotBy` and `pivotMode`.
+ */
 export type ServerRequest = {
     /** Zero-based index of the first row wanted (inclusive). */
     startRow: number;
@@ -82,6 +102,43 @@ export type ServerRequest = {
     groupKeys?: string[];
     /** Value columns to aggregate per group. */
     aggregations?: ServerAggregation[];
+    /**
+     * Server-side pivot: the columns whose distinct values become columns.
+     * With `pivotMode` on, a group row carries one value per (pivot key x
+     * aggregation) under a field named `<key>_<col>` (the separator is the
+     * row model's `pivotFieldSeparator`), and the response lists those
+     * fields in `pivotResultFields`. Only the Enterprise row model sets it.
+     */
+    pivotBy?: string[];
+    pivotMode?: boolean;
+    /**
+     * True on a top-level request when the grid wants a grand-total row and
+     * does not have one cached. Answer with `ServerResult.grandTotal`. Only
+     * the Enterprise server row model sets it.
+     */
+    needsGrandTotal?: boolean;
+    /**
+     * The group (or tree node) row being expanded, when this request is for
+     * its children. Handy for backends that key children off something on
+     * the parent rather than off `groupKeys`. Absent at the top level.
+     */
+    parentRow?: unknown;
+    /**
+     * Whatever the app passed as `context` to its controller, forwarded
+     * untouched on every request. Keep it JSON-serialisable: the SvelteKit
+     * transport posts the whole request to your endpoint.
+     */
+    context?: unknown;
+    /**
+     * Aborted when the grid no longer wants the answer: the block was purged
+     * or evicted, the sort or filter changed, a group was collapsed, the
+     * controller was disposed. Hand it to `fetch` and a query the user has
+     * scrolled past is cancelled at the server instead of completing for
+     * nothing; a rejection carrying the abort is ignored by the grid. Not
+     * serialisable - the SvelteKit transport reads it and leaves it out of
+     * the body.
+     */
+    signal?: AbortSignal;
 };
 /**
  * A group row in the server-side group/tree model - one distinct key at a
@@ -104,13 +161,28 @@ export type ServerGroupRow<TData> = {
     loading: boolean;
     /** Aggregate values keyed by column id, read from the group's response row. */
     aggregates: Record<string, unknown>;
+    /**
+     * How many rows this group holds, when the backend said (see the row
+     * model's `childCount` option). Drawn next to the key by `SvGroupCell`,
+     * and used to size the group's scrollbar before its first block lands.
+     */
+    childCount?: number;
+    /**
+     * `false` when nothing can open beneath this row: the innermost group
+     * level under a server-side pivot, whose rows are the result itself.
+     * The group cell then draws no expander.
+     */
+    expandable?: boolean;
     /** The raw response row for this group (key + aggregates), for cell rendering. */
     data: TData;
 };
+/** A data row in the display list. */
 export type ServerLeafRow<TData> = {
     kind: 'leaf';
     id: string;
     level: number;
+    /** The group path this leaf sits under. Set by the block-cached row model. */
+    route?: string[];
     data: TData;
 };
 /**
@@ -150,11 +222,64 @@ export type ServerSkeletonRow = {
     id: string;
     level: number;
 };
-/** A row in the flattened server-side group/tree display list. */
-export type ServerDisplayRow<TData> = ServerGroupRow<TData> | ServerLeafRow<TData> | ServerMoreRow | ServerFooterRow<TData> | ServerSkeletonRow;
+/**
+ * A grand-total row across the whole result. One per grid, at the top or
+ * the bottom, with the fixed id `sv-grand-total` so a transaction can
+ * address it.
+ */
+export type ServerGrandTotalRow<TData> = {
+    kind: 'grandTotal';
+    id: 'sv-grand-total';
+    level: 0;
+    aggregates: Record<string, unknown>;
+    data: TData;
+};
+/**
+ * A row whose data has not arrived: `loading` while its block is in
+ * flight, `failed` when the fetch rejected. Shared, frozen objects - one
+ * per state, not one per row - so a million unloaded rows cost nothing to
+ * represent. They also carry the grid's placeholder mark, so
+ * `rowPlaceholderState()` recognises them and the grid draws them itself.
+ */
+export type ServerPlaceholderRow = {
+    readonly kind: 'placeholder';
+    readonly state: 'loading' | 'failed';
+};
+/**
+ * The detail panel under a leaf whose detail is open: master-detail on a
+ * server-side row model. The grid draws it through `renderDetailRow`
+ * (mark it with `isDetailRow`); `master` is the leaf it belongs to.
+ */
+export type ServerDetailRow<TData> = {
+    kind: 'detail';
+    id: string;
+    level: number;
+    route?: string[];
+    /** The leaf's id, as `getRowId` names it. */
+    masterId: string;
+    master: TData;
+};
+/**
+ * Every row a server row model can put on screen. Each carries an `id` and
+ * a `level`. The block-cached model adds {@link ServerPlaceholderRow} for
+ * rows not yet loaded - see its own `ServerRowModelDisplayRow`.
+ */
+export type ServerDisplayRow<TData> = ServerGroupRow<TData> | ServerLeafRow<TData> | ServerDetailRow<TData> | ServerMoreRow | ServerFooterRow<TData> | ServerSkeletonRow | ServerGrandTotalRow<TData>;
+/**
+ * What `getRows` answers with: the rows for the requested range and the
+ * count after filtering, plus the grand total and the pivot fields when
+ * asked for.
+ */
 export type ServerResult<TData> = {
     rows: ReadonlyArray<TData>;
-    /** Total row count after filtering (for the pager). */
+    /**
+     * Total row count after filtering, for the pager and the scrollbar.
+     *
+     * Paging needs it. Infinite scrolling does not: send `-1` (or, from a
+     * source typed loosely, omit it) when counting is expensive, and the grid
+     * discovers the end from the first short block instead. See
+     * `mode: 'infinite'` on {@link ServerControllerOptions}.
+     */
     rowCount: number;
     /**
      * Set `true` ONLY when `filterModel.expression` was applied in full. Leave it
@@ -162,7 +287,53 @@ export type ServerResult<TData> = {
      * pretending the filter ran. See the contract on `ServerFilterModel.expression`.
      */
     appliedExpression?: boolean;
+    /**
+     * The grand-total row, in reply to `ServerRequest.needsGrandTotal`: an
+     * object sets it, `null` removes it, and leaving it out keeps whatever the
+     * grid already had. Shaped like a group row: the aggregate values live
+     * under their column ids.
+     */
+    grandTotal?: TData | null;
+    /**
+     * Pivot mode: the fields the group rows carry for the pivoted values,
+     * e.g. `["2024_amount", "2025_amount"]`, from which the grid builds one
+     * column per field under a header group per pivot key. Send the full
+     * list on every pivoted response; the grid keeps the union. Every group
+     * row carries every listed field, `null` where no rows fall in that
+     * cell.
+     */
+    pivotResultFields?: string[];
+    /**
+     * Pivot mode, the long way: full column definitions instead of field
+     * names, for a backend that wants to name and format them itself. Wins
+     * over `pivotResultFields` when both are present.
+     */
+    pivotResultColumns?: ReadonlyArray<unknown>;
+};
+/**
+ * A selection expressed as a rule rather than a list, for `updateWhere`.
+ * The flat shape is "these ids" or "everything except these"; the nested
+ * shape is the same idea per group, keyed by group key or leaf id, as the
+ * Enterprise row model keeps it under `groupSelects: 'descendants'`.
+ */
+export type ServerSelectionRule = {
+    selectAll: boolean;
+    toggled: string[];
+} | {
+    selectAllChildren: boolean;
+    toggled: Record<string, {
+        selectAllChildren: boolean;
+        toggled: Record<string, unknown>;
+        group?: boolean;
+    }>;
+    group?: boolean;
+    /** The group columns the tree's levels are keyed by, outer to inner. */
+    groupBy?: string[];
 };
+/**
+ * The contract a backend implements: `getRows`, and optionally the write
+ * methods, a bulk edit by rule and `destroy`.
+ */
 export type ServerDataSource<TData> = {
     getRows(request: ServerRequest): Promise<ServerResult<TData>>;
     /**
@@ -174,7 +345,28 @@ export type ServerDataSource<TData> = {
     createRow?(input: Partial<TData>): Promise<TData>;
     updateRow?(id: string, patch: Partial<TData>): Promise<TData>;
     deleteRow?(id: string): Promise<void>;
+    /**
+     * Apply one patch to every row a selection RULE names, server-side - the
+     * write behind a bulk edit of rows the grid never loaded. `filterModel`
+     * scopes the rows exactly as `getRows` does; `selection` is the rule:
+     * either "these ids" (`selectAll: false`) or "everything but these"
+     * (`selectAll: true`), or the per-group tree the Enterprise row model
+     * keeps under `groupSelects: 'descendants'`. Resolve with how many rows
+     * changed. Optional: without it, a bulk edit under select-all is refused
+     * rather than silently applied to the loaded rows only.
+     */
+    updateWhere?(filterModel: ServerFilterModel, patch: Partial<TData>, selection: ServerSelectionRule): Promise<number>;
+    /**
+     * Called once, from the controller's `dispose()`, for a source with
+     * something to close: a socket, a subscription, a worker.
+     */
+    destroy?(): void;
 };
+/**
+ * What `createServerDataSource` emits on every change: the rows on hand,
+ * the counts, the loading and saving flags, the last error, and the
+ * current sort and filter.
+ */
 export type ServerState<TData> = {
     rows: ReadonlyArray<TData>;
     total: number;
@@ -196,12 +388,50 @@ export type ServerState<TData> = {
      * compiling; the controller always sets it.
      */
     expressionUnapplied?: boolean;
+    /**
+     * Rows after filtering, or `null` when the backend has not said and the
+     * end has not been found yet. Only ever null in `infinite` mode; `total`
+     * carries the best current guess either way.
+     */
+    rowCount?: number | null;
+    /** False while the end of an infinite list is still being discovered. */
+    lastRowKnown?: boolean;
+    /** Blocks whose fetch failed, in `infinite` mode. Empty when all is well. */
+    failedBlocks?: number[];
 };
-export type ServerController<TData> = {
+/**
+ * Everything a controller can do, plus the {@link GridRowModel} surface, so
+ * one object can be driven by hand OR handed to `<SvGrid rowModel>` and wire
+ * itself up.
+ */
+export type ServerController<TData> = GridRowModel<TData> & {
     /** Re-fetch the current page (e.g. after a mutation). */
     refresh(): void;
+    /**
+     * The rows on screen, so `infinite` mode knows which blocks to fetch and
+     * which to spare from eviction. Wire it to the grid's
+     * `onVisibleRangeChange` - or pass the controller as `rowModel` and the
+     * grid wires it for you. No-op in `page` mode.
+     */
+    setViewport(startIndex: number, endIndex: number): void;
+    /** Re-fetch the blocks that failed. No-op in `page` mode. */
+    retryLoads(): void;
+    /**
+     * Throw away every cached block and reload from the current viewport.
+     * `refresh()` is the gentler option: it keeps the row count and the scroll
+     * position. No-op in `page` mode, where there is only ever one page held.
+     */
+    purge(): void;
+    /** Cached blocks and their state, for logging and tests. Empty in `page` mode. */
+    getCacheState(): BlockState[];
     setSort(sortModel: ServerSortModel): void;
-    setFilter(filterModel: ServerFilterModel): void;
+    /**
+     * Replace the filter. Takes the `ServerFilterModel` a request carries, or
+     * the payload the grid's own `onFiltersChange` hands you - which is a
+     * list of columns rather than a map, and is converted here so that every
+     * app does not write the same `Object.fromEntries` by hand.
+     */
+    setFilter(filterModel: ServerFilterModel | GridFilterState): void;
     setPage(pageIndex: number): void;
     setPageSize(pageSize: number): void;
     /**
@@ -225,10 +455,14 @@ export type ServerController<TData> = {
     /** Stop accepting in-flight responses (call on unmount). */
     dispose(): void;
 };
+/**
+ * Options for `createServerDataSource`: the page size, or the block
+ * settings in `infinite` mode, optimistic writes and the change callback.
+ */
 export type ServerControllerOptions<TData> = {
     pageSize?: number;
     /** Called whenever any of `rows` / `total` / `loading` / page changes. */
-    onChange: (state: ServerState<TData>) => void;
+    onChange?: (state: ServerState<TData>) => void;
     /**
      * Apply `updateRow` / `deleteRow` to the local rows immediately (before the
      * server confirms) and roll back on error - so edits feel instant and no
@@ -238,5 +472,37 @@ export type ServerControllerOptions<TData> = {
     optimistic?: boolean;
     /** Resolve a row's stable id, so optimistic update/delete can find it in `rows`. */
     getRowId?: (row: TData) => string;
+    /**
+     * How rows reach the grid.
+     *
+     * - `page` (default): one page at a time. `state.rows` is that page, and
+     *   `setPage` moves between them.
+     * - `infinite`: one long scrollable list. `state.rows` spans the whole
+     *   result, with placeholder rows standing in for blocks nobody has
+     *   scrolled to yet; blocks load as the viewport reaches them.
+     */
+    mode?: 'page' | 'infinite';
+    /** `infinite` mode: rows per request. Default 100. */
+    blockSize?: number;
+    /**
+     * `infinite` mode: keep at most this many loaded blocks, evicting the
+     * least recently seen. Unlimited by default.
+     */
+    maxBlocksInCache?: number;
+    /** `infinite` mode: requests open at once. Default 2. */
+    maxConcurrentRequests?: number;
+    /** `infinite` mode: wait for the scroll to settle this long before fetching. */
+    blockLoadDebounceMs?: number;
+    /**
+     * `infinite` mode: rows to claim before anything has loaded, so there is a
+     * scrollbar on first paint. Default 1.
+     */
+    initialRowCount?: number;
 };
+/**
+ * The free server row model over a `ServerDataSource`: one page at a time,
+ * or one block-cached list in `infinite` mode, with sort, filter, race
+ * safety and writes. The result is a `GridRowModel`, so
+ * `<SvGrid rowModel={ctl} />` wires every seam.
+ */
 export declare function createServerDataSource<TData>(source: ServerDataSource<TData>, options: ServerControllerOptions<TData>): ServerController<TData>;