@lavalogic/scoria 0.36.0 → 0.37.0

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

@@ -0,0 +1,751 @@
+import { tick } from 'svelte';
+import { devCatch } from '../../../../Helpers/Helpers.svelte.js';
+import { TableFocusDetails } from '../Focus/TableFocusDetails.svelte.js';
+/**
+ * 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 class FocusState {
+    _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). */
+    _focusStart = $state(null);
+    /** The opposite-corner cell of the focused range. Equal to
+     *  `focusStart` when a single cell is focused; differs during
+     *  Shift+Arrow / mouse-drag selection. */
+    _focusEnd = $state(null);
+    /** `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`. */
+    _focusStartIsBeingEdited = $state(false);
+    /** `true` between `startFocus` (mousedown on a cell) and `endFocus`
+     *  (mouseup). Drives the `setFocusEnd` mousemove listener attach /
+     *  detach in the table container. */
+    _isMousingDown = $state(false);
+    /**
+     * 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`).
+     */
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    _focusedRowIndices = $state(new Set());
+    /**
+     * Set of column ids currently inside the focused range. Mirrors
+     * `_focusedRowIndices` - populated by the parent's `$effect`.
+     */
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity
+    _focusedColumnIds = $state(new Set());
+    /**
+     * @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;
+    }
+    // -----------------------------------------------------------------
+    // state accessors (delegating-friendly: each slot is exposed
+    // through a public get/set pair so the parent's legacy getters
+    // can forward without piercing the boundary)
+    // -----------------------------------------------------------------
+    /** The anchor cell of the focused range. */
+    get focusStart() {
+        return this._focusStart;
+    }
+    /** The opposite-corner cell of the focused range. */
+    get focusEnd() {
+        return this._focusEnd;
+    }
+    set focusEnd(v) {
+        this._focusEnd = v;
+    }
+    /** `true` while the anchor cell is in edit-mode. */
+    get focusStartIsBeingEdited() {
+        return this._focusStartIsBeingEdited;
+    }
+    set focusStartIsBeingEdited(v) {
+        this._focusStartIsBeingEdited = v;
+    }
+    /** `true` between `startFocus` (mousedown) and `endFocus` (mouseup). */
+    get isMousingDown() {
+        return this._isMousingDown;
+    }
+    set isMousingDown(v) {
+        this._isMousingDown = v;
+    }
+    /** Set of row visible-indices currently inside the focused range. */
+    get focusedRowIndices() {
+        return this._focusedRowIndices;
+    }
+    /** Set of column ids currently inside the focused range. */
+    get focusedColumnIds() {
+        return this._focusedColumnIds;
+    }
+    /**
+     * 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, columnIds) {
+        this._focusedRowIndices = rowIndices;
+        this._focusedColumnIds = columnIds;
+    }
+    /**
+     * 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() {
+        if (!this._focusStart) {
+            return -1;
+        }
+        return this._deps.getVisualColumnIndexById(this._focusStart.id);
+    }
+    /**
+     * Visual-column index of `focusEnd`. Returns -1 when there is no
+     * active focus.
+     */
+    get focusEndVisualColumn() {
+        if (!this._focusEnd) {
+            return -1;
+        }
+        return this._deps.getVisualColumnIndexById(this._focusEnd.id);
+    }
+    // -----------------------------------------------------------------
+    // mouse-driven multi-cell selection (startFocus / endFocus /
+    // setFocusEnd) and the primary range writers (moveFocus / unfocus)
+    // -----------------------------------------------------------------
+    /** Begins a mouse-driven multi-cell selection at `coords`. */
+    startFocus = (coords) => {
+        this._isMousingDown = true;
+        this.moveFocus(coords);
+    };
+    /**
+     * 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).
+     */
+    moveFocus = (coords, startEditing = false) => {
+        this._focusStart = { ...coords };
+        this._focusEnd = { ...coords };
+        if (startEditing) {
+            tick()
+                .then(() => {
+                this._focusStartIsBeingEdited = true;
+            })
+                .catch(devCatch);
+        }
+    };
+    /** Clears focus start, focus end, and editing state. */
+    unfocus = () => {
+        this._focusStartIsBeingEdited = false;
+        this._focusStart = null;
+        this._focusEnd = null;
+    };
+    /** Ends a mouse-driven multi-cell selection at `coords`. */
+    endFocus = (coords) => {
+        if (this._isMousingDown) {
+            this._isMousingDown = false;
+            if (!this._deps.getAllowCopy()) {
+                return;
+            }
+            this._focusEnd = { ...coords };
+        }
+    };
+    /**
+     * Sets the end-of-range cell for keyboard-driven selection. Bound
+     * to mouse-drag start/end via `isMousingDown`; no-op when copy is
+     * disabled.
+     */
+    setFocusEnd = (coords) => {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        this._focusEnd = coords;
+    };
+    // -----------------------------------------------------------------
+    // range jumps (top / bottom / start / end)
+    // -----------------------------------------------------------------
+    /** Extends the focused range to the topmost row in the current page. */
+    focusToTop = () => {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        this._moveFocusEndRow(-Infinity);
+    };
+    /** Extends the focused range to the bottommost row in the current page. */
+    focusToBottom = () => {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        this._moveFocusEndRow(Infinity);
+    };
+    /** Moves the single focus cell to the bottommost row. */
+    moveToBottom = () => {
+        this._moveFocusRow(Infinity);
+    };
+    /** Moves the single focus cell to the topmost row. */
+    moveToTop = () => {
+        this._moveFocusRow(-Infinity);
+    };
+    /** Extends the focused range to the leftmost visible column. */
+    focusToStart = () => {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        if (!this._focusEnd) {
+            return;
+        }
+        const visualCols = this._deps.getVisualColumns();
+        if (visualCols.length > 0) {
+            const first = visualCols[0];
+            this._focusEnd = {
+                ...this._focusEnd,
+                id: first.id,
+                column: first.index,
+            };
+        }
+    };
+    /** Moves the single focus cell to the leftmost visible column. */
+    moveToStart = () => {
+        if (!this._focusStart) {
+            return;
+        }
+        const visualCols = this._deps.getVisualColumns();
+        if (visualCols.length > 0) {
+            const first = visualCols[0];
+            this.moveFocus({
+                ...this._focusStart,
+                id: first.id,
+                column: first.index,
+            });
+        }
+    };
+    /** Extends the focused range to the rightmost visible column. */
+    focusToEnd = () => {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        if (!this._focusEnd) {
+            return;
+        }
+        const visualCols = this._deps.getVisualColumns();
+        if (visualCols.length > 0) {
+            const last = visualCols[visualCols.length - 1];
+            this._focusEnd = {
+                ...this._focusEnd,
+                id: last.id,
+                column: last.index,
+            };
+        }
+    };
+    /** Moves the single focus cell to the rightmost visible column. */
+    moveToEnd = () => {
+        if (!this._focusStart) {
+            return;
+        }
+        const visualCols = this._deps.getVisualColumns();
+        if (visualCols.length > 0) {
+            const last = visualCols[visualCols.length - 1];
+            this.moveFocus({
+                ...this._focusStart,
+                id: last.id,
+                column: last.index,
+            });
+        }
+    };
+    // -----------------------------------------------------------------
+    // arrow-key moves (single-cell + range)
+    // -----------------------------------------------------------------
+    /** Extends the focused range one row up (Shift+ArrowUp). */
+    moveFocusUp = () => {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        this._moveFocusEndRow(-1);
+    };
+    /** Moves the single focus cell one row up (ArrowUp). */
+    setFocusUp = () => {
+        this._moveFocusRow(-1);
+    };
+    /** Extends the focused range one row down (Shift+ArrowDown). */
+    moveFocusDown = () => {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        this._moveFocusEndRow(1);
+    };
+    /** Moves the single focus cell one row down (ArrowDown). */
+    setFocusDown = () => {
+        this._moveFocusRow(1);
+    };
+    /** Extends the focused range one column left (Shift+ArrowLeft). */
+    moveFocusLeft = () => {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        if (this._focusEnd != null) {
+            const visualCols = this._deps.getVisualColumns();
+            const visualIndex = this._deps.getVisualColumnIndexById(this._focusEnd.id);
+            if (visualIndex > 0) {
+                const prev = visualCols[visualIndex - 1];
+                this._focusEnd = {
+                    ...this._focusEnd,
+                    id: prev.id,
+                    column: prev.index,
+                };
+            }
+        }
+    };
+    /** Moves the single focus cell one column left (ArrowLeft). */
+    setFocusLeft = () => {
+        if (!this._focusStart) {
+            return;
+        }
+        const visualCols = this._deps.getVisualColumns();
+        const visualIndex = this._deps.getVisualColumnIndexById(this._focusStart.id);
+        if (visualIndex > 0) {
+            const prev = visualCols[visualIndex - 1];
+            this.moveFocus({
+                ...this._focusStart,
+                id: prev.id,
+                column: prev.index,
+            });
+        }
+    };
+    /** Extends the focused range one column right (Shift+ArrowRight). */
+    moveFocusRight = () => {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        if (this._focusEnd != null) {
+            const visualCols = this._deps.getVisualColumns();
+            const visualIndex = this._deps.getVisualColumnIndexById(this._focusEnd.id);
+            if (visualIndex < visualCols.length - 1) {
+                const next = visualCols[visualIndex + 1];
+                this._focusEnd = {
+                    ...this._focusEnd,
+                    id: next.id,
+                    column: next.index,
+                };
+            }
+        }
+    };
+    /** Moves the single focus cell one column right (ArrowRight). */
+    setFocusRight = () => {
+        if (!this._focusStart) {
+            return;
+        }
+        const visualCols = this._deps.getVisualColumns();
+        const visualIndex = this._deps.getVisualColumnIndexById(this._focusStart.id);
+        if (visualIndex < visualCols.length - 1) {
+            const next = visualCols[visualIndex + 1];
+            this.moveFocus({
+                ...this._focusStart,
+                id: next.id,
+                column: next.index,
+            });
+        }
+    };
+    // -----------------------------------------------------------------
+    // Tab navigation (memory-order walk, skipping hidden columns)
+    // -----------------------------------------------------------------
+    /** 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. */
+    tabForward = () => {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        const visualCols = this._deps.getVisualColumns();
+        const rowBounds = this._deps.getSortedDataLength();
+        if (!this._focusStart || !rowBounds || visualCols.length === 0) {
+            return;
+        }
+        let { row, id: currentId } = this._focusStart;
+        let visualIndex = visualCols.findIndex((c) => c.id === currentId);
+        if (visualIndex < 0) {
+            return;
+        }
+        ++visualIndex;
+        while (row < rowBounds) {
+            if (visualIndex < visualCols.length) {
+                const def = visualCols[visualIndex];
+                this.moveFocus({ id: def.id, row, column: def.index }, this._focusStartIsBeingEdited);
+                return;
+            }
+            visualIndex = 0;
+            ++row;
+        }
+    };
+    /** Shift+Tab navigation: visit the previous visible cell in VISUAL
+     *  order, wrapping rows. Mirror of `tabForward`. */
+    tabBackward = () => {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        const visualCols = this._deps.getVisualColumns();
+        if (!this._focusStart || visualCols.length === 0) {
+            return;
+        }
+        let { row, id: currentId } = this._focusStart;
+        let visualIndex = visualCols.findIndex((c) => c.id === currentId);
+        if (visualIndex < 0) {
+            return;
+        }
+        --visualIndex;
+        while (row > -1) {
+            if (visualIndex > -1) {
+                const def = visualCols[visualIndex];
+                this.moveFocus({ id: def.id, row, column: def.index }, this._focusStartIsBeingEdited);
+                return;
+            }
+            visualIndex = visualCols.length - 1;
+            --row;
+        }
+    };
+    // -----------------------------------------------------------------
+    // keystroke routing
+    // -----------------------------------------------------------------
+    /**
+     * 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).
+     */
+    handleTdKeydown = (e) => {
+        e.stopPropagation();
+        if (e.key.toLocaleUpperCase() === 'F' && e.ctrlKey && this._deps.getAllowQuickFiltering()) {
+            e.preventDefault();
+            this._deps.toggleQuickFiltering();
+        }
+        else if (e.key === 'Escape') {
+            e.preventDefault();
+            this._focusStartIsBeingEdited = false;
+        }
+        else if (e.key === 'Tab') {
+            //allow regular operation in side panels
+            const target = e.target;
+            if (target?.closest('.side-panel') != null ||
+                target?.attributes.getNamedItem('data-type')?.value === 'quicksearch') {
+                return;
+            }
+            e.preventDefault();
+            if (e.getModifierState('Shift')) {
+                this._deps.tabBackward();
+            }
+            else {
+                this._deps.tabForward();
+            }
+        }
+        if (e.target.tagName === 'INPUT' &&
+            e.target.attributes.getNamedItem('type')?.value !== 'checkbox') {
+            return;
+        }
+        this.handleKeystroke(e).catch(devCatch);
+    };
+    /**
+     * 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.
+     */
+    async handleKeystroke(e) {
+        const allowCopy = this._deps.getAllowCopy();
+        switch (e.key) {
+            case 'Enter':
+            case 'F2':
+                if (!e.target?.classList.contains('editable')) {
+                    break;
+                }
+                e.preventDefault();
+                e.target?.dispatchEvent(new CustomEvent('edit', { detail: { selectAll: e.key === 'Enter' } }));
+                // focusStartIsBeingEdited.set(true);
+                break;
+            case 'ArrowUp': {
+                e.preventDefault();
+                if (e.getModifierState('Control')) {
+                    if (e.getModifierState('Shift')) {
+                        if (!allowCopy) {
+                            return;
+                        }
+                        this.focusToTop();
+                    }
+                    else {
+                        this.moveToTop();
+                    }
+                }
+                else if (e.getModifierState('Shift')) {
+                    if (!allowCopy) {
+                        return;
+                    }
+                    this.moveFocusUp();
+                }
+                else {
+                    this.setFocusUp();
+                }
+                return;
+            }
+            case 'ArrowDown': {
+                e.preventDefault();
+                if (e.getModifierState('Control')) {
+                    if (e.getModifierState('Shift')) {
+                        if (!allowCopy) {
+                            return;
+                        }
+                        this.focusToBottom();
+                    }
+                    else {
+                        this.moveToBottom();
+                    }
+                }
+                else if (e.getModifierState('Shift')) {
+                    if (!allowCopy) {
+                        return;
+                    }
+                    this.moveFocusDown();
+                }
+                else {
+                    this.setFocusDown();
+                }
+                return;
+            }
+            // TODO add ctrl-home and ctrl-end as ways to get to top-left/bottom-right
+            case 'ArrowLeft':
+            case 'Home': {
+                e.preventDefault();
+                if (e.getModifierState('Control') || e.key === 'Home') {
+                    if (e.getModifierState('Shift')) {
+                        if (!allowCopy) {
+                            return;
+                        }
+                        this.focusToStart();
+                    }
+                    else {
+                        this.moveToStart();
+                    }
+                    //these two at the bottom shouldn't happen on a home press
+                }
+                else if (e.getModifierState('Shift') && allowCopy) {
+                    this.moveFocusLeft();
+                }
+                else {
+                    this.setFocusLeft();
+                }
+                return;
+            }
+            case 'ArrowRight':
+            case 'End': {
+                e.preventDefault();
+                if (e.getModifierState('Control') || e.key === 'End') {
+                    if (e.getModifierState('Shift')) {
+                        if (!allowCopy) {
+                            return;
+                        }
+                        this.focusToEnd();
+                    }
+                    else {
+                        this.moveToEnd();
+                    }
+                }
+                else if (e.getModifierState('Shift') && allowCopy) {
+                    this.moveFocusRight();
+                }
+                else {
+                    this.setFocusRight();
+                }
+                return;
+            }
+            default: {
+                if (this._deps.getDebug()) {
+                    console.log(`handleKeystroke: ignoring key ${e.key}`);
+                }
+                break;
+            }
+        }
+        if (allowCopy) {
+            switch (e.key) {
+                case 'a': {
+                    if (e.ctrlKey) {
+                        e.preventDefault();
+                        this.moveToTop();
+                        this.moveToStart();
+                        this.focusToBottom();
+                        this.focusToEnd();
+                    }
+                    break;
+                }
+                case 'c':
+                case 'C':
+                    if (e.getModifierState('Control')) {
+                        e.preventDefault();
+                        await this._deps.copyDataToClipboard();
+                    }
+                    break;
+                default: {
+                    //nothing
+                    break;
+                }
+            }
+        }
+    }
+    // -----------------------------------------------------------------
+    // private row-axis offset walk
+    // -----------------------------------------------------------------
+    /**
+     * 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.
+     */
+    _moveFocusEndRow(offset) {
+        if (!this._deps.getAllowCopy()) {
+            return;
+        }
+        if (!this._focusEnd) {
+            console.warn('no focusEnd found');
+            return;
+        }
+        const focusEnd = this._focusEnd;
+        const prm = this._deps.getPaginationRowModel();
+        const rows = prm.rows;
+        const endRowIndex = rows.findIndex((row) => row.visibleIndex === focusEnd.row);
+        this._focusEnd = {
+            ...this._focusEnd,
+            row: rows[Math.max(Math.min(endRowIndex + offset, rows.length - 1), 0)].visibleIndex,
+        };
+    }
+    /**
+     * 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.
+     */
+    _moveFocusRow(offset) {
+        if (!this._focusStart) {
+            console.warn('no focusStart found');
+            return;
+        }
+        const focusStart = this._focusStart;
+        const newEndRowIndex = (() => {
+            const prm = this._deps.getPaginationRowModel();
+            const rows = prm.rows;
+            const endRowIndex = rows.findIndex((row) => row.visibleIndex === focusStart.row);
+            return rows[Math.max(Math.min(endRowIndex + offset, rows.length - 1), 0)].visibleIndex;
+        })();
+        this.moveFocus({ ...this._focusStart, row: newEndRowIndex });
+    }
+    // -----------------------------------------------------------------
+    // Per-cell TableFocusDetails reuse (Phase 7.1 Item C)
+    //
+    // Prior to Phase 7.1, every cell component (TableTextInput,
+    // FocusableImmutableCell, TableNumberInput, etc.) wrote
+    // `$derived(new TableFocusDetails(cell, tableContext))`. The
+    // `$derived` re-runs on each reactive dep change, so a freshly
+    // constructed `TableFocusDetails` was the dominant per-cell cost.
+    //
+    // Phase 6.6 deferred this because the natural cache key
+    // `${rowKey}:${columnId}` cannot be computed synchronously inside
+    // a cell render (SelectionState.cachedKey can return a Promise).
+    //
+    // Approach: use the cell reference ITSELF as the WeakMap key. Cell
+    // objects are constructed by `createRow` / `rowsPromise`; within a
+    // single render pass the same cell instance is passed through to
+    // each cell component, so the cache hits across the $derived
+    // re-evaluations that fire while the cell is mounted. When Item G
+    // stabilises Row references across pagination changes, cell refs
+    // also become stable and the cache hits across page flips too.
+    //
+    // `WeakMap` ensures cell objects do not pin TableFocusDetails
+    // after the row is dropped; GC reclaims both together.
+    // -----------------------------------------------------------------
+    _focusDetailsCache = new WeakMap();
+    /**
+     * 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(cell) {
+        let details = this._focusDetailsCache.get(cell);
+        if (!details) {
+            // The TableContext ref is supplied via a thunk to keep this
+            // sub-context decoupled from the parent. The thunk is
+            // expected to return the *current* parent reference; in
+            // practice the parent never recycles its TableContext.
+            const parent = this._deps.getTableContextRef();
+            details = new TableFocusDetails(cell, parent);
+            this._focusDetailsCache.set(cell, details);
+        }
+        return details;
+    }
+}