@lavalogic/scoria 0.36.0 → 0.37.0

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

@@ -1,14 +1,26 @@
+import { dev } from '$app/environment';
 import { SvelteSet } from 'svelte/reactivity';
 import { FilterType } from '../Filtering/FilterType.js';
 import { NumberDateFilterMode } from '../Filtering/NumberDateFilterMode.js';
 import { StringFilterMode } from '../Filtering/StringFilterMode.js';
 import { PaginationType } from '../Pagination/PaginationType.js';
 import { TableDataRepository } from './TableDataRepository.svelte.js';
+/**
+ * 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 const allowedEmptyFilterModes = new SvelteSet([
     StringFilterMode.Empty,
     StringFilterMode.null,
     NumberDateFilterMode.null,
 ]);
+/**
+ * Negation-style filter modes. Used by the per-row filter callbacks to
+ * decide whether a row with a missing or wrong-shaped value should pass
+ * the filter (rows that cannot be tested are included for negation
+ * modes and excluded for inclusion modes).
+ */
 const inclusiveFilterModes = new SvelteSet([
     //strings
     StringFilterMode.NotEquals,
@@ -21,7 +33,18 @@ const inclusiveFilterModes = new SvelteSet([
     NumberDateFilterMode.NotIn,
     NumberDateFilterMode.null,
 ]);
-// let totalRedraws = 0;
+/**
+ * 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 class LocalTableDataRepository extends TableDataRepository {
     addEmptyRow;
     debug;
@@ -36,6 +59,7 @@ export class LocalTableDataRepository extends TableDataRepository {
         this._totalRows = $derived(this._dataRef.value.length);
     }
     _isLoading = $state(false);
+    /** Whether a long-running operation is currently in flight. */
     get isLoading() {
         return this._isLoading;
     }
@@ -43,14 +67,17 @@ export class LocalTableDataRepository extends TableDataRepository {
         this._isLoading = v;
     }
     _dataRef;
+    /** The current data array (read from the underlying `RefWrapper`). */
     get data() {
         return this._dataRef.value;
     }
     _lastPage;
+    /** The last page index (1-based) given the current page size. */
     get lastPage() {
         return this._lastPage;
     }
     _sorting = $state([]);
+    /** The active sort columns, in precedence order. */
     get sorting() {
         return this._sorting;
     }
@@ -58,16 +85,22 @@ export class LocalTableDataRepository extends TableDataRepository {
         this._sorting = v;
     }
     _totalRows;
+    /** Total number of rows in the underlying data array. */
     get totalRows() {
         return this._totalRows;
     }
     _filtering = $state([]);
+    /** The active per-column filter values, in application order. */
     get filtering() {
         return this._filtering;
     }
     set filtering(v) {
         this._filtering = v;
     }
+    /**
+     * Replace the sorting state with either a literal array or a
+     * function that maps the previous state to a new state.
+     */
     updateSorting = (stateOrCallback) => {
         if (typeof stateOrCallback == 'function') {
             this.sorting = stateOrCallback(this.sorting);
@@ -77,6 +110,12 @@ export class LocalTableDataRepository extends TableDataRepository {
         }
     };
     paginationType = 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.
+     */
     setFilterMode = (id, mode) => {
         if (mode != undefined) {
             if (this.debug) {
@@ -95,6 +134,15 @@ export class LocalTableDataRepository extends TableDataRepository {
             this._filterModes.delete(id);
         }
     };
+    /**
+     * 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.
+     */
     filterBy = (id, value) => {
         if (typeof value === 'string') {
             value = value.trim();
@@ -134,16 +182,24 @@ export class LocalTableDataRepository extends TableDataRepository {
         this.filtering = newFiltering;
     };
     _pageStartIndex = $derived(this.paginationState.pageIndex * this.paginationState.pageSize);
+    /** Index of the first row on the current page. */
     get pageStartIndex() {
         return this._pageStartIndex;
     }
     _pageEndIndexExclusive = $derived((this.paginationState.pageIndex + 1) * this.paginationState.pageSize);
+    /** Index one past the last row on the current page. */
     get pageEndIndexExclusive() {
         return this._pageEndIndexExclusive;
     }
+    /** Clears every active filter value (keeps filter modes intact). */
     resetFilters = () => {
         this.filtering = [];
     };
+    /**
+     * 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) => {
         if (typeof size === 'string') {
             size = parseInt(size);
@@ -158,6 +214,7 @@ export class LocalTableDataRepository extends TableDataRepository {
             pageIndex: Math.max(0, Math.min(this.paginationState.pageIndex, lastIndex)),
         };
     };
+    /** Jumps to the given 1-based page number, clamped to the last page. */
     setPage = (page) => {
         const lastIndex = this._lastPage - 1;
         this.paginationState = {
@@ -165,6 +222,7 @@ export class LocalTableDataRepository extends TableDataRepository {
             pageIndex: Math.max(0, Math.min(lastIndex, page - 1)),
         };
     };
+    /** Advances to the next page, clamped to the last page. */
     nextPage = () => {
         const lastIndex = this._lastPage - 1;
         this.paginationState = {
@@ -172,6 +230,7 @@ export class LocalTableDataRepository extends TableDataRepository {
             pageIndex: Math.min(lastIndex, this.paginationState.pageIndex + 1),
         };
     };
+    /** Returns to the previous page, clamped to page 0. */
     prevPage = () => {
         this.paginationState = {
             ...this.paginationState,
@@ -179,12 +238,28 @@ export class LocalTableDataRepository extends TableDataRepository {
         };
     };
     // #region filters
+    /**
+     * 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.
+     */
     dateFilter = async (row, columnId, // & keyof T,
     [dateFrom, dateTo]) => {
         if (!dateFrom && !dateTo) {
             return true;
         }
-        const columnValue = (await row.getValue(columnId))?.valueOf();
+        const rawValue = await row.getValue(columnId);
+        if (!(rawValue instanceof Date)) {
+            if (dev && rawValue != null) {
+                console.warn(`dateFilter: column ${columnId} value was not a Date`, rawValue);
+            }
+            return false;
+        }
+        const columnValue = rawValue.valueOf();
         if (!columnValue) {
             return false;
         }
@@ -202,19 +277,24 @@ export class LocalTableDataRepository extends TableDataRepository {
             const dateToTimestamp = dateTo.valueOf();
             return columnValue <= dateToTimestamp;
         }
-        else {
+        else if (dev) {
             console.warn('no valid dateFrom or dateTo exist in filter');
             //should never happen
         }
         return true;
     };
+    /**
+     * 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.
+     */
     numberFilter = async (row, columnId, // & keyof T,
     values) => {
         const columnValue = await row.getValue(columnId);
         const mode = this.filterModes.get(columnId) ?? NumberDateFilterMode.In;
         const isValueInvalid = columnValue == null || typeof columnValue != 'number' || isNaN(columnValue);
         if (mode == NumberDateFilterMode.null) {
-            // TODO test
             return isValueInvalid;
         }
         if (isValueInvalid || typeof columnValue != 'number') {
@@ -290,18 +370,24 @@ export class LocalTableDataRepository extends TableDataRepository {
             case StringFilterMode.In:
             case StringFilterMode.NotIn:
             case StringFilterMode.Empty:
-            case StringFilterMode.null:
+                // StringFilterMode.null shares its value ('__null=') with NumberDateFilterMode.null
+                // and is handled by the early-return above; we do not list it here because the
+                // frozen-const filter mode types collapse to identical string literals.
                 throw new Error('Using string filter mode in a number filter column');
         }
         //default
         return !!values[0] && columnValue.toString().includes(values[0].toString());
     };
+    /**
+     * 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.
+     */
     selectFilter = async (row, columnId, // & keyof T,
     filterValue) => {
         if (!filterValue) {
             return true;
         }
-        void filterValue;
         const columnValue = (await row.getValue(columnId));
         if (Array.isArray(filterValue)) {
             return filterValue.find((it) => it === columnValue) != null;
@@ -314,11 +400,30 @@ export class LocalTableDataRepository extends TableDataRepository {
         }
         return filterValue == columnValue;
     };
+    /**
+     * 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.
+     */
     boolFilter = async (row, columnId, // & keyof T,
     filterValue) => {
-        const columnValue = (await row.getValue(columnId));
+        const columnValue = await row.getValue(columnId);
+        if (typeof columnValue !== 'boolean') {
+            if (dev && columnValue != null) {
+                console.warn(`boolFilter: column ${columnId} value was not a boolean`, columnValue);
+            }
+            return filterValue == null;
+        }
         return filterValue == null || filterValue === columnValue;
     };
+    /**
+     * 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).
+     */
     stringFilter = async (row, columnId, // & keyof T,
     filterValue) => {
         const filterType = this.filterModes.get(columnId) ?? StringFilterMode.Contains;

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

@@ -1,5 +1,17 @@
+/**
+ * One sort instruction. `id` is the column id and `desc` is `true` for
+ * descending, `false` for ascending. `id` is a bare `string` rather than
+ * `string & keyof T` because column-preset deserialisation cannot statically
+ * know the row type; tightening is deferred (workorder
+ * Types-DataRepository-interfaces finding 4).
+ */
 export interface ColumnSort {
     desc: boolean;
     id: string;
 }
+/**
+ * Ordered list of column sorts. Earlier entries win when
+ * `enableMultiSort` is on. An empty array means the data is in its natural
+ * (repository-supplied) order.
+ */
 export type SortingState = Array<ColumnSort>;

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

@@ -3,21 +3,50 @@ import type { ColumnFiltersState } from '../Filtering/ColumnFiltersState.js';
 import type { FilterMode } from '../Filtering/FilterMode.js';
 import type { FilterType } from '../Filtering/FilterType.js';
 import type { PaginationState } from '../Pagination/PaginationState.js';
+import { PaginationType } from '../Pagination/PaginationType.js';
 import type { IDataRepository } from './IDataRepository.js';
 import type { SortingState } from './SortingState.js';
+/**
+ * Pagination state with the read-only contract enforced at the type
+ * level. Both fields are read-only because consumers should never mutate
+ * an existing pagination object - they must reassign the whole shape
+ * through the public setter so the previously viewed page is tracked.
+ */
 export interface ReadonlyPaginationState extends PaginationState {
     readonly pageIndex: number;
     readonly pageSize: number;
 }
+/**
+ * Abstract base for every data repository that backs a `TableContext`.
+ * Owns pagination state with localStorage write-through on `pageSize`,
+ * the reactive filter-mode map, the force-refresh hook, and shared
+ * static helpers for parsing comma-separated filter input.
+ *
+ * The `out FilterValueType` variance annotation is currently advisory:
+ * `filtering` reads the parameter (contravariant) but `__queryValues`
+ * does not currently use it. A proper variance audit is deferred to a
+ * future workorder; the existing annotation does not break type
+ * checking.
+ */
 export declare abstract class TableDataRepository<T extends object, out FilterValueType> implements IDataRepository<T> {
     private tableName;
     protected getUserId: () => string | undefined;
-    abstract paginationType: 'Remote' | 'Local';
+    /**
+     * Discriminator used by `TableContext` to route pagination control
+     * flow. Subclasses must declare a concrete value drawn from
+     * `PaginationType` (currently `Local` or `Remote`).
+     */
+    abstract paginationType: typeof PaginationType.Local | typeof PaginationType.Remote;
     abstract filterType: FilterType;
     abstract totalRows: number;
     abstract isLoading: boolean;
     abstract data: Array<T>;
-    abstract setPageSize: (size: number) => void;
+    /**
+     * Subclasses widen the parameter to `number | string` so a raw input
+     * value coming from a `<select>` element can be parsed inline. The
+     * abstract signature mirrors that broader contract.
+     */
+    abstract setPageSize: (size: number | string) => void;
     abstract filtering: ColumnFiltersState<FilterValueType>;
     abstract setFilterMode: (id: string, mode: FilterMode) => void;
     abstract filterBy: (id: string, value: unknown) => void;
@@ -29,20 +58,76 @@ export declare abstract class TableDataRepository<T extends object, out FilterVa
     abstract pageStartIndex: number;
     abstract pageEndIndexExclusive: number;
     constructor(tableName: string, getUserId: () => string | undefined);
+    /**
+     * Reactive bag of consumer-defined query values keyed by column id.
+     * Stored as `unknown` because the shape depends on the column type;
+     * narrowing to `FilterValueType` is deferred (would force consumers
+     * to choose a single value type at construction time, which is too
+     * restrictive for tables mixing several filter modes).
+     */
     __queryValues: SvelteMap<string, unknown>;
     private _paginationState;
+    /** Current page index plus the configured page size. */
     get paginationState(): ReadonlyPaginationState;
+    /**
+     * Replaces pagination state and writes the new `pageSize` through to
+     * localStorage. Idempotent: identical states are dropped so the
+     * previously-viewed-page tracker does not lose its value when the
+     * same state is reassigned (e.g. from a `$derived` re-evaluation).
+     */
     set paginationState(v: ReadonlyPaginationState);
     private _previouslyViewedPage;
+    /**
+     * The page index that was current immediately before the most recent
+     * `paginationState` assignment. Used by `Table.svelte` to decide
+     * whether to scroll-reset on remote-load.
+     */
     get previouslyViewedPage(): number;
     private set previouslyViewedPage(value);
     protected _filterModes: SvelteMap<string, FilterMode>;
+    /** Per-column filter mode (e.g. `Equals`, `Contains`). */
     get filterModes(): SvelteMap<string, FilterMode>;
     private _forceRefresh;
+    /**
+     * Returns the currently-registered force-refresh callback. Until a
+     * consumer registers a callback via `registerRefreshMethod` the
+     * returned function logs a console warning and otherwise does
+     * nothing.
+     */
     get forceRefresh(): () => void;
+    /**
+     * Replaces the force-refresh callback. Also invokes the new callback
+     * immediately so callers wiring up a remote repo can request a fresh
+     * payload as a single assignment.
+     *
+     * The implicit invocation on set is a known footgun (TableDataRepository
+     * P1 finding): a future workorder will introduce a dedicated
+     * `triggerRefresh()` method and remove the side effect from the
+     * setter. Behaviour preserved here to avoid breaking existing
+     * consumers.
+     */
     set forceRefresh(v: () => void);
+    /**
+     * Registers a refresh callback without invoking it. Preferred over
+     * the `forceRefresh` setter when the caller does not want the
+     * implicit immediate refresh.
+     */
     readonly registerRefreshMethod: (method: () => void) => void;
+    /**
+     * Parses a comma-separated filter value list into a reactive set of
+     * finite numbers, dropping non-numeric entries.
+     */
     protected getValueSet(values: Array<string | number | undefined>): SvelteSet<number>;
+    /**
+     * Splits a comma-separated filter input into a numeric array,
+     * dropping `NaN` entries. Static so it can be reused inside filter
+     * functions without an instance reference.
+     */
     static getValues(values: Array<string | number | null | undefined>): Array<number>;
+    /**
+     * Parses up to two filter-input values into a `[min, max]` tuple,
+     * coalescing missing or non-numeric `max` to `min` so a single-input
+     * filter still compares against a useful upper bound.
+     */
     static getMinMax(values: Array<string | number | null | undefined>): number[] | undefined[];
 }

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

@@ -1,5 +1,18 @@
 import { browser } from '$app/environment';
 import { SvelteMap, SvelteSet } from 'svelte/reactivity';
+import { PaginationType } from '../Pagination/PaginationType.js';
+/**
+ * Abstract base for every data repository that backs a `TableContext`.
+ * Owns pagination state with localStorage write-through on `pageSize`,
+ * the reactive filter-mode map, the force-refresh hook, and shared
+ * static helpers for parsing comma-separated filter input.
+ *
+ * The `out FilterValueType` variance annotation is currently advisory:
+ * `filtering` reads the parameter (contravariant) but `__queryValues`
+ * does not currently use it. A proper variance audit is deferred to a
+ * future workorder; the existing annotation does not break type
+ * checking.
+ */
 export class TableDataRepository {
     tableName;
     getUserId;
@@ -7,22 +20,45 @@ export class TableDataRepository {
         this.tableName = tableName;
         this.getUserId = getUserId;
     }
+    /**
+     * Reactive bag of consumer-defined query values keyed by column id.
+     * Stored as `unknown` because the shape depends on the column type;
+     * narrowing to `FilterValueType` is deferred (would force consumers
+     * to choose a single value type at construction time, which is too
+     * restrictive for tables mixing several filter modes).
+     */
     __queryValues = new SvelteMap();
     _paginationState = $state({
         pageIndex: 0,
         pageSize: 20,
     });
+    /** Current page index plus the configured page size. */
     get paginationState() {
         return this._paginationState;
     }
+    /**
+     * Replaces pagination state and writes the new `pageSize` through to
+     * localStorage. Idempotent: identical states are dropped so the
+     * previously-viewed-page tracker does not lose its value when the
+     * same state is reassigned (e.g. from a `$derived` re-evaluation).
+     */
     set paginationState(v) {
+        if (v.pageIndex === this._paginationState.pageIndex &&
+            v.pageSize === this._paginationState.pageSize) {
+            return;
+        }
         this._previouslyViewedPage = this._paginationState.pageIndex;
         this._paginationState = v;
         if (browser) {
-            localStorage.setItem(`${this.getUserId()}-${this.tableName}-page-size`, v.pageSize.toString());
+            localStorage.setItem(`scoria-table:${this.getUserId() ?? 'anon'}:${this.tableName}:page-size`, v.pageSize.toString());
         }
     }
     _previouslyViewedPage = $state(0);
+    /**
+     * The page index that was current immediately before the most recent
+     * `paginationState` assignment. Used by `Table.svelte` to decide
+     * whether to scroll-reset on remote-load.
+     */
     get previouslyViewedPage() {
         return this._previouslyViewedPage;
     }
@@ -30,25 +66,57 @@ export class TableDataRepository {
         this._previouslyViewedPage = v;
     }
     _filterModes = $state(new SvelteMap());
+    /** Per-column filter mode (e.g. `Equals`, `Contains`). */
     get filterModes() {
         return this._filterModes;
     }
     _forceRefresh = $state(() => {
         console.warn('tried to force refresh without a callback registered');
     });
+    /**
+     * Returns the currently-registered force-refresh callback. Until a
+     * consumer registers a callback via `registerRefreshMethod` the
+     * returned function logs a console warning and otherwise does
+     * nothing.
+     */
     get forceRefresh() {
         return this._forceRefresh;
     }
+    /**
+     * Replaces the force-refresh callback. Also invokes the new callback
+     * immediately so callers wiring up a remote repo can request a fresh
+     * payload as a single assignment.
+     *
+     * The implicit invocation on set is a known footgun (TableDataRepository
+     * P1 finding): a future workorder will introduce a dedicated
+     * `triggerRefresh()` method and remove the side effect from the
+     * setter. Behaviour preserved here to avoid breaking existing
+     * consumers.
+     */
     set forceRefresh(v) {
         this._forceRefresh = v;
         this._forceRefresh();
     }
+    /**
+     * Registers a refresh callback without invoking it. Preferred over
+     * the `forceRefresh` setter when the caller does not want the
+     * implicit immediate refresh.
+     */
     registerRefreshMethod = (method) => {
         this._forceRefresh = method;
     };
+    /**
+     * Parses a comma-separated filter value list into a reactive set of
+     * finite numbers, dropping non-numeric entries.
+     */
     getValueSet(values) {
         return new SvelteSet(TableDataRepository.getValues(values));
     }
+    /**
+     * Splits a comma-separated filter input into a numeric array,
+     * dropping `NaN` entries. Static so it can be reused inside filter
+     * functions without an instance reference.
+     */
     static getValues(values) {
         return values
             .toString()
@@ -58,6 +126,11 @@ export class TableDataRepository {
         })
             .filter((it) => !isNaN(it));
     }
+    /**
+     * Parses up to two filter-input values into a `[min, max]` tuple,
+     * coalescing missing or non-numeric `max` to `min` so a single-input
+     * filter still compares against a useful upper bound.
+     */
     static getMinMax(values) {
         let [min, max] = values;
         if (typeof min === 'string') {

package/dist/Components/Table/Types/ExpandedPanel.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Discriminator on the currently-visible toolbar sidebar panel:
+ *
+ * - `None`    - no panel open (currently the `null` state is preferred in
+ *   `TableSidebar.svelte`; `None` is kept for symmetry but unused).
+ * - `Column`  - column-picker panel.
+ * - `Filter`  - advanced filter panel.
+ * - `Toolbox` - settings / toolbox panel.
+ */
 export declare const ExpandedPanel: {
     readonly None: "None";
     readonly Column: "Column";

package/dist/Components/Table/Types/ExpandedPanel.js

@@ -1,7 +1,16 @@
+/**
+ * Discriminator on the currently-visible toolbar sidebar panel:
+ *
+ * - `None`    - no panel open (currently the `null` state is preferred in
+ *   `TableSidebar.svelte`; `None` is kept for symmetry but unused).
+ * - `Column`  - column-picker panel.
+ * - `Filter`  - advanced filter panel.
+ * - `Toolbox` - settings / toolbox panel.
+ */
 export const ExpandedPanel = {
     None: 'None',
     Column: 'Column',
     Filter: 'Filter',
-    Toolbox: 'Toolbox'
+    Toolbox: 'Toolbox',
 };
 Object.freeze(ExpandedPanel);

package/dist/Components/Table/Types/Filtering/ColumnFiltersState.d.ts

@@ -1,5 +1,22 @@
+/**
+ * One filter entry: the column id (`string`, not narrowed to `keyof T` here
+ * because the state is heterogeneous across columns) plus the current filter
+ * value. The value's concrete shape depends on the column's
+ * `filterValueType` (see `FilterValueType`); the type parameter `T` here is
+ * the value-side, not the row-side, and defaults to `unknown` for the
+ * `ColumnFiltersState` aggregate.
+ *
+ * Tightening to a discriminated union (`{ kind: 'String'; value: string }
+ * | { kind: 'Number'; value: NumberFilterValueType } | ...`) is deferred to
+ * the `ColumnFilter` workorder.
+ */
 export interface ColumnFilter<T> {
     id: string;
     value: T;
 }
+/**
+ * Heterogeneous list of filter entries. Default `T = unknown` reflects the
+ * fact that the per-entry filter value type cannot be statically known once
+ * the entries are mixed.
+ */
 export type ColumnFiltersState<T = unknown> = Array<ColumnFilter<T>>;

package/dist/Components/Table/Types/Filtering/CustomFilter.d.ts

@@ -1,5 +1,26 @@
 import type { SelectOption } from '../../../../Types/Internal/SelectOption.js';
 import type { CustomFilterType } from './CustomFilterType.js';
+/**
+ * Description of a consumer-supplied "custom" filter, surfaced in the filter
+ * panel alongside the per-column filter inputs. Used to let remote tables
+ * register filters that are not tied to a single column (e.g. a
+ * facility-wide status filter).
+ *
+ * - `queryKey` is the URL parameter / GraphQL variable name the filter binds
+ *   to on the remote side.
+ * - `type` selects the input control (`String`, `Number`, `Select`, `Date`).
+ * - `id` is a stable identifier used as a map key in `CustomRemoteFilters`.
+ * - `options` is the static option set for `Select` filters; pass a Promise
+ *   to load them async.
+ * - `query` is the dynamic option fetcher for `Select` filters whose options
+ *   are searchable. The `value` argument is the user-entered search string
+ *   from the filter input.
+ *
+ * Security note: `query.value` is untrusted user input. Implementers
+ * forwarding it to a backend MUST escape / parameterise it; the type
+ * signature is intentionally `unknown` for backwards compatibility but the
+ * runtime value is the user's keystrokes from the search box.
+ */
 export interface CustomFilter<FilterValueType> {
     queryKey: string;
     type: CustomFilterType;

package/dist/Components/Table/Types/Filtering/CustomFilterType.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Input-type discriminator for a `CustomFilter`. Selects which control the
+ * filter panel renders for the custom filter (string field, number field,
+ * select dropdown, date picker).
+ */
 export declare const CustomFilterType: {
     readonly String: "String";
     readonly Number: "Number";

package/dist/Components/Table/Types/Filtering/CustomFilterType.js

@@ -1,7 +1,12 @@
+/**
+ * Input-type discriminator for a `CustomFilter`. Selects which control the
+ * filter panel renders for the custom filter (string field, number field,
+ * select dropdown, date picker).
+ */
 export const CustomFilterType = {
     String: 'String',
     Number: 'Number',
     Select: 'Select',
-    Date: 'Date'
+    Date: 'Date',
 };
 Object.freeze(CustomFilterType);