@lavalogic/scoria 0.36.0 → 0.37.0

package/dist/Components/Table/Types/Public/ColumnOptions.d.ts

@@ -0,0 +1,238 @@
+import type { Component, Snippet } from 'svelte';
+import type { CellCoordinates } from '../Coordinates/CellCoordinates.js';
+import type { CustomFilter } from '../Filtering/CustomFilter.js';
+import type { FilterValueType } from '../Filtering/FilterValueType.js';
+import type { Primitive } from '../Context/TableInitOptions.js';
+import type { BubbleColour } from '../../../BubbleColour.js';
+import type { SelectOption } from '../../../../Types/Internal/SelectOption.js';
+import type { ValidationFn } from '../Columns/Definitions/ValidationFn.js';
+import type { ColourSet } from '../../../../scss/colours.js';
+import type { BaseColumnOptions } from './BaseColumnOptions.js';
+import type { ColumnFactory } from './ColumnFactory.js';
+import type { ColumnSpec } from './ColumnSpec.js';
+import type { BooleanKeyOf, DateKeyOf, NumberKeyOf, StringKeyOf } from './KeyConstraints.js';
+/**
+ * Per-kind option interfaces for every method on `ColumnFactory<TRow>`.
+ *
+ * Naming convention: `<Kind>ColumnOptions<TRow, ...>` for every method
+ * `col.<kind>(opts)`. The generic parameter list mirrors the corresponding
+ * factory method.
+ *
+ * Optional fields default to scoria-sensible values; the column factory
+ * applies the defaults when constructing the underlying `ColumnDef` so
+ * consumers do not have to write them at every call site.
+ *
+ * Accessor kinds (text, number, checkbox, date, select, query) constrain
+ * `id` to a key of `TRow` whose value type matches the kind. The value
+ * inferred from `TRow[K]` is the type carried into the column's per-cell
+ * `accessor`, `isValid`, `isEditable`, and `onEdit` callbacks.
+ *
+ * Display kinds (display, bubble, progress, validity) generate their own
+ * synthetic id and do not take an `id` from the caller.
+ *
+ * Structural kinds (rowSelection, actions, expand, filterOnly) likewise
+ * generate their own synthetic id.
+ */
+/** Options for `col.text({ id, header, ... })`. */
+export interface TextColumnOptions<TRow extends object, K extends StringKeyOf<TRow>> extends BaseColumnOptions {
+    /** Column id; must be a string-valued field of `TRow`. */
+    id: K;
+    /** Reads the cell value from the row. Defaults to `row[id]`. */
+    accessor?: (row: TRow, index: number) => TRow[K] | Promise<TRow[K]>;
+    /** Placeholder shown in the edit input when the cell is empty. */
+    placeholder?: string;
+    /** Maximum input length. */
+    maxLength?: number;
+    /** Per-row validity predicate. Async return supported. */
+    isValid?: ValidationFn<TRow>;
+    /** Per-row editability predicate. Defaults to `false` (read-only).
+     *  Async return supported. */
+    isEditable?: (row: TRow, index: number) => boolean | Promise<boolean>;
+    /** Fires after a successful edit with the typed new value. */
+    onEdit?: (row: TRow, value: TRow[K], coords: CellCoordinates) => void | Promise<void>;
+    /** Row fields the `isValid` / `isEditable` predicates implicitly depend
+     *  on. Listed explicitly so the reactivity system tracks them; replaces
+     *  the `void row.x` idiom. Optional; omit if predicates only depend on
+     *  the cell's own value. */
+    reactiveDependencies?: (row: TRow) => ReadonlyArray<unknown>;
+}
+/** Options for `col.number({ id, header, ... })`. */
+export interface NumberColumnOptions<TRow extends object, K extends NumberKeyOf<TRow>> extends BaseColumnOptions {
+    id: K;
+    accessor?: (row: TRow, index: number) => TRow[K] | Promise<TRow[K]>;
+    /** Lower bound. The edit input enforces; values outside resolve as invalid. */
+    min?: number;
+    /** Upper bound. */
+    max?: number;
+    /** Step for keyboard increments and the input's `step` attribute. */
+    step?: number;
+    /** Whether decimal values are accepted. Defaults to true. */
+    decimal?: boolean;
+    isValid?: ValidationFn<TRow>;
+    isEditable?: (row: TRow, index: number) => boolean | Promise<boolean>;
+    onEdit?: (row: TRow, value: TRow[K], coords: CellCoordinates) => void | Promise<void>;
+    reactiveDependencies?: (row: TRow) => ReadonlyArray<unknown>;
+}
+/** Options for `col.checkbox({ id, header, ... })`. */
+export interface CheckboxColumnOptions<TRow extends object, K extends BooleanKeyOf<TRow>> extends BaseColumnOptions {
+    id: K;
+    accessor?: (row: TRow, index: number) => TRow[K] | Promise<TRow[K]>;
+    isEditable?: (row: TRow, index: number) => boolean | Promise<boolean>;
+    onEdit?: (row: TRow, value: TRow[K], coords: CellCoordinates) => void | Promise<void>;
+    reactiveDependencies?: (row: TRow) => ReadonlyArray<unknown>;
+}
+/** Options for `col.date({ id, header, ... })`. */
+export interface DateColumnOptions<TRow extends object, K extends DateKeyOf<TRow>> extends BaseColumnOptions {
+    id: K;
+    accessor?: (row: TRow, index: number) => TRow[K] | Promise<TRow[K]>;
+    /** Whether the time component is editable. Defaults to false (date-only). */
+    withTime?: boolean;
+    isValid?: ValidationFn<TRow>;
+    isEditable?: (row: TRow, index: number) => boolean | Promise<boolean>;
+    onEdit?: (row: TRow, value: TRow[K], coords: CellCoordinates) => void | Promise<void>;
+    reactiveDependencies?: (row: TRow) => ReadonlyArray<unknown>;
+}
+/** Options for `col.select({ id, header, options, ... })`. */
+export interface SelectColumnOptions<TRow extends object, K extends keyof TRow & string, TValue = TRow[K]> extends BaseColumnOptions {
+    id: K;
+    /** Option list. Static array or an async loader called on first read. */
+    options: ReadonlyArray<SelectOption<TValue>> | (() => Promise<ReadonlyArray<SelectOption<TValue>>>);
+    /** Per-row option override. Useful when the selectable set depends on
+     *  another field of the row (e.g. status options narrowed by category). */
+    rowOptions?: (row: TRow) => ReadonlyArray<SelectOption<TValue>> | Promise<ReadonlyArray<SelectOption<TValue>>>;
+    accessor?: (row: TRow, index: number) => TValue | Promise<TValue>;
+    /** Renders the cell value as a string for accessibility and preset paths.
+     *  Defaults to the matching option label. */
+    getDisplayValue?: (row: TRow, index: number) => string | null | Promise<string | null>;
+    isValid?: ValidationFn<TRow>;
+    isEditable?: (row: TRow, index: number) => boolean | Promise<boolean>;
+    onEdit?: (row: TRow, value: TValue, coords: CellCoordinates) => void | Promise<void>;
+    reactiveDependencies?: (row: TRow) => ReadonlyArray<unknown>;
+}
+/** Options for `col.query({ id, header, query, ... })`. */
+export interface QueryColumnOptions<TRow extends object, K extends keyof TRow & string, TValue = TRow[K]> extends BaseColumnOptions {
+    id: K;
+    /** Async query loader; called with the current user input and expected to
+     *  return matching options. */
+    query: (input: string) => Promise<ReadonlyArray<SelectOption<TValue>>>;
+    accessor?: (row: TRow, index: number) => TValue | Promise<TValue>;
+    getDisplayValue?: (row: TRow, index: number) => string | null | Promise<string | null>;
+    isValid?: ValidationFn<TRow>;
+    isEditable?: (row: TRow, index: number) => boolean | Promise<boolean>;
+    onEdit?: (row: TRow, value: TValue, coords: CellCoordinates) => void | Promise<void>;
+    reactiveDependencies?: (row: TRow) => ReadonlyArray<unknown>;
+}
+/** Options for `col.display({ header, value, ... })`. A computed read-only
+ *  cell. Auto-generates a synthetic id. */
+export interface DisplayColumnOptions<TRow extends object, TValue = unknown> extends BaseColumnOptions {
+    /** Reads the displayed value from the row. */
+    value: (row: TRow, index: number) => TValue | Promise<TValue>;
+    /** Optional modal opened when the cell is activated; receives the row. */
+    modal?: Component<DisplayModalProps<TRow>>;
+    /** Override the auto-generated id. Rare; only useful when the consumer
+     *  needs a stable id for preset persistence or test selectors. */
+    idHint?: string;
+}
+/** Options for `col.bubble({ header, value, colour, ... })`. Renders one or
+ *  more coloured pill bubbles per row. */
+export interface BubbleColumnOptions<TRow extends object, TValue = unknown> extends BaseColumnOptions {
+    /** Per-row value(s) to render. Returning an array renders one bubble per
+     *  entry. */
+    value: (row: TRow, index: number) => TValue | ReadonlyArray<TValue> | Promise<TValue | ReadonlyArray<TValue>>;
+    /** Bubble colour. Per-value; receives both the row and the bubble's value
+     *  so multi-bubble cells can colour each independently. */
+    colour: (row: TRow, index: number, value: TValue) => BubbleColour | Promise<BubbleColour>;
+    idHint?: string;
+}
+/** Options for `col.progress({ header, value, ... })`. Renders a horizontal
+ *  progress bar from a numeric ratio. */
+export interface ProgressColumnOptions<TRow extends object> extends BaseColumnOptions {
+    /** Returns a tuple `[current, total]` or a fraction between 0 and 1. */
+    value: (row: TRow, index: number) => [number, number] | number | Promise<[number, number] | number>;
+    /** Optional colour override. Defaults to scoria's progress colour ramp. */
+    colour?: (row: TRow, index: number, fraction: number) => ColourSet | Promise<ColourSet>;
+    idHint?: string;
+}
+/** Options for `col.validity({ header, ... })`. Renders the row's overall
+ *  validity indicator and (optionally) opens a modal with the validity
+ *  details. */
+export interface ValidityColumnOptions<TRow extends object> extends BaseColumnOptions {
+    /** Per-row validity. Defaults to aggregating each column's `isValid`. */
+    isValid?: ValidationFn<TRow>;
+    /** Modal opened when the validity cell is activated. */
+    modal?: Component<DisplayModalProps<TRow>>;
+    idHint?: string;
+}
+/** Options for `col.rowSelection({ ... })`. The row-selection checkbox
+ *  column; pair with `selection: { mode: 'single' | 'multiple' }` on the
+ *  Table options. */
+export interface RowSelectionColumnOptions<TRow extends object> {
+    /** Per-row selectability gate. Overrides `selection.isSelectable` when
+     *  set; if both are present, both must return true. Async supported. */
+    isSelectable?: (row: TRow) => boolean | Promise<boolean>;
+    /** Header content for the column; defaults to the select-all checkbox. */
+    header?: string | Snippet;
+    /** Width in pixels. Defaults to a fixed compact width that matches the
+     *  checkbox's intrinsic size. */
+    width?: number;
+}
+/** Options for `col.actions({ actions, ... })`. The row-actions column;
+ *  renders a fixed list of action buttons per row. */
+export interface ActionsColumnOptions<TRow extends object> extends Omit<BaseColumnOptions, 'header'> {
+    /** Header content; defaults to an empty string. */
+    header?: string | Snippet;
+    /** Action buttons rendered per row. */
+    actions: ReadonlyArray<RowAction<TRow>>;
+    /** Per-row gate for whether any actions render at all. Async supported. */
+    isEnabled?: (row: TRow) => boolean | Promise<boolean>;
+}
+/** Single row-action entry. */
+export interface RowAction<TRow extends object> {
+    label: string;
+    icon?: string;
+    colourSet?: ColourSet;
+    /** Invoked when the action is clicked. Receives the row. */
+    callback: (row: TRow) => void | Promise<void>;
+    /** Per-row enable predicate; overrides `ActionsColumnOptions.isEnabled` for
+     *  this specific action when both are set. Async supported. */
+    isEnabled?: (row: TRow) => boolean | Promise<boolean>;
+}
+/** Options for `col.expand({ name, childRows, childRowId, childColumns })`.
+ *  Each row exposes an expand affordance that mounts an inner Table over
+ *  the inner row collection. */
+export interface ExpandColumnOptions<TRow extends object, TInner extends object, TInnerId extends Primitive = string> extends Omit<BaseColumnOptions, 'header'> {
+    /** Header content; defaults to the inner table's name. */
+    header?: string | Snippet;
+    /** Inner-table name segment used in the persistence storage key. The
+     *  factory will namespace it under the outer Table's name automatically. */
+    name: string;
+    /** Inner row collection. Async return supported. */
+    childRows: (row: TRow) => ReadonlyArray<TInner> | Promise<ReadonlyArray<TInner>>;
+    /** Inner row-id extractor. Accepts either a key on `TInner` (e.g.
+     *  `'id'`) or an extractor function. Matches the top-level `rowId`
+     *  shape on `CreateTableOptions` so callers can use the same
+     *  shorthand at every nesting level. */
+    childRowId: (keyof TInner & string) | ((inner: TInner) => TInnerId | Promise<TInnerId>);
+    /** Inner column declarations. Builder closure receives a typed
+     *  `ColumnFactory<TInner>`. */
+    childColumns: (col: ColumnFactory<TInner>) => ReadonlyArray<ColumnSpec<TInner>>;
+}
+/** Options for `col.filterOnly({ id, header, ... })`. Renders in the filter
+ *  panel only; does not produce a body cell. Useful for surfacing a
+ *  filterable field that should not occupy a column. */
+export interface FilterOnlyColumnOptions<TRow extends object, K extends keyof TRow & string, TValue = TRow[K]> extends Omit<BaseColumnOptions, 'allowSorting' | 'resizable' | 'minWidth' | 'width'> {
+    id: K;
+    /** Filter value kind; drives which filter input is rendered. */
+    filterValueType: FilterValueType;
+    /** Filter predicate for the local filter path; remote tables typically
+     *  omit this and rely on the backend instead. */
+    customFilter?: CustomFilter<TValue>;
+}
+/** Props passed to a `DisplayColumnOptions.modal` / `ValidityColumnOptions.modal`
+ *  Component. Mirrors the existing `DisplayDefModalProps` shape so consumers
+ *  can reuse their existing modal components unchanged. */
+export interface DisplayModalProps<TRow extends object> {
+    row: TRow;
+    /** Closes the modal. */
+    close: () => void;
+}

