@lavalogic/scoria 0.36.0 → 0.37.0

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

@@ -0,0 +1,38 @@
+/**
+ * Per-Table persistence configuration. Every field defaults to `true`. Pass
+ * the literal `false` to disable persistence entirely (no storage reads, no
+ * storage writes); pass an object to enable a subset.
+ *
+ * Storage namespace is `scoria-table:<userId|'anon'>:<name>:<suffix>` as
+ * established in Phase 5 Group 6. The `name` segment is the Table's `name`
+ * option passed to `createTable`; the `userId` segment is whatever
+ * `getUserId()` returns at the time of the read or write, or the literal
+ * `'anon'` when it returns undefined.
+ */
+export type TablePersistence = boolean | TablePersistenceObject;
+/** Object form of `TablePersistence`. Use when enabling some layers and
+ *  disabling others; the boolean form is the all-or-nothing shortcut. */
+export interface TablePersistenceObject {
+    /** Saved column presets (visibility / pinning / sizing snapshots). Default
+     *  true. */
+    presets?: boolean;
+    /** User-controlled table settings (compact mode, alternate row colours,
+     *  single-click editing, etc.). Default true. */
+    settings?: boolean;
+    /** Last-selected page size. Default true. */
+    pageSize?: boolean;
+    /** Currently-expanded sub-table id (when the table has `ExpandDef`
+     *  columns). Default true. */
+    activeExpand?: boolean;
+    /** Custom storage backend. Useful for tests; defaults to `localStorage`
+     *  for presets and settings, `sessionStorage` for active state. */
+    storage?: TableStorageAdapter;
+}
+/** Storage backend hook for tests and custom persistence. Mirrors the subset
+ *  of the `Storage` interface scoria actually uses; matches the existing
+ *  internal contract so swapping a real backend in is a single-line change. */
+export interface TableStorageAdapter {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}

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

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

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

