@lavalogic/scoria 0.36.0 → 0.37.1

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

@@ -0,0 +1,166 @@
+import type { BoolFilterValueType, DateFilterValueType, FilterFn, NumberFilterValueType, SelectFilterValueType, StringFilterValueType } from '../Filtering/FilterFn.js';
+import type { CustomRemoteFilters } from '../Filtering/CustomRemoteFilters.js';
+import type { ColumnFiltersState } from '../Filtering/ColumnFiltersState.js';
+import type { OnChangeFn } from '../OnChangeFn.js';
+import { PaginationType } from '../Pagination/PaginationType.js';
+import { SvelteMap } from 'svelte/reactivity';
+/**
+ * Dependency surface that `FilteringState` 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` and `$effect` exactly as before the extraction.
+ */
+export interface FilteringStateDeps<T extends object> {
+    /** Underlying repository row array (pre-filter). Sourced from
+     *  `tableContext.dataRepo.data`. */
+    getRepoData: () => ReadonlyArray<T>;
+    /** Pagination mode of the active data repository; only `Local`
+     *  triggers in-process filtering of the data slice. */
+    getPaginationType: () => PaginationType | undefined;
+    /** Per-filter `FilterFn` for date columns, sourced from
+     *  `paginationRepo.dateFilter`. */
+    getDateFilterFn: () => FilterFn<T, DateFilterValueType> | undefined;
+    /** Per-filter `FilterFn` for number columns. */
+    getNumberFilterFn: () => FilterFn<T, NumberFilterValueType> | undefined;
+    /** Per-filter `FilterFn` for select columns. */
+    getSelectFilterFn: () => FilterFn<T, SelectFilterValueType<T>> | undefined;
+    /** Per-filter `FilterFn` for boolean columns. */
+    getBoolFilterFn: () => FilterFn<T, BoolFilterValueType> | undefined;
+    /** Per-filter `FilterFn` for string columns. */
+    getStringFilterFn: () => FilterFn<T, StringFilterValueType> | undefined;
+    /** Map of currently-selected rows keyed by id. Read when
+     *  `showSelectedOnly` is true so the filtered view bypasses
+     *  `_filteredIndices` and returns the selection map directly. */
+    getSelectedItems: () => SvelteMap<unknown, T>;
+    /** Master gate from `TableInitOptions.allowQuickFiltering`. When
+     *  false, `showQuickFiltering` is forced to `false` regardless of
+     *  the consumer's setter call. */
+    getAllowQuickFiltering: () => boolean;
+    /** Logger gate; mirrors the parent `TableContext.debug` field. */
+    getDebug: () => boolean;
+}
+/**
+ * Phase 6.2 god-object decomposition - sub-context that owns the
+ * filtering-related state, the relayed per-type `FilterFn` derived
+ * values, the `filteredData` $derived chain, the user-facing toggle
+ * flags (`showQuickFiltering`, `showSelectedOnly`), the remote-filter
+ * slot, and the `updateFilters` `OnChangeFn` slot.
+ *
+ * `TableContext` retains delegating getters / setters for every legacy
+ * surface (`filteredIndices`, `filteredData`, `showQuickFiltering`,
+ * `showSelectedOnly`, `remoteFilters`, `dateFilter`, `numberFilter`,
+ * `selectFilter`, `boolFilter`, `stringFilter`, `updateFilters`); future
+ * consumers can read `tableContext._filtering` directly once the
+ * migration completes (see
+ * `src/stories/Concepts/TableContext-decomposition.mdx`).
+ */
+export declare class FilteringState<T extends object> {
+    private readonly _deps;
+    /** Internal mutable state for the per-row filter result. The
+     *  population effect lives in `TableContext` (it depends on
+     *  `createRow` which is a parent concern); the sub-context exposes
+     *  the read surface and the write hook. */
+    private _filteredIndices;
+    private _showQuickFiltering;
+    private _showSelectedOnly;
+    private _remoteFilters;
+    private _updateFilters;
+    /**
+     * @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: FilteringStateDeps<T>);
+    /**
+     * Per-row filter pass result, addressed by `dataRepo.data` index.
+     * Driven by the `filteredIndices` `$effect` that lives in
+     * `TableContext` (it calls `this.createRow` to build the row shape
+     * each `FilterFn` expects). Use `setFilteredIndices` to write.
+     */
+    get filteredIndices(): ReadonlyArray<number>;
+    /**
+     * Writer for `filteredIndices`. Public so the parent `TableContext`
+     * effect that performs the per-row filter pass can publish the
+     * result without piercing the sub-context's encapsulation. Not part
+     * of the consumer-facing surface.
+     */
+    setFilteredIndices(indices: ReadonlyArray<number>): void;
+    /**
+     * Whether the quick-filter row is currently visible. The setter
+     * enforces the `allowQuickFiltering` gate (a master init option):
+     * if quick filtering is disabled at the table level, the setter is
+     * a no-op except for the debug log. Mirrors the pre-extraction
+     * `TableContext.showQuickFiltering` setter verbatim.
+     */
+    get showQuickFiltering(): boolean;
+    set showQuickFiltering(v: boolean);
+    /**
+     * Whether the table is currently restricted to the selected-only
+     * view. Toggle bypasses pagination (the entire selection map is
+     * returned in place of the page slice). Idempotent - reassigning
+     * the same value short-circuits to avoid a `$state` write.
+     */
+    get showSelectedOnly(): boolean;
+    set showSelectedOnly(v: boolean);
+    /**
+     * Optional caller-supplied remote-filter description (used by the
+     * QueryBuilder / advanced-filter dialog when the data repository
+     * forwards filters to a remote service). Read-only externally; the
+     * parent populates it from `defaultColumnDefs.remoteFilters` during
+     * `init()`.
+     */
+    get remoteFilters(): CustomRemoteFilters<unknown> | undefined;
+    /**
+     * Writer for `remoteFilters`. Internal-only at the sub-context
+     * level; the parent uses `_filtering.setRemoteFilters` during
+     * column-def setup. Marked public so the parent class body can call
+     * it, but should not be reached from consumer code.
+     */
+    setRemoteFilters(v: CustomRemoteFilters<unknown> | undefined): void;
+    /**
+     * Caller-supplied `OnChangeFn<ColumnFiltersState>` that observes
+     * filter updates issued by `paginationRepo.filterBy`. Plain pass-
+     * through slot; this sub-context never invokes it directly - it is
+     * read by `generateTableOptions` (the `ITable.onColumnFiltersChange`
+     * getter).
+     */
+    get updateFilters(): OnChangeFn<ColumnFiltersState> | undefined;
+    set updateFilters(v: OnChangeFn<ColumnFiltersState> | undefined);
+    /** Relayed `FilterFn` for date-typed columns. Sourced through the
+     *  parent thunk; the parent in turn reads
+     *  `paginationRepo.dateFilter`. The `$derived.by` form is required
+     *  here (over plain `$derived(expr)`) because class-field
+     *  initialisers run BEFORE the constructor body assigns `_deps`;
+     *  the function-form wrapper defers the read until the derived is
+     *  first evaluated. */
+    readonly dateFilter: FilterFn<T, DateFilterValueType> | undefined;
+    /** Relayed `FilterFn` for number-typed columns. */
+    readonly numberFilter: FilterFn<T, NumberFilterValueType> | undefined;
+    /** Relayed `FilterFn` for select-typed columns. */
+    readonly selectFilter: FilterFn<T, SelectFilterValueType<T>> | undefined;
+    /** Relayed `FilterFn` for boolean-typed columns. */
+    readonly boolFilter: FilterFn<T, BoolFilterValueType> | undefined;
+    /** Relayed `FilterFn` for string-typed columns. */
+    readonly stringFilter: FilterFn<T, StringFilterValueType> | undefined;
+    /**
+     * The filtered view of the upstream `dataRepo.data` array. Three
+     * branches:
+     *
+     * 1. `paginationType === Local && showSelectedOnly`: returns the
+     *    selection map's values directly (bypasses pagination so the
+     *    "show selected" mode renders every selected row regardless of
+     *    the active page).
+     * 2. `paginationType === Local`: maps `_filteredIndices` through
+     *    `dataRepo.data` so the visible row order matches the source.
+     * 3. Any other pagination mode (Remote / undefined): returns
+     *    `dataRepo.data` unchanged (remote filtering already applied
+     *    upstream).
+     *
+     * Reactivity note: `selectedItems` is intentionally NOT touched
+     * outside the `showSelectedOnly` branches. Reading it unconditionally
+     * would invalidate `filteredData` → `sortedData` → `currentPageData`
+     * → the entire row model on every single toggle (regression caught
+     * during Phase-5 Group 2).
+     */
+    readonly filteredData: T[];
+}

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

