@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/Table/Table.svelte.d.ts

@@ -7,10 +7,33 @@ declare global {
         }>;
     }
 }
+/**
+ * Top-level orchestrator props. Accepts either:
+ *
+ * - `table`: the structured `Table` instance returned by `createTable(...)`.
+ *   This is the consumer-facing form.
+ * - `tableContext`: the underlying `TableContext`. Used internally by
+ *   `NestedTable` which constructs a context directly for each
+ *   expansion. Not intended for consumer use.
+ *
+ * Exactly one of the two must be supplied; a runtime guard inside the
+ * component throws if both are missing. The reference passed in is
+ * captured at mount via `setContext` and should not be reassigned
+ * afterwards.
+ */
 export interface TableProps<T extends object, IdType extends Primitive> {
-    readonly tableContext: TableContext<T, IdType>;
+    readonly table?: {
+        readonly _context: TableContext<T, IdType>;
+    };
+    readonly tableContext?: TableContext<T, IdType>;
     nested?: boolean;
 }
+/**
+ * Symbol used to share the currently-open quick-filter select across
+ * every header in a single Table tree. Stored via `setContext` on
+ * the same component that hosts the Table tree so multiple
+ * independent tables on a page each own their own popup state.
+ */
 export declare const quickFilterContextIdentifier: symbol;
 declare function $$render<T extends object, IdType extends Primitive>(): {
     props: TableProps<T, IdType>;

package/dist/Components/Table/TableHelpers.svelte.d.ts

@@ -0,0 +1,58 @@
+import type { DefsWrapper } from './Types/Columns/DefsWrapper.js';
+import { TableContext } from './Types/Context/TableContext.svelte.js';
+import type { Primitive } from './Types/Context/TableInitOptions.js';
+import type { CustomFilter } from './Types/Filtering/CustomFilter.js';
+import type { RefWrapper } from '../../Types/Internal/RefWrapper.js';
+/**
+ * Argument object passed to {@link createLocalTable}.
+ *
+ * Lives under `Components/Table/` because it references Table-internal types
+ * ({@link DefsWrapper}, {@link Primitive}) that callers outside the Table
+ * subtree should not need to know about. Re-exported from the library entry
+ * point for public consumption.
+ */
+export interface ICreateTableArgs<T extends object, RowIdType extends Primitive> {
+    name: string;
+    defs: DefsWrapper<T>;
+    data: RefWrapper<Array<T>>;
+    getUserId: () => string | undefined;
+    selectionExtractor: (item: T) => RowIdType | Promise<RowIdType>;
+}
+/**
+ * Convenience factory that wires up a {@link TableContext} backed by a
+ * {@link LocalTableDataRepository} (in-memory, `$state`-backed data).
+ *
+ * Co-located with the Table subtree it serves: previously this lived in the
+ * generic `Helpers.svelte.ts`, which forced every consumer of unrelated
+ * helpers (such as `getErrorMessage` or `asyncMap`) to drag the entire Table
+ * subtree into their dependency graph and broke tree-shaking. Moving the
+ * factory here breaks the structural cycle
+ * `Helpers <-> TableContext <-> RowSelectionDef` while keeping the public
+ * `@lavalogic/scoria` surface unchanged via re-export from `src/lib/index.ts`.
+ */
+export declare function createLocalTable<T extends object, RowIdType extends Primitive>(args: ICreateTableArgs<T, RowIdType>): TableContext<T, RowIdType>;
+/**
+ * Typeguard narrowing a {@link CustomFilter} to a Select-typed filter that
+ * carries a non-null `query` function. Useful inside column definitions and
+ * filter panel components that need to differentiate query-driven select
+ * filters from value-list select filters before invoking the async loader.
+ *
+ * Belongs under `Components/Table/` because it is meaningful only for the
+ * {@link CustomFilter}/{@link CustomFilterType} discriminated union owned by
+ * the Table subtree.
+ */
+export declare function hasQuery<FilterValueType>(customFilter: CustomFilter<FilterValueType> | undefined): customFilter is CustomFilter<FilterValueType> & Required<Pick<CustomFilter<FilterValueType>, 'query'>>;
+/**
+ * Builds a stable two-row comparator for an arbitrary accessor function,
+ * honouring an ascending/descending flag. Used by Table sorting paths that
+ * need to sort raw rows (rather than column-aware cell values) by an
+ * extracted scalar.
+ *
+ * Nullish accessor results always sort last regardless of direction, mirroring
+ * the rendering convention that empty cells trail populated cells.
+ *
+ * Lives under `Components/Table/` because it is only meaningful in the
+ * context of Table sorting; the broader `Helpers` module deliberately does
+ * not depend on any Table type.
+ */
+export declare function getAccessorSortingFn<T, V>(accessorFn: (item: T) => V, desc: boolean): (a: T, b: T) => 1 | 0 | -1;

package/dist/Components/Table/TableHelpers.svelte.js

@@ -0,0 +1,88 @@
+import { TableContext } from './Types/Context/TableContext.svelte.js';
+import { LocalTableDataRepository } from './Types/DataRepository/LocalTableDataRepository.svelte.js';
+import { CustomFilterType } from './Types/Filtering/CustomFilterType.js';
+/**
+ * Convenience factory that wires up a {@link TableContext} backed by a
+ * {@link LocalTableDataRepository} (in-memory, `$state`-backed data).
+ *
+ * Co-located with the Table subtree it serves: previously this lived in the
+ * generic `Helpers.svelte.ts`, which forced every consumer of unrelated
+ * helpers (such as `getErrorMessage` or `asyncMap`) to drag the entire Table
+ * subtree into their dependency graph and broke tree-shaking. Moving the
+ * factory here breaks the structural cycle
+ * `Helpers <-> TableContext <-> RowSelectionDef` while keeping the public
+ * `@lavalogic/scoria` surface unchanged via re-export from `src/lib/index.ts`.
+ */
+export function createLocalTable(args) {
+    const localRepo = new LocalTableDataRepository(args.name, args.data, args.getUserId);
+    return TableContext.init(args.defs, args.name, localRepo, {
+        selectionExtractor: args.selectionExtractor,
+        getUserId: args.getUserId,
+    });
+}
+/**
+ * Typeguard narrowing a {@link CustomFilter} to a Select-typed filter that
+ * carries a non-null `query` function. Useful inside column definitions and
+ * filter panel components that need to differentiate query-driven select
+ * filters from value-list select filters before invoking the async loader.
+ *
+ * Belongs under `Components/Table/` because it is meaningful only for the
+ * {@link CustomFilter}/{@link CustomFilterType} discriminated union owned by
+ * the Table subtree.
+ */
+export function hasQuery(customFilter) {
+    return (!!customFilter &&
+        customFilter.type == CustomFilterType.Select &&
+        !!customFilter.query &&
+        typeof customFilter.query == 'function');
+}
+/**
+ * Builds a stable two-row comparator for an arbitrary accessor function,
+ * honouring an ascending/descending flag. Used by Table sorting paths that
+ * need to sort raw rows (rather than column-aware cell values) by an
+ * extracted scalar.
+ *
+ * Nullish accessor results always sort last regardless of direction, mirroring
+ * the rendering convention that empty cells trail populated cells.
+ *
+ * Lives under `Components/Table/` because it is only meaningful in the
+ * context of Table sorting; the broader `Helpers` module deliberately does
+ * not depend on any Table type.
+ */
+export function getAccessorSortingFn(accessorFn, desc) {
+    return desc
+        ? (_a, _b) => {
+            const a = accessorFn(_a);
+            const b = accessorFn(_b);
+            if (a == undefined && b != undefined) {
+                return 1;
+            }
+            if (b == undefined && a != undefined) {
+                return -1;
+            }
+            if (a < b) {
+                return 1;
+            }
+            if (a > b) {
+                return -1;
+            }
+            return 0;
+        }
+        : (_a, _b) => {
+            const a = accessorFn(_a);
+            const b = accessorFn(_b);
+            if (a == undefined && b != undefined) {
+                return 1;
+            }
+            if (b == undefined && a != undefined) {
+                return -1;
+            }
+            if (a < b) {
+                return -1;
+            }
+            if (a > b) {
+                return 1;
+            }
+            return 0;
+        };
+}

package/dist/Components/Table/Types/Columns/Column.d.ts

@@ -1,4 +1,14 @@
 import type { ColumnDef } from './Definitions/ColumnDef.svelte.js';
+/**
+ * Header / body view of one column. Wraps the underlying `ColumnDef`
+ * with view-layer affordances such as sort toggling, resizing, and
+ * visibility lookup.
+ *
+ * `id` is a bare `string` rather than `string & keyof T` because synthetic
+ * columns (actions, expand, row-selection) carry generated ids that are not
+ * properties of `T`. Tightening this to a union of accessor-keys and
+ * synthetic-prefixed brands is deferred (see workorder `ColumnDef` finding 1).
+ */
 export interface Column<T extends object, in FilterFnType = never, out FilterOptionsType = unknown> {
     id: string;
     columnDef: ColumnDef<T, FilterFnType, FilterOptionsType>;

package/dist/Components/Table/Types/Columns/ColumnPinningState.d.ts

@@ -1,3 +1,15 @@
+/**
+ * Runtime shape of the column-pinning state held by `TableContext`. Each map
+ * keys a column id to the width (in pixels) at which the column is currently
+ * pinned. A column id absent from both maps is unpinned (centre group).
+ *
+ * The widths are kept as bare numbers rather than `Pixels` brands because the
+ * resize handler and header code does arithmetic on them; brand promotion is
+ * tracked in the cross-cutting Pixels review.
+ *
+ * The matching serialisable shape is `JSONColumnPinningState`, which stores
+ * the same data as `Array<[id, width]>` pairs for `JSON.stringify`.
+ */
 export interface ColumnPinningState {
     left?: ReadonlyMap<string, number>;
     right?: ReadonlyMap<string, number>;

package/dist/Components/Table/Types/Columns/ColumnSizingState.d.ts

@@ -1 +1,9 @@
+/**
+ * Runtime shape of the per-column width state held by `TableContext`. Keyed
+ * by column id, valued by current width in pixels. Persisted to localStorage
+ * as-is (it is already a JSON-friendly record).
+ *
+ * Width is a bare `number` rather than a `Pixels` brand; brand promotion is
+ * tracked in the cross-cutting Pixels review.
+ */
 export type ColumnSizingState = Record<string, number>;

package/dist/Components/Table/Types/Columns/ColumnType.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Top-level taxonomy for column definitions. Every `ColumnDef` subclass sets
+ * `columnType` to one of these literals; the table context uses it to route
+ * cells to the correct cell component (`AccessorComponent`, `DisplayCell`,
+ * `ExpandCell`, etc.).
+ *
+ * - `Accessor` - data-backed column (text, number, date, select, query,
+ *   checkbox).
+ * - `Display` - read-only display column with no underlying accessor value
+ *   (bubble, progress, validity, plain display).
+ * - `Custom` - consumer-supplied column with a bespoke cell component.
+ * - `Expand` - master-detail expand control.
+ * - `RowSelect` - row-selection checkbox column.
+ * - `Actions` - action-button column.
+ * - `FilterOnly` - column that appears only in the filter panel; not rendered
+ *   in the body or header.
+ */
 export declare const ColumnType: {
     readonly Accessor: "Accessor";
     readonly Display: "Display";

package/dist/Components/Table/Types/Columns/ColumnType.js

@@ -1,3 +1,20 @@
+/**
+ * Top-level taxonomy for column definitions. Every `ColumnDef` subclass sets
+ * `columnType` to one of these literals; the table context uses it to route
+ * cells to the correct cell component (`AccessorComponent`, `DisplayCell`,
+ * `ExpandCell`, etc.).
+ *
+ * - `Accessor` - data-backed column (text, number, date, select, query,
+ *   checkbox).
+ * - `Display` - read-only display column with no underlying accessor value
+ *   (bubble, progress, validity, plain display).
+ * - `Custom` - consumer-supplied column with a bespoke cell component.
+ * - `Expand` - master-detail expand control.
+ * - `RowSelect` - row-selection checkbox column.
+ * - `Actions` - action-button column.
+ * - `FilterOnly` - column that appears only in the filter panel; not rendered
+ *   in the body or header.
+ */
 export const ColumnType = {
     Accessor: 'Accessor',
     Display: 'Display',
@@ -5,6 +22,6 @@ export const ColumnType = {
     Expand: 'Expand',
     RowSelect: 'RowSelect',
     Actions: 'Actions',
-    FilterOnly: 'Filter Only'
+    FilterOnly: 'Filter Only',
 };
 Object.freeze(ColumnType);

package/dist/Components/Table/Types/Columns/DateColumn.d.ts

@@ -1,4 +1,10 @@
 import type { DateInputDef } from './Definitions/Accessors/DateInputDef.svelte.js';
+/**
+ * Narrowed `Column<T>` whose `columnDef` is a `DateInputDef`. Currently
+ * declares its own shape rather than `extends Column<T, F, S>`; collapsing to
+ * an extension is deferred (see workorder Types-Columns finding 10) because
+ * the interface compatibility shift is consumer-facing.
+ */
 export interface DateColumn<T extends object, in FilterValueType, out SelectValueType> {
     id: string;
     columnDef: DateInputDef<T, FilterValueType, SelectValueType>;

package/dist/Components/Table/Types/Columns/DateTableCell.d.ts

@@ -1,5 +1,12 @@
 import type { Row } from '../Context/Row.js';
 import type { DateColumn } from './DateColumn.js';
+/**
+ * Narrowed `TableCell<T>` for date columns. `getValue` is still typed
+ * `unknown` because the canonical signature on `TableCell<T>` is also
+ * `unknown`; tightening to `Date | null | undefined | Promise<Date | null
+ * | undefined>` is deferred to the `TableCell.getValue` workorder so the
+ * tightening happens in one place rather than per cell variant.
+ */
 export interface DateTableCell<T extends object, in FilterValueType, out SelectValueType> {
     column: DateColumn<T, FilterValueType, SelectValueType>;
     row: Row<T>;

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

@@ -1 +1,14 @@
+/**
+ * `AccessorFn<T, TValue>` projects a row value out of `T` for a given column.
+ *
+ * The default `TValue = unknown` is retained for backwards compatibility:
+ * call sites that hold an `AccessorFn<T>` without a narrower second argument
+ * (notably `ColumnDef.accessorFn`) still compile unchanged.
+ *
+ * Concrete `ColumnDef` subclasses are expected to narrow `TValue` to the
+ * column's natural type (`boolean` for `CheckboxDef`, `number | string |
+ * null` for `NumberInputDef`, `string | null` for `TextInputDef`, etc.). This
+ * narrowing flows into the matching `TableCell` so that `cell.getValue()`
+ * returns the column's declared shape rather than `unknown`.
+ */
 export type AccessorFn<T extends object, TValue = unknown> = (originalRow: T, index: number) => TValue;

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

@@ -1,10 +1,35 @@
 import { ColumnDef, type ColumnDefProps } from '../ColumnDef.svelte.js';
 import type { AccessorType } from './AccessorType.js';
-export interface AccessorDefProps<T extends object, in FilterValueType, out FilterOptionsType> extends ColumnDefProps<T, FilterValueType, FilterOptionsType> {
+/**
+ * Construction-time props for every `AccessorDef` subclass. Narrows
+ * `id` to `string & keyof T` so the column id can be used as a literal
+ * accessor on `T` (e.g. `row.original[def.id]`).
+ *
+ * The `TValue` generic is threaded down from `ColumnDef` so subclasses
+ * (`CheckboxDef`, `NumberInputDef`, etc.) can pin it to their natural
+ * runtime shape.
+ */
+export interface AccessorDefProps<T extends object, in FilterValueType, out FilterOptionsType, TValue = unknown> extends ColumnDefProps<T, FilterValueType, FilterOptionsType, TValue> {
     readonly id: string & keyof T;
 }
-export declare abstract class AccessorDef<T extends object, in FilterValueType, out FilterOptionsType> extends ColumnDef<T, FilterValueType, FilterOptionsType> {
-    constructor(props: AccessorDefProps<T, FilterValueType, FilterOptionsType>);
+/**
+ * `AccessorDef<T, FilterValueType, FilterOptionsType, TValue>` is the
+ * base for every data-backed column definition. Discriminates as
+ * `ColumnType.Accessor` and exposes a further `accessorType` literal
+ * that each leaf subclass narrows (`Checkbox`, `Number`, `Text`,
+ * `Date`, `Select`, `Query`).
+ *
+ * The `TValue` generic is threaded down from `ColumnDef`; subclasses
+ * such as `CheckboxDef`, `NumberInputDef`, `TextInputDef`, and
+ * `DateInputDef` set it to their natural runtime shape so that the
+ * matching `TableCell.getValue()` returns the correct narrow type
+ * rather than `unknown`.
+ */
+export declare abstract class AccessorDef<T extends object, in FilterValueType, out FilterOptionsType, TValue = unknown> extends ColumnDef<T, FilterValueType, FilterOptionsType, TValue> {
+    constructor(props: AccessorDefProps<T, FilterValueType, FilterOptionsType, TValue>);
+    /** Discriminator literal pinning every `AccessorDef` subclass to the
+     *  `Accessor` column kind. Subclasses further narrow via `accessorType`. */
     readonly columnType: "Accessor";
+    /** Inner discriminator literal narrowed by each leaf subclass. */
     abstract readonly accessorType: AccessorType;
 }

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

@@ -1,10 +1,25 @@
 import { ColumnType } from '../../ColumnType.js';
 import { ColumnDef } from '../ColumnDef.svelte.js';
+/**
+ * `AccessorDef<T, FilterValueType, FilterOptionsType, TValue>` is the
+ * base for every data-backed column definition. Discriminates as
+ * `ColumnType.Accessor` and exposes a further `accessorType` literal
+ * that each leaf subclass narrows (`Checkbox`, `Number`, `Text`,
+ * `Date`, `Select`, `Query`).
+ *
+ * The `TValue` generic is threaded down from `ColumnDef`; subclasses
+ * such as `CheckboxDef`, `NumberInputDef`, `TextInputDef`, and
+ * `DateInputDef` set it to their natural runtime shape so that the
+ * matching `TableCell.getValue()` returns the correct narrow type
+ * rather than `unknown`.
+ */
 export class AccessorDef extends ColumnDef {
     // NOTE: constructor in place to enforce that we're using AccessorDefProps
     // eslint-disable-next-line @typescript-eslint/no-useless-constructor
     constructor(props) {
         super(props);
     }
+    /** Discriminator literal pinning every `AccessorDef` subclass to the
+     *  `Accessor` column kind. Subclasses further narrow via `accessorType`. */
     columnType = ColumnType.Accessor;
 }

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

@@ -1,3 +1,13 @@
+/**
+ * Sub-taxonomy for `Accessor`-typed columns. Selects which editor cell
+ * component the body renders for editable cells (`TableTextInput`,
+ * `TableNumberInput`, `TableDatePicker`, `TableSelect`, `TableQuerySelect`,
+ * `TableCheckbox`).
+ *
+ * Note: the value space deliberately overlaps with `DisplayType` (`'Date'`,
+ * `'Number'`). The unions never mix at the same call site because
+ * `ColumnType` discriminates between `Accessor` and `Display` first.
+ */
 export declare const AccessorType: {
     readonly Text: "Text";
     readonly Number: "Number";

package/dist/Components/Table/Types/Columns/Definitions/Accessors/AccessorType.js

@@ -1,9 +1,19 @@
+/**
+ * Sub-taxonomy for `Accessor`-typed columns. Selects which editor cell
+ * component the body renders for editable cells (`TableTextInput`,
+ * `TableNumberInput`, `TableDatePicker`, `TableSelect`, `TableQuerySelect`,
+ * `TableCheckbox`).
+ *
+ * Note: the value space deliberately overlaps with `DisplayType` (`'Date'`,
+ * `'Number'`). The unions never mix at the same call site because
+ * `ColumnType` discriminates between `Accessor` and `Display` first.
+ */
 export const AccessorType = {
     Text: 'Text',
     Number: 'Number',
     Date: 'Date',
     Select: 'Select',
     Query: 'Query',
-    Checkbox: 'Checkbox'
+    Checkbox: 'Checkbox',
 };
 Object.freeze(AccessorType);

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

@@ -1,11 +1,32 @@
 import type { BoolFilterValueType, FilterFn } from '../../../Filtering/FilterFn.js';
 import { AccessorDef, type AccessorDefProps } from './AccessorDef.svelte.js';
-export interface CheckboxDefProps<T extends object, in FilterValueType = BoolFilterValueType, out SelectValueType = BoolFilterValueType> extends AccessorDefProps<T, FilterValueType, SelectValueType> {
+/**
+ * Construction-time props for `CheckboxDef`. The `TValue` generic is
+ * pinned to `boolean` so `cell.getValue()` returns the narrow type.
+ *
+ * Notes:
+ * - `in FilterValueType` / `out SelectValueType` are unused by the
+ *   checkbox UI today but retained so the shape parallels every other
+ *   `AccessorDef` subclass.
+ * - The base interface is extended without adding fields; the marker
+ *   exists for symmetry and so future checkbox-specific props can be
+ *   added without a breaking-change rename.
+ */
+export interface CheckboxDefProps<T extends object, in FilterValueType = BoolFilterValueType, out SelectValueType = BoolFilterValueType> extends AccessorDefProps<T, FilterValueType, SelectValueType, boolean> {
 }
-export declare class CheckboxDef<T extends object, in FilterValueType = BoolFilterValueType, out SelectValueType = BoolFilterValueType> extends AccessorDef<T, FilterValueType, SelectValueType> {
+/**
+ * `CheckboxDef<T, FilterValueType, SelectValueType>` is an `AccessorDef`
+ * whose declared value is a `boolean`. The fixed `TValue = boolean`
+ * narrows `cell.getValue()` to `boolean | Promise<boolean>` at the cell
+ * layer.
+ */
+export declare class CheckboxDef<T extends object, in FilterValueType = BoolFilterValueType, out SelectValueType = BoolFilterValueType> extends AccessorDef<T, FilterValueType, SelectValueType, boolean> {
+    /** Inner discriminator literal. */
     readonly accessorType: "Checkbox";
     constructor(props: CheckboxDefProps<T, FilterValueType, SelectValueType>);
     private _filterFn;
+    /** Filter predicate. Reassignable so consumers can swap the filter
+     *  function post-construction. */
     get filterFn(): FilterFn<T, FilterValueType> | undefined;
     set filterFn(v: FilterFn<T, FilterValueType> | undefined);
 }

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

@@ -1,14 +1,21 @@
 import { AccessorDef } from './AccessorDef.svelte.js';
 import { AccessorType } from './AccessorType.js';
-// export interface CheckboxDefProps<T extends object>
-// 	extends AccessorDefProps<T, BoolFilterValueType> {}
+/**
+ * `CheckboxDef<T, FilterValueType, SelectValueType>` is an `AccessorDef`
+ * whose declared value is a `boolean`. The fixed `TValue = boolean`
+ * narrows `cell.getValue()` to `boolean | Promise<boolean>` at the cell
+ * layer.
+ */
 export class CheckboxDef extends AccessorDef {
+    /** Inner discriminator literal. */
     accessorType = AccessorType.Checkbox;
     constructor(props) {
         super(props);
         this._filterFn = $state(props.filterFn);
     }
     _filterFn;
+    /** Filter predicate. Reassignable so consumers can swap the filter
+     *  function post-construction. */
     get filterFn() {
         return this._filterFn;
     }

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

@@ -1,13 +1,32 @@
 import type { DateFilterValueType, FilterFn } from '../../../Filtering/FilterFn.js';
 import { AccessorDef, type AccessorDefProps } from './AccessorDef.svelte.js';
-export interface DateInputDefProps<T extends object, in FilterValueType = DateFilterValueType, out SelectValueType = DateFilterValueType> extends AccessorDefProps<T, FilterValueType, SelectValueType> {
+/**
+ * Construction-time props for `DateInputDef`. The `TValue` generic is
+ * pinned to `Date | null`.
+ *
+ * Notes:
+ * - `showTime` controls whether the input renders a time picker.
+ * - The third generic (`SelectValueType`) is unused by the date input
+ *   today but retained so the shape parallels every other
+ *   `AccessorDef` subclass.
+ */
+export interface DateInputDefProps<T extends object, in FilterValueType = DateFilterValueType, out SelectValueType = DateFilterValueType> extends AccessorDefProps<T, FilterValueType, SelectValueType, Date | null> {
+    /** Whether to render a time picker alongside the date picker. Defaults to false. */
     showTime?: boolean;
 }
-export declare class DateInputDef<T extends object, in FilterValueType = DateFilterValueType, out SelectValueType = DateFilterValueType> extends AccessorDef<T, FilterValueType, SelectValueType> {
+/**
+ * `DateInputDef<T, FilterValueType, SelectValueType>` fixes its
+ * declared value type at `Date | null` so cell consumers can drop the
+ * bespoke cast on `cell.getValue()`.
+ */
+export declare class DateInputDef<T extends object, in FilterValueType = DateFilterValueType, out SelectValueType = DateFilterValueType> extends AccessorDef<T, FilterValueType, SelectValueType, Date | null> {
+    /** Inner discriminator literal. */
     readonly accessorType: "Date";
     constructor(props: DateInputDefProps<T, FilterValueType, SelectValueType>);
     private _filterFn;
+    /** Filter predicate. Reassignable. */
     get filterFn(): FilterFn<T, FilterValueType> | undefined;
     set filterFn(v: FilterFn<T, FilterValueType> | undefined);
+    /** Whether to render a time picker. */
     readonly showTime: boolean;
 }

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

@@ -1,6 +1,12 @@
 import { AccessorDef } from './AccessorDef.svelte.js';
 import { AccessorType } from './AccessorType.js';
+/**
+ * `DateInputDef<T, FilterValueType, SelectValueType>` fixes its
+ * declared value type at `Date | null` so cell consumers can drop the
+ * bespoke cast on `cell.getValue()`.
+ */
 export class DateInputDef extends AccessorDef {
+    /** Inner discriminator literal. */
     accessorType = AccessorType.Date;
     constructor(props) {
         super(props);
@@ -8,11 +14,13 @@ export class DateInputDef extends AccessorDef {
         this._filterFn = $state(props.filterFn);
     }
     _filterFn;
+    /** Filter predicate. Reassignable. */
     get filterFn() {
         return this._filterFn;
     }
     set filterFn(v) {
         this._filterFn = v;
     }
+    /** Whether to render a time picker. */
     showTime;
 }

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

@@ -1,15 +1,41 @@
 import type { FilterFn, NumberFilterValueType } from '../../../Filtering/FilterFn.js';
 import { AccessorDef, type AccessorDefProps } from './AccessorDef.svelte.js';
-export interface NumberInputDefProps<T extends object, in FilterValueType = NumberFilterValueType, out OptionssValueType = NumberFilterValueType> extends AccessorDefProps<T, FilterValueType, OptionssValueType> {
+/**
+ * Construction-time props for `NumberInputDef`. The `TValue` generic is
+ * pinned to `number | string | null` - the widened union accepts the
+ * historic cell behaviour where a `string` may be parsed at render time
+ * and a `null` is interpreted as "no value".
+ *
+ * Notes:
+ * - `min` / `max` are not enforced at the definition layer; the input
+ *   widget clamps at render time. Tracked in the workorder.
+ * - The third generic (now `OptionsValueType`, previously misspelled
+ *   `OptionssValueType`) is unused by the number input today but
+ *   retained so the shape parallels every other `AccessorDef` subclass.
+ */
+export interface NumberInputDefProps<T extends object, in FilterValueType = NumberFilterValueType, out OptionsValueType = NumberFilterValueType> extends AccessorDefProps<T, FilterValueType, OptionsValueType, number | string | null> {
+    /** Minimum value accepted by the input widget. */
     min: number;
+    /** Maximum value accepted by the input widget. */
     max: number;
 }
-export declare class NumberInputDef<T extends object, in FilterValueType = NumberFilterValueType, out OptionssValueType = NumberFilterValueType> extends AccessorDef<T, FilterValueType, OptionssValueType> {
+/**
+ * `NumberInputDef<T, FilterValueType, OptionsValueType>` fixes its
+ * declared value type at `number | string | null`. The widened union
+ * accepts the historic cell behaviour where a `string` may be parsed
+ * at render time and a `null` is interpreted as "no value". Cell
+ * consumers can drop the `as number` cast on `cell.getValue()`.
+ */
+export declare class NumberInputDef<T extends object, in FilterValueType = NumberFilterValueType, out OptionsValueType = NumberFilterValueType> extends AccessorDef<T, FilterValueType, OptionsValueType, number | string | null> {
+    /** Inner discriminator literal. */
     readonly accessorType: "Number";
-    constructor(props: NumberInputDefProps<T, FilterValueType, OptionssValueType>);
+    constructor(props: NumberInputDefProps<T, FilterValueType, OptionsValueType>);
+    /** Minimum value accepted by the input widget. */
     readonly min: number;
+    /** Maximum value accepted by the input widget. */
     readonly max: number;
     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/NumberInputDef.svelte.js

@@ -1,6 +1,14 @@
 import { AccessorDef } from './AccessorDef.svelte.js';
 import { AccessorType } from './AccessorType.js';
+/**
+ * `NumberInputDef<T, FilterValueType, OptionsValueType>` fixes its
+ * declared value type at `number | string | null`. The widened union
+ * accepts the historic cell behaviour where a `string` may be parsed
+ * at render time and a `null` is interpreted as "no value". Cell
+ * consumers can drop the `as number` cast on `cell.getValue()`.
+ */
 export class NumberInputDef extends AccessorDef {
+    /** Inner discriminator literal. */
     accessorType = AccessorType.Number;
     constructor(props) {
         super(props);
@@ -8,9 +16,12 @@ export class NumberInputDef extends AccessorDef {
         this.max = $derived(props.max);
         this._filterFn = $state(props.filterFn);
     }
+    /** Minimum value accepted by the input widget. */
     min;
+    /** Maximum value accepted by the input widget. */
     max;
     _filterFn;
+    /** Filter predicate. Reassignable. */
     get filterFn() {
         return this._filterFn;
     }