@@ -0,0 +1,157 @@
+import type { SvelteMap } from 'svelte/reactivity';
+import type { CellCoordinates } from '../Coordinates/CellCoordinates.js';
+import type { ColumnFiltersState } from '../Filtering/ColumnFiltersState.js';
+import type { ColumnPinningState } from '../Columns/ColumnPinningState.js';
+import type { ColumnSizingState } from '../Columns/ColumnSizingState.js';
+import type { FilterMode } from '../Filtering/FilterMode.js';
+import type { Primitive } from '../Context/TableInitOptions.js';
+import type { SortingState } from '../DataRepository/SortingState.js';
+import type { TableSettings } from '../Context/TableSettings.js';
+import type { VisibilityState } from '../Columns/VisibilityState.js';
+import type { ColumnSpec } from './ColumnSpec.js';
+/**
+ * Public sub-API surface of a `Table<TRow, TRowId>` instance. Each interface
+ * here is the canonical consumer-facing replacement for one of the Phase 6
+ * internal sub-contexts (`_selection`, `_filtering`, `_columnLayout`,
+ * `_preferences`, `_focus`, `_sorting`, plus pagination and clipboard which
+ * stayed on `TableContext` proper).
+ *
+ * The interfaces are intentionally narrower than the underlying internals.
+ * Methods that exist purely for internal lifecycle reasons (boot-time
+ * hydration, abort-controller plumbing, the per-row mutation rebind path)
+ * are not surfaced here. If a consumer use case appears that needs one of
+ * those, surface it explicitly on the matching sub-API rather than exposing
+ * the internal symbol.
+ *
+ * Every field is reactive: reading triggers the Svelte 5 reactivity graph
+ * just as it does for the underlying `$state`/`$derived` slot on the
+ * implementation. Writes go through the listed setter methods.
+ */
+export interface SelectionApi<TRow extends object, TRowId extends Primitive> {
+    /** Live selection map. Reactive; identical reference whether selection is
+     *  internally owned or externally bound. */
+    readonly map: SvelteMap<TRowId, TRow>;
+    /** Number of selected rows. Reactive convenience read. */
+    readonly size: number;
+    /** Per-row toggle. Honours `isSelectable`; no-ops when false. */
+    toggle(row: TRow): void;
+    /** Set or clear selection for a single row. */
+    set(rowId: TRowId, row: TRow): void;
+    delete(rowId: TRowId): void;
+    clear(): void;
+    values(): IterableIterator<TRow>;
+    keys(): IterableIterator<TRowId>;
+    entries(): IterableIterator<[TRowId, TRow]>;
+    /** Selects every row on the current page that passes `isSelectable`. */
+    selectAll(): void;
+    /** Map of selected rows whose `isValid` returned `Validity.Invalid`. */
+    readonly invalidMap: SvelteMap<TRowId, TRow>;
+    /** Convenience: `invalidMap.size > 0`. */
+    readonly hasInvalid: boolean;
+}
+export interface FilteringApi<TRow extends object> {
+    /** Current column-filter state. Reactive. */
+    readonly state: ColumnFiltersState;
+    /** Set or clear the filter for a single column. */
+    set(columnId: keyof TRow & string, value: unknown): void;
+    /** Reset every column's filter to its default. */
+    reset(): void;
+    /** Change the filter mode (e.g. `'contains'` vs `'starts-with'`) for a
+     *  string column or `'between'` for a number / date column. */
+    setMode(columnId: keyof TRow & string, mode: FilterMode): void;
+    /** Whether the quick-filter input row is visible. */
+    showQuickFilter: boolean;
+    /** Whether the table is showing only selected rows. */
+    showSelectedOnly: boolean;
+}
+export interface SortingApi<TRow extends object> {
+    /** Current sort state. Reactive. */
+    readonly state: SortingState;
+    /** Set the sort for a single column. When `desc` is omitted, ascending. */
+    setSort(columnId: keyof TRow & string, desc?: boolean): void;
+    /** Clear sorting on every column. */
+    clear(): void;
+}
+export interface PaginationApi {
+    readonly page: number;
+    readonly pageSize: number;
+    readonly totalPages: number;
+    readonly totalRows: number;
+    next(): void;
+    prev(): void;
+    goTo(page: number): void;
+    setPageSize(size: number): void;
+}
+export interface ColumnsApi<TRow extends object> {
+    /** Ordered column specs in memory order. */
+    readonly specs: ReadonlyArray<ColumnSpec<TRow>>;
+    /** Lookup map by column id. */
+    readonly byId: ReadonlyMap<string, ColumnSpec<TRow>>;
+    /** Visual order of column ids (pinned-left -> centre -> pinned-right,
+     *  excluding hidden columns). */
+    readonly visualOrder: ReadonlyArray<string>;
+    /** Current visibility map. */
+    readonly visibility: VisibilityState;
+    /** Current pinning map. */
+    readonly pinning: ColumnPinningState;
+    /** Current sizing map. */
+    readonly sizing: ColumnSizingState;
+    setVisibility(columnId: string, visible: boolean): void;
+    setPinning(columnId: string, side: 'left' | 'right' | 'none'): void;
+    resize(columnId: string, width: number): void;
+    reorder(fromIndex: number, toIndex: number): void;
+}
+export interface FocusApi<TRow extends object> {
+    /** Start of the focused range, or `undefined` when no cell is focused. */
+    readonly start: CellCoordinates | undefined;
+    /** End of the focused range (equals `start` for single-cell focus). */
+    readonly end: CellCoordinates | undefined;
+    /** Whether the focused cell is currently in edit mode. */
+    readonly isEditing: boolean;
+    /** Move focus to a specific cell. */
+    moveTo(row: number, column: number): void;
+    /** Clear focus. */
+    clear(): void;
+    /** Phantom; carries the row type through the API so generic inference
+     *  flows from `Table<TRow, ...>` into focus callbacks. Never read. */
+    readonly _row?: TRow;
+}
+/** Stored preset shape. Mirrors the existing internal `JSONColumnDefSet`. */
+export interface SavedPreset {
+    readonly name: string;
+    readonly savedAt: string;
+    readonly columns: ReadonlyArray<{
+        readonly id: string;
+        readonly visible: boolean;
+        readonly width: number;
+        readonly pinned: 'left' | 'right' | 'none';
+    }>;
+}
+export interface PreferencesApi<TRow extends object> {
+    /** Saved column presets. Reactive. */
+    readonly presets: ReadonlyArray<SavedPreset>;
+    /** Currently-applied preset, or `undefined`. */
+    readonly selectedPreset: SavedPreset | undefined;
+    savePreset(name: string): void;
+    applyPreset(preset: SavedPreset): void;
+    deletePreset(name: string): void;
+    /** Live table settings (compact mode, etc). Reading via `.settings.x`
+     *  is reactive; writing via the per-field setters below persists. */
+    readonly settings: Readonly<TableSettings>;
+    compact: boolean;
+    alternateRowColours: boolean;
+    singleClickEditing: boolean;
+    changeColourOnHover: boolean;
+    copyWithHeaders: boolean;
+    commaSeparatedCopy: boolean;
+    /** Phantom; carries the row type. */
+    readonly _row?: TRow;
+}
+export interface ClipboardApi<TRow extends object> {
+    /** Copy the current selection to the clipboard. */
+    copySelection(): Promise<void>;
+    /** Copy the currently-highlighted range. */
+    copyHighlighted(): Promise<void>;
+    /** Copy a single cell. */
+    copyCell(row: TRow, columnId: string): Promise<void>;
+}

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

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

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

