@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/Table/Types/DataRepository/BuiltInRemoteRepository.svelte.js

@@ -0,0 +1,454 @@
+/**
+ * Built-in remote data repository used by `createTable({ rows: { kind: 'remote' } })`.
+ *
+ * Phase 1 of the new Table API: this class absorbs the URL construction,
+ * filter encoding, pagination, sort, debouncing, and page-size persistence
+ * that every consumer was previously reimplementing for itself (see the
+ * FloWMS-owned `RemoteTableDataRepository.svelte.ts` for the prior shape).
+ *
+ * The default filter-encoding strategy is `'query-string'`, which produces
+ * a flat `?filter[<id>]=<value>&page=<n>&pageSize=<m>&sort=<col>&direction=<asc|desc>`
+ * URL. Consumers whose backend expects a different shape pass a custom
+ * `filterEncoding: { encode }` function. Consumers needing complete
+ * control over the request lifecycle drop to `kind: 'custom'`, which
+ * bypasses this repository entirely.
+ *
+ * The repository extends `TableDataRepository` for its pagination-state /
+ * filter-modes / force-refresh plumbing and implements
+ * `IRemoteDataRepository<TRow>` for the surface `TableContext` consumes.
+ *
+ * @remarks
+ *
+ * Out of scope for Phase 1:
+ *
+ * - Sophisticated filter-mode encoding (`StringFilterMode.NotIn`, the
+ *   `[min, max]` tuple form for ranges, etc.). The Phase 1 default
+ *   encoder emits raw `?filter[<id>]=<JSON-encoded-value>`. Consumers
+ *   needing the rich encoding the FloWMS repo currently does should pass
+ *   a custom encoder in Phase 1 and we will lift the common encodings
+ *   into the library in Phase 2 once the audit of the consumer's actual
+ *   backend shape is complete.
+ * - The five filter callbacks (`dateFilter` / `numberFilter` / etc.).
+ *   These are local-only and not meaningful for a remote source. The
+ *   interface inherits them as optional; left undefined here.
+ */
+import { browser } from '$app/environment';
+import { devCatch } from '../../../../Helpers/Helpers.svelte.js';
+import { FilterType } from '../Filtering/FilterType.js';
+import { PaginationType } from '../Pagination/PaginationType.js';
+import { TableDataRepository } from './TableDataRepository.svelte.js';
+export class BuiltInRemoteRepository extends TableDataRepository {
+    _options;
+    paginationType = PaginationType.Remote;
+    filterType = FilterType.Virtual;
+    manualSorting = true;
+    _data = $state([]);
+    get data() {
+        return this._data;
+    }
+    set data(v) {
+        this._data = v;
+    }
+    _totalRows = $state(0);
+    get totalRows() {
+        return this._totalRows;
+    }
+    set totalRows(v) {
+        this._totalRows = v;
+    }
+    _lastPage = $state(0);
+    get lastPage() {
+        return this._lastPage;
+    }
+    set lastPage(v) {
+        this._lastPage = v;
+    }
+    _isLoading = $state(false);
+    get isLoading() {
+        return this._isLoading;
+    }
+    loadingMessage = undefined;
+    _sorting = $state([]);
+    get sorting() {
+        return this._sorting;
+    }
+    set sorting(v) {
+        this._sorting = v;
+    }
+    _filtering = $state([]);
+    get filtering() {
+        return this._filtering;
+    }
+    _abortController = null;
+    _debounceTimer = null;
+    _quickFilterFocusCount = 0;
+    constructor(_options) {
+        super(_options.tableName, _options.getUserId);
+        this._options = _options;
+        // Restore persisted page size if present.
+        if (browser) {
+            const userId = this.getUserId() ?? 'anon';
+            const saved = localStorage.getItem(`scoria-table:${userId}:${_options.tableName}:page-size`);
+            if (saved !== null) {
+                const parsed = Number.parseInt(saved, 10);
+                if (Number.isFinite(parsed) && parsed > 0) {
+                    this.paginationState = { pageIndex: 0, pageSize: parsed };
+                }
+            }
+            else if (_options.pageSize) {
+                this.paginationState = { pageIndex: 0, pageSize: _options.pageSize };
+            }
+        }
+    }
+    // ── IRemoteDataRepository surface ────────────────────────────────
+    setFilterMode = (id, mode) => {
+        this._filterModes.set(id, mode);
+        this.scheduleReload();
+    };
+    filterBy = (id, value) => {
+        const existing = this._filtering.findIndex((f) => f.id === id);
+        const next = [...this._filtering];
+        if (value === undefined || value === null || value === '') {
+            if (existing !== -1) {
+                next.splice(existing, 1);
+            }
+        }
+        else {
+            const entry = { id, value };
+            if (existing !== -1) {
+                next[existing] = entry;
+            }
+            else {
+                next.push(entry);
+            }
+        }
+        this._filtering = next;
+        this.scheduleReload();
+    };
+    resetFilters = () => {
+        this._filtering = [];
+        this.scheduleReload();
+    };
+    setPage = (page) => {
+        this.paginationState = { ...this.paginationState, pageIndex: page };
+        this.scheduleReload({ immediate: true });
+    };
+    nextPage = () => {
+        this.setPage(this.paginationState.pageIndex + 1);
+    };
+    prevPage = () => {
+        this.setPage(Math.max(0, this.paginationState.pageIndex - 1));
+    };
+    setPageSize = (size) => {
+        const parsed = typeof size === 'number' ? size : Number.parseInt(size, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            return;
+        }
+        this.paginationState = { pageIndex: 0, pageSize: parsed };
+        this.scheduleReload({ immediate: true });
+    };
+    updateSorting = (next) => {
+        this._sorting = typeof next === 'function' ? next(this._sorting) : next;
+        this.scheduleReload({ immediate: true });
+    };
+    get pageStartIndex() {
+        return this.paginationState.pageIndex * this.paginationState.pageSize;
+    }
+    get pageEndIndexExclusive() {
+        return Math.min(this.pageStartIndex + this.paginationState.pageSize, this._totalRows);
+    }
+    /**
+     * Fetches a fresh page from the configured endpoint. Cancels any
+     * in-flight request first. The `debounced` flag (when true) coalesces
+     * rapid calls into a single trailing request after the configured
+     * debounce window.
+     */
+    reload = async (debounced) => {
+        if (debounced) {
+            this.scheduleReload();
+            return;
+        }
+        await this._reloadNow();
+    };
+    // ── Internals ──────────────────────────────────────────────────
+    scheduleReload(opts) {
+        const debounce = opts?.immediate ? 0 : this._options.reloadDebounce;
+        if (debounce === false) {
+            return;
+        }
+        if (this._debounceTimer !== null) {
+            clearTimeout(this._debounceTimer);
+        }
+        const delay = typeof debounce === 'number' ? debounce : this._quickFilterFocusCount > 0 ? 300 : 0;
+        this._debounceTimer = setTimeout(() => {
+            this._debounceTimer = null;
+            void this._reloadNow();
+        }, delay);
+    }
+    async _reloadNow() {
+        this._abortController?.abort();
+        const controller = new AbortController();
+        this._abortController = controller;
+        const merged = this._buildMergedFilters();
+        const request = this._buildRequestInit(merged, controller.signal);
+        this._isLoading = true;
+        try {
+            const url = this._buildUrl(merged);
+            const response = await fetch(url, request);
+            if (!response.ok) {
+                throw new Error(`scoria: remote table fetch failed (${response.status} ${response.statusText})`);
+            }
+            const raw = await response.json();
+            if (controller.signal.aborted) {
+                return;
+            }
+            const transformed = this._applyResponseTransform(raw);
+            this._data = [...transformed.rows];
+            this._totalRows = transformed.totalRows;
+            this._lastPage = Math.max(0, Math.ceil(transformed.totalRows / this.paginationState.pageSize) - 1);
+        }
+        catch (e) {
+            if (e.name === 'AbortError') {
+                return;
+            }
+            devCatch(e);
+        }
+        finally {
+            if (this._abortController === controller) {
+                this._isLoading = false;
+            }
+        }
+    }
+    _buildMergedFilters() {
+        // Transient request-scoped map; consumed immediately by `_buildUrl` /
+        // `_buildRequestInit`, never observed reactively.
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const merged = new Map();
+        const defaults = this._options.defaultFilters?.();
+        if (defaults) {
+            for (const [k, v] of Object.entries(defaults)) {
+                merged.set(k, v);
+            }
+        }
+        for (const f of this._filtering) {
+            merged.set(f.id, f.value);
+        }
+        return merged;
+    }
+    _buildUrl(_mergedFilters) {
+        const encoding = this._options.filterEncoding ?? 'query-string';
+        if (encoding === 'json-body' || typeof encoding === 'object') {
+            // For POST-body encodings the URL is the bare endpoint; the body
+            // carries pagination, filters, and sort.
+            return this._options.endpoint;
+        }
+        // Default: query-string encoding. The URL is constructed for the
+        // current request only; reactivity is not required.
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const url = new URL(this._options.endpoint, browser ? window.location.origin : 'http://localhost');
+        const params = url.searchParams;
+        params.set('page', String(this.paginationState.pageIndex));
+        params.set('pageSize', String(this.paginationState.pageSize));
+        for (const sort of this._sorting) {
+            params.append('sort', sort.id);
+            params.append('direction', sort.desc ? 'desc' : 'asc');
+        }
+        for (const [id, value] of _mergedFilters) {
+            const mode = this._filterModes.get(id);
+            if (mode) {
+                params.set(`filter[${id}][mode]`, mode);
+            }
+            params.set(`filter[${id}]`, typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean'
+                ? String(value)
+                : JSON.stringify(value));
+        }
+        return url.toString();
+    }
+    _buildRequestInit(merged, signal) {
+        const method = this._options.method ?? 'GET';
+        const headers = {
+            'Content-Type': 'application/json',
+            ...this._options.headers?.(),
+        };
+        const encoding = this._options.filterEncoding ?? 'query-string';
+        if (typeof encoding === 'object') {
+            // Custom encoding: ask the consumer for the full RequestInit.
+            const custom = encoding.encode({
+                page: this.paginationState.pageIndex,
+                pageSize: this.paginationState.pageSize,
+                filters: this._filtering,
+                sort: this._sorting,
+            });
+            return { signal, headers, ...custom };
+        }
+        if (encoding === 'json-body') {
+            const body = {
+                page: this.paginationState.pageIndex,
+                pageSize: this.paginationState.pageSize,
+                filters: Object.fromEntries(merged),
+                sort: this._sorting,
+            };
+            return { method, headers, signal, body: JSON.stringify(body) };
+        }
+        return { method, headers, signal };
+    }
+    _applyResponseTransform(raw) {
+        const transformer = this._options.responseTransform;
+        if (transformer) {
+            return transformer(raw);
+        }
+        // Default shape: `{ rows: TRow[]; totalRows: number }`.
+        if (raw !== null &&
+            typeof raw === 'object' &&
+            'rows' in raw &&
+            'totalRows' in raw &&
+            Array.isArray(raw.rows)) {
+            const o = raw;
+            return { rows: o.rows, totalRows: o.totalRows };
+        }
+        throw new Error(`scoria: remote table response did not match the expected { rows, totalRows } shape. ` +
+            `Pass a 'responseTransform' option to RemoteRowSource if your backend returns a different shape.`);
+    }
+}
+/**
+ * Thin adapter for `kind: 'custom'`. Delegates to a consumer-supplied
+ * `fetch` function on every page / filter / sort change. Inherits
+ * `TableDataRepository` for pagination and filter-mode plumbing.
+ */
+export class CustomRemoteRepository extends TableDataRepository {
+    _fetch;
+    paginationType = PaginationType.Remote;
+    filterType = FilterType.Virtual;
+    manualSorting = true;
+    _data = $state([]);
+    get data() {
+        return this._data;
+    }
+    set data(v) {
+        this._data = v;
+    }
+    _totalRows = $state(0);
+    get totalRows() {
+        return this._totalRows;
+    }
+    set totalRows(v) {
+        this._totalRows = v;
+    }
+    _lastPage = $state(0);
+    get lastPage() {
+        return this._lastPage;
+    }
+    set lastPage(v) {
+        this._lastPage = v;
+    }
+    _isLoading = $state(false);
+    get isLoading() {
+        return this._isLoading;
+    }
+    loadingMessage = undefined;
+    _sorting = $state([]);
+    get sorting() {
+        return this._sorting;
+    }
+    set sorting(v) {
+        this._sorting = v;
+    }
+    _filtering = $state([]);
+    get filtering() {
+        return this._filtering;
+    }
+    _abortController = null;
+    constructor(tableName, getUserId, _fetch) {
+        super(tableName, getUserId);
+        this._fetch = _fetch;
+    }
+    setFilterMode = (id, mode) => {
+        this._filterModes.set(id, mode);
+        void this.reload();
+    };
+    filterBy = (id, value) => {
+        const existing = this._filtering.findIndex((f) => f.id === id);
+        const next = [...this._filtering];
+        if (value === undefined || value === null || value === '') {
+            if (existing !== -1) {
+                next.splice(existing, 1);
+            }
+        }
+        else {
+            const entry = { id, value };
+            if (existing !== -1) {
+                next[existing] = entry;
+            }
+            else {
+                next.push(entry);
+            }
+        }
+        this._filtering = next;
+        void this.reload();
+    };
+    resetFilters = () => {
+        this._filtering = [];
+        void this.reload();
+    };
+    setPage = (page) => {
+        this.paginationState = { ...this.paginationState, pageIndex: page };
+        void this.reload();
+    };
+    nextPage = () => {
+        this.setPage(this.paginationState.pageIndex + 1);
+    };
+    prevPage = () => {
+        this.setPage(Math.max(0, this.paginationState.pageIndex - 1));
+    };
+    setPageSize = (size) => {
+        const parsed = typeof size === 'number' ? size : Number.parseInt(size, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            return;
+        }
+        this.paginationState = { pageIndex: 0, pageSize: parsed };
+        void this.reload();
+    };
+    updateSorting = (next) => {
+        this._sorting = typeof next === 'function' ? next(this._sorting) : next;
+        void this.reload();
+    };
+    get pageStartIndex() {
+        return this.paginationState.pageIndex * this.paginationState.pageSize;
+    }
+    get pageEndIndexExclusive() {
+        return Math.min(this.pageStartIndex + this.paginationState.pageSize, this._totalRows);
+    }
+    reload = async () => {
+        this._abortController?.abort();
+        const controller = new AbortController();
+        this._abortController = controller;
+        this._isLoading = true;
+        try {
+            const request = {
+                page: this.paginationState.pageIndex,
+                pageSize: this.paginationState.pageSize,
+                filters: this._filtering,
+                sort: this._sorting,
+                signal: controller.signal,
+            };
+            const response = await this._fetch(request);
+            if (controller.signal.aborted) {
+                return;
+            }
+            this._data = [...response.rows];
+            this._totalRows = response.totalRows;
+            this._lastPage = Math.max(0, Math.ceil(response.totalRows / this.paginationState.pageSize) - 1);
+        }
+        catch (e) {
+            if (e.name === 'AbortError') {
+                return;
+            }
+            devCatch(e);
+        }
+        finally {
+            if (this._abortController === controller) {
+                this._isLoading = false;
+            }
+        }
+    };
+}

