@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/Table/Types/Columns/Definitions/Accessors/QueryDef.svelte.d.ts

@@ -1,16 +1,39 @@
 import type { SelectOption } from '../../../../../../Types/Internal/SelectOption.js';
 import type { FilterFn } from '../../../Filtering/FilterFn.js';
 import { AccessorDef, type AccessorDefProps } from './AccessorDef.svelte.js';
+/**
+ * Construction-time props for `QueryDef`. Both `query` and
+ * `getDisplayValue` are required: the dropdown is asynchronously
+ * populated from `query` and the cell display is decoupled from the
+ * stored value.
+ *
+ * Security: `query` receives raw user input from the quick-search box.
+ * Implementations forwarding the query string to a backend MUST escape
+ * or parameterise it before use. Documented in the workorder.
+ */
 export interface QueryDefProps<T extends object, in FilterValueType = unknown, out FilterOptionsType = unknown> extends AccessorDefProps<T, FilterValueType, FilterOptionsType> {
+    /** Async option provider. Receives raw user input from the search box;
+     *  implementations forwarding to a backend must escape the query. */
     query: (queryString: string, item: T, index: number) => Promise<Array<SelectOption<unknown>>>;
+    /** Required. Maps the stored value to a display label. */
     getDisplayValue: (item: T, index: number) => string | null | Promise<string | null>;
+    /** Whether the widget exposes a clear affordance. Defaults to true. */
     clearable?: boolean;
 }
+/**
+ * `QueryDef<T, FilterValueType, FilterOptionsType>` is an `AccessorDef`
+ * backed by an asynchronous option provider (typeahead).
+ */
 export declare class QueryDef<T extends object, FilterValueType = unknown, out FilterOptionsType = unknown> extends AccessorDef<T, FilterValueType, FilterOptionsType> {
+    /** Inner discriminator literal. */
     readonly accessorType: "Query";
     constructor(props: QueryDefProps<T, FilterValueType, FilterOptionsType>);
+    /** Filter predicate. Bound at construction. */
     readonly filterFn: FilterFn<T, FilterValueType> | undefined;
+    /** Required at the subclass layer. */
     getDisplayValue: (item: T, index: number) => string | null | Promise<string | null>;
+    /** Async option provider. */
     readonly query: (queryString: string, item: T, index: number) => Promise<Array<SelectOption<unknown>>>;
+    /** Whether the widget exposes a clear affordance. */
     readonly clearable: boolean;
 }

package/dist/Components/Table/Types/Columns/Definitions/Accessors/QueryDef.svelte.js

@@ -1,6 +1,11 @@
 import { AccessorDef } from './AccessorDef.svelte.js';
 import { AccessorType } from './AccessorType.js';