@@ -0,0 +1,20 @@
+/**
+ * Barrel re-export of every public Table API type. Imported by
+ * `src/lib/index.ts` and by sub-deliverable 1.2's `ColumnFactory`
+ * runtime module.
+ *
+ * Phase 1 is type-only; no runtime symbols flow through this barrel.
+ */
+export type { AnyEditEvent } from './AnyEditEvent.js';
+export type { BaseColumnOptions } from './BaseColumnOptions.js';
+export type { ColumnFactory } from './ColumnFactory.js';
+export type { ActionsColumnOptions, BubbleColumnOptions, CheckboxColumnOptions, DateColumnOptions, DisplayColumnOptions, DisplayModalProps, ExpandColumnOptions, FilterOnlyColumnOptions, NumberColumnOptions, ProgressColumnOptions, QueryColumnOptions, RowAction, RowSelectionColumnOptions, SelectColumnOptions, TextColumnOptions, ValidityColumnOptions, } from './ColumnOptions.js';
+export type { ColumnKind, ColumnSpec } from './ColumnSpec.js';
+export type { CreateTableOptions } from './CreateTableOptions.js';
+export type { BooleanKeyOf, DateKeyOf, LiteralRowIdKey, NumberKeyOf, StringKeyOf, } from './KeyConstraints.js';
+export type { CustomRowSource, LocalRowSource, RemoteRowSource, RowFetchRequest, RowFetchResponse, RowSource, } from './RowSource.js';
+export type { SelectionOptions } from './SelectionOptions.js';
+export type { Table } from './Table.js';
+export type { TableInitialState } from './TableInitialState.js';
+export type { TablePersistence, TablePersistenceObject, TableStorageAdapter, } from './TablePersistence.js';
+export type { ClipboardApi, ColumnsApi, FilteringApi, FocusApi, PaginationApi, PreferencesApi, SavedPreset, SelectionApi, SortingApi, } from './TableSubApis.js';

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

@@ -0,0 +1,8 @@
+/**
+ * Barrel re-export of every public Table API type. Imported by
+ * `src/lib/index.ts` and by sub-deliverable 1.2's `ColumnFactory`
+ * runtime module.
+ *
+ * Phase 1 is type-only; no runtime symbols flow through this barrel.
+ */
+export {};

package/dist/Components/Table/Types/Toolbar/ToolbarPosition.d.ts

