@lavalogic/scoria 0.36.0 → 0.37.1

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

@@ -1,3 +1,5 @@
+import { PreferencesState } from './PreferencesState.svelte.js';
+import { SelectionState } from './SelectionState.svelte.js';
 import { SvelteMap } from 'svelte/reactivity';
 import type { Updater } from 'svelte/store';
 import type { ColumnPinningState } from '../Columns/ColumnPinningState.js';
@@ -7,9 +9,13 @@ import type { ColumnDefSet } from '../Columns/Definitions/ColumnDefSet.js';
 import type { DefsWrapper } from '../Columns/DefsWrapper.js';
 import type { VisibilityState } from '../Columns/VisibilityState.js';
 import type { CellCoordinates } from '../Coordinates/CellCoordinates.js';
-import type { CellCoordinatesWithoutColumn } from '../Coordinates/CellCoordinatesWithoutColumn.js';
 import type { VisualColumnIndex } from '../Coordinates/ColumnIndices.js';
 import type { IDataRepository } from '../DataRepository/IDataRepository.js';
+import { SortingState } from './SortingState.svelte.js';
+import { FilteringState } from './FilteringState.svelte.js';
+import { ColumnLayoutState } from './ColumnLayoutState.svelte.js';
+import { FocusState } from './FocusState.svelte.js';
+import { VirtualisationState } from './VirtualisationState.svelte.js';
 import type { ColumnFiltersState } from '../Filtering/ColumnFiltersState.js';
 import type { CustomRemoteFilters } from '../Filtering/CustomRemoteFilters.js';
 import type { BoolFilterValueType, DateFilterValueType, FilterFn, NumberFilterValueType, SelectFilterValueType, StringFilterValueType } from '../Filtering/FilterFn.js';
@@ -19,6 +25,25 @@ import { ToolbarPosition } from '../Toolbar/ToolbarPosition.js';
 import type { ITable } from './ITable.js';
 import type { RowModel } from './RowModel.js';
 import type { Primitive, TableInitOptions } from './TableInitOptions.js';