@@ -0,0 +1,180 @@
+import { PaginationType } from '../Pagination/PaginationType.js';
+import { SvelteMap } from 'svelte/reactivity';
+/**
+ * Phase 6.2 god-object decomposition - sub-context that owns the
+ * filtering-related state, the relayed per-type `FilterFn` derived
+ * values, the `filteredData` $derived chain, the user-facing toggle
+ * flags (`showQuickFiltering`, `showSelectedOnly`), the remote-filter
+ * slot, and the `updateFilters` `OnChangeFn` slot.
+ *
+ * `TableContext` retains delegating getters / setters for every legacy
+ * surface (`filteredIndices`, `filteredData`, `showQuickFiltering`,
+ * `showSelectedOnly`, `remoteFilters`, `dateFilter`, `numberFilter`,
+ * `selectFilter`, `boolFilter`, `stringFilter`, `updateFilters`); future
+ * consumers can read `tableContext._filtering` directly once the
+ * migration completes (see
+ * `src/stories/Concepts/TableContext-decomposition.mdx`).
+ */
+export class FilteringState {
+    _deps;
+    /** Internal mutable state for the per-row filter result. The
+     *  population effect lives in `TableContext` (it depends on
+     *  `createRow` which is a parent concern); the sub-context exposes
+     *  the read surface and the write hook. */
+    _filteredIndices = $state([]);
+    _showQuickFiltering = $state(false);
+    _showSelectedOnly = $state(false);
+    _remoteFilters = $state();
+    _updateFilters = $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;
+    }
+    /**
+     * Per-row filter pass result, addressed by `dataRepo.data` index.
+     * Driven by the `filteredIndices` `$effect` that lives in
+     * `TableContext` (it calls `this.createRow` to build the row shape
+     * each `FilterFn` expects). Use `setFilteredIndices` to write.
+     */
+    get filteredIndices() {
+        return this._filteredIndices;
+    }
+    /**
+     * Writer for `filteredIndices`. Public so the parent `TableContext`
+     * effect that performs the per-row filter pass can publish the
+     * result without piercing the sub-context's encapsulation. Not part
+     * of the consumer-facing surface.
+     */
+    setFilteredIndices(indices) {
+        this._filteredIndices = indices;
+    }
+    /**
+     * Whether the quick-filter row is currently visible. The setter
+     * enforces the `allowQuickFiltering` gate (a master init option):
+     * if quick filtering is disabled at the table level, the setter is
+     * a no-op except for the debug log. Mirrors the pre-extraction
+     * `TableContext.showQuickFiltering` setter verbatim.
+     */
+    get showQuickFiltering() {
+        return this._showQuickFiltering;
+    }
+    set showQuickFiltering(v) {
+        if (this._deps.getDebug()) {
+            if (!this._deps.getAllowQuickFiltering()) {
+                console.log(`attempted to toggle quick filtering when allowQuickFiltering = false`);
+            }
+            else {
+                console.log(`setting quick filtering = ${v}`);
+            }
+        }
+        this._showQuickFiltering = this._deps.getAllowQuickFiltering() && v;
+    }
+    /**
+     * Whether the table is currently restricted to the selected-only
+     * view. Toggle bypasses pagination (the entire selection map is
+     * returned in place of the page slice). Idempotent - reassigning
+     * the same value short-circuits to avoid a `$state` write.
+     */
+    get showSelectedOnly() {
+        return this._showSelectedOnly;
+    }
+    set showSelectedOnly(v) {
+        if (v === this._showSelectedOnly) {
+            return;
+        }
+        this._showSelectedOnly = v;
+    }
+    /**
+     * Optional caller-supplied remote-filter description (used by the
+     * QueryBuilder / advanced-filter dialog when the data repository
+     * forwards filters to a remote service). Read-only externally; the
+     * parent populates it from `defaultColumnDefs.remoteFilters` during
+     * `init()`.
+     */
+    get remoteFilters() {
+        return this._remoteFilters;
+    }
+    /**
+     * Writer for `remoteFilters`. Internal-only at the sub-context
+     * level; the parent uses `_filtering.setRemoteFilters` during
+     * column-def setup. Marked public so the parent class body can call
+     * it, but should not be reached from consumer code.
+     */
+    setRemoteFilters(v) {
+        this._remoteFilters = v;
+    }
+    /**
+     * Caller-supplied `OnChangeFn<ColumnFiltersState>` that observes
+     * filter updates issued by `paginationRepo.filterBy`. Plain pass-
+     * through slot; this sub-context never invokes it directly - it is
+     * read by `generateTableOptions` (the `ITable.onColumnFiltersChange`
+     * getter).
+     */
+    get updateFilters() {
+        return this._updateFilters;
+    }
+    set updateFilters(v) {
+        this._updateFilters = v;
+    }
+    /** Relayed `FilterFn` for date-typed columns. Sourced through the
+     *  parent thunk; the parent in turn reads
+     *  `paginationRepo.dateFilter`. The `$derived.by` form is required
+     *  here (over plain `$derived(expr)`) because class-field
+     *  initialisers run BEFORE the constructor body assigns `_deps`;
+     *  the function-form wrapper defers the read until the derived is
+     *  first evaluated. */
+    dateFilter = $derived.by(() => this._deps.getDateFilterFn());
+    /** Relayed `FilterFn` for number-typed columns. */
+    numberFilter = $derived.by(() => this._deps.getNumberFilterFn());
+    /** Relayed `FilterFn` for select-typed columns. */
+    selectFilter = $derived.by(() => this._deps.getSelectFilterFn());
+    /** Relayed `FilterFn` for boolean-typed columns. */
+    boolFilter = $derived.by(() => this._deps.getBoolFilterFn());
+    /** Relayed `FilterFn` for string-typed columns. */
+    stringFilter = $derived.by(() => this._deps.getStringFilterFn());
+    /**
+     * The filtered view of the upstream `dataRepo.data` array. Three
+     * branches:
+     *
+     * 1. `paginationType === Local && showSelectedOnly`: returns the
+     *    selection map's values directly (bypasses pagination so the
+     *    "show selected" mode renders every selected row regardless of
+     *    the active page).
+     * 2. `paginationType === Local`: maps `_filteredIndices` through
+     *    `dataRepo.data` so the visible row order matches the source.
+     * 3. Any other pagination mode (Remote / undefined): returns
+     *    `dataRepo.data` unchanged (remote filtering already applied
+     *    upstream).
+     *
+     * Reactivity note: `selectedItems` is intentionally NOT touched
+     * outside the `showSelectedOnly` branches. Reading it unconditionally
+     * would invalidate `filteredData` → `sortedData` → `currentPageData`
+     * → the entire row model on every single toggle (regression caught
+     * during Phase-5 Group 2).
+     */
+    filteredData = $derived.by(() => {
+        const repoData = this._deps.getRepoData();
+        void this._filteredIndices;
+        void this._showSelectedOnly;
+        const paginationType = this._deps.getPaginationType();
+        if (paginationType == PaginationType.Local) {
+            const data = this._showSelectedOnly
+                ? // FIXME this will show the selected items by order of insertion to the selectedItems map.
+                    [...this._deps.getSelectedItems().values()]
+                : this._filteredIndices.map((index) => {
+                    return repoData[index];
+                });
+            return data;
+        }
+        if (this._deps.getDebug()) {
+            console.log(`updating filtered data. Selected only: ${this._showSelectedOnly}`);
+        }
+        return this._showSelectedOnly
+            ? [...this._deps.getSelectedItems().values()]
+            : repoData;
+    });
+}

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

