@toolbox-web/grid 2.1.1 → 2.3.0

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

@@ -38,6 +38,26 @@ export interface ServerSideConfig {
      * @default 2
      */
     maxConcurrentRequests?: number;
+    /**
+     * Prefetch slack in **node count** (rows). When `> 0`, blocks are loaded as
+     * soon as the user is within `loadThreshold` rows of an unloaded block,
+     * rather than only when the visible window enters it. This reduces the
+     * number of placeholder rows the user sees during gentle scrolling at the
+     * cost of slightly more eager fetching.
+     *
+     * The threshold is applied symmetrically: the viewport is expanded by
+     * `loadThreshold` rows in both directions before block coverage is
+     * computed. The `maxConcurrentRequests` cap and per-block dedup still
+     * apply, so a large threshold during fast scrolling will not flood the
+     * server with requests.
+     *
+     * A reasonable starting point is `pageSize / 2`. Values larger than
+     * `cacheBlockSize` will eagerly request 2+ blocks ahead, which can hurt
+     * perceived performance with slow backends.
+     *
+     * @default 0 (fetch only when the visible window enters an unloaded block)
+     */
+    loadThreshold?: number;
     /**
      * Data source for server-side loading.
      * When provided, the plugin auto-initializes on attach — no need to call `setDataSource()`.
@@ -58,6 +78,34 @@ export interface ServerSideConfig {
      * ```
      */
     dataSource?: ServerSideDataSource;
+    /**
+     * 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.
+     * - `'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. Placeholder rows (`__loading: true`)
+     *   are pinned to the end regardless of direction.
+     *
+     * 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).
+     *
+     * @default 'server'
+     */
+    sortMode?: 'server' | 'local';
+    /**
+     * How filter changes affect the cache.
+     * - `'server'` (default): purge cache and refetch via `getRows({ filterModel })`.
+     * - `'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.
+     *
+     * In `'local'` mode the user only filters the currently loaded subset —
+     * scrolling further loads more blocks which then re-enter the local filter.
+     *
+     * @default 'server'
+     */
+    filterMode?: 'server' | 'local';
 }
 export interface ServerSideState {
     dataSource: ServerSideDataSource | null;