+/**
+ * Default values applied by `TableContext.init` for any `TableInitOptions`
+ * field the consumer omits. Frozen so callers (notably `NestedTable`)
+ * can spread it without risking accidental shared-object mutation.
+ *
+ * Mirrors the default literals consumed inside `init`; both share this
+ * constant so the two cannot drift.
+ */
+export declare const DEFAULT_TABLE_INIT_OPTIONS: Readonly<{
+    allowCopy: true;
+    enableResize: true;
+    allowColumnReordering: true;
+    allowQuickFiltering: true;
+    showQuickFilterByDefault: true;
+    allowAdvancedFiltering: true;
+    toolbar: "Right";
+    displayFooter: true;
+    debug: false;
+}>;
 export declare class TableContext<T extends object, RowIdType extends Primitive> {
     readonly defaultColumnDefs: DefsWrapper<T>;
     readonly tableName: string;
@@ -35,61 +60,131 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
     private _onEditCell;
     readonly debug: boolean;
     static readonly identifier: unique symbol;
+    /**
+     * Factory for `TableContext`. Coalesces every optional flag from the
+     * caller-supplied `options` against `DEFAULT_TABLE_INIT_OPTIONS` so
+     * the constructor receives a complete set of values. The constructor
+     * itself is `protected` and gated by an internal symbol to make it
+     * impossible to construct a `TableContext` without going through
+     * `init`.
+     */
     static init<T extends object, RowIdType extends Primitive>(defaultColumnDefs: DefsWrapper<T>, tableName: string, dataRepo: IDataRepository<T>, options: TableInitOptions<T, RowIdType>): TableContext<T, RowIdType>;
     protected constructor(INTERNAL_ONLY: symbol, defaultColumnDefs: DefsWrapper<T>, tableName: string, dataRepo: IDataRepository<T>, allowCopy: boolean, enableResize: boolean, allowColumnReordering: boolean, allowQuickFiltering: boolean, showQuickFilterByDefault: boolean, allowAdvancedFiltering: boolean, toolbarPosition: ToolbarPosition, displayFooter: boolean, selectionExtractor: TableInitOptions<T, RowIdType>['selectionExtractor'], getUserId: () => string | undefined, _onEditCell: TableInitOptions<T, RowIdType>['onEditCell'], debug: boolean);
-    private readonly userId;
     private isSelectable;
     private _paginationRepo;
     get paginationRepo(): IDataRepository<T> | undefined;
     set paginationRepo(v: IDataRepository<T> | undefined);
-    private _showQuickFiltering;
+    /**
+     * Delegating accessor preserved for backwards compatibility; reads /
+     * writes through to `_filtering.showQuickFiltering`. The sub-context
+     * owns the `allowQuickFiltering` gate so the setter logic stays
+     * identical to the pre-extraction implementation.
+     */
     get showQuickFiltering(): boolean;
     set showQuickFiltering(v: boolean);
     private _dataRepo;
     get dataRepo(): IDataRepository<T>;
     private set dataRepo(value);
-    private _remoteFilters;
+    /**
+     * Delegating getter preserved for backwards compatibility. Reads
+     * through to `_filtering.remoteFilters`; the parent uses
+     * `_filtering.setRemoteFilters` during column-def setup to write the
+     * caller-supplied value.
+     */
     get remoteFilters(): CustomRemoteFilters<unknown> | undefined;
-    private set remoteFilters(value);
-    private _showSelectedOnly;
+    /**
+     * Delegating accessor preserved for backwards compatibility; reads /
+     * writes through to `_filtering.showSelectedOnly`. The sub-context
+     * preserves the idempotency short-circuit (re-assigning the same
+     * value is a no-op).
+     */
     get showSelectedOnly(): boolean;
     set showSelectedOnly(v: boolean);
-    readonly dateFilter: FilterFn<T, DateFilterValueType> | undefined;
-    readonly numberFilter: FilterFn<T, NumberFilterValueType> | undefined;
-    readonly selectFilter: FilterFn<T, SelectFilterValueType<T>> | undefined;
-    readonly boolFilter: FilterFn<T, BoolFilterValueType> | undefined;
-    readonly stringFilter: FilterFn<T, StringFilterValueType> | undefined;
+    /**
+     * Delegating getters that relay the per-type `FilterFn` from
+     * `_filtering`. The sub-context's `$derived` chain reads through
+     * `paginationRepo` via the thunk so the source of truth stays
+     * with the data repository; consumers that bind these getters
+     * (notably `setupDefaultColumnDefs`) need no migration.
+     */
+    get dateFilter(): FilterFn<T, DateFilterValueType> | undefined;
+    get numberFilter(): FilterFn<T, NumberFilterValueType> | undefined;
+    get selectFilter(): FilterFn<T, SelectFilterValueType<T>> | undefined;
+    get boolFilter(): FilterFn<T, BoolFilterValueType> | undefined;
+    get stringFilter(): FilterFn<T, StringFilterValueType> | undefined;
     private _limitFooter;
     get limitFooter(): boolean;
     set limitFooter(v: boolean);
     private _dragTarget;
     get dragTarget(): ColumnDef<T> | null;
     set dragTarget(v: ColumnDef<T> | null);
-    private _columnDefs;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * actual `$state` slot lives on `_columnLayout`; this getter / setter
+     * pair forwards reads and writes so existing consumers need no
+     * migration. See `_columnLayout` below for the sub-context.
+     */
     get columnDefs(): Array<ColumnDef<T>>;
     set columnDefs(v: Array<ColumnDef<T>>);
-    private _columnPresets;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * actual `$state` slot lives on `_preferences._columnPresets`
+     * (Phase 6.4). The setter is private because the consumer-facing
+     * write path goes through `saveColumnPreset` (which also persists
+     * the list to localStorage); internal call sites that need to
+     * mutate the list directly call `_preferences.setPresets(...)`.
+     */
     get columnPresets(): ReadonlyArray<ColumnDefSet<T>>;
-    private set columnPresets(value);
-    private _selectedPreset;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * actual `$state` slot lives on `_preferences._selectedPreset`
+     * (Phase 6.4). Reads / writes through to the sub-context.
+     */
     get selectedPreset(): ColumnDefSet<T> | undefined;
     set selectedPreset(v: ColumnDefSet<T> | undefined);
-    private _focusedRowIndices;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * `$state` slot lives on `_focus._focusedRowIndices` (Phase 6.6).
+     * Populated by the parent's focus-derived `$effect` through
+     * `_focus.setFocusedDerived(rows, cols)`.
+     */
     get focusedRowIndices(): ReadonlySet<number>;
-    private readonly _highlightedItems;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * actual `$state` slot lives on `_selection._highlightedItems`
+     * (Phase 6.5).
+     */
     get highlightedItems(): SvelteMap<RowIdType, T>;
-    _focusedColumnIds: ReadonlySet<string>;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * `$state` slot lives on `_focus._focusedColumnIds` (Phase 6.6).
+     */
     get focusedColumnIds(): ReadonlySet<string>;
-    private _isMousingDown;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * `$state` slot lives on `_focus._isMousingDown` (Phase 6.6).
+     */
     get isMousingDown(): boolean;
     set isMousingDown(v: boolean);
-    private _focusStart;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * `$state` slot lives on `_focus._focusStart` (Phase 6.6). The
+     * setter remains read-only at this surface; the write path is
+     * `moveFocus` / `unfocus` / `tabForward` / `tabBackward` /
+     * `endFocus` / `setFocusEnd` / `startFocus` (all delegated below).
+     */
     get focusStart(): CellCoordinates | null;
-    private set focusStart(value);
-    private _focusStartIsBeingEdited;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * `$state` slot lives on `_focus._focusStartIsBeingEdited`
+     * (Phase 6.6).
+     */
     get focusStartIsBeingEdited(): boolean;
     set focusStartIsBeingEdited(v: boolean);
-    private _focusEnd;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * `$state` slot lives on `_focus._focusEnd` (Phase 6.6).
+     */
     get focusEnd(): CellCoordinates | null;
     set focusEnd(v: CellCoordinates | null);
     private _singleClickEditing;
@@ -110,42 +205,280 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
     private _commaSeparatedCopy;
     get commaSeparatedCopy(): boolean;
     set commaSeparatedCopy(v: boolean);
-    private _columnSizing;
+    /**
+     * Delegating accessor preserved for backwards compatibility. Reads
+     * through to `_columnLayout.columnSizing`. Per-key mutations (e.g.
+     * `this.columnSizing[id] = w` in `autoResize`) work because the
+     * underlying `$state` slot is a Svelte proxy.
+     */
     get columnSizing(): ColumnSizingState;
     set columnSizing(v: ColumnSizingState);
-    private _columnPinning;
+    /**
+     * Delegating accessor preserved for backwards compatibility. Reads
+     * through to `_columnLayout.columnPinning`. The `setColumnPinning`
+     * updater below honours the `allowColumnReordering` master gate; the
+     * direct setter does not, by design (used for preset switches and
+     * the init flow where the gate has already been checked).
+     */
     get columnPinning(): ColumnPinningState;
     set columnPinning(v: ColumnPinningState);
-    private _columnVisibility;
+    /**
+     * Delegating accessor preserved for backwards compatibility. Reads
+     * through to `_columnLayout.columnVisibility`. Tri-state semantics
+     * (`true` / `false` / `undefined`) are preserved.
+     */
     get columnVisibility(): VisibilityState;
     set columnVisibility(v: VisibilityState);
-    private _openModalCoordinates;
-    get openModalCoordinates(): CellCoordinatesWithoutColumn | null;
-    set openModalCoordinates(v: CellCoordinatesWithoutColumn | null);
-    private _allSelectedAsync;
-    private _allSelectedInCurrentPage;
+    /**
+     * Identifies the cell whose `col.validity({ modal })` /
+     * `col.display({ modal })` modal is currently open, or `null` when no
+     * modal is open.
+     *
+     * Keyed on the **row object reference**, not on visible index, so the
+     * open-modal state is stable across pagination, sort, and filter
+     * changes - the cell renderer matches via `cell.row.original ===
+     * openModalCell.row`. Visible-index-based keying (the old
+     * `CellCoordinatesWithoutColumn` shape) silently re-targeted the modal
+     * to whichever row happened to occupy the same index after a page
+     * change.
+     */
+    private _openModalCell;
+    get openModalCell(): {
+        row: T;
+        columnId: string;
+    } | null;
+    set openModalCell(v: {
+        row: T;
+        columnId: string;
+    } | null);
+    private _shownActionsPopup;
+    get shownActionsPopup(): symbol | undefined;
+    set shownActionsPopup(v: symbol | undefined);
+    /**
+     * Delegating getter preserved for backwards compatibility. The
+     * actual `$derived` chain (and the async-result cache) live on
+     * `_selection.allSelectedInCurrentPage` (Phase 6.5).
+     */
     get allSelectedInCurrentPage(): boolean;
-    private allSelectedBySelectableMethod;
-    private _areAllHighlighted;
-    private _allHighlighted;
+    /**
+     * Delegating getter preserved for backwards compatibility. Reads
+     * through to `_selection.allHighlighted`; the value is published by
+     * the `_allHighlightedEffect` below which lives on this class
+     * because it reads `paginationRepo.pageStartIndex` / `pageEndIndexExclusive`
+     * directly.
+     */
     get allHighlighted(): boolean;
-    private _hasHighlightedItems;
+    /**
+     * Delegating getter preserved for backwards compatibility. The
+     * `$derived` lives on `_selection.hasHighlightedItems` (Phase 6.5).
+     */
     get hasHighlightedItems(): boolean;
-    private _selectedItems;
+    /**
+     * Delegating accessors preserved for backwards compatibility. The
+     * `$state` slots live on `_selection` (Phase 6.5). `selectedItems`
+     * is read-only at this surface; the consumer-facing writers are
+     * `toggleSelected` / `setSelected` / `resetSelectedItems` /
+     * `setSelectionMap` below.
+     */
     get selectedItems(): SvelteMap<RowIdType, T>;
-    private _invalidValues;
     get invalidValues(): SvelteMap<RowIdType, T>;
     set invalidValues(v: SvelteMap<RowIdType, T>);
     private _hasInvalidSelectedItems;
     get hasInvalidSelectedItems(): boolean;
     private set hasInvalidSelectedItems(value);
-    private columnDefsById;
-    private readonly getSortingFn;
-    private _filteredIndices;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * id->def lookup map is owned by `_columnLayout.columnDefsById`
+     * (Phase 6.3); previously this was a `$derived` private field on
+     * `TableContext`. Made `public get` (instead of the previous
+     * `private` field) so the dependent sub-contexts (`SortingState`)
+     * and helpers (`generateTableOptions`) can read it through the
+     * legacy surface without piercing the sub-context boundary.
+     */
+    get columnDefsById(): ReadonlyMap<string, ColumnDef<T>>;
+    /**
+     * Phase 6.3 sub-context that owns the column-layout state:
+     * `columnDefs`, `columnSizing`, `columnPinning`, `columnVisibility`,
+     * the `columnDefsById` reverse-lookup map, the `visualColumns`
+     * cached array (and the paired `visualColumnIndexById` O(1) lookup),
+     * the gated `setColumnPinning` updater, the `updateDefsBasedOnPinning`
+     * helper, and the `setNewPinningState` helper.
+     *
+     * Dependencies are passed as thunks so the sub-context never holds
+     * a reference to the parent. The `allowColumnReordering` thunk
+     * gates the public `setColumnPinning` updater; the `debug` thunk
+     * mirrors the parent's logger gate.
+     */
+    readonly _columnLayout: ColumnLayoutState<T>;
+    /**
+     * Phase 6.2 sub-context that owns the filtering-related state: the
+     * per-row filter result (`filteredIndices`), the `filteredData`
+     * derived chain, the user-facing toggles (`showQuickFiltering`,
+     * `showSelectedOnly`), the per-type `FilterFn` relays, the
+     * remote-filter slot, and the `updateFilters` `OnChangeFn` slot.
+     *
+     * Dependencies are passed as thunks so the sub-context never holds
+     * a reference to the parent; the population effect for
+     * `_filteredIndices` stays in `TableContext` because it calls
+     * `this.createRow` (parent concern) - the effect publishes its
+     * result via `this._filtering.setFilteredIndices`.
+     */
+    readonly _filtering: FilteringState<T>;
+    /**
+     * Delegating getter preserved for backwards compatibility. Reads
+     * through to `_filtering.filteredIndices`, which is populated by
+     * the per-row filter `$effect` in this class (the effect calls
+     * `this.createRow` and must stay where `createRow` lives).
+     */
     get filteredIndices(): ReadonlyArray<number>;
-    readonly filteredData: T[];
-    private sortedDataAbortController;
-    readonly sortedData: T[];
+    /**
+     * Delegating getter preserved for backwards compatibility. Reads
+     * through to `_filtering.filteredData`, which owns the local /
+     * remote / show-selected-only branching.
+     */
+    get filteredData(): Array<T>;
+    /**
+     * Phase 6.1 sub-context that owns the sort-related derived chain and
+     * the per-`ColumnDef` comparator dispatch. The dependency thunks
+     * close over `this.columnDefsById` / `this.filteredData` /
+     * `this.dataRepo` / `this.paginationRepo` / `this.debug`, so the
+     * sub-context never holds a direct reference to the parent and the
+     * reactivity graph remains threaded through `$derived` only.
+     *
+     * Exposed as a public field so future consumers can read sorting
+     * state directly; the legacy `sortedData` getter below preserves the
+     * pre-decomposition surface for backwards compatibility.
+     */
+    readonly _sorting: SortingState<T>;
+    /**
+     * Phase 6.4 sub-context that owns every persistence / preferences
+     * concern previously held directly on `TableContext`:
+     *
+     * - the saved column-presets list and currently-selected preset
+     *   (`columnPresets`, `selectedPreset`);
+     * - the `userIdSegment` `$derived` (used to namespace every
+     *   `scoria-table:<user>:<tableName>:<suffix>` storage key);
+     * - the `saveColumnPreset` / `setSelectedPreset` writers (which
+     *   apply the layout AND persist);
+     * - the `loadPresets` / `loadSelectedPresetName` /
+     *   `loadSavedSettings` boot-time hydration helpers;
+     * - the `persistSettings` writer used by the in-app settings
+     *   toggles (`setIsCompact`, `setAlternateRowColours`, etc.);
+     * - the schema-validation typeguards (exported alongside the
+     *   sub-context for unit testing).
+     *
+     * The settings fields themselves (`isCompact`, `singleClickEditing`,
+     * `alternateRowColours`, etc.) stay on `TableContext` because each
+     * one drives reactive UI; only the localStorage round-trip moved.
+     * `TableContext` retains delegating getters/setters/methods for
+     * every legacy surface (`columnPresets`, `selectedPreset`,
+     * `saveColumnPreset`, `setSelectedPreset`, `setIsCompact`, etc.).
+     */
+    readonly _preferences: PreferencesState<T>;
+    /**
+     * Phase 6.5 sub-context that owns every selection + highlighting +
+     * key-cache concern previously held directly on `TableContext`:
+     *
+     * - `selectedItems` / `invalidValues` / `highlightedItems`
+     *   (`SvelteMap` slots, keyed by `selectionExtractor(item)`);
+     * - the `WeakMap<T, RowIdType>` key-cache that memoises the
+     *   extractor result for each row reference;
+     * - the pending-flush buffer and its debounced microtask
+     *   (`_pendingSelectionChanges` -> `tick().then(flush)`);
+     * - the `allSelectedInCurrentPage` `$derived` (with the async-
+     *   result cache for promise-returning `selectionExtractor` /
+     *   `RowSelectionDef.isSelectable`);
+     * - the `selectAllInCurrentPage` / `updateSelectedItems` /
+     *   `onHighlightAll` flows;
+     * - the `handleItemMutation` split that powers the parent's
+     *   `onEditCell` - the sub-context owns the key-cache delete +
+     *   selection rebind; the user-supplied callback stays on this
+     *   class.
+     *
+     * Dependencies are passed as thunks so the sub-context never holds
+     * a direct reference to `TableContext`. The two `$effect`s that
+     * historically lived on this class continue to live here (they
+     * read `paginationRepo` directly) but publish their results
+     * through `_selection.setAllHighlighted(...)` and
+     * `_selection.updateSelectedItems()`.
+     */
+    readonly _selection: SelectionState<T, RowIdType>;
+    /**
+     * Phase 6.6 sub-context that owns every focus + keyboard-navigation
+     * concern previously held directly on `TableContext`:
+     *
+     * - `focusStart` / `focusEnd` / `focusStartIsBeingEdited` /
+     *   `isMousingDown` (the `$state` slots that define the focused
+     *   cell-range);
+     * - the `focusedRowIndices` / `focusedColumnIds` sets (populated
+     *   by the parent's `$effect` through `setFocusedDerived(...)`);
+     * - every focus writer (`startFocus`, `moveFocus`, `unfocus`,
+     *   `endFocus`, `setFocusEnd`, `focusToTop`, `focusToBottom`,
+     *   `focusToStart`, `focusToEnd`, `moveToTop`, `moveToBottom`,
+     *   `moveToStart`, `moveToEnd`, `setFocusUp` / `setFocusDown` /
+     *   `setFocusLeft` / `setFocusRight`, and the
+     *   `moveFocusUp` / `moveFocusDown` / `moveFocusLeft` /
+     *   `moveFocusRight` range-extension variants);
+     * - `handleTdKeydown` (the root `onkeydown` router) and the
+     *   private `handleKeystroke` dispatch.
+     *
+     * Dependencies are passed as thunks so the sub-context never holds
+     * a direct reference to `TableContext`. The Ctrl+F / Tab / Ctrl+C
+     * paths in `handleTdKeydown` and `handleKeystroke` call back into
+     * the parent through the `toggleQuickFiltering` / `tabForward` /
+     * `tabBackward` / `copyDataToClipboard` thunks because those
+     * methods read fields owned by other sub-contexts (or the parent
+     * directly) and would otherwise need to import them.
+     *
+     * The focus-derived `$effect` that publishes
+     * `focusedRowIndices` / `focusedColumnIds` lives on `TableContext`
+     * because it reads `paginationRowModel` + `_visualColumns` directly;
+     * it calls `_focus.setFocusedDerived(rows, cols)` to publish.
+     *
+     * Group 2 Item C (per-cell `TableFocusDetails` reuse cache) is
+     * deferred for Phase 6.6 - see the class-level JSDoc on
+     * `FocusState` for the deferral rationale.
+     */
+    readonly _focus: FocusState<T>;
+    /**
+     * Phase 7.4 row-virtualisation sub-context. Owns the visible-row
+     * window plus the top / bottom spacer-height derived chain that
+     * `TableBody.svelte` renders. Threshold defaults to 100 rows
+     * (below that the legacy code path renders every row directly);
+     * overscan defaults to 10 rows above and below the viewport so a
+     * fast flick of the wheel does not surface a blank band before
+     * the next paint.
+     *
+     * Dependencies are thunks - the sub-context reads
+     * `paginationRowModel.rows` through `getRows`, the max-side
+     * observed height from the `_columnLayout` row-height pool
+     * through `getRowHeight`, and the per-table-density estimate
+     * through `getEstimatedRowHeight`.
+     */
+    /**
+     * Rendered widths of header cells, keyed by columnId. TableHead
+     * observes each `<div role="columnheader">` with a `ResizeObserver`
+     * and writes the actual rendered width here; TableRow / TableBody
+     * read these widths when computing sticky pinning offsets so that
+     * pinned columns can flex with `minmax(W, 1fr)` like centre columns
+     * (matching width-preservation expectation on pinning) while the
+     * sticky-cell offsets stay accurate.
+     *
+     * Fallback when a column has not yet been measured: 0. The first
+     * frame after pinning toggles may render with stale offsets but the
+     * resize observer fires immediately afterwards.
+     */
+    readonly _columnRenderedWidths: SvelteMap<string, number>;
+    readonly _virtualisation: VirtualisationState<T>;
+    /**
+     * Delegating getter preserved for backwards compatibility. Reads
+     * through to `_sorting.sortedData`, which owns the comparator-hoist
+     * optimisation and the `AbortController` short-circuit. Consumers
+     * inside `src/lib` already point at `tableContext.sortedData`; the
+     * delegation will be removed once Phase 6 v-next migrates every
+     * reader to `tableContext._sorting.sortedData` directly.
+     */
+    get sortedData(): Array<T>;
     private _sortedRowModel;
     get sortedRowModel(): RowModel<T>;
     private CurrentPageDataAbortController;
@@ -155,96 +488,285 @@ export declare class TableContext<T extends object, RowIdType extends Primitive>
     private rowsPromise;
     private _paginationRowModel;
     get paginationRowModel(): RowModel<T>;
-    private readonly _keyCache;
+    /**
+     * Delegating wrapper preserved for backwards compatibility. The
+     * key-extraction cache lives on `_selection` (Phase 6.5); this
+     * method forwards to `_selection.cachedKey(item)` so legacy call
+     * sites in `getHighlightedRowData` / `getFocusElementData` /
+     * `originalRowIndices` / `sortedRowModel` / `onHighlightAll` see
+     * no behavioural change.
+     */
     private _cachedKey;
-    private readonly _pendingSelectionChanges;
-    private _flushScheduled;
-    private _flushPendingSelectionChanges;
-    private _schedulePendingFlush;
+    /** Delegating accessor preserved for backwards compatibility. The
+     *  implementation lives on `_selection.selectionContains` (Phase 6.5). */
     readonly selectionContains: (item: T) => boolean | Promise<boolean>;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly addInvalidValue: (item: T) => void | Promise<void>;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly removeInvalidValue: (item: T) => void | Promise<void>;
-    readonly setOpenModalCoordinates: (coordinates: CellCoordinatesWithoutColumn | null) => void;
+    /**
+     * Stores or clears the cell whose per-cell modal is currently open.
+     *
+     * Pass `{ row, columnId }` to open; pass `null` to close. The `row`
+     * value must be the same object reference the table holds for that row
+     * (`cell.row.original`) - identity comparison is what the cell
+     * renderers use to decide which one of them should render the modal.
+     */
+    readonly setOpenModalCell: (cell: {
+        row: T;
+        columnId: string;
+    } | null) => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly toggleHighlightedRow: (item: T) => void | Promise<void>;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly resetHighlightedRows: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly toggleSelected: (item: T) => void | Promise<void>;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly setSelected: (item: T, selected: boolean) => void | Promise<void>;
+    /** Delegating accessor preserved for backwards compatibility. */
     setSelectionMap: (set: SvelteMap<RowIdType, T>) => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly updateSelectedItems: () => Promise<void>;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly resetSelectedItems: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly selectAllInCurrentPage: () => Promise<void>;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly onHighlightAll: () => void | Promise<void>;
+    /**
+     * Invoked by every editable cell on commit. Split between this
+     * class (the user-supplied edit callback) and `_selection`
+     * (the key-cache invalidation + selection-rebind half). The
+     * sub-context's `handleItemMutation` accepts a thunk that runs
+     * the consumer callback between the pre- and post-edit selection
+     * bookkeeping so the boundary stays explicit.
+     */
     readonly onEditCell: (item: T, coords: CellCoordinates, value: unknown) => Promise<void>;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * implementation lives on `_focus.handleTdKeydown` (Phase 6.6).
+     * Bound to the root `<table>` container's `onkeydown` listener;
+     * routes Ctrl+F / Escape / Tab synchronously and dispatches the
+     * arrow-key / Home / End / Ctrl+A / Ctrl+C path asynchronously.
+     */
     readonly handleTdKeydown: (e: KeyboardEvent) => void;
-    private handleKeystroke;
+    /** Toggles quick-filtering visibility and refocuses the matching cell. */
     readonly toggleQuickFiltering: () => void;
+    /**
+     * Applies an updater to the column-pinning state (left / right
+     * pins). Delegates to `_columnLayout.setColumnPinning`, which
+     * enforces the `allowColumnReordering` master gate.
+     */
     readonly setColumnPinning: (updater: Updater<ColumnPinningState>) => void;
-    updateFilters: OnChangeFn<ColumnFiltersState> | undefined;
+    /**
+     * Delegating accessor preserved for backwards compatibility. The
+     * actual `$state` slot lives on `_filtering`; this getter / setter
+     * pair forwards reads and writes so existing consumers (notably
+     * `generateTableOptions`) need no migration.
+     */
+    get updateFilters(): OnChangeFn<ColumnFiltersState> | undefined;
+    set updateFilters(v: OnChangeFn<ColumnFiltersState> | undefined);
     updateVisibility: OnChangeFn<VisibilityState>;
     readonly table: ITable<T>;
     readonly lastPage: number;
+    /** Canvas-measured width of a column header label, plus padding. */
     readonly measureHeaderWidth: (columnDef: ColumnDef<T>) => number;
+    /** Sizes a column to fit its widest current-page cell label. */
     readonly autoResize: (columnDef: ColumnDef<T>) => Promise<void>;
-    reorderColumn: (dropTarget: HTMLLIElement | HTMLTableCellElement | null) => void;
+    /**
+     * Drops the in-progress column drag onto the supplied target,
+     * updating `columnDefs`, pinning state, and focus. No-op when
+     * column reordering is disabled.
+     */
+    reorderColumn: (dropTarget: HTMLLIElement | HTMLElement | null) => void;
+    /**
+     * Programmatic column-reorder primitive used by keyboard accessibility
+     * shortcuts in the column-management panel. Moves the column at
+     * {@link currentIndex} to {@link newIndex} (both expressed in the
+     * sorted-by-`index` order of {@link columnDefs}). No-op when column
+     * reordering is disabled or indices are out of range / unchanged.
+     */
+    moveColumnTo: (currentIndex: number, newIndex: number) => void;
+    /** Copies the highlighted rows to the OS clipboard as TSV / CSV. */
     copyHighlightedRowsToClipboard: () => Promise<void>;
+    /** Copies the currently focused cell range to the OS clipboard. */
     copyDataToClipboard: () => Promise<void>;
     private _performRowCopy;
+    /** Delegating accessor preserved for backwards compatibility. The
+     *  implementation lives on `_focus.startFocus` (Phase 6.6). */
     readonly startFocus: (coords: CellCoordinates) => void;
+    /** Delegating accessor preserved for backwards compatibility. The
+     *  implementation lives on `_focus.moveFocus` (Phase 6.6). */
     readonly moveFocus: (coords: CellCoordinates, startEditing?: boolean) => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly unfocus: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly focusToTop: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly focusToBottom: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly moveToBottom: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly moveToTop: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly moveFocusUp: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly setFocusUp: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly tabForward: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly tabBackward: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly focusToStart: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly moveToStart: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly focusToEnd: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly moveToEnd: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly moveFocusDown: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly setFocusDown: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly moveFocusLeft: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly setFocusLeft: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly moveFocusRight: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly setFocusRight: () => void;
+    /** Delegating accessor preserved for backwards compatibility. */
     readonly endFocus: (coords: CellCoordinates) => void;
+    /** Toggles compact row sizing and persists to localStorage. */
     readonly setIsCompact: (value: boolean) => void;
+    /** Toggles alternating row colours and persists to localStorage. */
     readonly setAlternateRowColours: (value: boolean) => void;
+    /** Toggles single-click editing and persists to localStorage. */
     readonly setSingleClickEditing: (value: boolean) => void;
+    /** Toggles row-hover colour change and persists to localStorage. */
     readonly setChangeColourOnHover: (value: boolean) => void;
+    /** Toggles whether copy-to-clipboard prepends a header row and persists. */
     readonly setCopyWithHeaders: (value: boolean) => void;
+    /** Toggles CSV vs TSV copy-to-clipboard separator and persists. */
     readonly setCommaSeparatedCopy: (value: boolean) => void;
+    /**
+     * Delegating method preserved for backwards compatibility. Applies
+     * the preset to the live column layout, forwards the preset's
+     * `sortingState` to the data-repository updater, and persists the
+     * selected name. The underlying implementation lives on
+     * `_preferences.setSelectedPreset` (Phase 6.4).
+     *
+     * The pre-extraction debug warning ("no sorting state found") was
+     * emitted unconditionally when `paginationRepo.updateSorting` was
+     * absent; the sub-context skips that warning because the
+     * `applySortingState` thunk already no-ops in that case. The
+     * warning is reinstated below so the surface is byte-identical.
+     */
     readonly setSelectedPreset: (preset: ColumnDefSet<T>) => void;
+    /**
+     * Delegating method preserved for backwards compatibility. Adds or
+     * replaces a saved preset for the current column layout and
+     * persists the full preset list to localStorage. Delegates to
+     * `_preferences.saveColumnPreset` (Phase 6.4).
+     */
     readonly saveColumnPreset: (name: string) => void;
     /**
      * This listener should be added and removed based on isMousingDown
      */
+    /** Delegating accessor preserved for backwards compatibility. The
+     *  implementation lives on `_focus.setFocusEnd` (Phase 6.6). */
     readonly setFocusEnd: (coords: CellCoordinates) => void;
     private createRow;
     private columnDefReturnsTextValue;
+    /**
+     * Builds the user-controlled settings blob from the current
+     * `$state` slots and delegates the actual `localStorage.setItem`
+     * call to `_preferences.persistSettings` (Phase 6.4). The settings
+     * field set (`isCompact`, `singleClickEditing`, etc.) still lives
+     * on `TableContext` because each one drives reactive UI; only the
+     * persistence side of the boundary moved.
+     */
     private _updateLocalStorageSettings;
     /**
-     * Columns in visual display order: pinned-left → center → pinned-right,
-     * preserving memory order within each section. Only includes visible columns.
+     * Delegating accessor preserved for backwards compatibility. The
+     * cached visual-column array and its paired O(1) id->index map now
+     * live on `_columnLayout` (Phase 6.3). The underscore prefix is
+     * preserved on `TableContext` to keep the existing read sites in
+     * `tabForward` / `focusToStart` / `moveFocusLeft` / etc. untouched.
      */
-    private get _visualColumns();
-    /** Returns the visual index of the column with the given id, or -1 if not found. */
+    get _visualColumns(): Array<ColumnDef<T>>;
+    /** Returns the visual index of the column with the given id, or
+     *  -1 if not found. Delegates to `_columnLayout.columnVisualIndex`
+     *  which provides the O(1) lookup. */
     columnVisualIndex(id: string): VisualColumnIndex;
+    /**
+     * Delegating getter preserved for backwards compatibility. The
+     * implementation lives on `_focus.focusStartVisualColumn`
+     * (Phase 6.6); the visual-index lookup itself is owned by
+     * `_columnLayout.columnVisualIndex` (Phase 6.3).
+     */
     get focusStartVisualColumn(): VisualColumnIndex;
+    /**
+     * Delegating getter preserved for backwards compatibility. The
+     * implementation lives on `_focus.focusEndVisualColumn`
+     * (Phase 6.6).
+     */
     get focusEndVisualColumn(): VisualColumnIndex;
-    private _moveFocusEndRow;
-    private _moveFocusRow;
     private getHighlightedRowData;
     private getFocusElementData;
     private updateDefsBasedOnPinning;
     private assertNoDuplicateIds;
     private setupDefaultColumnDefs;
+    /**
+     * Reads the persisted per-table user-settings blob through
+     * `_preferences.loadSavedSettings` (Phase 6.4) and applies each
+     * field to the live `$state` slot. Field defaults mirror the
+     * pre-extraction behaviour:
+     *
+     * - missing slot: `singleClickEditing` defaults to `true`; every
+     *   other field keeps its constructor default.
+     * - present slot: each field is applied if it would deviate from
+     *   the constructor default (the "only alter when the user
+     *   explicitly disabled" semantics are preserved verbatim).
+     */
     private _getUserDefaults;
     private _setNewPinningState;
     readonly getToggleSortingHandler: (def: ColumnDef<T>) => () => void;
     private reassignDefsToPresets;
 }
 export declare function isSearchable<T extends object, FilterValueType, FilterOptionsType, CD extends ColumnDef<T, FilterValueType, FilterOptionsType>>(def: CD): def is CD & HasCustomFilterFunction;
