@lavalogic/scoria 0.36.0 → 0.37.1

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

@@ -1,3 +1,20 @@
 import type { Validity } from '../../../../../Types/Internal/Validity.js';
 import type { ValidityWrapper } from '../../../../../Types/Internal/ValidityWrapper.js';
+/**
+ * Per-row validity callback supplied via `ColumnDef.isValid`. Receives the
+ * row and a flag indicating whether the row is currently selected (which
+ * may itself be a `Promise` if `selectionExtractor` is async).
+ *
+ * The return union is asymmetric: the synchronous path may resolve to a
+ * plain `Validity` enum value or a `ValidityWrapper` with a `reason` string,
+ * while the asynchronous path wraps both possibilities in a Promise. The
+ * normalised form would be `Validity | ValidityWrapper |
+ * Promise<Validity | ValidityWrapper>`; this is a non-breaking renaming of
+ * the existing union and is deferred to the dedicated workorder (`ValidationFn`
+ * P2 finding).
+ *
+ * Security note: a throw inside the synchronous part propagates into the
+ * caller's effect. Wrapping callers in a `try`/`catch` fence is deferred to
+ * the centralised `safeCallerFn` work.
+ */
 export type ValidationFn<T> = (item: T, isSelected: boolean | Promise<boolean>) => Validity | Promise<Validity | ValidityWrapper> | ValidityWrapper;

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

@@ -1,5 +1,15 @@
 import type { CustomRemoteFilters } from '../Filtering/CustomRemoteFilters.js';
 import type { ColumnDef } from './Definitions/ColumnDef.svelte.js';