package/dist/Components/Table/Types/DataRepository/IDataRepository.d.ts

@@ -7,6 +7,27 @@ import type { OnChangeFn } from '../OnChangeFn.js';
 import type { PaginationState } from '../Pagination/PaginationState.js';
 import type { PaginationType } from '../Pagination/PaginationType.js';
 import type { SortingState } from './SortingState.js';
+/**
+ * Union surface implemented by both `LocalTableDataRepository` and any
+ * consumer-supplied remote repository. `TableContext` reads from `dataRepo`
+ * and `paginationRepo` via this contract; everything reactive is exposed
+ * through the underlying `$state`-backed properties on the implementation.
+ *
+ * Implementers are responsible for:
+ *
+ * - Snapshot consistency: `data`, `totalRows`, `pageStartIndex`,
+ *   `pageEndIndexExclusive`, and `paginationState` must all describe the
+ *   same logical page when read together.
+ * - Filter safety (remote): `filterBy` accepts `unknown` here for backwards
+ *   compatibility; remote implementations MUST escape values before
+ *   forwarding to a backend (URL encoding, parameterised SQL, etc.). Nothing
+ *   in scoria enforces this and no validation happens server-side on
+ *   scoria's behalf.
+ * - LSP: `setPageSize: (size: number) => void` is widened to
+ *   `(size: number | string) => void` in the concrete repositories so they
+ *   can accept page-size inputs from a `<select>` element. Callers that hold
+ *   the base interface should always pass `number`.
+ */
 export interface IDataRepository<T extends object> {
     paginationState: PaginationState;
     setPageSize: (size: number) => void;

package/dist/Components/Table/Types/DataRepository/ILocalDataRepository.d.ts

@@ -3,6 +3,16 @@ import type { ColumnFiltersState } from '../Filtering/ColumnFiltersState.js';
 import type { BoolFilterValueType, DateFilterValueType, FilterFn, NumberFilterValueType, SelectFilterValueType, StringFilterValueType } from '../Filtering/FilterFn.js';
 import type { FilterMode } from '../Filtering/FilterMode.js';
 import type { IDataRepository } from './IDataRepository.js';
+/**
+ * Repository contract for in-memory tables. Narrows `paginationType` to the
+ * `'Local'` literal so consumers can discriminate on it. All filter functions
+ * are required (the local repository must filter rows itself because there
+ * is no backend to delegate to).
+ *
+ * `setPageSize` is widened from `(size: number) => void` to
+ * `(size: number | string) => void` to accept input values from a HTML
+ * `<select>` element directly without an intermediate parse step.
+ */
 export interface ILocalDataRepository<T extends object> extends IDataRepository<T> {
     readonly paginationType: 'Local';
     setPageSize: (size: number | string) => void;

package/dist/Components/Table/Types/DataRepository/IRemoteDataRepository.d.ts

@@ -2,6 +2,22 @@ import type { SvelteMap } from 'svelte/reactivity';
 import type { ColumnFiltersState } from '../Filtering/ColumnFiltersState.js';
 import type { FilterMode } from '../Filtering/FilterMode.js';
 import type { IDataRepository } from './IDataRepository.js';
+/**
+ * Repository contract for remotely-paged tables. Narrows `paginationType` to
+ * the `'Remote'` literal and makes `lastPage` required (the remote backend
+ * is authoritative on the page count). Filter functions are inherited but
+ * left optional because remote tables typically delegate filtering to the
+ * backend and only need a subset of client-side filter functions.
+ *
+ * `reload` accepts a `debounced` flag so consumers can request a
+ * batched reload (e.g. while the user is still typing into a filter input).
+ *
+ * Security note: remote implementations MUST escape filter values and
+ * column ids before forwarding them to the backend. The interface signature
+ * accepts `unknown` for `filterBy(value)` for backwards compatibility, but
+ * the implementation must validate it. See the security section of the
+ * `IDataRepository` JSDoc.
+ */
 export interface IRemoteDataRepository<T extends object> extends IDataRepository<T> {
     readonly paginationType: 'Remote';
     setPageSize: (size: number | string) => void;

package/dist/Components/Table/Types/DataRepository/LocalTableDataRepository.svelte.d.ts

@@ -4,13 +4,28 @@ import type { Row } from '../Context/Row.js';
 import type { ColumnFiltersState } from '../Filtering/ColumnFiltersState.js';
 import type { BoolFilterValueType, NumberFilterValueType, SelectFilterValueType, StringFilterValueType } from '../Filtering/FilterFn.js';
 import type { FilterMode } from '../Filtering/FilterMode.js';
-import { NumberDateFilterMode } from '../Filtering/NumberDateFilterMode.js';
-import { StringFilterMode } from '../Filtering/StringFilterMode.js';
 import type { OnChangeFn } from '../OnChangeFn.js';
 import type { ILocalDataRepository } from './ILocalDataRepository.js';
 import type { SortingState } from './SortingState.js';
 import { TableDataRepository } from './TableDataRepository.svelte.js';
-export declare const allowedEmptyFilterModes: SvelteSet<StringFilterMode | NumberDateFilterMode>;
+/**
+ * Filter modes that accept an empty filter value (e.g. "show empty",
+ * "show null"). Used by `setFilterMode` / `filterBy` to decide whether
+ * to keep an empty stub filter in the active filtering list.
+ */
+export declare const allowedEmptyFilterModes: SvelteSet<FilterMode>;
+/**
+ * Concrete in-memory data repository. The data array is supplied as a
+ * `RefWrapper` so consumers can mutate the underlying array and the
+ * repo's `$derived` totals will update reactively without a full
+ * reassignment.
+ *
+ * Implements the five filter callbacks (date / number / select / bool
+ * / string). The async signature is preserved across all five even
+ * though the bodies are synchronous; converting to a sync fast-path is
+ * deferred (LocalTableDataRepository P0 finding, requires a coordinated
+ * change to TableContext's `_filteredIndices` loop).
+ */
 export declare class LocalTableDataRepository<T extends object> extends TableDataRepository<T, unknown> implements ILocalDataRepository<T> {
     addEmptyRow?: (() => void) | undefined;
     private debug;
@@ -18,40 +33,109 @@ export declare class LocalTableDataRepository<T extends object> extends TableDat
     constructor(tableName: string, dataRef: RefWrapper<Array<T>>, // reactive
     getUserId: () => string | undefined, addEmptyRow?: (() => void) | undefined, debug?: boolean);
     private _isLoading;
+    /** Whether a long-running operation is currently in flight. */
     get isLoading(): boolean;
     set isLoading(v: boolean);
     private _dataRef;
+    /** The current data array (read from the underlying `RefWrapper`). */
     get data(): Array<T>;
     private _lastPage;
+    /** The last page index (1-based) given the current page size. */
     get lastPage(): number;
     private _sorting;
+    /** The active sort columns, in precedence order. */
     get sorting(): SortingState;
     set sorting(v: SortingState);
     private _totalRows;
+    /** Total number of rows in the underlying data array. */
     get totalRows(): number;
     private _filtering;
+    /** The active per-column filter values, in application order. */
     get filtering(): ColumnFiltersState;
     set filtering(v: ColumnFiltersState);
+    /**
+     * Replace the sorting state with either a literal array or a
+     * function that maps the previous state to a new state.
+     */
     updateSorting: OnChangeFn<SortingState>;
     readonly paginationType: "Local";
+    /**
+     * Sets (or clears) the filter mode for a column. Passing `undefined`
+     * removes the mode entry; setting an empty-allowed mode (e.g.
+     * "Empty", "Null") additionally adds a stub filter value so the
+     * filter actually applies even though no value was typed.
+     */
     readonly setFilterMode: (id: string, mode: FilterMode | undefined) => void;
+    /**
+     * Sets or updates the filter value for a column. Empty values are
+     * dropped from the filtering list unless the column's active mode
+     * explicitly accepts an empty value (e.g. "Empty", "Null").
+     *
+     * Per-keystroke debouncing is deferred to the input layer; the
+     * `LocalTableDataRepository` P0 finding tracks adding a
+     * `filterByDebounced` helper here.
+     */
     readonly filterBy: (id: string, value: unknown) => void;
     private _pageStartIndex;
+    /** Index of the first row on the current page. */
     get pageStartIndex(): number;
     private _pageEndIndexExclusive;
+    /** Index one past the last row on the current page. */
     get pageEndIndexExclusive(): number;
+    /** Clears every active filter value (keeps filter modes intact). */
     readonly resetFilters: () => void;
+    /**
+     * Sets the page size and clamps the current page index so the new
+     * page count covers the current view. Accepts a string so a raw
+     * `<select>` value can be passed through without parsing first.
+     */
     setPageSize: (size: number | string) => void;
+    /** Jumps to the given 1-based page number, clamped to the last page. */
     setPage: (page: number) => void;
+    /** Advances to the next page, clamped to the last page. */
     nextPage: () => void;
+    /** Returns to the previous page, clamped to page 0. */
     prevPage: () => void;
+    /**
+     * Date range filter. The filter value is a `[from, to]` tuple where
+     * either bound may be `null` (or `undefined`) to leave that side
+     * unbounded. Rows whose value is not a `Date` are excluded.
+     *
+     * Inner `<T>` generic shadowing of the class `T` (workorder P1) is
+     * a known limitation, retained pending a coordinated signature
+     * change.
+     */
     readonly dateFilter: ILocalDataRepository<T>['dateFilter'];
+    /**
+     * Numeric filter supporting equality, range, set, and negation
+     * modes. String filter modes that share a literal value are caught
+     * at the switch and throw, surfacing a programming error before the
+     * user sees stale data.
+     */
     readonly numberFilter: (row: Row<T>, columnId: string, // & keyof T,
     values: NumberFilterValueType) => Promise<boolean>;
+    /**
+     * Multi-select / single-value equality filter. Accepts an array, a
+     * `Set`, an option-object with a `value` field, or a primitive
+     * compared with loose equality.
+     */
     readonly selectFilter: <columnType = T[keyof T]>(row: Row<T>, columnId: string, // & keyof T,
     filterValue: SelectFilterValueType<T>) => Promise<boolean>;
+    /**
+     * Boolean filter. Rows whose value is not a boolean are excluded
+     * (dev warning logged) so an accidental non-boolean accessor does
+     * not silently match every row.
+     */
     readonly boolFilter: (row: Row<T>, columnId: string, // & keyof T,
     filterValue: BoolFilterValueType) => Promise<boolean>;
+    /**
+     * String filter implementing every `StringFilterMode` variant.
+     * Comparisons are case-insensitive and use trimmed lowercase forms;
+     * an empty filter value yields a positive match for inclusion modes
+     * and a negative match for negation modes (so empty inputs do not
+     * accidentally hide rows when the user is mid-typing a "not equals"
+     * filter).
+     */
     readonly stringFilter: (row: Row<T>, columnId: string, // & keyof T,
     filterValue: StringFilterValueType) => Promise<boolean>;
 }