@toolbox-web/grid 3.9.1 → 3.10.0

package/lib/plugins/server-side/server-side-plugin.d.ts

@@ -54,6 +54,7 @@ import { ServerSideConfig } from './types';
  * @since 0.1.1
  */
 export declare class ServerSidePlugin extends BaseGridPlugin<ServerSideConfig> {
+    #private;
     /**
      * Plugin manifest declaring capabilities, hooks, events, and queries.
      * @internal
@@ -75,7 +76,15 @@ export declare class ServerSidePlugin extends BaseGridPlugin<ServerSideConfig> {
      * can cancel the underlying network call.
      */
     private blockControllers;
-    private lastRequestId;
+    /**
+     * In-flight `getChildRows` requests. Aborted only on `detach()` or when the
+     * requester's `FetchChildrenQuery.signal` fires — NOT on sort/filter/refresh:
+     * cancellation is requester-owned (Tree, GroupingRows, MasterDetail each
+     * abort their own stale loads). An abort broadcasts only `datasource:loading`
+     * `false`, which no requester treats as a release, so an unrequested abort
+     * would strand its loading state.
+     */
+    private childControllers;
     private scrollDebounceTimer?;
     /**
      * One-shot flag set when a block lands; consumed in `afterRender()` to re-check
@@ -90,11 +99,28 @@ export declare class ServerSidePlugin extends BaseGridPlugin<ServerSideConfig> {
     /** @internal */
     detach(): void;
     /**
-     * Abort all in-flight block requests. Called when the plugin tears down,
-     * the data source is replaced, the cache is purged, or the sort/filter
-     * model changes (the previously loaded block coordinates no longer apply).
+     * Abort all in-flight block requests and release their loading slots. Called
+     * when the plugin tears down, the data source is replaced, the cache is purged,
+     * or the sort/filter model changes (the previously loaded block coordinates no
+     * longer apply).
      */
     private abortAllBlocks;
+    /**
+     * Release `blockNum`'s in-flight slot when its request settles — but only if
+     * `controller` still owns it. An aborted request settles a microtask after the
+     * abort, by which time a superseding request (refresh, sort/filter change) may
+     * have re-registered the same block; deleting that entry would orphan the new
+     * request from `abortAllBlocks()` and let stale rows land in the cache.
+     */
+    private releaseBlock;
+    /**
+     * Effective sort/filter ownership. The `data-src` URL source only slices a cached
+     * dataset and ignores `sortModel` / `filterModel`, so it is always `'local'` —
+     * otherwise a sort or filter would refetch the unchanged rows and nobody would
+     * apply it.
+     */
+    private get sortMode();
+    private get filterMode();
     /**
      * Build enrichment params by querying sort/filter models from loaded plugins.
      *
@@ -104,10 +130,29 @@ export declare class ServerSidePlugin extends BaseGridPlugin<ServerSideConfig> {
      */
     private getEnrichmentParams;
     /**
-     * Translate visible viewport indices to node-space indices via structural plugins.
-     * Falls back to 1:1 mapping (flat data) when no structural plugin responds.
-     */
-    private getViewportMapping;
+     * Blocks (ascending) the viewport — expanded by `threshold` rows both ways to
+     * prefetch — needs loaded. The viewport is translated through a structural
+     * plugin's `datasource:viewport-mapping` when one responds, else 1:1 (flat data).
+     *
+     * When the displayed rows are not `managedNodes` itself, a later stage may have
+     * dropped or reordered rows (local filter or sort), or a structural plugin
+     * renumbered the rows it kept (Tree counts the remaining roots from zero). Then a
+     * display index is no longer a node index, so the blocks of the placeholders on
+     * screen are added: their `__index` is their node index, and loaded rows need no fetch.
+     */
+    private getRequiredBlockNumbers;
+    /**
+     * `totalNodeCount`, or `Infinity` while it is unknown — `0` means "not yet loaded"
+     * (just after purgeCache, or before the first fetch resolves), and block 0 must
+     * still be fetchable then.
+     */
+    private get knownTotal();
+    /** Whether the displayed rows are not `managedNodes` itself, so display indices may not be node indices. */
+    private get displayDiffers();
+    /** A structural plugin's (Tree, GroupingRows) translation of the viewport to node space, if any. */
+    private queryViewportMapping;
+    /** Add the block of every placeholder displayed in `[displayStart, displayEnd)` (may be fractional). */
+    private addPlaceholderBlocks;
     /**
      * Handle sort or filter model changes.
      * Purge cache and refetch current viewport with new enrichment params.
@@ -125,6 +170,12 @@ export declare class ServerSidePlugin extends BaseGridPlugin<ServerSideConfig> {
      * Returns loaded rows + one extra block of placeholders to trigger next fetch.
      */
     private getInfiniteScrollEstimate;
+    /**
+     * Length `managedNodes` must have: the infinite-scroll estimate, else
+     * `totalNodeCount` (guarded against an invalid value from a malformed
+     * datasource response, e.g. `undefined`).
+     */
+    private getNodeCount;
     /**
      * Check current viewport and load any missing blocks.
      */
@@ -141,6 +192,8 @@ export declare class ServerSidePlugin extends BaseGridPlugin<ServerSideConfig> {
     handleQuery(query: PluginQuery): unknown;
     /**
      * Fetch child rows via the datasource and broadcast the result.
+     * `requesterSignal` (from `FetchChildrenQuery.signal`) aborts the request;
+     * an aborted request broadcasts only `datasource:loading` `false`.
      */
     private fetchChildren;
     /**

package/lib/plugins/server-side/types.d.ts

@@ -76,6 +76,8 @@ export interface ServerSideConfig {
      * How sort changes affect the cache.
      * - `'server'` (default): purge cache and refetch via `getRows({ sortModel })`.
      *   Use when the backend supports the requested sort shape natively.
+     *   MultiSortPlugin does not re-sort the returned rows locally — the data
+     *   source's order (and its loading placeholders' block positions) is shown as-is.
      * - `'local'`: keep the loaded blocks; sort the loaded rows in-place via
      *   the active sort plugin (MultiSort or core sort). `sortModel` is **not**
      *   sent on subsequent block fetches. Loading placeholder rows
@@ -83,6 +85,7 @@ export interface ServerSideConfig {
      *
      * Use `'local'` when the server cannot sort by every column the user can sort
      * (e.g. APIs that only support a single sort field, or no sort at all).
+     * Ignored for the `data-src` URL source, which always sorts locally.
      *
      * @default 'server'
      */
@@ -90,9 +93,14 @@ export interface ServerSideConfig {
     /**
      * How filter changes affect the cache.
      * - `'server'` (default): purge cache and refetch via `getRows({ filterModel })`.
+     *   FilteringPlugin does not re-filter the returned rows locally — the data
+     *   source's result (and its loading placeholders) is shown as-is.
      * - `'local'`: keep the loaded blocks; filter only the rows currently in cache
      *   via FilteringPlugin's normal pipeline. `filterModel` is **not** sent on
-     *   subsequent block fetches.
+     *   subsequent block fetches. Loading placeholders (see `isLoadingPlaceholder()`)
+     *   always pass the filter until their block loads.
+     *
+     * Ignored for the `data-src` URL source, which always filters locally.
      *
      * In `'local'` mode the user only filters the currently loaded subset —
      * scrolling further loads more blocks which then re-enter the local filter.

package/lib/plugins/shared/form-field-target.d.ts

@@ -0,0 +1,10 @@
+/**
+ * True when a keyboard event originates in a text-entry control — `<input>`, `<select>`,
+ * `<textarea>` or a contenteditable element. Plugin key handlers (e.g. Space to toggle a tree
+ * row) must defer to the control so the keystroke is typed rather than swallowed.
+ *
+ * Reads `composedPath()[0]` so controls inside an editor's open shadow root are recognised;
+ * `event.target` is retargeted to the shadow host by the time the grid sees the event.
+ * @internal
+ */
+export declare function isFormFieldKeyTarget(event: Event): boolean;

package/lib/plugins/shared/format-value.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Call a column `format` outside the core cell pipeline (filter-panel labels, Pivot aggregates).
+ *
+ * Some of these values have no source row — `valuesHandler` results and Pivot aggregates — so
+ * `row` is `undefined` there even though `format` is typed `(value, row: TRow)`. A formatter
+ * that reads the row then throws; this guard reports the error and lets the caller fall back
+ * to the raw value, mirroring the core cell pipeline (TBW062).
+ *
+ * @returns The formatted string (`''` for a nullish result), or `undefined` when `format` threw.
+ * @internal
+ */
+export declare function tryFormat<TRow>(format: (value: unknown, row: TRow) => unknown, value: unknown, row: TRow | undefined, onError: (error: unknown) => void): string | undefined;