+/**
+ * `QueryDef<T, FilterValueType, FilterOptionsType>` is an `AccessorDef`
+ * backed by an asynchronous option provider (typeahead).
+ */
 export class QueryDef extends AccessorDef {
+    /** Inner discriminator literal. */
     accessorType = AccessorType.Query;
     constructor(props) {
         super(props);
@@ -8,7 +13,10 @@ export class QueryDef extends AccessorDef {
         this.filterFn = $derived(props.filterFn);
         this.clearable = $derived(props.clearable ?? true);
     }
+    /** Filter predicate. Bound at construction. */
     filterFn;
+    /** Async option provider. */
     query;
+    /** Whether the widget exposes a clear affordance. */
     clearable;
 }

package/dist/Components/Table/Types/Columns/Definitions/Accessors/SelectDef.svelte.d.ts

@@ -1,22 +1,53 @@
 import type { SelectOption } from '../../../../../../Types/Internal/SelectOption.js';
 import type { FilterFn } from '../../../Filtering/FilterFn.js';
 import { AccessorDef, type AccessorDefProps } from './AccessorDef.svelte.js';
+/**
+ * Construction-time props for `SelectDef`. Unlike the base
+ * `ColumnDefProps`, both `getOptions` and `getDisplayValue` are
+ * required - the option label is decoupled from the stored value and
+ * the dropdown cannot render without an option set.
+ *
+ * Notes:
+ * - `getSpecificOptions` returns a per-row option set; it is invoked
+ *   per cell per render with no caching (tracked in perf workorder).
+ * - `optional` controls whether the cell may be cleared; `clearable`
+ *   controls whether the widget exposes a clear affordance.
+ */
 export interface SelectDefProps<T extends object, in FilterValueType, out SelectValueType> extends AccessorDefProps<T, FilterValueType, SelectValueType> {
+    /** Required. Returns the global option set for the dropdown. */
     getOptions: () => Array<SelectOption<SelectValueType>> | Promise<Array<SelectOption<SelectValueType>>>;
+    /** Required. Maps the stored value to a display label. */
     getDisplayValue: (item: T, index: number) => string | null | Promise<string | null>;
+    /** Optional per-row option override. Invoked per cell per render. */
     getSpecificOptions?: (item: T, index: number) => Array<SelectOption<SelectValueType>> | Promise<Array<SelectOption<SelectValueType>>>;
+    /** Whether the cell may be cleared. Defaults to false. */
     optional?: boolean;
+    /** Whether the widget exposes a clear affordance. Defaults to true. */
     clearable?: boolean;
 }
+/**
+ * `SelectDef<T, FilterValueType, SelectValueType>` is an `AccessorDef`
+ * backed by a finite option set. The `declare`-redeclaration of
+ * `getDisplayValue` / `getOptions` below narrows the optional base
+ * contract to required: callers can rely on both being defined at the
+ * subclass layer.
+ */
 export declare class SelectDef<T extends object, in FilterValueType, out SelectValueType> extends AccessorDef<T, FilterValueType, SelectValueType> {
     constructor(props: SelectDefProps<T, FilterValueType, SelectValueType>);
+    /** Inner discriminator literal. */
     readonly accessorType: "Select";
     private _filterFn;
+    /** Filter predicate. Reassignable. */
     get filterFn(): FilterFn<T, FilterValueType> | undefined;
     set filterFn(v: FilterFn<T, FilterValueType> | undefined);
+    /** Whether the cell may be cleared. */
     readonly optional: boolean;
+    /** Whether the widget exposes a clear affordance. */
     readonly clearable: boolean;
+    /** Per-row option override; invoked per cell per render. */
     readonly getSpecificOptions?: (item: T, index: number) => Array<SelectOption<SelectValueType>> | Promise<Array<SelectOption<SelectValueType>>>;
+    /** Required at the subclass layer. */
     getDisplayValue: (item: T, index: number) => string | null | Promise<string | null>;
+    /** Required at the subclass layer. */
     getOptions: () => Array<SelectOption<SelectValueType>> | Promise<Array<SelectOption<SelectValueType>>>;
 }

package/dist/Components/Table/Types/Columns/Definitions/Accessors/SelectDef.svelte.js

@@ -1,24 +1,38 @@
+import { memoiseRowAccessor } from '../../../../../../Helpers/memoiseByRow.js';
 import { AccessorDef } from './AccessorDef.svelte.js';
 import { AccessorType } from './AccessorType.js';
+/**
+ * `SelectDef<T, FilterValueType, SelectValueType>` is an `AccessorDef`
+ * backed by a finite option set. The `declare`-redeclaration of
+ * `getDisplayValue` / `getOptions` below narrows the optional base
+ * contract to required: callers can rely on both being defined at the
+ * subclass layer.
+ */
 export class SelectDef extends AccessorDef {
     constructor(props) {
         super(props);
-        this.getSpecificOptions = $derived(props.getSpecificOptions); //done in the base class now
-        // this.getOptions = $derived(props.getOptions); // done in the base class now
+        // Row-keyed WeakMap cache around the per-row options provider. For
+        // Promise returns the Promise itself is cached, so {#await} resolves
+        // once per row rather than per render.
+        this.getSpecificOptions = $derived(memoiseRowAccessor(props.getSpecificOptions));
         this.optional = $derived(props.optional ?? false);
         this.clearable = $derived(props.clearable ?? true);
-        // this.getDisplayValue = $derived(props.getDisplayValue); //done in the base class now
         this._filterFn = $state(props.filterFn);
     }
+    /** Inner discriminator literal. */
     accessorType = AccessorType.Select;
     _filterFn;
+    /** Filter predicate. Reassignable. */
     get filterFn() {
         return this._filterFn;
     }
     set filterFn(v) {
         this._filterFn = v;
     }
+    /** Whether the cell may be cleared. */
     optional;
+    /** Whether the widget exposes a clear affordance. */
     clearable;
+    /** Per-row option override; invoked per cell per render. */
     getSpecificOptions;
 }

package/dist/Components/Table/Types/Columns/Definitions/Accessors/TextInputDef.svelte.d.ts

@@ -1,12 +1,31 @@
 import type { FilterFn, StringFilterValueType } from '../../../Filtering/FilterFn.js';
 import { AccessorDef, type AccessorDefProps } from './AccessorDef.svelte.js';
-export interface TextInputDefProps<T extends object, in FilterValueType = StringFilterValueType, out SelectValueType = StringFilterValueType> extends AccessorDefProps<T, FilterValueType, SelectValueType> {
+/**
+ * Construction-time props for `TextInputDef`. The `TValue` generic is
+ * pinned to `string | null`.
+ *
+ * Notes:
+ * - `filterValueType?: 'String'` is redeclared here as documentation:
+ *   it pins the filter-row UI to the string-input variant.
+ * - The third generic (`SelectValueType`) is unused by the text input
+ *   today but retained so the shape parallels every other
+ *   `AccessorDef` subclass.
+ */
+export interface TextInputDefProps<T extends object, in FilterValueType = StringFilterValueType, out SelectValueType = StringFilterValueType> extends AccessorDefProps<T, FilterValueType, SelectValueType, string | null> {
+    /** Filter input variant; pinned to `'String'`. */
     filterValueType?: 'String';
 }
-export declare class TextInputDef<T extends object, in FilterValueType = StringFilterValueType, out SelectValueType = StringFilterValueType> extends AccessorDef<T, FilterValueType, SelectValueType> {
+/**
+ * `TextInputDef<T, FilterValueType, SelectValueType>` fixes its
+ * declared value type at `string | null`. Cells reading
+ * `cell.getValue()` now see the narrower type instead of `unknown`.
+ */
+export declare class TextInputDef<T extends object, in FilterValueType = StringFilterValueType, out SelectValueType = StringFilterValueType> extends AccessorDef<T, FilterValueType, SelectValueType, string | null> {
+    /** Inner discriminator literal. */
     readonly accessorType: "Text";
     constructor(props: TextInputDefProps<T, FilterValueType, SelectValueType>);
     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/Accessors/TextInputDef.svelte.js

@@ -1,12 +1,19 @@
 import { AccessorDef } from './AccessorDef.svelte.js';
 import { AccessorType } from './AccessorType.js';
+/**
+ * `TextInputDef<T, FilterValueType, SelectValueType>` fixes its
+ * declared value type at `string | null`. Cells reading
+ * `cell.getValue()` now see the narrower type instead of `unknown`.
+ */
 export class TextInputDef extends AccessorDef {
+    /** Inner discriminator literal. */
     accessorType = AccessorType.Text;
     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/Actions/ActionsDef.svelte.d.ts

@@ -1,16 +1,44 @@
 import type { ColourSet } from '../../../../../../scss/colours.js';
 import type { TableActionButton } from '../../TableActionButton.js';
 import { ColumnDef, type ColumnDefProps } from '../ColumnDef.svelte.js';
+/**
+ * Construction-time props for `ActionsDef`. Omits `id` and `header`
+ * because the class generates a stable id via `generateUUID` and pins
+ * the header to `'Actions'`.
+ *
+ * Notes:
+ * - `isEnabled` defaults to `true` for every button if omitted.
+ * - `getColourSet` defaults to the button's own colour if omitted.
+ * - Both callbacks receive the button currently being rendered so a
+ *   single `ActionsDef` can drive a row of differently-styled actions.
+ */
 export interface ActionsDefProps<T extends object, in FilterValueType, out FilterOptionsType = unknown> extends Omit<ColumnDefProps<T, FilterValueType, FilterOptionsType>, 'id' | 'header'> {
+    /** The buttons rendered for every row. */
     actions: Array<TableActionButton<T>>;
+    /** Per-row, per-button enable predicate; assumed `true` if missing. */
     isEnabled?: (item: T, index: number, button: TableActionButton<T>) => boolean | Promise<boolean>;
+    /** Per-row, per-button colour override. */
     getColourSet?: (item: T, index: number, button: TableActionButton<T>) => ColourSet;
 }
+/**
+ * `ActionsDef<T, FilterValueType, FilterOptionsType>` is a column whose
+ * cells render a row of buttons. It is non-sortable, non-filterable,
+ * and pins its header to `'Actions'`.
+ *
+ * Note: the generated id uses `generateUUID()` (UUIDv7); two `ActionsDef`
+ * instances constructed in the same render pass will have distinct ids
+ * so consumers must keep a single instance per table.
+ */
 export declare class ActionsDef<T extends object, FilterValueType, out FilterOptionsType = unknown> extends ColumnDef<T, FilterValueType, FilterOptionsType> {
-    constructor(props: ActionsDefProps<T, FilterValueType>);
+    constructor(props: ActionsDefProps<T, FilterValueType, FilterOptionsType>);
+    /** Discriminator literal. */
     readonly columnType: "Actions";
+    /** The buttons rendered for every row. */
     readonly actions: Array<TableActionButton<T>>;
+    /** Per-row, per-button enable predicate. */
     readonly isEnabled?: (item: T, index: number, button: TableActionButton<T>) => boolean | Promise<boolean>;
+    /** Per-row, per-button colour override. */
     readonly getColourSet?: (item: T, index: number, button: TableActionButton<T>) => ColourSet;
+    /** Actions columns are never filtered. */
     readonly filterFn: undefined;
 }

package/dist/Components/Table/Types/Columns/Definitions/Actions/ActionsDef.svelte.js

@@ -1,10 +1,19 @@
-import { generateUUID } from '../../../../../../Helpers/Helpers.svelte.js';
+import { generateUUID, syntheticColumnId } from '../../../../../../Helpers/Helpers.svelte.js';
 import { ColumnType } from '../../ColumnType.js';
 import { ColumnDef } from '../ColumnDef.svelte.js';
+/**
+ * `ActionsDef<T, FilterValueType, FilterOptionsType>` is a column whose
+ * cells render a row of buttons. It is non-sortable, non-filterable,
+ * and pins its header to `'Actions'`.
+ *
+ * Note: the generated id uses `generateUUID()` (UUIDv7); two `ActionsDef`
+ * instances constructed in the same render pass will have distinct ids
+ * so consumers must keep a single instance per table.
+ */
 export class ActionsDef extends ColumnDef {
     constructor(props) {
         super({
-            id: `actions-${generateUUID()}`,
+            id: syntheticColumnId(`actions-${generateUUID()}`),
             header: 'Actions',
             allowSorting: false,
             allowFiltering: false,
@@ -13,9 +22,14 @@ export class ActionsDef extends ColumnDef {
         this.isEnabled = $derived(props.isEnabled);
         this.getColourSet = $derived(props.getColourSet);
     }
+    /** Discriminator literal. */
     columnType = ColumnType.Actions;
+    /** The buttons rendered for every row. */
     actions;
-    isEnabled; // assumed true if missing
+    /** Per-row, per-button enable predicate. */
+    isEnabled;
+    /** Per-row, per-button colour override. */
     getColourSet;
+    /** Actions columns are never filtered. */
     filterFn = undefined;
 }

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

@@ -1,4 +1,4 @@
-import type { Pixels } from '../../../../../Types/Internal/Misc.js';
+import type { ColumnId, Pixels } from '../../../../../Types/Internal/Misc.js';
 import type { SelectOption } from '../../../../../Types/Internal/SelectOption.js';
 import type { Snippet } from 'svelte';
 import type { MemoryColumnIndex } from '../../Coordinates/ColumnIndices.js';
@@ -7,63 +7,174 @@ import type { FilterValueType } from '../../Filtering/FilterValueType.js';
 import { ColumnType } from '../ColumnType.js';
 import type { AccessorFn } from './AccessorFn.js';
 import type { ValidationFn } from './ValidationFn.js';
-export interface ColumnDefProps<T extends object, in FilterFnType, out OptionsType> {
-    id: string;
+/**
+ * Construction-time props shared by every `ColumnDef` subclass. The
+ * generics mirror those of `ColumnDef` itself:
+ *
+ * - `T`: the row shape.
+ * - `FilterFnType` (contravariant): the value the column's `filterFn`
+ *   receives at filter-evaluation time (e.g. `BoolFilterValueType` for
+ *   `CheckboxDef`).
+ * - `OptionsType` (covariant): the value produced by `getOptions` for
+ *   select-style filtering.
+ * - `TValue`: the declared row-value type; defaults to `unknown` so
+ *   non-accessor columns do not need to thread it.
+ */
+export interface ColumnDefProps<T extends object, in FilterFnType, out OptionsType, TValue = unknown> {
+    /** Stable column identifier. Two-arm union: either a `string & keyof T`
+     *  literal (accessor-backed column) or a {@link SyntheticColumnId} brand
+     *  (pseudo column with no row binding, e.g. row-selection / expand /
+     *  actions). `AccessorDef` subclasses narrow this to `string & keyof T`.
+     *
+     *  Construct synthetic ids via the `syntheticColumnId(...)` helper
+     *  (re-exported from `$lib`). */
+    id: ColumnId<T>;
+    /** Header content. A plain string renders as text; a Snippet renders
+     *  arbitrary markup. Note: only string headers serialise cleanly via
+     *  `toJSON` for preset storage. */
     header: string | Snippet;
+    /** When true the cell, header, and filter row log per-render debug info. */
     debug?: boolean;
+    /** Declared memory order. If omitted, the column is given index 0 and is
+     *  expected to be reassigned by the surrounding context. */
     index?: MemoryColumnIndex;
+    /** Whether this column may be filtered. Defaults to `true`. */
     allowFiltering?: boolean;
+    /** Whether this column may be sorted. Defaults to `true`. */
     allowSorting?: boolean;
+    /** Whether the column is hidden by default (still appears in the column picker). */
     defaultHidden?: boolean;
+    /** Minimum width in pixels. Defaults to the column-min-width token. */
     minSize?: Pixels;
+    /** Initial width in pixels. Defaults to `minSize`. */
     width?: Pixels;
+    /** Async-flag predicate for whether a given cell is currently editable. */
     isEditable?: (item: T, index: number) => boolean | Promise<boolean>;
+    /** Whether the column may be resized by the user. Defaults to `true`. */
     resizable?: boolean;
+    /** Per-row validity predicate; surfaces in `ValidityDef` and inline UI. */
     isValid?: ValidationFn<T>;
+    /** Predicate used during filtering. Subclasses redeclare it with a
+     *  narrowed `FilterFnType`. */
     filterFn?: FilterFn<T, FilterFnType>;
+    /** Sort comparator factory; receives the desc flag, returns a comparator. */
     getSortingFn?: (desc: boolean) => (a: T, b: T) => 1 | -1 | 0;
+    /** Determines which filter input is rendered in the filter panel. */
     filterValueType?: FilterValueType;
+    /** Required when `filterValueType === 'Select'`. Returns the option set
+     *  rendered in the filter dropdown. */
     getOptions?: () => Array<SelectOption<OptionsType>> | Promise<Array<SelectOption<OptionsType>>>;
-    accessorFn?: AccessorFn<T>;
+    /** Reads the cell value from a row. For `AccessorDef` subclasses this is
+     *  required at the subclass layer. */
+    accessorFn?: AccessorFn<T, TValue>;
+    /** Renders the cell value as a string. Required for `SelectDef` /
+     *  `QueryDef` where the option label is decoupled from the stored value. */
     getDisplayValue?: (item: T, index: number) => string | null | Promise<string | null>;
+    /** Optional grouping label for this column's filter row in the
+     *  advanced filter panel. See `BaseColumnOptions.filterGroup` for
+     *  the consumer-facing description. */
+    filterGroup?: string;
 }
-export declare abstract class ColumnDef<T extends object, in FilterFnType = never, out OptionsType = unknown> {
-    protected constructor(props: ColumnDefProps<T, FilterFnType, OptionsType>);
-    readonly id: string;
+/**
+ * `ColumnDef<T, FilterFnType, OptionsType, TValue>` is the abstract base
+ * for every Table column kind. Owns identification, layout (`minSize`,
+ * `width`, `resizable`), gating flags (`allowFiltering`, `allowSorting`,
+ * `defaultHidden`, `isEditable`), data accessors (`accessorFn`,
+ * `getDisplayValue`), and filtering / sorting hooks (`filterFn`,
+ * `filterValueType`, `getOptions`, `getSortingFn`).
+ *
+ * The `TValue` generic captures the declared row-value type for
+ * data-backed columns (e.g. `boolean` for `CheckboxDef`,
+ * `number | string | null` for `NumberInputDef`). Defaulting to `unknown`
+ * keeps every existing call site that uses three or fewer generic
+ * arguments unchanged.
+ *
+ * @remarks
+ *
+ * Several fields are `$derived(props.x)` so that a consumer who rebuilds
+ * the `ColumnDef` props object via `columnDefs = [...]` propagates the
+ * change reactively. This is a reactivity escape hatch rather than
+ * derived state; flattening to plain `readonly` fields is a per-Def
+ * optimisation tracked in the perf report.
+ */
+export declare abstract class ColumnDef<T extends object, in FilterFnType = never, out OptionsType = unknown, TValue = unknown> {
+    protected constructor(props: ColumnDefProps<T, FilterFnType, OptionsType, TValue>);
+    /** Stable column identifier. */
+    readonly id: ColumnId<T>;
+    /** When true, callers may log per-render debug info. */
     debug: boolean;
     private _index;
+    /** Declared memory order; reassigned by `TableContext` during pinning. */
     get index(): MemoryColumnIndex;
     set index(v: MemoryColumnIndex);
+    /** Discriminator literal narrowed by each subclass. */
     abstract readonly columnType: ColumnType;
+    /** Whether the column is hidden by default. */
     readonly defaultHidden: boolean;
+    /** Whether the column may be sorted. */
     readonly allowSorting: boolean;
+    /** Whether the column may be filtered. */
     readonly allowFiltering: boolean;
+    /** Per-row validity predicate. */
     readonly isValid: ValidationFn<T> | undefined;
-    readonly accessorFn: AccessorFn<T> | undefined;
+    /** Reads the row value. Required at the `AccessorDef` subclass layer. */
+    readonly accessorFn: AccessorFn<T, TValue> | undefined;
+    /** Filter predicate. Each subclass narrows the generic parameter. */
     abstract filterFn: FilterFn<T, FilterFnType> | undefined;
     private _minSize;
+    /** Minimum width in pixels. */
     get minSize(): Pixels;
     set minSize(v: Pixels);
     private _width;
+    /** Current width in pixels. Mutated by the resize handle. */
     get width(): Pixels;
     set width(v: Pixels);
     private _isResizing;
+    /** Whether the resize handle is currently active. */
     get isResizing(): boolean;
     set isResizing(v: boolean);
-    private _visible;
-    get visible(): boolean;
-    set visible(v: boolean);
+    private _userResized;
+    /**
+     * Whether the user has explicitly resized this column via the
+     * resize handle. Drives the grid-template-columns track strategy:
+     * non-resized columns use `minmax(width, 1fr)` so they flex to
+     * fill the table's horizontal space; resized columns use a fixed
+     * `${width}px` so dragging one column's handle does not
+     * redistribute the other resized columns' widths. When the total
+     * fixed width drops below the table's width, the still-flexing
+     * (non-resized) columns automatically expand to fill the gap.
+     */
+    get userResized(): boolean;
+    set userResized(v: boolean);
     private _filterValueType;
+    /** Filter input kind; drives the filter panel renderer. */
     get filterValueType(): FilterValueType | undefined;
     set filterValueType(v: FilterValueType | undefined);
+    /** Renders the cell value as a string for preset / accessibility paths.
+     *  Required at the `SelectDef` / `QueryDef` subclass layer. */
     readonly getDisplayValue: ((item: T, index: number) => string | null | Promise<string | null>) | undefined;
+    /** Preset-serialisation projection. Note that `header.toString()` returns
+     *  `[Function]` for Snippet headers; preset-saving consumers should pass
+     *  a string header. Tracked in the workorder. */
     toJSON(): ColumnJSONRepresentation;
+    /** Sort comparator factory. */
     readonly getSortingFn: ((desc: boolean) => (a: T, b: T) => 1 | -1 | 0) | undefined;
+    /** Async-flag predicate for cell editability. */
     readonly isEditable: (item: T, index: number) => boolean | Promise<boolean>;
+    /** Whether the column may be resized by the user. */
     readonly resizable: boolean;
+    /** Header content; string or Snippet. */
     readonly header: string | Snippet;
+    /** Options provider for select-style filter inputs. */
     readonly getOptions?: () => Array<SelectOption<OptionsType>> | Promise<Array<SelectOption<OptionsType>>>;
+    /** Optional grouping label for this column's filter row in the
+     *  advanced filter panel. Columns sharing the same `filterGroup`
+     *  string render under a single collapsible section in
+     *  `FilterPanel.svelte`. `undefined` puts the column in the
+     *  fallback "Other" group. */
+    readonly filterGroup: string | undefined;
 }
+/** Preset-storage shape produced by `ColumnDef.toJSON`. */
 export interface ColumnJSONRepresentation {
     columnType: ColumnType;
     id: string;

package/dist/Components/Table/Types/Columns/Definitions/ColumnDef.svelte.js

@@ -1,8 +1,34 @@
+import { memoiseRowAccessor } from '../../../../../Helpers/memoiseByRow.js';
 import { ColumnType } from '../ColumnType.js';
+/**
+ * `ColumnDef<T, FilterFnType, OptionsType, TValue>` is the abstract base
+ * for every Table column kind. Owns identification, layout (`minSize`,
+ * `width`, `resizable`), gating flags (`allowFiltering`, `allowSorting`,
+ * `defaultHidden`, `isEditable`), data accessors (`accessorFn`,
+ * `getDisplayValue`), and filtering / sorting hooks (`filterFn`,
+ * `filterValueType`, `getOptions`, `getSortingFn`).
+ *
+ * The `TValue` generic captures the declared row-value type for
+ * data-backed columns (e.g. `boolean` for `CheckboxDef`,
+ * `number | string | null` for `NumberInputDef`). Defaulting to `unknown`
+ * keeps every existing call site that uses three or fewer generic
+ * arguments unchanged.
+ *
+ * @remarks
+ *
+ * Several fields are `$derived(props.x)` so that a consumer who rebuilds
+ * the `ColumnDef` props object via `columnDefs = [...]` propagates the
+ * change reactively. This is a reactivity escape hatch rather than
+ * derived state; flattening to plain `readonly` fields is a per-Def
+ * optimisation tracked in the perf report.
+ */
 export class ColumnDef {
     constructor(props) {
         this.id = $derived(props.id);
-        this._index = $state(props.index ?? 0); // HACK this may prove problematic and be turned to a required property
+        // HACK: `index` defaults to 0 and is expected to be reassigned by the
+        // surrounding TableContext during column pinning calculation. Tracked
+        // in the ColumnDef workorder as a candidate for a required prop.
+        this._index = $state(props.index ?? 0);
         this.defaultHidden = $derived(props.defaultHidden ?? false);
         this.allowFiltering = $derived(props.allowFiltering ?? true);
         this.allowSorting = $derived(props.allowSorting ?? true);
@@ -14,26 +40,41 @@ export class ColumnDef {
         this.resizable = $derived(props.resizable ?? true);
         this.header = $derived(props.header);
         this._filterValueType = $derived(props.filterValueType);
-        this.getDisplayValue = $derived(props.getDisplayValue);
+        // Row-keyed WeakMap cache so a 1000-row render invokes the user
+        // callback at most once per row. Reassigning props.getDisplayValue
+        // re-derives the wrapper and discards the stale cache automatically.
+        // Async returns: the Promise itself is cached, so repeated reads
+        // return the same Promise and Svelte's {#await} resolves once.
+        this.getDisplayValue = $derived(memoiseRowAccessor(props.getDisplayValue));
         this.debug = $derived(props.debug ?? false);
         this.getSortingFn = $derived(props.getSortingFn);
         this.getOptions = $derived(props.getOptions);
+        this.filterGroup = $derived(props.filterGroup);
     }
+    /** Stable column identifier. */
     id;
+    /** When true, callers may log per-render debug info. */
     debug;
     _index;
+    /** Declared memory order; reassigned by `TableContext` during pinning. */
     get index() {
         return this._index;
     }
     set index(v) {
         this._index = v;
     }
+    /** Whether the column is hidden by default. */
     defaultHidden;
+    /** Whether the column may be sorted. */
     allowSorting;
+    /** Whether the column may be filtered. */
     allowFiltering;
+    /** Per-row validity predicate. */
     isValid;
+    /** Reads the row value. Required at the `AccessorDef` subclass layer. */
     accessorFn;
     _minSize;
+    /** Minimum width in pixels. */
     get minSize() {
         return this._minSize;
     }
@@ -41,6 +82,7 @@ export class ColumnDef {
         this._minSize = v;
     }
     _width;
+    /** Current width in pixels. Mutated by the resize handle. */
     get width() {
         return this._width;
     }
@@ -48,6 +90,7 @@ export class ColumnDef {
         this._width = v;
     }
     _isResizing = $state(false);
+    /** Whether the resize handle is currently active. */
     get isResizing() {
         return this._isResizing;
     }
@@ -58,25 +101,37 @@ export class ColumnDef {
         }
         this._isResizing = v;
     }
-    _visible = $state(true);
-    get visible() {
-        return this._visible;
+    _userResized = $state(false);
+    /**
+     * Whether the user has explicitly resized this column via the
+     * resize handle. Drives the grid-template-columns track strategy:
+     * non-resized columns use `minmax(width, 1fr)` so they flex to
+     * fill the table's horizontal space; resized columns use a fixed
+     * `${width}px` so dragging one column's handle does not
+     * redistribute the other resized columns' widths. When the total
+     * fixed width drops below the table's width, the still-flexing
+     * (non-resized) columns automatically expand to fill the gap.
+     */
+    get userResized() {
+        return this._userResized;
     }
-    set visible(v) {
-        if (v && !this.allowSorting) {
-            console.warn(`Column ${this.id} is not sortable`);
-            return;
-        }
-        this._visible = v;
+    set userResized(v) {
+        this._userResized = v;
     }
     _filterValueType;
+    /** Filter input kind; drives the filter panel renderer. */
     get filterValueType() {
         return this._filterValueType;
     }
     set filterValueType(v) {
         this._filterValueType = v;
     }
+    /** Renders the cell value as a string for preset / accessibility paths.
+     *  Required at the `SelectDef` / `QueryDef` subclass layer. */
     getDisplayValue;
+    /** Preset-serialisation projection. Note that `header.toString()` returns
+     *  `[Function]` for Snippet headers; preset-saving consumers should pass
+     *  a string header. Tracked in the workorder. */
     toJSON() {
         return {
             columnType: this.columnType,
@@ -85,9 +140,20 @@ export class ColumnDef {
             filterValueType: this.filterValueType,
         };
     }
+    /** Sort comparator factory. */
     getSortingFn;
+    /** Async-flag predicate for cell editability. */
     isEditable;
+    /** Whether the column may be resized by the user. */
     resizable;
+    /** Header content; string or Snippet. */
     header;
+    /** Options provider for select-style filter inputs. */
     getOptions;
+    /** Optional grouping label for this column's filter row in the
+     *  advanced filter panel. Columns sharing the same `filterGroup`
+     *  string render under a single collapsible section in
+     *  `FilterPanel.svelte`. `undefined` puts the column in the
+     *  fallback "Other" group. */
+    filterGroup;
 }