@lavalogic/scoria 0.37.44 → 0.37.45

package/dist/Components/Table/Types/Context/VirtualisationState.svelte.d.ts

@@ -1,76 +1,63 @@
 import type { Row } from './Row.js';
 /**
  * Dependency surface that `VirtualisationState` reads from the
- * surrounding `TableContext`. Every dependency is passed as a thunk so
- * the sub-context never holds a direct reference to the parent;
- * reactivity threads through `$derived` exactly as it does for the
- * other Phase 6 sub-contexts.
+ * surrounding `TableContext`. Each dependency is a thunk so the
+ * sub-context never holds a direct reference to the parent; reactivity
+ * threads through `$derived`.
  */
 export interface VirtualisationStateDeps<T extends object> {
-    /** The full, ordered list of rows currently in scope (the
-     *  `paginationRowModel.rows` array from `TableContext`). */
+    /** Full, ordered row list currently in scope
+     *  (`paginationRowModel.rows` from `TableContext`). */
     getRows: () => ReadonlyArray<Row<T>>;
-    /** Per-row height lookup. The implementation reads from the
-     *  `_columnLayout` row-height pool (Phase 7.1 Item B) - whichever
-     *  side has the tallest registered height for the row. Returning
-     *  `undefined` (or 0) means "no observation yet" and the
-     *  estimated-row-height fallback is used. */
+    /** Per-row height lookup. Reads the largest observed height across
+     *  sides from the `_columnLayout` row-height pool. Returning
+     *  `undefined` or 0 means "not observed yet" and the estimated
+     *  row-height fallback is used. */
     getRowHeight: (rowId: string) => number | undefined;
-    /** Estimated row height used when no observed height is available
-     *  yet for a row. Defaults to 48 (the CSS `--height: 3rem` baseline).
-     *  Compact tables (`isCompact = true`) pass a smaller estimate via
-     *  this thunk so the totalHeight is in the right ballpark before
-     *  any row has been observed. */
+    /** Estimated row height when no observation is available yet.
+     *  Defaults to 48 (the `--height: 3rem` baseline); compact tables
+     *  pass a smaller estimate so `totalHeight` is in the right
+     *  ballpark before any row is observed. */
     getEstimatedRowHeight: () => number;
 }
 /**
- * Phase 7.4 row virtualisation. When the current row count exceeds
- * `_virtualisationThreshold` (default 100) only the rows currently in
- * the viewport (plus a small overscan band above and below) are
- * rendered; the rest of the body height is reserved by two spacer
- * `<tr>` rows in `TableBody.svelte`. Below the threshold every row is
- * rendered directly, matching the legacy behaviour.
+ * Row virtualisation. When the row count exceeds
+ * `_virtualisationThreshold` (default 100), only viewport rows plus a
+ * small overscan band above and below are rendered; the remaining body
+ * height is reserved by two spacer `<tr>` rows in `TableBody.svelte`.
+ * Below threshold every row is rendered directly.
  *
- * The state is a sibling to `_columnLayout`, `_filtering`, `_sorting`,
- * etc. Three reasons it lives in its own sub-context rather than on
- * `_columnLayout`:
- *
- *   - the threshold + overscan + scroll position are virtualisation-
- *     specific concerns the column-layout code does not need;
- *   - the heights map on `_columnLayout` is keyed by `(side, rowId)`
- *     while virtualisation only ever wants the max across sides
- *     (which determines the row's slot height);
+ * Owns its own sub-context (rather than living on `_columnLayout`)
+ * because:
+ *   - threshold + overscan + scroll position are virtualisation-only;
+ *   - `_columnLayout`'s height map is keyed by `(side, rowId)` whereas
+ *     virtualisation needs the max across sides (the row's slot height);
  *   - the `visibleRange` / `visibleRows` derived chain is read by all
- *     three `TableBody` instances; keeping it on its own state object
- *     means `_columnLayout` does not become a god-object again.
+ *     three `TableBody` instances and keeping it separate avoids growing
+ *     `_columnLayout` into a god-object.
  *
- * Scroll synchronisation: the three side `<table>` elements sit inside
- * the same `.datatable` overflow container (see `Table.svelte`), so
- * vertical scrolling is already shared. Only ONE scroll listener is
- * needed - it is attached in `Table.svelte` on the outer
- * `.datatable` element and reports both `scrollTop` and
- * `clientHeight` via `registerScrollPosition`.
+ * Scroll synchronisation: the three side `<table>` elements share the
+ * same `.datatable` overflow container, so vertical scrolling is
+ * already shared. ONE scroll listener (attached in `Table.svelte` on
+ * the outer `.datatable`) reports `scrollTop` and `clientHeight` via
+ * `registerScrollPosition`.
  *
- * Stability across sort / filter / pagination: rows are keyed by
- * `row.id` (the visible index as a string assigned by
+ * Keying: rows are keyed by `row.id` (the visible index assigned by
  * `paginationRowModel`), so `{#each visibleRows as { row } (row.id)}`
- * remains the keying surface and Svelte's diffing stays unchanged.
- * The `_selection._keyCache` (Phase 6.5) is keyed by `row.original`,
- * not by index or `row.id`, so virtualisation is transparent to it.
+ * keeps Svelte's diffing intact. `_selection._keyCache` is keyed by
+ * `row.original`, so virtualisation is transparent to it.
  */
 export declare class VirtualisationState<T extends object> {
     private readonly _deps;
     private readonly _virtualisationThreshold;
     private readonly _overscan;
     /** Latest scroll position reported by the host. 0 by default so the
-     *  first paint (before any scroll event) shows the top of the
-     *  list. */
+     *  first paint (before any scroll event) shows the top of the list. */
     private _scrollTop;
-    /** Latest viewport height reported by the host. The fallback of
-     *  600 is chosen so that virtualisation has SOMETHING to clip
-     *  against before the first measurement - the overscan band keeps
-     *  the initial paint reasonable even if the real height is
-     *  smaller. */
+    /** Latest viewport height reported by the host. 600 is a sensible
+     *  pre-measurement fallback so virtualisation has something to clip
+     *  against; overscan keeps the initial paint reasonable when the
+     *  real height is smaller. */
     private _viewportHeight;
     constructor(deps: VirtualisationStateDeps<T>, options?: {
         threshold?: number;
@@ -81,11 +68,11 @@ export declare class VirtualisationState<T extends object> {
     get scrollTop(): number;
     get viewportHeight(): number;
     /**
-     * Returns true when the current row count is above the
-     * virtualisation threshold. Below threshold the public API still
-     * works (visibleRows returns every row, padding spacers are 0),
-     * but consumers can short-circuit DOM work that is only needed in
-     * the virtualised path by reading this flag.
+     * True when the current row count is above the virtualisation
+     * threshold. Below threshold the public API still works
+     * (`visibleRows` returns every row, padding spacers are 0), but
+     * consumers can short-circuit virtualisation-only DOM work by
+     * reading this flag.
      */
     readonly isVirtualised: boolean;
     /**
@@ -96,26 +83,23 @@ export declare class VirtualisationState<T extends object> {
      */
     private _resolveHeight;
     /**
-     * Sum of all row heights. This is the height the body container
-     * must reserve so the scrollbar matches the un-virtualised height.
+     * Sum of all row heights. The body container reserves this height
+     * so the scrollbar matches the un-virtualised height.
      *
-     * Below threshold the value is still correct (sum of all observed
-     * row heights or fallbacks), but consumers should generally not
-     * apply it as `min-height` to the body container when below
-     * threshold - the natural row flow does the right thing.
+     * Below threshold the value is still correct, but consumers should
+     * generally not apply it as `min-height` - the natural row flow is
+     * fine and forcing the min-height fights against zero-row layout.
      */
     readonly totalHeight: number;
     /**
-     * Half-open `[start, end)` row-index range that should be rendered
-     * in the DOM. Below the virtualisation threshold this is the full
-     * `[0, rows.length)`. Above threshold it is the slice covering the
-     * viewport (scrollTop -> scrollTop + viewportHeight) widened by
-     * `_overscan` rows above and below.
+     * Half-open `[start, end)` row-index range to render. Below threshold
+     * this is the full `[0, rows.length)`. Above threshold it is the
+     * slice covering `[scrollTop, scrollTop + viewportHeight]` widened
+     * by `_overscan` rows on each side.
      *
-     * The walk over row heights is O(N) per re-derive but only fires
-     * when `_scrollTop`, `_viewportHeight`, the rows array, or any
-     * relevant row height changes; for N <= a few thousand this is
-     * well under a millisecond.
+     * The O(N) walk re-runs only when `_scrollTop`, `_viewportHeight`,
+     * the rows array, or a relevant row height changes; well under a
+     * millisecond for N up to a few thousand.
      */
     readonly visibleRange: {
         start: number;
@@ -153,15 +137,14 @@ export declare class VirtualisationState<T extends object> {
      */
     readonly bottomSpacerHeight: number;
     /**
-     * Reports the current scroll position and viewport height. Called
-     * by `Table.svelte` from a single scroll listener on the outer
-     * `.datatable` container; the three side TableBody instances all
-     * read the resulting `visibleRows` so they stay in sync without
-     * extra plumbing.
+     * Report the current scroll position and viewport height. Called by
+     * `Table.svelte` from a single scroll listener on the outer
+     * `.datatable` container; the three side TableBody instances read
+     * the resulting `visibleRows` and stay in sync.
      *
-     * The setter early-exits when neither value changed so identical
-     * back-to-back scroll events (common on macOS rubber-band) do not
-     * retrigger the derived chain.
+     * Early-exits when neither value changed so identical back-to-back
+     * scroll events (common on macOS rubber-band) do not re-trigger the
+     * derived chain.
      */
     readonly registerScrollPosition: (scrollTop: number, viewportHeight: number) => void;
 }

package/dist/Components/Table/Types/Context/VirtualisationState.svelte.js

@@ -1,65 +1,50 @@
 /**
- * Phase 7.4 row virtualisation. When the current row count exceeds
- * `_virtualisationThreshold` (default 100) only the rows currently in
- * the viewport (plus a small overscan band above and below) are
- * rendered; the rest of the body height is reserved by two spacer
- * `<tr>` rows in `TableBody.svelte`. Below the threshold every row is
- * rendered directly, matching the legacy behaviour.
+ * Row virtualisation. When the row count exceeds
+ * `_virtualisationThreshold` (default 100), only viewport rows plus a
+ * small overscan band above and below are rendered; the remaining body
+ * height is reserved by two spacer `<tr>` rows in `TableBody.svelte`.
+ * Below threshold every row is rendered directly.
  *
- * The state is a sibling to `_columnLayout`, `_filtering`, `_sorting`,
- * etc. Three reasons it lives in its own sub-context rather than on
- * `_columnLayout`:
- *
- *   - the threshold + overscan + scroll position are virtualisation-
- *     specific concerns the column-layout code does not need;
- *   - the heights map on `_columnLayout` is keyed by `(side, rowId)`
- *     while virtualisation only ever wants the max across sides
- *     (which determines the row's slot height);
+ * Owns its own sub-context (rather than living on `_columnLayout`)
+ * because:
+ *   - threshold + overscan + scroll position are virtualisation-only;
+ *   - `_columnLayout`'s height map is keyed by `(side, rowId)` whereas
+ *     virtualisation needs the max across sides (the row's slot height);
  *   - the `visibleRange` / `visibleRows` derived chain is read by all
- *     three `TableBody` instances; keeping it on its own state object
- *     means `_columnLayout` does not become a god-object again.
+ *     three `TableBody` instances and keeping it separate avoids growing
+ *     `_columnLayout` into a god-object.
  *
- * Scroll synchronisation: the three side `<table>` elements sit inside
- * the same `.datatable` overflow container (see `Table.svelte`), so
- * vertical scrolling is already shared. Only ONE scroll listener is
- * needed - it is attached in `Table.svelte` on the outer
- * `.datatable` element and reports both `scrollTop` and
- * `clientHeight` via `registerScrollPosition`.
+ * Scroll synchronisation: the three side `<table>` elements share the
+ * same `.datatable` overflow container, so vertical scrolling is
+ * already shared. ONE scroll listener (attached in `Table.svelte` on
+ * the outer `.datatable`) reports `scrollTop` and `clientHeight` via
+ * `registerScrollPosition`.
  *
- * Stability across sort / filter / pagination: rows are keyed by
- * `row.id` (the visible index as a string assigned by
+ * Keying: rows are keyed by `row.id` (the visible index assigned by
  * `paginationRowModel`), so `{#each visibleRows as { row } (row.id)}`
- * remains the keying surface and Svelte's diffing stays unchanged.
- * The `_selection._keyCache` (Phase 6.5) is keyed by `row.original`,
- * not by index or `row.id`, so virtualisation is transparent to it.
+ * keeps Svelte's diffing intact. `_selection._keyCache` is keyed by
+ * `row.original`, so virtualisation is transparent to it.
  */
 export class VirtualisationState {
     _deps;
     _virtualisationThreshold;
     _overscan;
     /** Latest scroll position reported by the host. 0 by default so the
-     *  first paint (before any scroll event) shows the top of the
-     *  list. */
+     *  first paint (before any scroll event) shows the top of the list. */
     _scrollTop = $state(0);
-    /** Latest viewport height reported by the host. The fallback of
-     *  600 is chosen so that virtualisation has SOMETHING to clip
-     *  against before the first measurement - the overscan band keeps
-     *  the initial paint reasonable even if the real height is
-     *  smaller. */
+    /** Latest viewport height reported by the host. 600 is a sensible
+     *  pre-measurement fallback so virtualisation has something to clip
+     *  against; overscan keeps the initial paint reasonable when the
+     *  real height is smaller. */
     _viewportHeight = $state(600);
     constructor(deps, options = {}) {
         this._deps = deps;
         this._virtualisationThreshold = options.threshold ?? 100;
-        // Overscan controls how many rows above/below the viewport are
-        // kept rendered so a fast wheel-scroll does not surface an empty
-        // grey band before the next paint. The previous default of 10
-        // was too tight on tables with hundreds of rows: a single wheel
-        // flick easily moves the viewport past the overscan band before
-        // the `$derived` chain reschedules and re-renders the visible
-        // slice. 30 rows is enough to absorb a typical wheel flick at
-        // 60Hz while still keeping the rendered cell count bounded
-        // (~52 rows for a 600px viewport at the default 28-48px row
-        // height: 12 visible + 30 below + 10 above = 52).
+        // Overscan rows above and below the viewport stay rendered so a
+        // fast wheel-scroll does not surface an empty grey band before
+        // the next paint. 30 rows is enough to absorb a typical 60Hz
+        // wheel flick while keeping the rendered cell count bounded
+        // (~52 rows for a 600px viewport at default row heights).
         this._overscan = options.overscan ?? 30;
     }
     get virtualisationThreshold() {
@@ -75,11 +60,11 @@ export class VirtualisationState {
         return this._viewportHeight;
     }
     /**
-     * Returns true when the current row count is above the
-     * virtualisation threshold. Below threshold the public API still
-     * works (visibleRows returns every row, padding spacers are 0),
-     * but consumers can short-circuit DOM work that is only needed in
-     * the virtualised path by reading this flag.
+     * True when the current row count is above the virtualisation
+     * threshold. Below threshold the public API still works
+     * (`visibleRows` returns every row, padding spacers are 0), but
+     * consumers can short-circuit virtualisation-only DOM work by
+     * reading this flag.
      */
     isVirtualised = $derived.by(() => this._deps.getRows().length > this._virtualisationThreshold);
     /**
@@ -96,13 +81,12 @@ export class VirtualisationState {
         return this._deps.getEstimatedRowHeight();
     }
     /**
-     * Sum of all row heights. This is the height the body container
-     * must reserve so the scrollbar matches the un-virtualised height.
+     * Sum of all row heights. The body container reserves this height
+     * so the scrollbar matches the un-virtualised height.
      *
-     * Below threshold the value is still correct (sum of all observed
-     * row heights or fallbacks), but consumers should generally not
-     * apply it as `min-height` to the body container when below
-     * threshold - the natural row flow does the right thing.
+     * Below threshold the value is still correct, but consumers should
+     * generally not apply it as `min-height` - the natural row flow is
+     * fine and forcing the min-height fights against zero-row layout.
      */
     totalHeight = $derived.by(() => {
         const rows = this._deps.getRows();
@@ -113,16 +97,14 @@ export class VirtualisationState {
         return total;
     });
     /**
-     * Half-open `[start, end)` row-index range that should be rendered
-     * in the DOM. Below the virtualisation threshold this is the full
-     * `[0, rows.length)`. Above threshold it is the slice covering the
-     * viewport (scrollTop -> scrollTop + viewportHeight) widened by
-     * `_overscan` rows above and below.
+     * Half-open `[start, end)` row-index range to render. Below threshold
+     * this is the full `[0, rows.length)`. Above threshold it is the
+     * slice covering `[scrollTop, scrollTop + viewportHeight]` widened
+     * by `_overscan` rows on each side.
      *
-     * The walk over row heights is O(N) per re-derive but only fires
-     * when `_scrollTop`, `_viewportHeight`, the rows array, or any
-     * relevant row height changes; for N <= a few thousand this is
-     * well under a millisecond.
+     * The O(N) walk re-runs only when `_scrollTop`, `_viewportHeight`,
+     * the rows array, or a relevant row height changes; well under a
+     * millisecond for N up to a few thousand.
      */
     visibleRange = $derived.by(() => {
         const rows = this._deps.getRows();
@@ -216,15 +198,14 @@ export class VirtualisationState {
         return total;
     });
     /**
-     * Reports the current scroll position and viewport height. Called
-     * by `Table.svelte` from a single scroll listener on the outer
-     * `.datatable` container; the three side TableBody instances all
-     * read the resulting `visibleRows` so they stay in sync without
-     * extra plumbing.
+     * Report the current scroll position and viewport height. Called by
+     * `Table.svelte` from a single scroll listener on the outer
+     * `.datatable` container; the three side TableBody instances read
+     * the resulting `visibleRows` and stay in sync.
      *
-     * The setter early-exits when neither value changed so identical
-     * back-to-back scroll events (common on macOS rubber-band) do not
-     * retrigger the derived chain.
+     * Early-exits when neither value changed so identical back-to-back
+     * scroll events (common on macOS rubber-band) do not re-trigger the
+     * derived chain.
      */
     registerScrollPosition = (scrollTop, viewportHeight) => {
         if (scrollTop === this._scrollTop && viewportHeight === this._viewportHeight) {

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

@@ -1,36 +1,25 @@
 /**
- * Built-in remote data repository used by `createTable({ rows: { kind: 'remote' } })`.
+ * Built-in remote data repository used by
+ * `createTable({ rows: { kind: 'remote' } })`. Owns URL construction,
+ * filter encoding, pagination, sort, debouncing, and page-size
+ * persistence so consumers do not have to reimplement them.
  *
- * 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'`, producing
+ * `?filter[<id>]=<value>&page=<n>&pageSize=<m>&sort=<col>&direction=<asc|desc>`.
+ * Pass a custom `filterEncoding: { encode }` for backends that expect a
+ * different shape, or drop to `kind: 'custom'` for full control.
  *
- * 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.
+ * Extends `TableDataRepository` for pagination / 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.
+ * The default encoder emits raw `?filter[<id>]=<JSON-encoded-value>` and
+ * does NOT cover rich filter modes (`StringFilterMode.NotIn`, `[min,max]`
+ * range tuples, etc.); pass a custom encoder if the backend needs them.
+ * The five local-only filter callbacks (`dateFilter` / `numberFilter` /
+ * etc.) are inherited as optional and left undefined here.
  */
 import type { ColumnFiltersState } from '../Filtering/ColumnFiltersState.js';
 import type { FilterMode } from '../Filtering/FilterMode.js';

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

@@ -1,36 +1,25 @@
 /**
- * Built-in remote data repository used by `createTable({ rows: { kind: 'remote' } })`.
+ * Built-in remote data repository used by
+ * `createTable({ rows: { kind: 'remote' } })`. Owns URL construction,
+ * filter encoding, pagination, sort, debouncing, and page-size
+ * persistence so consumers do not have to reimplement them.
  *
- * 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'`, producing
+ * `?filter[<id>]=<value>&page=<n>&pageSize=<m>&sort=<col>&direction=<asc|desc>`.
+ * Pass a custom `filterEncoding: { encode }` for backends that expect a
+ * different shape, or drop to `kind: 'custom'` for full control.
  *
- * 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.
+ * Extends `TableDataRepository` for pagination / 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.
+ * The default encoder emits raw `?filter[<id>]=<JSON-encoded-value>` and
+ * does NOT cover rich filter modes (`StringFilterMode.NotIn`, `[min,max]`
+ * range tuples, etc.); pass a custom encoder if the backend needs them.
+ * The five local-only filter callbacks (`dateFilter` / `numberFilter` /
+ * etc.) are inherited as optional and left undefined here.
  */
 import { browser } from '$app/environment';
 import { devCatch } from '../../../../Helpers/Helpers.svelte.js';

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

@@ -10,23 +10,21 @@ 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.
+ * and `paginationRepo` via this contract; reactivity is exposed through
+ * the underlying `$state`-backed properties on the implementation.
  *
- * Implementers are responsible for:
+ * Implementers must guarantee:
  *
  * - 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`.
+ *   `pageEndIndexExclusive`, and `paginationState` must describe the same
+ *   logical page when read together.
+ * - Filter safety (remote): `filterBy` accepts `unknown`; remote
+ *   implementations MUST escape values before forwarding to a backend
+ *   (URL encoding, parameterised SQL, etc.). scoria does not enforce
+ *   this and no validation happens server-side on its behalf.
+ * - LSP: concrete repositories widen `setPageSize` to
+ *   `(size: number | string) => void` so they can accept raw `<select>`
+ *   values; callers holding the base interface should pass `number`.
  */
 export interface IDataRepository<T extends object> {
     paginationState: PaginationState;
@@ -52,7 +50,6 @@ export interface IDataRepository<T extends object> {
     pageStartIndex: number;
     pageEndIndexExclusive: number;
     previouslyViewedPage: number;
-    __queryValues: SvelteMap<string, unknown>;
     readonly paginationType: PaginationType;
     filterType: FilterType;
     data: Array<T>;

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

@@ -8,9 +8,9 @@ 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.
+ * level. Consumers reassign the whole shape through the public setter
+ * (rather than mutating fields) so the previously-viewed page is
+ * tracked.
  */
 export interface ReadonlyPaginationState extends PaginationState {
     readonly pageIndex: number;
@@ -21,12 +21,6 @@ export interface ReadonlyPaginationState extends PaginationState {
  * 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;
@@ -58,22 +52,14 @@ 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
+     * Replace pagination state and write 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).
+     * previously-viewed-page tracker keeps its value when the same state
+     * is reassigned (e.g. from a `$derived` re-evaluation).
      */
     set paginationState(v: ReadonlyPaginationState);
     private _previouslyViewedPage;
@@ -96,21 +82,20 @@ export declare abstract class TableDataRepository<T extends object, out FilterVa
      */
     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.
+     * @deprecated Assigning the setter both replaces the callback AND
+     * invokes it immediately, which is a footgun for callers wiring it up
+     * inside a constructor or `$effect.pre`. Use `registerRefreshMethod`
+     * to assign without the implicit invoke; call `repo.forceRefresh()`
+     * via the getter when an explicit refresh is wanted.
      *
-     * 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.
+     * Behaviour is preserved for backwards compatibility; the setter logs
+     * a dev-only warning so existing call sites surface in development.
      */
     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.
+     * the deprecated `forceRefresh` setter; call `repo.forceRefresh()`
+     * separately when an explicit refresh is wanted.
      */
     readonly registerRefreshMethod: (method: () => void) => void;
     /**