@@ -0,0 +1,316 @@
+import type { ColumnDef } from '../Columns/Definitions/ColumnDef.svelte.js';
+import type { VisibilityState } from '../Columns/VisibilityState.js';
+import type { TableCell } from '../Columns/TableCell.js';
+import type { CellCoordinates } from '../Coordinates/CellCoordinates.js';
+import type { VisualColumnIndex } from '../Coordinates/ColumnIndices.js';
+import { TableFocusDetails } from '../Focus/TableFocusDetails.svelte.js';
+import type { Primitive } from './TableInitOptions.js';
+import type { RowModel } from './RowModel.js';
+/**
+ * Dependency surface that `FocusState` reads from the surrounding
+ * `TableContext`. Every dependency is passed as a thunk (or a callback
+ * for parent-owned side effects) so the sub-context never holds a
+ * direct reference to the parent; reactivity threads through `$state`
+ * exactly as before the extraction.
+ *
+ * Splits cleanly into four groups:
+ *
+ *   1. Master gates: `getAllowCopy`, `getAllowQuickFiltering`. Gate
+ *      the range-extension and Ctrl+F keystroke paths.
+ *
+ *   2. Column-layout thunks (`getColumnDefs`, `getColumnVisibility`,
+ *      `getVisualColumns`, `getVisualColumnIndexById`) - used by the
+ *      tab navigation walk and the left/right focus moves. These read
+ *      through to `_columnLayout` on the parent.
+ *
+ *   3. Data-shape thunks (`getSortedDataLength`,
+ *      `getPaginationRowModel`) - bound the row-axis walk.
+ *
+ *   4. Parent-side actions:
+ *      - `copyDataToClipboard` (Ctrl+C in `handleKeystroke`),
+ *      - `toggleQuickFiltering` (Ctrl+F in `handleTdKeydown`).
+ *
+ * `getDebug` mirrors the parent's logger gate.
+ */
+export interface FocusStateDeps<T extends object> {
+    /** Master gate from `TableInitOptions.allowCopy`. When false,
+     *  every range-extension keystroke (Shift+Arrow / Ctrl+Shift+Arrow /
+     *  Ctrl+A / Ctrl+C / Tab) is a no-op. */
+    getAllowCopy: () => boolean;
+    /** Master gate from `TableInitOptions.allowQuickFiltering`. Gates
+     *  the `Ctrl+F` keystroke that toggles the quick-filter row. */
+    getAllowQuickFiltering: () => boolean;
+    /** Live column-def array. Used by `tabForward` / `tabBackward`
+     *  to walk memory-index order. */
+    getColumnDefs: () => ReadonlyArray<ColumnDef<T>>;
+    /** Live column-visibility map. Used by tab navigation to skip
+     *  hidden columns. */
+    getColumnVisibility: () => VisibilityState;
+    /** Visual-order column array from `ColumnLayoutState`. Used by
+     *  left/right focus moves and Home/End jumps. */
+    getVisualColumns: () => ReadonlyArray<ColumnDef<T>>;
+    /** O(1) id->visual-index lookup from `ColumnLayoutState`. */
+    getVisualColumnIndexById: (id: string) => VisualColumnIndex;
+    /** Length of the sorted-and-filtered data array. Used by
+     *  `tabForward` row-axis bounds. */
+    getSortedDataLength: () => number;
+    /** Live `paginationRowModel`. Used by the row-axis offset walk
+     *  in `_moveFocusEndRow` / `_moveFocusRow`. */
+    getPaginationRowModel: () => RowModel<T>;
+    /** Parent's `copyDataToClipboard` (Ctrl+C path in handleKeystroke).
+     *  Stays on the parent because it reads `_visualColumns` and the
+     *  per-row accessor chain. */
+    copyDataToClipboard: () => Promise<void>;
+    /** Parent's `toggleQuickFiltering` (Ctrl+F path in handleTdKeydown).
+     *  Stays on the parent because it reads `showQuickFiltering` /
+     *  `tableName` and synchronously refocuses a DOM element. */
+    toggleQuickFiltering: () => void;
+    /** Parent's `tabForward` keystroke. Stays on the parent so the
+     *  sub-context has a single delegation seam for keyboard routing
+     *  while leaving the column-walk in this class. */
+    tabForward: () => void;
+    /** Parent's `tabBackward` keystroke. Same rationale as
+     *  `tabForward`. */
+    tabBackward: () => void;
+    /** Logger gate; mirrors the parent `TableContext.debug` field. */
+    getDebug: () => boolean;
+    /** Returns the parent `TableContext`. Used by
+     *  `getFocusDetailsFor` to construct `TableFocusDetails`
+     *  lazily on cache-miss (Phase 7.1 Item C). The thunk is
+     *  used instead of a direct ref so the sub-context never
+     *  closes over the parent at construction time. */
+    getTableContextRef: () => unknown;
+}
+/**
+ * Phase 6.6 god-object decomposition - sub-context that owns every
+ * focus + keyboard-navigation concern previously held directly on
+ * `TableContext`:
+ *
+ * - `focusStart` / `focusEnd` (the two `CellCoordinates` slots that
+ *   define the focused cell-range);
+ * - `focusStartIsBeingEdited` (the editing-mode flag);
+ * - `isMousingDown` (drag-select sentinel for mouse-driven multi-cell
+ *   selection);
+ * - the `focusedRowIndices` / `focusedColumnIds` derived sets that
+ *   power the per-cell `TableFocusDetails` outline computation;
+ * - `startFocus` / `moveFocus` / `unfocus` / `endFocus` / `setFocusEnd`
+ *   (consumer-facing writers - mouse-driven and direct);
+ * - `focusToTop` / `focusToBottom` / `moveToTop` / `moveToBottom` /
+ *   `focusToStart` / `focusToEnd` / `moveToStart` / `moveToEnd`
+ *   (range jumps);
+ * - `moveFocusUp` / `setFocusUp` / `moveFocusDown` / `setFocusDown` /
+ *   `moveFocusLeft` / `setFocusLeft` / `moveFocusRight` / `setFocusRight`
+ *   (single-cell vs. range arrow moves);
+ * - `handleTdKeydown` (the table-container `onkeydown` router);
+ * - `handleKeystroke` (the dispatch into the arrow/Home/End/Ctrl+A/
+ *   Ctrl+C paths);
+ * - `focusStartVisualColumn` / `focusEndVisualColumn` (visual-column
+ *   getters powered by `getVisualColumnIndexById`).
+ *
+ * Effect lifecycle: the parent owns the `$effect` that publishes
+ * `_focusedRowIndices` / `_focusedColumnIds`. That effect now calls
+ * into this sub-context through `setFocusedDerived(rows, cols)`
+ * rather than mutating the state slots directly. The effect lives
+ * on `TableContext` because it needs the parent's
+ * `paginationRowModel` + `_visualColumns` reads.
+ *
+ * `TableContext` retains delegating getters / setters / methods for
+ * every legacy surface (`focusStart`, `focusEnd`, `focusStartIsBeingEdited`,
+ * `isMousingDown`, `focusedRowIndices`, `focusedColumnIds`,
+ * `focusStartVisualColumn`, `focusEndVisualColumn`, `startFocus`,
+ * `moveFocus`, `unfocus`, `endFocus`, `setFocusEnd`, `setFocusUp`,
+ * `setFocusDown`, `setFocusLeft`, `setFocusRight`, `moveFocusUp`,
+ * `moveFocusDown`, `moveFocusLeft`, `moveFocusRight`, `moveToTop`,
+ * `moveToBottom`, `moveToStart`, `moveToEnd`, `focusToTop`,
+ * `focusToBottom`, `focusToStart`, `focusToEnd`, `handleTdKeydown`)
+ * so existing consumers need no migration.
+ *
+ * @remarks
+ * Group 2 Item C (per-cell `TableFocusDetails` reuse) is deferred for
+ * Phase 6.6. The cache would need a `${rowKey}:${columnId}` key, but
+ * `selectionExtractor` can be async (the sub-context's `cachedKey`
+ * returns `RowIdType | Promise<RowIdType>`), so the cache lookup
+ * cannot complete synchronously inside a cell render. The reuse
+ * requires a follow-up refactor that either:
+ *   a) memoises `TableFocusDetails` instances on the row reference
+ *      (a `WeakMap<TableCell<T>, TableFocusDetails<T, RowIdType>>`),
+ *      which side-steps the async key entirely, or
+ *   b) hoists the key resolution into a `$state` slot populated by
+ *      `updateSelectedItems` so the lookup is sync at render time.
+ * Both are larger surface changes than the FocusState extraction;
+ * tracked under Phase 6.7 BREAKING-CHANGES.md.
+ */
+export declare class FocusState<T extends object> {
+    private readonly _deps;
+    /** The anchor cell of the focused range. `null` when the table has no
+     *  active focus (post-`unfocus`, or before the first mouse / keyboard
+     *  interaction). */
+    private _focusStart;
+    /** The opposite-corner cell of the focused range. Equal to
+     *  `focusStart` when a single cell is focused; differs during
+     *  Shift+Arrow / mouse-drag selection. */
+    private _focusEnd;
+    /** `true` while the anchor cell is in edit-mode (the cell's editable
+     *  child input has focus). Set by `moveFocus(coords, true)` and
+     *  cleared by `Escape` / `unfocus`. */
+    private _focusStartIsBeingEdited;
+    /** `true` between `startFocus` (mousedown on a cell) and `endFocus`
+     *  (mouseup). Drives the `setFocusEnd` mousemove listener attach /
+     *  detach in the table container. */
+    private _isMousingDown;
+    /**
+     * Set of row visible-indices currently inside the focused range.
+     * Populated by the parent's `$effect` through `setFocusedDerived`
+     * (the effect reads `paginationRowModel` directly so it stays on
+     * `TableContext`).
+     */
+    private _focusedRowIndices;
+    /**
+     * Set of column ids currently inside the focused range. Mirrors
+     * `_focusedRowIndices` - populated by the parent's `$effect`.
+     */
+    private _focusedColumnIds;
+    /**
+     * @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: FocusStateDeps<T>);
+    /** The anchor cell of the focused range. */
+    get focusStart(): CellCoordinates | null;
+    /** The opposite-corner cell of the focused range. */
+    get focusEnd(): CellCoordinates | null;
+    set focusEnd(v: CellCoordinates | null);
+    /** `true` while the anchor cell is in edit-mode. */
+    get focusStartIsBeingEdited(): boolean;
+    set focusStartIsBeingEdited(v: boolean);
+    /** `true` between `startFocus` (mousedown) and `endFocus` (mouseup). */
+    get isMousingDown(): boolean;
+    set isMousingDown(v: boolean);
+    /** Set of row visible-indices currently inside the focused range. */
+    get focusedRowIndices(): ReadonlySet<number>;
+    /** Set of column ids currently inside the focused range. */
+    get focusedColumnIds(): ReadonlySet<string>;
+    /**
+     * Setter for the two derived sets, driven by the parent's
+     * `$effect`. The effect lives on `TableContext` because it needs
+     * the parent's `paginationRowModel` + `_visualColumns` reads; the
+     * sub-context publishes its result through this single seam.
+     */
+    setFocusedDerived(rowIndices: ReadonlySet<number>, columnIds: ReadonlySet<string>): void;
+    /**
+     * Visual-column index of `focusStart`. Returns -1 when there is no
+     * active focus. Reads through to the `getVisualColumnIndexById`
+     * thunk (which is owned by `ColumnLayoutState`).
+     */
+    get focusStartVisualColumn(): VisualColumnIndex;
+    /**
+     * Visual-column index of `focusEnd`. Returns -1 when there is no
+     * active focus.
+     */
+    get focusEndVisualColumn(): VisualColumnIndex;
+    /** Begins a mouse-driven multi-cell selection at `coords`. */
+    readonly startFocus: (coords: CellCoordinates) => void;
+    /**
+     * Moves the focused cell to `coords`, collapsing any multi-cell
+     * range onto the single coordinate. Pass `startEditing` to enter
+     * edit mode on the next microtask (after the DOM has caught up to
+     * the new focus target).
+     */
+    readonly moveFocus: (coords: CellCoordinates, startEditing?: boolean) => void;
+    /** Clears focus start, focus end, and editing state. */
+    readonly unfocus: () => void;
+    /** Ends a mouse-driven multi-cell selection at `coords`. */
+    readonly endFocus: (coords: CellCoordinates) => void;
+    /**
+     * Sets the end-of-range cell for keyboard-driven selection. Bound
+     * to mouse-drag start/end via `isMousingDown`; no-op when copy is
+     * disabled.
+     */
+    readonly setFocusEnd: (coords: CellCoordinates) => void;
+    /** Extends the focused range to the topmost row in the current page. */
+    readonly focusToTop: () => void;
+    /** Extends the focused range to the bottommost row in the current page. */
+    readonly focusToBottom: () => void;
+    /** Moves the single focus cell to the bottommost row. */
+    readonly moveToBottom: () => void;
+    /** Moves the single focus cell to the topmost row. */
+    readonly moveToTop: () => void;
+    /** Extends the focused range to the leftmost visible column. */
+    readonly focusToStart: () => void;
+    /** Moves the single focus cell to the leftmost visible column. */
+    readonly moveToStart: () => void;
+    /** Extends the focused range to the rightmost visible column. */
+    readonly focusToEnd: () => void;
+    /** Moves the single focus cell to the rightmost visible column. */
+    readonly moveToEnd: () => void;
+    /** Extends the focused range one row up (Shift+ArrowUp). */
+    readonly moveFocusUp: () => void;
+    /** Moves the single focus cell one row up (ArrowUp). */
+    readonly setFocusUp: () => void;
+    /** Extends the focused range one row down (Shift+ArrowDown). */
+    readonly moveFocusDown: () => void;
+    /** Moves the single focus cell one row down (ArrowDown). */
+    readonly setFocusDown: () => void;
+    /** Extends the focused range one column left (Shift+ArrowLeft). */
+    readonly moveFocusLeft: () => void;
+    /** Moves the single focus cell one column left (ArrowLeft). */
+    readonly setFocusLeft: () => void;
+    /** Extends the focused range one column right (Shift+ArrowRight). */
+    readonly moveFocusRight: () => void;
+    /** Moves the single focus cell one column right (ArrowRight). */
+    readonly setFocusRight: () => void;
+    /** Tab-key navigation: visit the next visible cell in VISUAL order,
+     *  wrapping rows. Visual order means left-pinned columns come
+     *  first (in pin order), then centre columns (in column-def
+     *  order), then right-pinned columns. The `visualColumns` array
+     *  on `ColumnLayoutState` is already pre-filtered to visible
+     *  columns, so no separate visibility check is required here. */
+    readonly tabForward: () => void;
+    /** Shift+Tab navigation: visit the previous visible cell in VISUAL
+     *  order, wrapping rows. Mirror of `tabForward`. */
+    readonly tabBackward: () => void;
+    /**
+     * Root-level `onkeydown` handler attached at the table-container
+     * level. Owns: Ctrl+F toggle for quick filter, Escape exit-edit,
+     * Tab cycle, and dispatch into the arrow-key navigation paths via
+     * `handleKeystroke`.
+     *
+     * The Ctrl+F and Tab branches delegate to parent thunks
+     * (`toggleQuickFiltering`, `tabForward`, `tabBackward`) because the
+     * parent owns the legacy public surface and may need to coordinate
+     * with DOM concerns (the quick-filter toggle synchronously
+     * refocuses a `<td>` after the toggle).
+     */
+    readonly handleTdKeydown: (e: KeyboardEvent) => void;
+    /**
+     * Arrow / Home / End / Ctrl+A / Ctrl+C dispatch. Split out from
+     * `handleTdKeydown` so the synchronous Ctrl+F / Escape / Tab
+     * branches can run before the async copy path.
+     */
+    private handleKeystroke;
+    /**
+     * Shift the focusEnd row by `offset` rows in the current
+     * `paginationRowModel`. `Infinity` / `-Infinity` jumps to the last /
+     * first row. No-op when `allowCopy` is false or focusEnd is null.
+     */
+    private _moveFocusEndRow;
+    /**
+     * Move the single-cell focus (focusStart + focusEnd) by `offset`
+     * rows in the current `paginationRowModel`. Reused for the
+     * non-range arrow keys (ArrowDown / ArrowUp without Shift) and the
+     * Ctrl+ArrowDown / Ctrl+ArrowUp jumps to the top / bottom row.
+     */
+    private _moveFocusRow;
+    private readonly _focusDetailsCache;
+    /**
+     * Returns a `TableFocusDetails` keyed on the supplied cell. The
+     * first call for a given cell constructs the instance; subsequent
+     * calls return the cached instance.
+     *
+     * Generic - the returned `TableFocusDetails<T, IdType>` is widened
+     * to `Primitive` for the cache, but the typed cast on return keeps
+     * the call-site signature clean for cell consumers.
+     */
+    getFocusDetailsFor<IdType extends Primitive = Primitive>(cell: TableCell<T>): TableFocusDetails<T, IdType>;
+}