package/dist/Components/Table/Types/Public/ColumnOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/Components/Table/Types/Public/ColumnSpec.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Opaque column-declaration handle returned by every `ColumnFactory` method.
+ *
+ * Consumers never read fields off a `ColumnSpec` directly; they pass the spec
+ * (or an array of specs) into a `Table` via the `columns:` builder. The
+ * internal Table implementation unwraps the spec to recover the underlying
+ * column definition.
+ *
+ * The `kind` discriminator is exposed so consumers can build small helpers
+ * that switch on it (for example, a story or a debug overlay that lists a
+ * Table's columns). The `id` is exposed because column ids are public-grade
+ * information (they appear in DOM attributes, in saved column presets, and in
+ * filter / sort state) and are useful for logging and debugging.
+ *
+ * The implementation detail of which `ColumnDef` subclass backs each spec
+ * lives behind a non-enumerable symbol-keyed property and is not part of the
+ * public type. Phase 2 will tighten this further.
+ */
+export interface ColumnSpec<TRow extends object = object, Kind extends ColumnKind = ColumnKind> {
+    /** Discriminator literal. Useful for column-listing helpers. */
+    readonly kind: Kind;
+    /** Stable column id. Synthetic for `rowSelection`, `actions`, `expand`, and
+     *  `filterOnly` columns; equal to the consumer-supplied key for accessor
+     *  columns; equal to a builder-minted id for `display` / `bubble` /
+     *  `progress` / `validity` columns. */
+    readonly id: string;
+    /** Brand. Present to make `ColumnSpec` structurally distinct from a plain
+     *  `{ kind, id }` object literal so consumers cannot accidentally hand-roll
+     *  one. */
+    readonly _scoriaColumnSpec: true;
+    /** Phantom; carries `TRow` through the type system so the per-kind option
+     *  generics survive into the spec array's element type. Never read. */
+    readonly _row?: TRow;
+}
+/**
+ * Discriminator for `ColumnSpec`. Mirrors the names of the
+ * `ColumnFactory<TRow>` methods.
+ */
+export type ColumnKind = 'text' | 'number' | 'checkbox' | 'date' | 'select' | 'query' | 'display' | 'bubble' | 'progress' | 'validity' | 'rowSelection' | 'actions' | 'expand' | 'filterOnly';

package/dist/Components/Table/Types/Public/ColumnSpec.js

@@ -0,0 +1 @@
+export {};

package/dist/Components/Table/Types/Public/CreateTableOptions.d.ts

@@ -0,0 +1,87 @@
+import type { Primitive } from '../Context/TableInitOptions.js';
+import type { AnyEditEvent } from './AnyEditEvent.js';
+import type { ColumnFactory } from './ColumnFactory.js';
+import type { ColumnSpec } from './ColumnSpec.js';
+import type { LiteralRowIdKey } from './KeyConstraints.js';
+import type { RowSource } from './RowSource.js';
+import type { SelectionOptions } from './SelectionOptions.js';
+import type { TableInitialState } from './TableInitialState.js';
+import type { TablePersistence } from './TablePersistence.js';
+/**
+ * Top-level options accepted by `createTable<TRow, TRowId>(options)`.
+ *
+ * Layout: required fields and independent behaviour switches sit at the top
+ * level for autocomplete discoverability. Three grouped optionals
+ * (`selection`, `persistence`, `initialState`) carry coordinated multi-field
+ * concerns where the grouping is load-bearing.
+ *
+ * Every behaviour switch has a default that matches the current scoria
+ * behaviour, so a Table that omits them gets the same result it would have
+ * had under the existing API.
+ */
+export interface CreateTableOptions<TRow extends object, TRowId extends Primitive = string> {
+    /** Unique name. Used as the namespace prefix for any persisted state
+     *  (presets / settings / page size / active expand). Two Tables with the
+     *  same name on the same user share storage; if that is not intended,
+     *  vary the name per call site. */
+    name: string;
+    /** Stable row-id extractor. Function form supports composite and async
+     *  ids; literal-key form is the shortcut for the common case
+     *  `rowId: 'id'`. */
+    rowId: ((row: TRow) => TRowId | Promise<TRowId>) | LiteralRowIdKey<TRow, TRowId>;
+    /** Row data source. One of `localRows(...)`, `remoteRows(...)`, or
+     *  `customRows(...)` (or an inline object with the matching `kind`). */
+    rows: RowSource<TRow>;
+    /** Column declarations. The closure receives a typed `ColumnFactory<TRow>`;
+     *  return the column specs in memory order. */
+    columns: (col: ColumnFactory<TRow>) => ReadonlyArray<ColumnSpec<TRow>>;
+    /** Selection. Defaults to `{ mode: 'multiple' }` with internal map ownership. */
+    selection?: SelectionOptions<TRow, TRowId>;
+    /** Persistence. Defaults to all layers enabled. Pass `false` to disable
+     *  everything, an object to enable a subset. */
+    persistence?: TablePersistence;
+    /** Initial state applied before persistence hydration. Persistence wins
+     *  when both have a value for the same field. */
+    initialState?: TableInitialState<TRow>;
+    /** Toolbar position. Defaults to `'right'`. */
+    toolbar?: 'top' | 'right' | 'left' | 'none';
+    /** Whether to render the footer. Defaults to true. */
+    showFooter?: boolean;
+    /** Whether copy operations are enabled. Defaults to true. */
+    allowCopy?: boolean;
+    /** Whether columns may be user-resized. Defaults to true. */
+    allowResize?: boolean;
+    /** Whether columns may be user-reordered. Defaults to true. */
+    allowReorder?: boolean;
+    /** Whether the quick-filter (per-column inline filter) is offered.
+     *  Defaults to true. */
+    allowQuickFilter?: boolean;
+    /** Whether the advanced filter panel is offered. Defaults to true. */
+    allowAdvancedFilter?: boolean;
+    /** Whether the quick-filter input row is open at first mount. Defaults
+     *  to true. */
+    showQuickFilterByDefault?: boolean;
+    /** Clipboard format. Defaults to `'tsv'`. */
+    copyFormat?: 'tsv' | 'csv';
+    /** Whether the header row is included in copy output. Defaults to true. */
+    copyWithHeaders?: boolean;
+    /** Page-size options shown in the footer's page-size picker. Defaults to
+     *  `[10, 25, 50, 100]`. */
+    pageSizes?: ReadonlyArray<number>;
+    /** Row count above which virtualisation kicks in. Defaults to 100;
+     *  matches Phase 7.4. */
+    rowVirtualisationThreshold?: number;
+    /** Fires after every cell edit, regardless of column. Use for change
+     *  tracking, batched saves, telemetry. `value` is `unknown` at this
+     *  seam; use per-column `onEdit` for the typed value. When both are
+     *  configured, per-column fires first; `onAnyEdit` runs after the
+     *  per-column callback resolves. A per-column callback that throws or
+     *  rejects suppresses the corresponding `onAnyEdit`. */
+    onAnyEdit?: (event: AnyEditEvent<TRow>) => void | Promise<void>;
+    /** Identity for storage namespacing and remote-request authentication.
+     *  Defaults to `() => undefined`, which namespaces persisted state under
+     *  the literal segment `'anon'`. */
+    getUserId?: () => string | undefined;
+    /** Per-Table debug logging gate. Defaults to false. */
+    debug?: boolean;
+}

package/dist/Components/Table/Types/Public/CreateTableOptions.js

@@ -0,0 +1 @@
+export {};

package/dist/Components/Table/Types/Public/KeyConstraints.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Type-level helpers that constrain a column id to the subset of `keyof TRow`
+ * whose value type matches the column kind. Used by `ColumnFactory` to give
+ * `col.text({ id: ... })` an `id` autocomplete that only lists string-typed
+ * fields, `col.number({ id: ... })` an `id` autocomplete that only lists
+ * number-typed fields, and so on.
+ *
+ * Each helper is structurally equivalent to:
+ *
+ * ```ts
+ * { [K in keyof TRow & string]: NonNullable<TRow[K]> extends Kind ? K : never }[keyof TRow & string]
+ * ```
+ *
+ * with `Kind` set to `string`, `number`, `boolean`, or `Date`.
+ *
+ * The `NonNullable<...>` unwrap means optional/nullable fields are still
+ * accepted (`reference?: string` and `reference: string | null` both qualify
+ * for `text`), which matches how the existing accessor cells render nullable
+ * values. Branded primitives flow through unchanged because they structurally
+ * extend their underlying type.
+ */
+/** Subset of `keyof TRow` whose (non-nullable) value type is a string. */
+export type StringKeyOf<TRow extends object> = {
+    [K in keyof TRow & string]: NonNullable<TRow[K]> extends string ? K : never;
+}[keyof TRow & string];
+/** Subset of `keyof TRow` whose (non-nullable) value type is a number. */
+export type NumberKeyOf<TRow extends object> = {
+    [K in keyof TRow & string]: NonNullable<TRow[K]> extends number ? K : never;
+}[keyof TRow & string];
+/** Subset of `keyof TRow` whose (non-nullable) value type is a boolean. */
+export type BooleanKeyOf<TRow extends object> = {
+    [K in keyof TRow & string]: NonNullable<TRow[K]> extends boolean ? K : never;
+}[keyof TRow & string];
+/** Subset of `keyof TRow` whose (non-nullable) value type is a `Date`. */
+export type DateKeyOf<TRow extends object> = {
+    [K in keyof TRow & string]: NonNullable<TRow[K]> extends Date ? K : never;
+}[keyof TRow & string];
+/** The literal-key form of `rowId`. Narrows to the subset of `keyof TRow`
+ *  whose value type extends `TRowId`. */
+export type LiteralRowIdKey<TRow extends object, TRowId> = {
+    [K in keyof TRow & string]: TRow[K] extends TRowId ? K : never;
+}[keyof TRow & string];

package/dist/Components/Table/Types/Public/KeyConstraints.js

@@ -0,0 +1,22 @@
+/**
+ * Type-level helpers that constrain a column id to the subset of `keyof TRow`
+ * whose value type matches the column kind. Used by `ColumnFactory` to give
+ * `col.text({ id: ... })` an `id` autocomplete that only lists string-typed
+ * fields, `col.number({ id: ... })` an `id` autocomplete that only lists
+ * number-typed fields, and so on.
+ *
+ * Each helper is structurally equivalent to:
+ *
+ * ```ts
+ * { [K in keyof TRow & string]: NonNullable<TRow[K]> extends Kind ? K : never }[keyof TRow & string]
+ * ```
+ *
+ * with `Kind` set to `string`, `number`, `boolean`, or `Date`.
+ *
+ * The `NonNullable<...>` unwrap means optional/nullable fields are still
+ * accepted (`reference?: string` and `reference: string | null` both qualify
+ * for `text`), which matches how the existing accessor cells render nullable
+ * values. Branded primitives flow through unchanged because they structurally
+ * extend their underlying type.
+ */
+export {};

package/dist/Components/Table/Types/Public/RowSource.d.ts

@@ -0,0 +1,87 @@
+import type { RefWrapper } from '../../../../Types/Internal/RefWrapper.js';
+import type { ColumnFiltersState } from '../Filtering/ColumnFiltersState.js';
+import type { SortingState } from '../DataRepository/SortingState.js';
+/**
+ * Data source for a Table. One of three variants:
+ *
+ * - `local`: in-memory array, optionally `$state`-reactive.
+ * - `remote`: HTTP endpoint with library-managed pagination, filter, and sort
+ *   serialisation. Replaces the per-consumer remote-repository boilerplate.
+ * - `custom`: full control via a consumer-supplied `fetch` function. The
+ *   library calls it on every pagination / filter / sort change with an
+ *   `AbortSignal` for cancellation.
+ *
+ * The `kind` discriminator is what the implementation switches on. The two
+ * helper exports `localRows(...)` and `remoteRows(...)` (defined in the
+ * factory module) stamp the `kind` literal so consumers do not have to
+ * remember which string to write.
+ */
+export type RowSource<TRow extends object> = LocalRowSource<TRow> | RemoteRowSource<TRow> | CustomRowSource<TRow>;
+/** In-memory row source. */
+export interface LocalRowSource<TRow extends object> {
+    kind: 'local';
+    /** Source array. A `RefWrapper<Array<TRow>>` is reactive (the Table picks
+     *  up mutations and reassignments); a plain array is a snapshot at init
+     *  time. */
+    source: RefWrapper<Array<TRow>> | ReadonlyArray<TRow>;
+    /** Optional pre-filter applied before user-driven column filters. Use for
+     *  permanent visibility rules (e.g. "exclude archived rows"). */
+    initialFilter?: (row: TRow) => boolean;
+}
+/** Remote row source. The library handles URL construction, filter encoding,
+ *  page-size persistence, debounced reload, and abort-on-supersession. */
+export interface RemoteRowSource<TRow extends object> {
+    kind: 'remote';
+    /** Endpoint URL. May be a path (joined onto the application origin) or an
+     *  absolute URL. */
+    endpoint: string;
+    /** HTTP method. Defaults to `'GET'`. `'POST'` puts pagination / filter /
+     *  sort state into the request body alongside any caller-supplied body
+     *  shape via `filterEncoding`. */
+    method?: 'GET' | 'POST';
+    /** Filters merged into every request. Useful for permanent context such as
+     *  the current warehouse or tenant id. Re-evaluated per request, so a
+     *  reactive read here triggers a reload. */
+    defaultFilters?: () => Record<string, unknown>;
+    /** Transforms a raw response into the row array and total row count. If
+     *  omitted, the library expects `{ rows: TRow[]; totalRows: number }` and
+     *  reports a clear error if the shape does not match. */
+    responseTransform?: (raw: unknown) => {
+        rows: ReadonlyArray<TRow>;
+        totalRows: number;
+    };
+    /** Encoding strategy for pagination, filters, and sort. Defaults to
+     *  `'query-string'`. Pass a custom function for full control. */
+    filterEncoding?: 'query-string' | 'json-body' | {
+        encode: (request: Pick<RowFetchRequest, 'page' | 'pageSize' | 'filters' | 'sort'>) => RequestInit;
+    };
+    /** Per-request headers. Authentication tokens, content negotiation, etc.
+     *  Invoked once per request. */
+    headers?: () => Record<string, string>;
+    /** Debounce window in milliseconds before issuing a request after the
+     *  state changes. Defaults to 300 ms while a filter input has focus,
+     *  0 ms otherwise. Pass `false` to disable. */
+    reloadDebounce?: number | false;
+}
+/** Custom row source. Consumer-supplied `fetch` is called on every
+ *  pagination / filter / sort change. */
+export interface CustomRowSource<TRow extends object> {
+    kind: 'custom';
+    /** Called whenever the Table needs new rows. The library passes an
+     *  `AbortSignal` so consumers can cancel an in-flight request when its
+     *  result is superseded. */
+    fetch: (request: RowFetchRequest) => Promise<RowFetchResponse<TRow>>;
+}
+/** Argument passed to `CustomRowSource.fetch`. */
+export interface RowFetchRequest {
+    page: number;
+    pageSize: number;
+    filters: ColumnFiltersState;
+    sort: SortingState;
+    signal: AbortSignal;
+}
+/** Return value of `CustomRowSource.fetch`. */
+export interface RowFetchResponse<TRow> {
+    rows: ReadonlyArray<TRow>;
+    totalRows: number;
+}

package/dist/Components/Table/Types/Public/RowSource.js

@@ -0,0 +1 @@
+export {};

package/dist/Components/Table/Types/Public/SelectionOptions.d.ts

@@ -0,0 +1,26 @@
+import type { SvelteMap } from 'svelte/reactivity';
+import type { Primitive } from '../Context/TableInitOptions.js';
+/**
+ * Selection configuration. Decided at construction time and immutable for the
+ * lifetime of the Table. Late binding via a `setSelectionMap`-style method is
+ * deliberately not supported; the construction-time form covers every audited
+ * use case in the consumer.
+ *
+ * Default when omitted: `{ mode: 'multiple' }` with internal map ownership.
+ *
+ * `bindTo` is the externally-owned-map form: pass a `SvelteMap<TRowId, TRow>`
+ * and the Table writes through to it. Reads from `table.selection.map` return
+ * the same map reference. Useful when a wizard step or modal owns the
+ * selection state and needs it to outlive the Table mount.
+ */
+export type SelectionOptions<TRow extends object, TRowId extends Primitive> = {
+    mode: 'none';
+} | {
+    mode: 'single' | 'multiple';
+    /** Per-row selectability predicate. Defaults to `() => true`. Async
+     *  return supported. */
+    isSelectable?: (row: TRow) => boolean | Promise<boolean>;
+    /** External map to write selections through. When omitted, the Table
+     *  owns its own internal `SvelteMap`. */
+    bindTo?: SvelteMap<TRowId, TRow>;
+};

package/dist/Components/Table/Types/Public/SelectionOptions.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,39 @@
+import type { Primitive } from '../Context/TableInitOptions.js';
+import type { ClipboardApi, ColumnsApi, FilteringApi, FocusApi, PaginationApi, PreferencesApi, SelectionApi, SortingApi } from './TableSubApis.js';
+/**
+ * Public Table instance returned by `createTable(...)`. Mount the underlying
+ * Table component via `<Table {table} />`; the structured object below is
+ * the surface every consumer reads and writes against.
+ *
+ * The interface is reactive throughout: `table.rows` re-runs the consumer's
+ * expression whenever the current page or filter state changes;
+ * `table.selection.map` is the underlying `SvelteMap` (whether internally
+ * owned or externally bound via `selection.bindTo`); each sub-API is a thin
+ * facade over the corresponding internal sub-context.
+ *
+ * Lifecycle: `reload()` is a no-op for local tables and forwards to the
+ * underlying fetch for remote / custom tables. `destroy()` is currently a
+ * no-op; Phase 2 introduces a real teardown hook when `<Table>` consumes the
+ * structured instance directly.
+ */
+export interface Table<TRow extends object, TRowId extends Primitive> {
+    readonly name: string;
+    /** Current page of rows. Post-filter, post-sort, paginated. Reactive. */
+    readonly rows: ReadonlyArray<TRow>;
+    /** Total row count across every page after filtering. Reactive. */
+    readonly totalRows: number;
+    /** Whether the underlying data source is currently fetching. Reactive. */
+    readonly isLoading: boolean;
+    readonly columns: ColumnsApi<TRow>;
+    readonly selection: SelectionApi<TRow, TRowId>;
+    readonly filtering: FilteringApi<TRow>;
+    readonly sorting: SortingApi<TRow>;
+    readonly pagination: PaginationApi;
+    readonly focus: FocusApi<TRow>;
+    readonly preferences: PreferencesApi<TRow>;
+    readonly clipboard: ClipboardApi<TRow>;
+    /** Trigger a refetch (remote / custom) or a recompute (local). */
+    reload(): Promise<void>;
+    /** Tear down any subscriptions and abort in-flight requests. */
+    destroy(): void;
+}

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

@@ -0,0 +1 @@
+export {};

package/dist/Components/Table/Types/Public/TableInitialState.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Initial state applied to a Table immediately after construction, before
+ * any persisted state is loaded. When both `initialState` and persistence
+ * have a value for the same field, persistence wins (so user-saved presets
+ * survive a code change to `initialState`).
+ *
+ * Every field is optional. Omitted fields fall through to the default state
+ * the Table would otherwise have used.
+ */
+export interface TableInitialState<TRow extends object> {
+    /** Initial sort. Multiple entries express multi-column sort with the
+     *  first entry as the primary sort key. */
+    sortBy?: ReadonlyArray<{
+        id: keyof TRow & string;
+        /** When omitted, defaults to ascending. */
+        desc?: boolean;
+    }>;
+    /** Initial column filters keyed by column id. Use values of the same
+     *  shape the column's filter input would produce. */
+    filters?: ReadonlyMap<string, unknown>;
+    /** Initial column visibility. Keys are column ids; missing keys retain the
+     *  column's `defaultHidden` value. */
+    columnVisibility?: Partial<Record<string, boolean>>;
+    /** Whether to start in compact mode. */
+    compact?: boolean;
+}

package/dist/Components/Table/Types/Public/TableInitialState.js

@@ -0,0 +1 @@
+export {};