+/**
+ * Neutralises CSV / TSV formula-injection prefixes recognised by Excel,
+ * LibreOffice Calc, Google Sheets, and Apple Numbers.
+ *
+ * When a clipboard payload reaches a spreadsheet, any cell whose first
+ * character is one of `=`, `+`, `-`, `@`, `\t`, `\r` is treated as a
+ * formula and evaluated in the user's context. Untrusted row data
+ * containing `=cmd|'/c calc'!A1` (or DDE / web-query equivalents) is the
+ * canonical attack vector. Prefixing such a value with a single quote
+ * (`'`) makes the spreadsheet interpret the cell as a literal string
+ * instead.
+ *
+ * Trade-off: the leading apostrophe is invisible in the rendered cell of
+ * every major spreadsheet, but the underlying cell value differs from the
+ * source when read back by another formula referencing the cell. This is
+ * the accepted industry mitigation (OWASP CSV Injection cheat sheet).
+ *
+ * Private helper - keep this colocated with `encapsulate` so every
+ * clipboard-bound string flows through both functions before being
+ * written to the OS clipboard.
+ */
+declare function escapeForSpreadsheet(value: string): string;
+declare function encapsulate(value: string): string;
+/**
+ * Internal exports for tests. Not part of the public API; do not import
+ * from consumer code. Allows the clipboard formula-escape regression test
+ * to call the module-private helpers directly.
+ */
+export declare const _internal: {
+    escapeForSpreadsheet: typeof escapeForSpreadsheet;
+    encapsulate: typeof encapsulate;
+};
+export {};