@@ -1,3 +1,7 @@
+/**
+ * Placement of the table's toolbar. Set via `TableInitOptions.toolbar`
+ * (defaults to `Right` when the option is omitted).
+ */
 export declare const ToolbarPosition: {
     readonly None: "None";
     readonly Left: "Left";

package/dist/Components/Table/Types/Toolbar/ToolbarPosition.js

@@ -1,7 +1,11 @@
+/**
+ * Placement of the table's toolbar. Set via `TableInitOptions.toolbar`
+ * (defaults to `Right` when the option is omitted).
+ */
 export const ToolbarPosition = {
     None: 'None',
     Left: 'Left',
     Top: 'Top',
-    Right: 'Right'
+    Right: 'Right',
 };
 Object.freeze(ToolbarPosition);

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

@@ -0,0 +1,53 @@
+/**
+ * `createTable` is the entry point for the new public Table API. It accepts
+ * a single options object and returns a structured `Table<TRow, TRowId>`
+ * instance.
+ *
+ * Phase 1 implementation strategy: this function is a thin facade. It
+ * unwraps the column specs, constructs the existing internal repository
+ * (`LocalTableDataRepository` for `kind: 'local'`, the new
+ * `BuiltInRemoteRepository` for `kind: 'remote'`, an adapter for
+ * `kind: 'custom'`), invokes `TableContext.init`, wires the per-column
+ * edit handlers and the optional `onAnyEdit` observer, then returns a
+ * structured `Table` instance whose sub-APIs are facades over the Phase 6
+ * sub-contexts. Phase 2 will inline the internals.
+ *
+ * The structured `Table` instance is also exposed as the `_context` field
+ * for the Phase 1 `<Table>` component which still reads from a
+ * `TableContext` via `setContext`. Phase 2 reshapes `<Table>` to consume
+ * the structured instance directly.
+ */
+import { TableContext } from './Types/Context/TableContext.svelte.js';
+import type { Primitive } from './Types/Context/TableInitOptions.js';
+import type { CreateTableOptions } from './Types/Public/CreateTableOptions.js';
+import type { CustomRowSource, LocalRowSource, RemoteRowSource } from './Types/Public/RowSource.js';
+import type { Table } from './Types/Public/Table.js';
+/**
+ * Construct a new Table from the supplied options. Returns the structured
+ * `Table<TRow, TRowId>` instance. Mount the rendering component via
+ * `<Table {table} />` (Phase 1 also accepts the legacy
+ * `<Table tableContext={table._context} />` form).
+ *
+ * @example
+ * ```ts
+ * const table = createTable<PickWave>({
+ *   name: 'pick-waves',
+ *   rowId: 'id',
+ *   rows: { kind: 'local', source: dataRef },
+ *   columns: (col) => [
+ *     col.rowSelection(),
+ *     col.text({ id: 'reference', header: 'Reference' }),
+ *     col.number({ id: 'lineCount', header: 'Lines' }),
+ *   ],
+ * });
+ * ```
+ */
+export declare function createTable<TRow extends object, TRowId extends Primitive = string>(options: CreateTableOptions<TRow, TRowId>): Table<TRow, TRowId> & {
+    readonly _context: TableContext<TRow, TRowId>;
+};
+/** Helper that stamps `kind: 'local'` for type-safe row-source construction. */
+export declare function localRows<TRow extends object>(options: Omit<LocalRowSource<TRow>, 'kind'>): LocalRowSource<TRow>;
+/** Helper that stamps `kind: 'remote'`. */
+export declare function remoteRows<TRow extends object>(options: Omit<RemoteRowSource<TRow>, 'kind'>): RemoteRowSource<TRow>;
+/** Helper that stamps `kind: 'custom'`. */
+export declare function customRows<TRow extends object>(options: Omit<CustomRowSource<TRow>, 'kind'>): CustomRowSource<TRow>;

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

@@ -0,0 +1,269 @@
+/**
+ * `createTable` is the entry point for the new public Table API. It accepts
+ * a single options object and returns a structured `Table<TRow, TRowId>`
+ * instance.
+ *
+ * Phase 1 implementation strategy: this function is a thin facade. It
+ * unwraps the column specs, constructs the existing internal repository
+ * (`LocalTableDataRepository` for `kind: 'local'`, the new
+ * `BuiltInRemoteRepository` for `kind: 'remote'`, an adapter for
+ * `kind: 'custom'`), invokes `TableContext.init`, wires the per-column
+ * edit handlers and the optional `onAnyEdit` observer, then returns a
+ * structured `Table` instance whose sub-APIs are facades over the Phase 6
+ * sub-contexts. Phase 2 will inline the internals.
+ *
+ * The structured `Table` instance is also exposed as the `_context` field
+ * for the Phase 1 `<Table>` component which still reads from a
+ * `TableContext` via `setContext`. Phase 2 reshapes `<Table>` to consume
+ * the structured instance directly.
+ */
+import { devCatch, refWrapper } from '../../Helpers/Helpers.svelte.js';
+import { BuiltInRemoteRepository, CustomRemoteRepository, } from './Types/DataRepository/BuiltInRemoteRepository.svelte.js';
+import { LocalTableDataRepository } from './Types/DataRepository/LocalTableDataRepository.svelte.js';
+import { TableContext } from './Types/Context/TableContext.svelte.js';
+import { ToolbarPosition } from './Types/Toolbar/ToolbarPosition.js';
+import { createColumnFactory, unwrapColumnSpec } from './ColumnFactory.svelte.js';
+import { makeClipboardApi, makeColumnsApi, makeFilteringApi, makeFocusApi, makePaginationApi, makePreferencesApi, makeSelectionApi, makeSortingApi, } from './SubApis.svelte.js';
+// ─────────────────────────────────────────────────────────────────────────
+// Public entry point
+// ─────────────────────────────────────────────────────────────────────────
+/**
+ * Construct a new Table from the supplied options. Returns the structured
+ * `Table<TRow, TRowId>` instance. Mount the rendering component via
+ * `<Table {table} />` (Phase 1 also accepts the legacy
+ * `<Table tableContext={table._context} />` form).
+ *
+ * @example
+ * ```ts
+ * const table = createTable<PickWave>({
+ *   name: 'pick-waves',
+ *   rowId: 'id',
+ *   rows: { kind: 'local', source: dataRef },
+ *   columns: (col) => [
+ *     col.rowSelection(),
+ *     col.text({ id: 'reference', header: 'Reference' }),
+ *     col.number({ id: 'lineCount', header: 'Lines' }),
+ *   ],
+ * });
+ * ```
+ */
+export function createTable(options) {
+    // ── 1. Resolve rowId ────────────────────────────────────────────
+    const rowIdFn = resolveRowId(options.rowId);
+    // ── 2. Run the column-builder closure ───────────────────────────
+    const factory = createColumnFactory();
+    const specs = options.columns(factory);
+    // Build a Map<columnId, ColumnSpec> for the ColumnsApi, plus a
+    // Map<columnId, perColumnOnEdit> for the onEditCell dispatcher.
+    // These are constructed once during init and never reassigned reactively,
+    // so a plain Map is correct here.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    const specsById = new Map();
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    const editHandlers = new Map();
+    const defs = specs.map((spec) => {
+        specsById.set(spec.id, spec);
+        const internal = unwrapColumnSpec(spec);
+        if (internal.onEdit) {
+            editHandlers.set(spec.id, internal.onEdit);
+        }
+        return internal.def;
+    });
+    const defsWrapper = { defs };
+    // ── 3. Construct the repository for the chosen row source ──────
+    const repository = makeRepository(options.name, options.rows, options.getUserId);
+    // ── 4. Build the `onEditCell` wrapper ──────────────────────────
+    const onEditCell = makeOnEditCell(editHandlers, options.onAnyEdit);
+    // ── 5. Translate the new options to TableInitOptions ───────────
+    const initOptions = {
+        selectionExtractor: rowIdFn,
+        getUserId: options.getUserId ?? (() => undefined),
+        allowCopy: options.allowCopy,
+        enableResize: options.allowResize,
+        allowColumnReordering: options.allowReorder,
+        allowQuickFiltering: options.allowQuickFilter,
+        showQuickFilterByDefault: options.showQuickFilterByDefault,
+        allowAdvancedFiltering: options.allowAdvancedFilter,
+        toolbar: translateToolbar(options.toolbar),
+        displayFooter: options.showFooter,
+        onEditCell,
+        debug: options.debug,
+    };
+    // ── 6. Build the TableContext ──────────────────────────────────
+    const ctx = TableContext.init(defsWrapper, options.name, repository, initOptions);
+    // ── 7. Wire selection.bindTo (Phase 1 uses the existing setter) ─
+    if (options.selection && options.selection.mode !== 'none' && options.selection.bindTo) {
+        ctx.setSelectionMap(options.selection.bindTo);
+    }
+    // ── 8. Apply initialState ───────────────────────────────────────
+    if (options.initialState) {
+        applyInitialState(ctx, options.initialState);
+    }
+    // ── 9. Build the structured Table instance ─────────────────────
+    const table = Object.freeze({
+        get name() {
+            return ctx.tableName;
+        },
+        get rows() {
+            return ctx.currentPageData;
+        },
+        get totalRows() {
+            return ctx.dataRepo.totalRows;
+        },
+        get isLoading() {
+            return ctx.dataRepo.isLoading ?? false;
+        },
+        columns: makeColumnsApi(ctx, specsById),
+        selection: makeSelectionApi(ctx),
+        filtering: makeFilteringApi(ctx),
+        sorting: makeSortingApi(ctx),
+        pagination: makePaginationApi(ctx),
+        focus: makeFocusApi(ctx),
+        preferences: makePreferencesApi(ctx),
+        clipboard: makeClipboardApi(ctx),
+        reload() {
+            return ctx.dataRepo.reload?.() ?? Promise.resolve();
+        },
+        destroy() {
+            // Phase 1: no teardown hook exists on TableContext. Phase 2 will
+            // introduce one when <Table> consumes the structured instance.
+        },
+        _context: ctx,
+    });
+    return table;
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Row-source helpers (nominal `kind` stampers)
+// ─────────────────────────────────────────────────────────────────────────
+/** Helper that stamps `kind: 'local'` for type-safe row-source construction. */
+export function localRows(options) {
+    return { kind: 'local', ...options };
+}
+/** Helper that stamps `kind: 'remote'`. */
+export function remoteRows(options) {
+    return { kind: 'remote', ...options };
+}
+/** Helper that stamps `kind: 'custom'`. */
+export function customRows(options) {
+    return { kind: 'custom', ...options };
+}
+// ─────────────────────────────────────────────────────────────────────────
+// Internals
+// ─────────────────────────────────────────────────────────────────────────
+/** Resolve the `rowId` option (function form or literal-key form) to a
+ *  uniform `(row) => TRowId | Promise<TRowId>` function. */
+function resolveRowId(rowId) {
+    if (typeof rowId === 'function') {
+        return rowId;
+    }
+    const key = rowId;
+    return (row) => row[key];
+}
+/** Construct the underlying `IDataRepository<TRow>` for the chosen row
+ *  source variant. */
+function makeRepository(tableName, source, getUserId) {
+    const userIdFn = getUserId ?? (() => undefined);
+    switch (source.kind) {
+        case 'local': {
+            const raw = source.source;
+            const dataRef = Array.isArray(raw)
+                ? refWrapper(Array.from(raw))
+                : raw;
+            return new LocalTableDataRepository(tableName, dataRef, userIdFn);
+        }
+        case 'remote': {
+            const repo = new BuiltInRemoteRepository({
+                tableName,
+                getUserId: userIdFn,
+                endpoint: source.endpoint,
+                method: source.method,
+                defaultFilters: source.defaultFilters,
+                responseTransform: source.responseTransform,
+                filterEncoding: source.filterEncoding,
+                headers: source.headers,
+                reloadDebounce: source.reloadDebounce,
+            });
+            // Fire the first fetch immediately so the table shows real data
+            // on mount. Errors route to devCatch inside the repository.
+            void repo.reload();
+            return repo;
+        }
+        case 'custom': {
+            const repo = new CustomRemoteRepository(tableName, userIdFn, source.fetch);
+            void repo.reload();
+            return repo;
+        }
+    }
+}
+/** Build the `onEditCell` wrapper. Dispatches to the per-column `onEdit`
+ *  (from the column factory) first; if that resolves successfully and the
+ *  consumer supplied a top-level `onAnyEdit`, fires that next. A per-column
+ *  callback that throws or rejects suppresses the corresponding
+ *  `onAnyEdit`. */
+function makeOnEditCell(editHandlers, onAnyEdit) {
+    if (editHandlers.size === 0 && !onAnyEdit) {
+        return () => {
+            /* no-op: no edit handlers wired */
+        };
+    }
+    return async (item, coords, value) => {
+        const handler = editHandlers.get(coords.id);
+        if (handler) {
+            try {
+                await handler(item, value, coords);
+            }
+            catch (e) {
+                devCatch(e);
+                // Suppress onAnyEdit on per-column failure (documented behaviour).
+                return;
+            }
+        }
+        if (onAnyEdit) {
+            try {
+                await onAnyEdit({ column: coords.id, value, row: item, coords });
+            }
+            catch (e) {
+                devCatch(e);
+            }
+        }
+    };
+}
+/** Translate the public `toolbar` string into the internal
+ *  `ToolbarPosition` enum value. */
+function translateToolbar(toolbar) {
+    if (!toolbar) {
+        return undefined;
+    }
+    switch (toolbar) {
+        case 'top':
+            return ToolbarPosition.Top;
+        case 'right':
+            return ToolbarPosition.Right;
+        case 'left':
+            return ToolbarPosition.Left;
+        case 'none':
+            return ToolbarPosition.None;
+    }
+}
+/** Apply the `initialState` options to a freshly-constructed TableContext.
+ *  Phase 1 wires the subset of fields the existing sub-contexts already
+ *  support; Phase 2 may extend the surface. */
+function applyInitialState(ctx, state) {
+    if (state.sortBy && state.sortBy.length > 0) {
+        ctx.dataRepo.updateSorting?.(state.sortBy.map((s) => ({ id: s.id, desc: s.desc ?? false })));
+    }
+    if (state.filters && state.filters.size > 0) {
+        for (const [columnId, value] of state.filters) {
+            ctx.dataRepo.filterBy(columnId, value);
+        }
+    }
+    if (state.columnVisibility) {
+        ctx._columnLayout.columnVisibility = {
+            ...ctx._columnLayout.columnVisibility,
+            ...state.columnVisibility,
+        };
+    }
+    if (state.compact !== undefined) {
+        ctx.setIsCompact(state.compact);
+    }
+}