@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/Table/Types/Columns/Definitions/ColumnDefSet.d.ts

@@ -2,6 +2,15 @@ import type { SortingState } from '../../DataRepository/SortingState.js';
 import type { ColumnPinningState } from '../ColumnPinningState.js';
 import type { VisibilityState } from '../VisibilityState.js';
 import type { ColumnDef } from './ColumnDef.svelte.js';
+/**
+ * A named runtime preset: a snapshot of the column-defs array plus the
+ * sort / visibility / pinning state to apply when the preset is loaded.
+ * Used by the column-preset dropdown for save/load.
+ *
+ * The serialised mirror is `JSONColumnDefSet` (substitutes
+ * `JSONColumnPinningState` for `ColumnPinningState` and
+ * `Array<ColumnJSONRepresentation>` for `Array<ColumnDef<T>>`).
+ */
 export interface ColumnDefSet<T extends object> {
     name: string;
     sortingState: SortingState;

package/dist/Components/Table/Types/Columns/Definitions/Display/AbstractDisplayDef.svelte.d.ts

@@ -2,18 +2,58 @@ import type { Component } from 'svelte';
 import type { DisplayType } from '../../DisplayType.js';
 import type { TableCell } from '../../TableCell.js';
 import { ColumnDef, type ColumnDefProps } from '../ColumnDef.svelte.js';
+/**
+ * Props passed to the modal a display column may open.
+ *
+ * - `cell`: the source cell, used to read row context and the row value.
+ * - `onclose`: invoked when the user dismisses without committing.
+ * - `onsubmit`: invoked when the user commits.
+ *
+ * Note: neither callback carries a payload today (engineering F-secondary);
+ * callers persist any state through the cell's row reference.
+ */
 export interface DisplayDefModalProps<T extends object, in FilterValueType = never, out FilterOptionsType = unknown> {
+    /** The source cell. */
     cell: TableCell<T, FilterValueType, FilterOptionsType>;
+    /** Invoked on dismissal without commit. */
     onclose: () => void;
+    /** Invoked on commit. */
     onsubmit: () => void;
 }
+/**
+ * Construction-time props for every `AbstractDisplayDef` subclass.
+ *
+ * Note: `modal` is typed with `Component<any, any, any>` because the
+ * dynamic-dispatch site cannot statically know the consumer's full
+ * exports / events / slots triple. The narrowing is delegated to the
+ * caller via `DisplayDefModalProps`.
+ */
 export interface AbstractDisplayDefProps<T extends object, in FilterFnType, out FilterOptionsType> extends ColumnDefProps<T, FilterFnType, FilterOptionsType> {
+    /** Optional Svelte component opened as a modal from the cell. The
+     *  `any` triple is intentional: see class JSDoc. */
     modal?: Component<any, any, any>;
 }
+/**
+ * `AbstractDisplayDef<T, FilterValueType, FilterOptionsType>` is the
+ * shared base for display-only columns (Bubble, Display, ProgressBar,
+ * Validity). Each subclass pins `columnType = ColumnType.Display` and
+ * further narrows the `displayType` inner discriminator.
+ *
+ * @remarks
+ *
+ * `modal` is `Component<any, any, any>` rather than a narrower generic
+ * because the consumer-supplied modal component declares its own
+ * exports / events / slots and the cell dispatch site cannot statically
+ * know the full triple. Callers should accept `DisplayDefModalProps`
+ * as props and ignore the slot / event channels.
+ */
 export declare abstract class AbstractDisplayDef<T extends object, in FilterValueType = never, out FilterOptionsType = unknown> extends ColumnDef<T, FilterValueType, FilterOptionsType> {
+    /** Inner discriminator literal narrowed by each leaf subclass. */
     abstract readonly displayType: DisplayType;
     constructor(props: AbstractDisplayDefProps<T, FilterValueType, FilterOptionsType>);
+    /** Discriminator literal pinning every display column to `Display`. */
     readonly columnType: "Display";
-    readonly modal: //HACK out parameter. Need to check if it's possible to be strict
+    /** Optional Svelte component opened as a modal from the cell. */
+    readonly modal: // eslint-disable-next-line @typescript-eslint/no-explicit-any
     Component<DisplayDefModalProps<T>, any, any> | undefined;
 }

package/dist/Components/Table/Types/Columns/Definitions/Display/AbstractDisplayDef.svelte.js

@@ -1,10 +1,26 @@
 import { ColumnType } from '../../ColumnType.js';
 import { ColumnDef } from '../ColumnDef.svelte.js';
+/**
+ * `AbstractDisplayDef<T, FilterValueType, FilterOptionsType>` is the
+ * shared base for display-only columns (Bubble, Display, ProgressBar,
+ * Validity). Each subclass pins `columnType = ColumnType.Display` and
+ * further narrows the `displayType` inner discriminator.
+ *
+ * @remarks
+ *
+ * `modal` is `Component<any, any, any>` rather than a narrower generic
+ * because the consumer-supplied modal component declares its own
+ * exports / events / slots and the cell dispatch site cannot statically
+ * know the full triple. Callers should accept `DisplayDefModalProps`
+ * as props and ignore the slot / event channels.
+ */
 export class AbstractDisplayDef extends ColumnDef {
     constructor(props) {
         super(props);
         this.modal = $derived(props.modal);
     }
+    /** Discriminator literal pinning every display column to `Display`. */
     columnType = ColumnType.Display;
+    /** Optional Svelte component opened as a modal from the cell. */
     modal;
 }

package/dist/Components/Table/Types/Columns/Definitions/Display/BubbleDef.svelte.d.ts

@@ -1,14 +1,32 @@
 import type { BubbleColour } from '../../../../../BubbleColour.js';
 import type { FilterFn, StringFilterValueType } from '../../../Filtering/FilterFn.js';
 import { AbstractDisplayDef, type AbstractDisplayDefProps } from './AbstractDisplayDef.svelte.js';
+/**
+ * Construction-time props for `BubbleDef`.
+ *
+ * Notes:
+ * - `getColour` may return either a sync `BubbleColour` or an async
+ *   `BubbleColour | null | undefined`. The asymmetric nullability is
+ *   preserved for backwards compatibility; tracked in the workorder.
+ * - `value` is a string today (the rendered cell text); a future
+ *   tightening could thread the column's `TValue`.
+ */
 export interface BubbleDefProps<T extends object, in FilterValueType, out FilterOptionsType> extends AbstractDisplayDefProps<T, FilterValueType, FilterOptionsType> {
+    /** Per-bubble colour mapper. Invoked per bubble value per render. */
     getColour?: (item: T, index: number, value: string) => BubbleColour | Promise<BubbleColour | null | undefined>;
 }
+/**
+ * `BubbleDef<T, FilterValueType, FilterOptionsType>` renders the cell
+ * value as a row of coloured bubbles.
+ */
 export declare class BubbleDef<T extends object, in FilterValueType = StringFilterValueType, out FilterOptionsType = unknown> extends AbstractDisplayDef<T, FilterValueType, FilterOptionsType> {
+    /** Inner discriminator literal. */
     readonly displayType: "Bubbles";
     constructor(props: BubbleDefProps<T, FilterValueType, FilterOptionsType>);
     private _filterFn;
+    /** Filter predicate. Reassignable. */
     get filterFn(): FilterFn<T, FilterValueType> | undefined;
     set filterFn(v: FilterFn<T, FilterValueType> | undefined);
-    getColour: ((item: T, index: number, value: string) => BubbleColour | Promise<BubbleColour | null | undefined>) | undefined;
+    /** Per-bubble colour mapper. */
+    readonly getColour: ((item: T, index: number, value: string) => BubbleColour | Promise<BubbleColour | null | undefined>) | undefined;
 }

package/dist/Components/Table/Types/Columns/Definitions/Display/BubbleDef.svelte.js

@@ -1,18 +1,29 @@
+import { memoiseRowValueAccessor } from '../../../../../../Helpers/memoiseByRow.js';
 import { DisplayType } from '../../DisplayType.js';
 import { AbstractDisplayDef } from './AbstractDisplayDef.svelte.js';
+/**
+ * `BubbleDef<T, FilterValueType, FilterOptionsType>` renders the cell
+ * value as a row of coloured bubbles.
+ */
 export class BubbleDef extends AbstractDisplayDef {
+    /** Inner discriminator literal. */
     displayType = DisplayType.Bubbles;
     constructor(props) {
         super(props);
-        this.getColour = $derived(props.getColour);
+        // Wrap user callback in a row-keyed WeakMap cache so 1000-row renders
+        // invoke the user fn at most once per (row, value) pair. Reassigning
+        // props.getColour re-derives the wrapper and discards the stale cache.
+        this.getColour = $derived(memoiseRowValueAccessor(props.getColour));
         this._filterFn = $state(props.filterFn);
     }
     _filterFn;
+    /** Filter predicate. Reassignable. */
     get filterFn() {
         return this._filterFn;
     }
     set filterFn(v) {
         this._filterFn = v;
     }
+    /** Per-bubble colour mapper. */
     getColour;
 }

package/dist/Components/Table/Types/Columns/Definitions/Display/DisplayDef.svelte.d.ts

@@ -1,12 +1,23 @@
 import type { FilterFn } from '../../../Filtering/FilterFn.js';
 import { DisplayType } from '../../DisplayType.js';
 import { AbstractDisplayDef, type AbstractDisplayDefProps } from './AbstractDisplayDef.svelte.js';
+/**
+ * Construction-time props for `DisplayDef`. The interface adds no
+ * fields over `AbstractDisplayDefProps`; it exists so future
+ * display-specific props can be added without a breaking-change rename.
+ */
 export interface DisplayDefProps<T extends object, in FilterValueType, out FilterOptionsType> extends AbstractDisplayDefProps<T, FilterValueType, FilterOptionsType> {
 }
+/**
+ * `DisplayDef<T, FilterValueType, FilterOptionsType>` renders the cell
+ * value as plain text. The default display kind for non-input columns.
+ */
 export declare class DisplayDef<T extends object, in FilterValueType, out FilterOptionsType> extends AbstractDisplayDef<T, FilterValueType, FilterOptionsType> {
+    /** Inner discriminator literal. */
     readonly displayType: DisplayType;
     constructor(props: DisplayDefProps<T, FilterValueType, FilterOptionsType>);
     private _filterFn;
+    /** Filter predicate. Reassignable. */
     get filterFn(): FilterFn<T, FilterValueType> | undefined;
     set filterFn(v: FilterFn<T, FilterValueType> | undefined);
 }

package/dist/Components/Table/Types/Columns/Definitions/Display/DisplayDef.svelte.js

@@ -1,15 +1,18 @@
 import { DisplayType } from '../../DisplayType.js';
 import { AbstractDisplayDef } from './AbstractDisplayDef.svelte.js';
-// export interface DisplayDefProps<T extends object> extends AbstractDisplayDefProps<T, any> {
-// 	// readonly displayType: DisplayType.Normal;
-// }
+/**
+ * `DisplayDef<T, FilterValueType, FilterOptionsType>` renders the cell
+ * value as plain text. The default display kind for non-input columns.
+ */
 export class DisplayDef extends AbstractDisplayDef {
+    /** Inner discriminator literal. */
     displayType = DisplayType.Normal;
     constructor(props) {
         super(props);
         this._filterFn = $state(props.filterFn);
     }
     _filterFn;
+    /** Filter predicate. Reassignable. */
     get filterFn() {
         return this._filterFn;
     }

package/dist/Components/Table/Types/Columns/Definitions/Display/ProgressBarDef.svelte.d.ts

@@ -1,14 +1,33 @@
 import type { BubbleColour } from '../../../../../BubbleColour.js';
 import type { FilterFn, NumberFilterValueType } from '../../../Filtering/FilterFn.js';
 import { AbstractDisplayDef, type AbstractDisplayDefProps } from './AbstractDisplayDef.svelte.js';
+/**
+ * Construction-time props for `ProgressBarDef`.
+ *
+ * Notes:
+ * - `getColour` is required. The return type is
+ *   `BubbleColour | Promise<BubbleColour> | undefined`; the
+ *   `| undefined` slot was historically inside the Promise and is
+ *   preserved verbatim. Tracked in the workorder.
+ * - `value: [number, number]` represents `[current, total]`; the
+ *   column data shape is not yet connected to this tuple.
+ */
 export interface ProgressBarDefProps<T extends object, in FilterValueType, out FilterOptionsType> extends AbstractDisplayDefProps<T, FilterValueType, FilterOptionsType> {
+    /** Required. Per-cell colour mapper given the `[current, total]` tuple. */
     getColour: (item: T, index: number, value: [number, number]) => BubbleColour | Promise<BubbleColour> | undefined;
 }
+/**
+ * `ProgressBarDef<T, FilterValueType, FilterOptionsType>` renders the
+ * cell value as a horizontal progress bar.
+ */
 export declare class ProgressBarDef<T extends object, in FilterValueType = NumberFilterValueType, out FilterOptionsType = unknown> extends AbstractDisplayDef<T, FilterValueType, FilterOptionsType> {
+    /** Inner discriminator literal. */
     readonly displayType: "Progress";
     constructor(props: ProgressBarDefProps<T, FilterValueType, FilterOptionsType>);
+    /** Per-cell colour mapper. */
     readonly getColour: (item: T, index: number, value: [number, number]) => BubbleColour | Promise<BubbleColour> | undefined;
     private _filterFn;
+    /** Filter predicate. Reassignable. */
     get filterFn(): FilterFn<T, FilterValueType> | undefined;
     set filterFn(v: FilterFn<T, FilterValueType> | undefined);
 }

package/dist/Components/Table/Types/Columns/Definitions/Display/ProgressBarDef.svelte.js

@@ -1,14 +1,38 @@
 import { DisplayType } from '../../DisplayType.js';
 import { AbstractDisplayDef } from './AbstractDisplayDef.svelte.js';
+/**
+ * `ProgressBarDef<T, FilterValueType, FilterOptionsType>` renders the
+ * cell value as a horizontal progress bar.
+ */
 export class ProgressBarDef extends AbstractDisplayDef {
+    /** Inner discriminator literal. */
     displayType = DisplayType.Progress;
     constructor(props) {
         super(props);
-        this.getColour = $derived(props.getColour);
+        // Row-keyed WeakMap cache. The `[done, total]` tuple is row-derived,
+        // so row identity alone is sufficient as the cache key (the same row
+        // will always be queried with the same logical tuple within a render).
+        // Reassigning props.getColour re-derives the wrapper, which constructs
+        // a fresh WeakMap and discards the stale cache.
+        this.getColour = $derived.by(() => {
+            const raw = props.getColour;
+            const cache = new WeakMap();
+            return (item, index, value) => {
+                const hit = cache.get(item);
+                if (hit !== undefined || cache.has(item)) {
+                    return hit;
+                }
+                const result = raw(item, index, value);
+                cache.set(item, result);
+                return result;
+            };
+        });
         this._filterFn = $state(props.filterFn);
     }
+    /** Per-cell colour mapper. */
     getColour;
     _filterFn;
+    /** Filter predicate. Reassignable. */
     get filterFn() {
         return this._filterFn;
     }

package/dist/Components/Table/Types/Columns/Definitions/Display/ValidityDef.svelte.d.ts

@@ -1,11 +1,37 @@
 import type { ValidationFn } from '../ValidationFn.js';
 import { AbstractDisplayDef, type AbstractDisplayDefProps } from './AbstractDisplayDef.svelte.js';
+/**
+ * Construction-time props for `ValidityDef`. `isValid` is required
+ * because the validity column has no other content; the rest of the
+ * shape mirrors `AbstractDisplayDefProps`.
+ */
 export interface ValidityDefProps<T extends object, in FilterValueType, out FilterOptionsType> extends AbstractDisplayDefProps<T, FilterValueType, FilterOptionsType> {
+    /** Required per-row validity predicate. */
     isValid: ValidationFn<T>;
 }
+/**
+ * `ValidityDef<T, FilterValueType, FilterOptionsType>` renders the row
+ * validity as a status icon. Non-sortable and non-filterable.
+ *
+ * @remarks
+ *
+ * The class no longer mutates the incoming `props` object. Instead it
+ * spreads `props` and overrides the relevant flags when forwarding to
+ * `super(...)`. The original implementation mutated
+ * `props.allowSorting` / `props.allowFiltering` in place before calling
+ * `super`, which surprised callers who reused the same props object.
+ *
+ * The base class' `isValid` field is `ValidationFn<T> | undefined`;
+ * the subclass narrows the public type to required (`isValid` is
+ * mandatory on the subclass props) via the `declare` re-declaration
+ * below. The runtime assignment happens in the base constructor.
+ */
 export declare class ValidityDef<T extends object, in FilterValueType, out FilterOptionsType> extends AbstractDisplayDef<T, FilterValueType, FilterOptionsType> {
+    /** Inner discriminator literal. */
     readonly displayType: "Validity";
     constructor(props: ValidityDefProps<T, FilterValueType, FilterOptionsType>);
+    /** Validity columns are never filtered. */
     readonly filterFn: undefined;
+    /** Required per-row validity predicate (narrowed from the base optional). */
     readonly isValid: ValidationFn<T>;
 }

package/dist/Components/Table/Types/Columns/Definitions/Display/ValidityDef.svelte.js

@@ -1,13 +1,28 @@
 import { DisplayType } from '../../DisplayType.js';
 import { AbstractDisplayDef } from './AbstractDisplayDef.svelte.js';
+/**
+ * `ValidityDef<T, FilterValueType, FilterOptionsType>` renders the row
+ * validity as a status icon. Non-sortable and non-filterable.
+ *
+ * @remarks
+ *
+ * The class no longer mutates the incoming `props` object. Instead it
+ * spreads `props` and overrides the relevant flags when forwarding to
+ * `super(...)`. The original implementation mutated
+ * `props.allowSorting` / `props.allowFiltering` in place before calling
+ * `super`, which surprised callers who reused the same props object.
+ *
+ * The base class' `isValid` field is `ValidationFn<T> | undefined`;
+ * the subclass narrows the public type to required (`isValid` is
+ * mandatory on the subclass props) via the `declare` re-declaration
+ * below. The runtime assignment happens in the base constructor.
+ */
 export class ValidityDef extends AbstractDisplayDef {
+    /** Inner discriminator literal. */
     displayType = DisplayType.Validity;
     constructor(props) {
-        props.allowSorting = false;
-        props.allowFiltering = false;
-        super(props);
-        this.isValid = $derived(props.isValid);
+        super({ ...props, allowSorting: false, allowFiltering: false });
     }
+    /** Validity columns are never filtered. */
     filterFn = undefined;
-    isValid;
 }

package/dist/Components/Table/Types/Columns/Definitions/Expand/ExpandDef.svelte.d.ts

@@ -1,23 +1,59 @@
 import type { IconProps } from '../../../../../IconProps.js';
+import type { ScoriaStorageKey } from '../../../../../../Types/Internal/Misc.js';
 import type { Primitive, TableInitOptions } from '../../../Context/TableInitOptions.js';
 import type { DefsWrapper } from '../../DefsWrapper.js';
 import { ColumnDef, type ColumnDefProps } from '../ColumnDef.svelte.js';
-export interface ExpandDefProps<T extends object, R extends object, InnterIdType extends Primitive = Primitive, in FilterValueType = unknown, out FilterOptionsType = unknown> extends ColumnDefProps<T, FilterValueType, FilterOptionsType> {
+/**
+ * Construction-time props for `ExpandDef`. The generic name
+ * `InnerIdType` (previously `InnterIdType` - typo) parameterises the
+ * inner table's row id.
+ *
+ * Notes:
+ * - `getInnerColumnDefs` and `accessorFn` are invoked per expansion;
+ *   caching is the consumer's responsibility (tracked in perf workorder).
+ * - The class no longer mutates the incoming `props` object before
+ *   calling `super`; the override is forwarded via a spread.
+ */
+export interface ExpandDefProps<T extends object, R extends object, InnerIdType extends Primitive = Primitive, in FilterValueType = unknown, out FilterOptionsType = unknown> extends ColumnDefProps<T, FilterValueType, FilterOptionsType> {
+    /** Per-row enable predicate for the expansion affordance. */
     isEnabled: (item: T, index: number) => boolean | Promise<boolean>;
+    /** Builds the inner table's column defs. Invoked per expansion. */
     getInnerColumnDefs: (item: T, index: number) => DefsWrapper<R>;
+    /** Header icon name on the expand-toggle button. */
     headerIcon: IconProps['name'];
-    innerTableName: string;
-    innerTableOptions: TableInitOptions<R, InnterIdType>;
+    /** Display name of the inner table; surfaces in storage / a11y. */
+    innerTableName: ScoriaStorageKey;
+    /** Init options for the inner table. */
+    innerTableOptions: TableInitOptions<R, InnerIdType>;
+    /** Accessor returning the inner-row array for a given outer row. */
     accessorFn: (item: T, index: number) => ReadonlyArray<R> | Promise<ReadonlyArray<R>>;
 }
-export declare class ExpandDef<T extends object, R extends object, InnterIdType extends Primitive = Primitive, in FilterValueType = unknown, out FilterOptionsType = unknown> extends ColumnDef<T, FilterValueType, FilterOptionsType> {
+/**
+ * `ExpandDef<T, R, InnerIdType, FilterValueType, FilterOptionsType>` is
+ * a column whose cells expand to reveal an inner table.
+ *
+ * @remarks
+ *
+ * Non-sortable and non-filterable; the class spreads `props` with the
+ * relevant overrides when forwarding to `super(...)` rather than
+ * mutating the incoming props object.
+ */
+export declare class ExpandDef<T extends object, R extends object, InnerIdType extends Primitive = Primitive, in FilterValueType = unknown, out FilterOptionsType = unknown> extends ColumnDef<T, FilterValueType, FilterOptionsType> {
+    /** Discriminator literal. */
     readonly columnType: "Expand";
-    constructor(props: ExpandDefProps<T, R, InnterIdType, FilterValueType, FilterOptionsType>);
+    constructor(props: ExpandDefProps<T, R, InnerIdType, FilterValueType, FilterOptionsType>);
+    /** Narrowed accessorFn: returns the inner-row array. */
     readonly accessorFn: (item: T, index: number) => ReadonlyArray<R> | Promise<ReadonlyArray<R>>;
+    /** Expand columns are never filtered. */
     readonly filterFn: undefined;
-    readonly innerTableName: string;
+    /** Display name of the inner table. */
+    readonly innerTableName: ScoriaStorageKey;
+    /** Builds the inner table's column defs. */
     readonly getInnerColumnDefs: (item: T, index: number) => DefsWrapper<R>;
+    /** Header icon name on the expand-toggle button. */
     readonly headerIcon: IconProps['name'];
+    /** Per-row enable predicate for the expansion affordance. */
     readonly isEnabled: (item: T, index: number) => boolean | Promise<boolean>;
-    readonly innerTableOptions: TableInitOptions<R, InnterIdType>;
+    /** Init options for the inner table. */
+    readonly innerTableOptions: TableInitOptions<R, InnerIdType>;
 }

package/dist/Components/Table/Types/Columns/Definitions/Expand/ExpandDef.svelte.js

@@ -1,21 +1,36 @@
 import { ColumnType } from '../../ColumnType.js';
 import { ColumnDef } from '../ColumnDef.svelte.js';
+/**
+ * `ExpandDef<T, R, InnerIdType, FilterValueType, FilterOptionsType>` is
+ * a column whose cells expand to reveal an inner table.
+ *
+ * @remarks
+ *
+ * Non-sortable and non-filterable; the class spreads `props` with the
+ * relevant overrides when forwarding to `super(...)` rather than
+ * mutating the incoming props object.
+ */
 export class ExpandDef extends ColumnDef {
+    /** Discriminator literal. */
     columnType = ColumnType.Expand;
     constructor(props) {
-        props.allowFiltering = false;
-        props.allowSorting = false;
-        super(props);
+        super({ ...props, allowFiltering: false, allowSorting: false });
         this.isEnabled = $derived(props.isEnabled);
         this.headerIcon = $derived(props.headerIcon);
         this.getInnerColumnDefs = $derived(props.getInnerColumnDefs);
         this.innerTableName = $derived(props.innerTableName);
         this.innerTableOptions = $derived(props.innerTableOptions);
     }
+    /** Expand columns are never filtered. */
     filterFn = undefined;
+    /** Display name of the inner table. */
     innerTableName;
+    /** Builds the inner table's column defs. */
     getInnerColumnDefs;
+    /** Header icon name on the expand-toggle button. */
     headerIcon;
+    /** Per-row enable predicate for the expansion affordance. */
     isEnabled;
+    /** Init options for the inner table. */
     innerTableOptions;
 }

package/dist/Components/Table/Types/Columns/Definitions/FilterOnly/FilterOnlyDef.svelte.d.ts

@@ -1,10 +1,24 @@
 import type { FilterFn } from '../../../Filtering/FilterFn.js';
-import { ColumnType } from '../../ColumnType.js';
 import { ColumnDef, type ColumnDefProps } from '../ColumnDef.svelte.js';
-export interface FilterOnlyDefProps<T extends object, FilterFnType = unknown, out FilterOptionsType = unknown> extends ColumnDefProps<T, FilterFnType, FilterOptionsType> {
+/**
+ * Construction-time props for `FilterOnlyDef`. Adds no fields over
+ * `ColumnDefProps`; the marker exists so future filter-only-specific
+ * props can be added without a breaking-change rename.
+ */
+export interface FilterOnlyDefProps<T extends object, in FilterFnType = unknown, out FilterOptionsType = unknown> extends ColumnDefProps<T, FilterFnType, FilterOptionsType> {
 }
-export declare class FilterOnlyDef<T extends object, FilterFnType = unknown, out FilterOptionsType = unknown> extends ColumnDef<T, FilterFnType, FilterOptionsType> {
+/**
+ * `FilterOnlyDef<T, FilterFnType, FilterOptionsType>` is a column that
+ * participates in filtering but never renders a body cell. Used to
+ * surface a filter input in the filter panel without occupying a body
+ * slot.
+ */
+export declare class FilterOnlyDef<T extends object, in FilterFnType = unknown, out FilterOptionsType = unknown> extends ColumnDef<T, FilterFnType, FilterOptionsType> {
     constructor(props: FilterOnlyDefProps<T, FilterFnType, FilterOptionsType>);
-    readonly columnType: ColumnType;
-    readonly filterFn: FilterFn<T, FilterFnType> | undefined;
+    /** Discriminator literal. */
+    readonly columnType: "Filter Only";
+    private _filterFn;
+    /** Filter predicate. Reassignable; properly initialised from props. */
+    get filterFn(): FilterFn<T, FilterFnType> | undefined;
+    set filterFn(v: FilterFn<T, FilterFnType> | undefined);
 }

package/dist/Components/Table/Types/Columns/Definitions/FilterOnly/FilterOnlyDef.svelte.js

@@ -1,13 +1,24 @@
 import { ColumnType } from '../../ColumnType.js';
 import { ColumnDef } from '../ColumnDef.svelte.js';
-// export interface FilterOnlyDefProps<T extends object, FilterFnType> extends ColumnDefProps<
-// 	T,
-// 	FilterFnType
-// > {}
+/**
+ * `FilterOnlyDef<T, FilterFnType, FilterOptionsType>` is a column that
+ * participates in filtering but never renders a body cell. Used to
+ * surface a filter input in the filter panel without occupying a body
+ * slot.
+ */
 export class FilterOnlyDef extends ColumnDef {
     constructor(props) {
         super(props);
+        this._filterFn = $state(props.filterFn);
     }
+    /** Discriminator literal. */
     columnType = ColumnType.FilterOnly;
-    filterFn;
+    _filterFn;
+    /** Filter predicate. Reassignable; properly initialised from props. */
+    get filterFn() {
+        return this._filterFn;
+    }
+    set filterFn(v) {
+        this._filterFn = v;
+    }
 }

package/dist/Components/Table/Types/Columns/Definitions/JSONColumnDefSet.d.ts

@@ -2,6 +2,20 @@ import type { SortingState } from '../../DataRepository/SortingState.js';
 import type { JSONColumnPinningState } from '../JSONColumnPinningState.js';
 import type { VisibilityState } from '../VisibilityState.js';
 import type { ColumnJSONRepresentation } from './ColumnDef.svelte.js';
+/**
+ * Persisted-to-localStorage projection of `ColumnDefSet`. Differs from the
+ * runtime form in that:
+ *
+ * - `columnPinningState` is `JSONColumnPinningState` (`Array<[id, width]>`)
+ *   instead of `ReadonlyMap`-based for `JSON.stringify` round-tripping.
+ * - `columnDefs` carries the JSON representation of each `ColumnDef`
+ *   (a `ColumnJSONRepresentation` produced by `toJSON()` on each def) rather
+ *   than the live class instances.
+ *
+ * Security note: `JSONColumnDefSet` is read back from localStorage and must
+ * pass schema validation before being trusted. The validator helper is
+ * tracked under the StoragePresetSchemaValidation cross-cutting workorder.
+ */
 export interface JSONColumnDefSet {
     name: string;
     sortingState: SortingState;

package/dist/Components/Table/Types/Columns/Definitions/RowSelection/RowSelectionDef.svelte.d.ts

@@ -1,9 +1,41 @@
 import type { BoolFilterValueType } from '../../../Filtering/FilterFn.js';
-import { ColumnType } from '../../ColumnType.js';
 import { ColumnDef, type ColumnDefProps } from '../ColumnDef.svelte.js';
+/**
+ * Construction-time props for `RowSelectionDef`. Mirrors the
+ * named-args object shape used by every other `*Def` class so callers
+ * can construct it consistently. The legacy positional signature is
+ * retained as an overload for backwards compatibility.
+ */
+export interface RowSelectionDefProps<T extends object, FilterValueType = BoolFilterValueType, FilterOptionsType = undefined> {
+    /** Per-row predicate for whether the row may be selected. */
+    isSelectable: (item: T, index: number) => boolean | Promise<boolean>;
+    /** Optional row validity predicate. */
+    isValid?: ColumnDefProps<T, FilterValueType, FilterOptionsType>['isValid'];
+}
+/**
+ * `RowSelectionDef<T, FilterValueType, FilterOptionsType>` is the
+ * checkbox column that drives row selection. Non-sortable and
+ * non-filterable; the header reads `'Row Selected'` and the id is
+ * generated via `generateUUID` (UUIDv7).
+ *
+ * @remarks
+ *
+ * Two construction forms are supported:
+ *
+ * - `new RowSelectionDef(isSelectable, isValid?)` - legacy positional
+ *   signature retained for backwards compatibility.
+ * - `new RowSelectionDef({ isSelectable, isValid })` - props-object
+ *   signature parallel to every other `*Def` class.
+ *
+ * The positional form was the only outlier in the Def family;
+ * consumers are encouraged to migrate to the props-object form.
+ */
 export declare class RowSelectionDef<T extends object, in FilterValueType = BoolFilterValueType, out FilterOptionsType = undefined> extends ColumnDef<T, FilterValueType, FilterOptionsType> {
+    /** Discriminator literal. */
+    readonly columnType: "RowSelect";
     readonly isSelectable: (item: T, index: number) => boolean | Promise<boolean>;
-    readonly columnType: ColumnType;
+    constructor(props: RowSelectionDefProps<T, FilterValueType, FilterOptionsType>);
     constructor(isSelectable: (item: T, index: number) => boolean | Promise<boolean>, isValid?: ColumnDefProps<T, FilterValueType, FilterOptionsType>['isValid']);
+    /** Row-selection columns are never filtered. */
     readonly filterFn: undefined;
 }