+/**
+ * Container returned by every column-defs factory (e.g.
+ * `generateExampleItemColumnDefs`). Holds the array of `ColumnDef` instances
+ * for a given table plus any custom remote-filter providers.
+ *
+ * `remoteFilters` is typed `CustomRemoteFilters<unknown>` because the wrapper
+ * cannot know the per-column filter value types in advance; the type
+ * strictness review tracks tightening this in workorder `TableContext`
+ * finding 2.
+ */
 export interface DefsWrapper<T extends object> {
     defs: Array<ColumnDef<T>>;
     remoteFilters?: CustomRemoteFilters<unknown>;

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

@@ -1,3 +1,16 @@
+/**
+ * Sub-taxonomy for `Display`-typed columns. Selects which read-only cell
+ * component renders the column body:
+ *
+ * - `Normal` - plain `DisplayCell` (text-only).
+ * - `Bubbles` - `BubbleCell` (one bubble per item in the accessor array).
+ * - `Progress` - `ProgressCell` (numeric pair rendered as a progress bar).
+ * - `Validity` - validity-icon column driven by `ColumnDef.isValid`.
+ *
+ * Note: the string values overlap deliberately with `AccessorType` (`'Date'`,
+ * `'Normal'`); type-side these are distinct because the unions never mix at
+ * the same call site.
+ */
 export declare const DisplayType: {
     readonly Normal: "Normal";
     readonly Bubbles: "Bubbles";

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

@@ -1,8 +1,21 @@
+/**
+ * Sub-taxonomy for `Display`-typed columns. Selects which read-only cell
+ * component renders the column body:
+ *
+ * - `Normal` - plain `DisplayCell` (text-only).
+ * - `Bubbles` - `BubbleCell` (one bubble per item in the accessor array).
+ * - `Progress` - `ProgressCell` (numeric pair rendered as a progress bar).
+ * - `Validity` - validity-icon column driven by `ColumnDef.isValid`.
+ *
+ * Note: the string values overlap deliberately with `AccessorType` (`'Date'`,
+ * `'Normal'`); type-side these are distinct because the unions never mix at
+ * the same call site.
+ */
 export const DisplayType = {
     Normal: 'Normal',
     Bubbles: 'Bubbles',
     Progress: 'Progress',
     // Icon: 'Icon', // NYI
-    Validity: 'Validity'
+    Validity: 'Validity',
 };
 Object.freeze(DisplayType);

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

@@ -1,5 +1,10 @@
 import type { Primitive } from '../Context/TableInitOptions.js';
 import type { ExpandDef } from './Definitions/Expand/ExpandDef.svelte.js';
+/**
+ * Narrowed `Column<T>` whose `columnDef` is an `ExpandDef` (master/detail).
+ * `T` is the outer row type, `R` the inner-table row type, `IdType` the
+ * `selectionExtractor` return type for the inner table.
+ */
 export interface ExpandColumn<T extends object, R extends object, IdType extends Primitive, FilterValueType> {
     id: string;
     columnDef: ExpandDef<T, R, IdType, FilterValueType>;

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

@@ -1,6 +1,13 @@
 import type { Row } from '../Context/Row.js';
 import type { Primitive } from '../Context/TableInitOptions.js';
 import type { ExpandColumn } from './ExpandColumn.js';
+/**
+ * Narrowed `TableCell<T>` for expand columns. The natural shape of
+ * `getValue` would be `ReadonlyArray<R> | Promise<ReadonlyArray<R>>`
+ * (the inner-table rows for this row), but the cell is currently typed
+ * `unknown` for consistency with `TableCell.getValue`; tightening is deferred
+ * to the parent `TableCell.getValue` workorder.
+ */
 export interface ExpandTableCell<T extends object, R extends object, IdType extends Primitive, FilterValueType> {
     column: ExpandColumn<T, R, IdType, FilterValueType>;
     row: Row<T>;

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

@@ -1,3 +1,9 @@
+/**
+ * Serialisable mirror of `ColumnPinningState`. `ReadonlyMap` is not
+ * `JSON.stringify`-friendly, so column-preset save/restore code in
+ * `TableContext` converts to/from this `Array<[id, width]>` representation
+ * for localStorage round-trips.
+ */
 export interface JSONColumnPinningState {
     left?: Array<[string, number]>;
     right?: Array<[string, number]>;

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

@@ -1,4 +1,9 @@
 import type { ProgressBarDef } from './Definitions/Display/ProgressBarDef.svelte.js';
+/**
+ * Narrowed `Column<T>` whose `columnDef` is a `ProgressBarDef`. As with
+ * `DateColumn`, this currently declares its own shape; collapsing to
+ * `extends Column<T, F>` is deferred (workorder Types-Columns finding 10).
+ */
 export interface ProgressBarColumn<T extends object, FilterValueType> {
     id: string;
     columnDef: ProgressBarDef<T, FilterValueType>;

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

@@ -2,6 +2,15 @@ import type { Row } from '../Context/Row.js';
 import type { NumberFilterValueType } from '../Filtering/FilterFn.js';
 import type { ProgressBarColumn } from './ProgressBarColumn.js';
 import type { TableCell } from './TableCell.js';
+/**
+ * Narrowed `TableCell<T>` for progress-bar columns. The natural shape of
+ * `getValue` here is `[number, number] | Promise<[number, number]>`
+ * (current, max); tightening is deferred to the parent `TableCell.getValue`
+ * workorder so the change happens in one place.
+ *
+ * Default `FilterValueType = NumberFilterValueType` reflects the fact that
+ * the only sensible filter shape for a progress column is a numeric range.
+ */
 export interface ProgressBarTableCell<T extends object, FilterValueType = NumberFilterValueType> extends TableCell<T, FilterValueType> {
     column: ProgressBarColumn<T, FilterValueType>;
     row: Row<T>;

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

@@ -1,4 +1,16 @@
 import type { ColourSet } from '../../../../scss/colours.js';
+/**
+ * One per-row action exposed by an `ActionsDef`. Rendered as a `Button`
+ * inside `ActionsCell.svelte`.
+ *
+ * - `getLabel(item, index)` produces the visible label (and tooltip /
+ *   `aria-label`) per row. May return a `Promise` so consumers can read from
+ *   an async source.
+ * - `callback(item, index)` is invoked synchronously on click. The cell
+ *   awaits any returned promise via `devCatch`.
+ * - `colourSet` controls the button colour set (defaults to `Auxiliary`).
+ * - `disabled` is a static fallback; `isDisabled` overrides per-row.
+ */
 export interface TableActionButton<T> {
     getLabel: (item: T, index: number) => string | Promise<string>;
     callback: (item: T, index: number) => void;

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

@@ -1,8 +1,22 @@
 import type { Row } from '../Context/Row.js';
 import type { Column } from './Column.js';
-export interface TableCell<T extends object, in FilterValueType = never, out FilterOptionsType = unknown> {
+/**
+ * `TableCell<T, FilterValueType, FilterOptionsType, TValue>` is the per-cell
+ * handle exposed to body components.
+ *
+ * The optional `TValue` generic is the declared value type for the column
+ * the cell belongs to. Defaulting it to `unknown` keeps all existing call
+ * sites compiling: a cell consumer that does not parametrise on `TValue`
+ * continues to see `unknown | Promise<unknown>` exactly as before.
+ *
+ * Cell hosts that know the column shape (`TableNumberInput`, `TableCheckbox`,
+ * etc.) can pass a narrower `TValue` either explicitly or by reading it from
+ * a `ColumnDef<T, ..., TValue>`. The intent is to let `cell.getValue()` be
+ * typed instead of `unknown` without breaking any external consumer.
+ */
+export interface TableCell<T extends object, in FilterValueType = never, out FilterOptionsType = unknown, TValue = unknown> {
     column: Column<T, FilterValueType, FilterOptionsType>;
     row: Row<T>;
     id: string;
-    getValue: () => unknown | Promise<unknown>;
+    getValue: () => TValue | Promise<TValue>;
 }

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

@@ -1 +1,13 @@
+/**
+ * Per-column visibility map keyed by column id. Tri-state by design:
+ *
+ * - `true` - column is visible (set explicitly by the user).
+ * - `false` - column is hidden.
+ * - `undefined` - no user preference recorded; the table treats this as
+ *   visible (every `getIsVisible()` check uses `!== false`).
+ *
+ * Persisted to localStorage as-is. The tri-state contract is intentional and
+ * must be preserved when refactoring; collapsing to `Record<string, boolean>`
+ * would lose the "no preference" branch the column-preset code relies on.
+ */
 export type VisibilityState = Record<string, boolean | undefined>;

package/dist/Components/Table/Types/Context/ColumnLayoutState.svelte.d.ts

@@ -0,0 +1,173 @@
+import type { ColumnDef } from '../Columns/Definitions/ColumnDef.svelte.js';
+import type { ColumnPinningState } from '../Columns/ColumnPinningState.js';
+import type { ColumnSizingState } from '../Columns/ColumnSizingState.js';
+import type { VisibilityState } from '../Columns/VisibilityState.js';
+import type { VisualColumnIndex } from '../Coordinates/ColumnIndices.js';
+/**
+ * Dependency surface that `ColumnLayoutState` reads from the surrounding
+ * `TableContext`. Every dependency is passed as a thunk so the sub-context
+ * never holds a direct reference to the parent; reactivity threads through
+ * `$derived` exactly as before the extraction.
+ */
+export interface ColumnLayoutStateDeps {
+    /** Master gate from `TableInitOptions.allowColumnReordering`. When
+     *  false, `setColumnPinning` short-circuits. */
+    getAllowColumnReordering: () => boolean;
+    /** Logger gate; mirrors the parent `TableContext.debug` field. */
+    getDebug: () => boolean;
+}
+/**
+ * Phase 6.3 god-object decomposition - sub-context that owns every
+ * column-layout concern previously held directly on `TableContext`:
+ *
+ * - `columnDefs` (the ordered array of column definitions),
+ * - `columnDefsById` (`$derived` id->def lookup map),
+ * - `columnPinning` / `columnSizing` / `columnVisibility` (the three
+ *   per-column maps the consumer mutates through the public setters),
+ * - `_visualColumns` and `_visualColumnIndexById` (the cached visual
+ *   display order plus the paired `Map<id, VisualColumnIndex>` that
+ *   makes `columnVisualIndex` an O(1) lookup - Phase-5 Group 1
+ *   workorder P0),
+ * - `columnVisualIndex(id)` (the public lookup),
+ * - `setColumnPinning(updater)` (delegating writer that respects the
+ *   `allowColumnReordering` master gate).
+ *
+ * `TableContext` retains delegating getters / setters / methods for
+ * every legacy surface (`columnDefs`, `columnPinning`, `columnSizing`,
+ * `columnVisibility`, `columnDefsById`, `columnVisualIndex`,
+ * `_visualColumns`, `setColumnPinning`, etc.) so existing consumers
+ * need no migration. Future consumers can read `tableContext._columnLayout`
+ * directly once the migration is complete (see
+ * `src/stories/Concepts/TableContext-decomposition.mdx`).
+ *
+ * The `focusStartVisualColumn` / `focusEndVisualColumn` getters straddle
+ * column-layout and focus; the column-layout-side calculation
+ * (`columnVisualIndex` lookup) lives here, but the focus-side state
+ * (`focusStart`, `focusEnd`) stays on `TableContext` until the Phase 6.6
+ * `FocusState` extraction. The parent's `focusStartVisualColumn` getter
+ * therefore reads `this.focusStart?.id` and calls
+ * `this._columnLayout.columnVisualIndex(...)`.
+ */
+export declare class ColumnLayoutState<T extends object> {
+    private readonly _deps;
+    private _columnDefs;
+    private _columnSizing;
+    private _columnPinning;
+    private _columnVisibility;
+    /**
+     * @param deps thunks the sub-context reads from the parent.
+     *             Constructor-only - no implicit setup so the parent
+     *             remains in control of effect ownership and lifecycle.
+     */
+    constructor(deps: ColumnLayoutStateDeps);
+    /**
+     * The ordered array of column definitions. Memory order (declaration
+     * order) is preserved across reorder operations - drag-reorder
+     * mutates the per-def `.index` field but does not change the array
+     * identity until the consumer reassigns `columnDefs` wholesale.
+     *
+     * Setter accepts any array of `ColumnDef<T>`; the parent
+     * `TableContext` is responsible for index normalisation when
+     * applying drag-drop or preset switches (see `reorderColumn`,
+     * `moveColumnTo`, `setSelectedPreset`).
+     */
+    get columnDefs(): Array<ColumnDef<T>>;
+    set columnDefs(v: Array<ColumnDef<T>>);
+    /**
+     * Per-column width state (pixels), keyed by column id. Persisted to
+     * localStorage as-is by `TableContext._updateLocalStorageSettings`.
+     * Setter accepts a full replacement object; per-key writes are
+     * handled by `autoResize` mutating in place (which is fine because
+     * the underlying `$state` slot is itself the proxy).
+     */
+    get columnSizing(): ColumnSizingState;
+    set columnSizing(v: ColumnSizingState);
+    /**
+     * Per-column pin state (left / right). Setter is exposed publicly
+     * for direct assignment by the parent (e.g. `setSelectedPreset` and
+     * the init flow); the gated `setColumnPinning` updater below honours
+     * the `allowColumnReordering` master gate.
+     */
+    get columnPinning(): ColumnPinningState;
+    set columnPinning(v: ColumnPinningState);
+    /**
+     * Tri-state per-column visibility map. `true` = visible, `false` =
+     * hidden, `undefined` = no preference (treated as visible). See
+     * `VisibilityState` for the design rationale.
+     */
+    get columnVisibility(): VisibilityState;
+    set columnVisibility(v: VisibilityState);
+    /**
+     * `$derived` id->def lookup map. Re-built whenever `columnDefs`
+     * changes; reads on this getter inside `$derived` / `$effect`
+     * contexts therefore re-subscribe automatically without the caller
+     * having to thread `void this.columnDefs` reads themselves.
+     *
+     * Made `public` so the parent `TableContext` can pass it directly
+     * to other sub-contexts (`SortingState` reads it through the
+     * `getColumnDefsById` thunk, the per-row accessor in
+     * `createRow` / `rowsPromise` uses it for id-keyed lookups).
+     */
+    readonly columnDefsById: ReadonlyMap<string, ColumnDef<T>>;
+    /**
+     * Columns in visual display order: pinned-left -> centre ->
+     * pinned-right, preserving memory order within each section.
+     * Excludes columns whose visibility is explicitly `false`.
+     *
+     * Cached as a `$derived` array (rebuilt only when `columnDefs`,
+     * `columnVisibility`, or `columnPinning` change). Phase-5 Group 1
+     * workorder P0 introduced this caching layer to avoid the
+     * O(columns) filter cost on every focus-arrow keystroke; see the
+     * paired `_visualColumnIndexById` below for the O(1) reverse-lookup
+     * map.
+     *
+     * Made `public` (with the underscore prefix preserved) so the
+     * parent `TableContext` can delegate its legacy `_visualColumns`
+     * field. Future consumers should read
+     * `tableContext._columnLayout.visualColumns` directly.
+     */
+    readonly visualColumns: Array<ColumnDef<T>>;
+    /**
+     * Paired `visualColumns` id->index reverse-lookup map. Rebuilt in
+     * lockstep with `visualColumns`; addresses the O(1) requirement of
+     * `columnVisualIndex` (which is called on every focus-arrow press
+     * inside the keyboard nav loop).
+     */
+    readonly visualColumnIndexById: ReadonlyMap<string, VisualColumnIndex>;
+    /**
+     * Returns the visual index of the column with the given id, or
+     * `-1` (branded as `VisualColumnIndex`) if the id is not in the
+     * current visible-column set. O(1) under the
+     * `visualColumnIndexById` cache.
+     */
+    columnVisualIndex(id: string): VisualColumnIndex;
+    /**
+     * Applies an updater to the column-pinning state (left / right
+     * pins). No-op when column reordering is disabled at the table
+     * level. Mirrors the pre-extraction
+     * `TableContext.setColumnPinning` writer verbatim.
+     */
+    readonly setColumnPinning: (updater: (state: ColumnPinningState) => ColumnPinningState) => void;
+    /**
+     * Re-normalises the per-def `.index` field so that pinned-left
+     * columns occupy the leading indices, unpinned (centre) columns
+     * the middle, and pinned-right columns the trailing indices.
+     * Returns the resulting array (sorted by the new index ordering).
+     *
+     * Pure with respect to `this._columnDefs` / `this._columnPinning`:
+     * mutates the per-def `.index` fields in place and returns a new
+     * array view. The parent uses this as a helper inside
+     * `reorderColumn` / `moveColumnTo` after rearranging the array
+     * so the memory-index brand stays consistent with the pin
+     * sections.
+     */
+    readonly updateDefsBasedOnPinning: () => Array<ColumnDef<T>>;
+    /**
+     * Re-publishes the column-pinning map so its left / right entries
+     * are keyed by the current `columnDefs` ordering. Used by the
+     * parent's drag-drop and `moveColumnTo` flows after a reorder
+     * operation; preserves the pre-extraction
+     * `TableContext._setNewPinningState` contract verbatim.
+     */
+    readonly setNewPinningState: () => void;
+}

package/dist/Components/Table/Types/Context/ColumnLayoutState.svelte.js

@@ -0,0 +1,241 @@
+/**
+ * Phase 6.3 god-object decomposition - sub-context that owns every
+ * column-layout concern previously held directly on `TableContext`:
+ *
+ * - `columnDefs` (the ordered array of column definitions),
+ * - `columnDefsById` (`$derived` id->def lookup map),
+ * - `columnPinning` / `columnSizing` / `columnVisibility` (the three
+ *   per-column maps the consumer mutates through the public setters),
+ * - `_visualColumns` and `_visualColumnIndexById` (the cached visual
+ *   display order plus the paired `Map<id, VisualColumnIndex>` that
+ *   makes `columnVisualIndex` an O(1) lookup - Phase-5 Group 1
+ *   workorder P0),
+ * - `columnVisualIndex(id)` (the public lookup),
+ * - `setColumnPinning(updater)` (delegating writer that respects the
+ *   `allowColumnReordering` master gate).
+ *
+ * `TableContext` retains delegating getters / setters / methods for
+ * every legacy surface (`columnDefs`, `columnPinning`, `columnSizing`,
+ * `columnVisibility`, `columnDefsById`, `columnVisualIndex`,
+ * `_visualColumns`, `setColumnPinning`, etc.) so existing consumers
+ * need no migration. Future consumers can read `tableContext._columnLayout`
+ * directly once the migration is complete (see
+ * `src/stories/Concepts/TableContext-decomposition.mdx`).
+ *
+ * The `focusStartVisualColumn` / `focusEndVisualColumn` getters straddle
+ * column-layout and focus; the column-layout-side calculation
+ * (`columnVisualIndex` lookup) lives here, but the focus-side state
+ * (`focusStart`, `focusEnd`) stays on `TableContext` until the Phase 6.6
+ * `FocusState` extraction. The parent's `focusStartVisualColumn` getter
+ * therefore reads `this.focusStart?.id` and calls
+ * `this._columnLayout.columnVisualIndex(...)`.
+ */
+export class ColumnLayoutState {
+    _deps;
+    _columnDefs = $state([]);
+    _columnSizing = $state({});
+    _columnPinning = $state({});
+    _columnVisibility = $state({});
+    /**
+     * @param deps thunks the sub-context reads from the parent.
+     *             Constructor-only - no implicit setup so the parent
+     *             remains in control of effect ownership and lifecycle.
+     */
+    constructor(deps) {
+        this._deps = deps;
+    }
+    /**
+     * The ordered array of column definitions. Memory order (declaration
+     * order) is preserved across reorder operations - drag-reorder
+     * mutates the per-def `.index` field but does not change the array
+     * identity until the consumer reassigns `columnDefs` wholesale.
+     *
+     * Setter accepts any array of `ColumnDef<T>`; the parent
+     * `TableContext` is responsible for index normalisation when
+     * applying drag-drop or preset switches (see `reorderColumn`,
+     * `moveColumnTo`, `setSelectedPreset`).
+     */
+    get columnDefs() {
+        return this._columnDefs;
+    }
+    set columnDefs(v) {
+        this._columnDefs = v;
+    }
+    /**
+     * Per-column width state (pixels), keyed by column id. Persisted to
+     * localStorage as-is by `TableContext._updateLocalStorageSettings`.
+     * Setter accepts a full replacement object; per-key writes are
+     * handled by `autoResize` mutating in place (which is fine because
+     * the underlying `$state` slot is itself the proxy).
+     */
+    get columnSizing() {
+        return this._columnSizing;
+    }
+    set columnSizing(v) {
+        this._columnSizing = v;
+    }
+    /**
+     * Per-column pin state (left / right). Setter is exposed publicly
+     * for direct assignment by the parent (e.g. `setSelectedPreset` and
+     * the init flow); the gated `setColumnPinning` updater below honours
+     * the `allowColumnReordering` master gate.
+     */
+    get columnPinning() {
+        return this._columnPinning;
+    }
+    set columnPinning(v) {
+        this._columnPinning = v;
+    }
+    /**
+     * Tri-state per-column visibility map. `true` = visible, `false` =
+     * hidden, `undefined` = no preference (treated as visible). See
+     * `VisibilityState` for the design rationale.
+     */
+    get columnVisibility() {
+        return this._columnVisibility;
+    }
+    set columnVisibility(v) {
+        this._columnVisibility = v;
+    }
+    /**
+     * `$derived` id->def lookup map. Re-built whenever `columnDefs`
+     * changes; reads on this getter inside `$derived` / `$effect`
+     * contexts therefore re-subscribe automatically without the caller
+     * having to thread `void this.columnDefs` reads themselves.
+     *
+     * Made `public` so the parent `TableContext` can pass it directly
+     * to other sub-contexts (`SortingState` reads it through the
+     * `getColumnDefsById` thunk, the per-row accessor in
+     * `createRow` / `rowsPromise` uses it for id-keyed lookups).
+     */
+    columnDefsById = $derived(
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    new Map(this._columnDefs.map((it) => [it.id, it])));
+    /**
+     * Columns in visual display order: pinned-left -> centre ->
+     * pinned-right, preserving memory order within each section.
+     * Excludes columns whose visibility is explicitly `false`.
+     *
+     * Cached as a `$derived` array (rebuilt only when `columnDefs`,
+     * `columnVisibility`, or `columnPinning` change). Phase-5 Group 1
+     * workorder P0 introduced this caching layer to avoid the
+     * O(columns) filter cost on every focus-arrow keystroke; see the
+     * paired `_visualColumnIndexById` below for the O(1) reverse-lookup
+     * map.
+     *
+     * Made `public` (with the underscore prefix preserved) so the
+     * parent `TableContext` can delegate its legacy `_visualColumns`
+     * field. Future consumers should read
+     * `tableContext._columnLayout.visualColumns` directly.
+     */
+    visualColumns = $derived.by(() => {
+        const visibility = this._columnVisibility;
+        const pinLeft = this._columnPinning.left;
+        const pinRight = this._columnPinning.right;
+        const visible = this._columnDefs.filter((it) => visibility[it.id] !== false);
+        return [
+            ...visible.filter((it) => pinLeft?.has(it.id)),
+            ...visible.filter((it) => !pinLeft?.has(it.id) && !pinRight?.has(it.id)),
+            ...visible.filter((it) => pinRight?.has(it.id)),
+        ];
+    });
+    /**
+     * Paired `visualColumns` id->index reverse-lookup map. Rebuilt in
+     * lockstep with `visualColumns`; addresses the O(1) requirement of
+     * `columnVisualIndex` (which is called on every focus-arrow press
+     * inside the keyboard nav loop).
+     */
+    visualColumnIndexById = $derived.by(() => {
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity
+        const map = new Map();
+        const cols = this.visualColumns;
+        for (let i = 0; i < cols.length; i++) {
+            map.set(cols[i].id, i);
+        }
+        return map;
+    });
+    /**
+     * Returns the visual index of the column with the given id, or
+     * `-1` (branded as `VisualColumnIndex`) if the id is not in the
+     * current visible-column set. O(1) under the
+     * `visualColumnIndexById` cache.
+     */
+    columnVisualIndex(id) {
+        return this.visualColumnIndexById.get(id) ?? -1;
+    }
+    /**
+     * Applies an updater to the column-pinning state (left / right
+     * pins). No-op when column reordering is disabled at the table
+     * level. Mirrors the pre-extraction
+     * `TableContext.setColumnPinning` writer verbatim.
+     */
+    setColumnPinning = (updater) => {
+        if (!this._deps.getAllowColumnReordering()) {
+            if (this._deps.getDebug()) {
+                console.log('setColumnPinning: ignored (allowColumnReordering=false)');
+            }
+            return;
+        }
+        this._columnPinning = updater(this._columnPinning);
+    };
+    /**
+     * Re-normalises the per-def `.index` field so that pinned-left
+     * columns occupy the leading indices, unpinned (centre) columns
+     * the middle, and pinned-right columns the trailing indices.
+     * Returns the resulting array (sorted by the new index ordering).
+     *
+     * Pure with respect to `this._columnDefs` / `this._columnPinning`:
+     * mutates the per-def `.index` fields in place and returns a new
+     * array view. The parent uses this as a helper inside
+     * `reorderColumn` / `moveColumnTo` after rearranging the array
+     * so the memory-index brand stays consistent with the pin
+     * sections.
+     */
+    updateDefsBasedOnPinning = () => {
+        const leftDefs = [];
+        const midDefs = [];
+        const rightDefs = [];
+        this._columnDefs.forEach((def) => {
+            if (this._columnPinning.left?.has(def.id)) {
+                leftDefs.push(def);
+            }
+            else if (this._columnPinning.right?.has(def.id)) {
+                rightDefs.push(def);
+            }
+            else {
+                midDefs.push(def);
+            }
+        });
+        leftDefs.sort((a, b) => a.index - b.index);
+        midDefs.sort((a, b) => a.index - b.index);
+        rightDefs.sort((a, b) => a.index - b.index);
+        const allDefs = leftDefs.concat(midDefs, rightDefs);
+        allDefs.forEach((def, index) => {
+            def.index = index;
+        });
+        return allDefs;
+    };
+    /**
+     * Re-publishes the column-pinning map so its left / right entries
+     * are keyed by the current `columnDefs` ordering. Used by the
+     * parent's drag-drop and `moveColumnTo` flows after a reorder
+     * operation; preserves the pre-extraction
+     * `TableContext._setNewPinningState` contract verbatim.
+     */
+    setNewPinningState = () => {
+        this._columnPinning = {
+            // eslint-disable-next-line svelte/prefer-svelte-reactivity
+            left: new Map(this._columnPinning.left &&
+                this._columnDefs
+                    .filter((col) => {
+                    return this._columnPinning.left?.has(col.id);
+                })
+                    .map((col, index) => [col.id, index])),
+            // eslint-disable-next-line svelte/prefer-svelte-reactivity
+            right: new Map(this._columnPinning.right &&
+                this._columnDefs
+                    .filter((col) => this._columnPinning.right?.has(col.id))
+                    .map((col, index) => [col.id, index])),
+        };
+    };
+}