@sheetxl/grid-react 0.8.0-beta.1 → 0.8.0-beta.11

package/types/src/selection/SelectionLayer.d.ts

@@ -1,11 +1,11 @@
 import { default as React } from 'react';
-import { CellCoords, RangeCoords } from '@sheetxl/utils';
+import { RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
 import { LayerProps, GridPlacement } from '../layer';
 import { VisualSVGProps } from '../svg';
 import { RangeEdge } from '../range';
 import { ISelection } from './ISelection';
 import { SelectionNavigation } from './Types';
-import { SelectionRangeStyle } from './SelectionStyle';
+import { SelectionRangeStyle, InsertBarStyle } from './SelectionStyle';
 /**
  * The in-flight selection gesture passed to {@link SelectionLayerProps.renderTip}:
  * - `select` — a drag-select growing the active range (Excel's live R×C);
@@ -19,11 +19,44 @@ export type SelectionGesture = {
     kind: 'move';
     from: RangeCoords;
     to: RangeCoords;
+    drop: MoveDrop;
 } | {
     kind: 'fill';
     template: RangeCoords;
     destination: RangeCoords;
 };
+/**
+ * What a move drag would DO if released now — the destination plus the mode its modifiers select.
+ * Excel's three grip gestures, as data: drag relocates, Ctrl+drag copies, Shift+drag inserts (and
+ * Ctrl+Shift inserts a copy).
+ *
+ * @remarks
+ * The mode lives here rather than being re-derived from a pointer event by each consumer, because the
+ * modifiers change with the pointer standing still — see {@link DragMoveInfo}.
+ */
+export interface MoveDrop {
+    /**
+     * Where the block lands. For an insert this is the block RE-ANCHORED on the pointer's cell, not the
+     * drag's translation — take the destination from here rather than re-deriving it.
+     */
+    to: RangeCoords;
+    /** Ctrl / Cmd is held: the source is copied rather than cut. */
+    copy: boolean;
+    /**
+     * Shift is held: INSERT at {@link MoveDrop.to} instead of dropping over it — the cells already there
+     * step aside along this axis (`Row` = down, `Column` = right), which is also the edge of `to` the
+     * I-beam is drawn on. Absent for a plain overwrite drop.
+     */
+    insert?: RangeAxis;
+    /**
+     * The drop cannot be performed and a release does nothing: a cut INSERT whose line falls inside the
+     * block being dragged, or one that would shift only part of it (see `CoordUtils.classifyInsertCut`
+     * - the same call the model makes, so a beam drawn as legal is one the model will accept), or
+     * whatever else {@link SelectionLayerProps.isDropRefused} rules out. The preview draws the I-beam
+     * (or the ghost) in the refused color instead, and `onMove` never fires.
+     */
+    refused?: boolean;
+}
 /**
  * Props for {@link SelectionLayer}.
  */
@@ -41,7 +74,7 @@ export interface SelectionLayerProps extends LayerProps {
     getContentBounds?: () => RangeCoords;
     /**
      * The bounding REGION enclosing a cell — a table's data range from a tier that knows tables (the sheet
-     * layer), else `null` (the bare sheet). Drives Tab/Enter wrapping inside a table and the row/column
+     * layer), else `null` (the bare sheet). Drives Tab wrapping inside a table and the row/column
      * span of Ctrl/Shift+Space. Omit it (the dumb {@link DefaultSelection} tier) and there is no enclosing
      * region: Tab is a plain move and Ctrl/Shift+Space select the whole grid. The layer never learns it's a
      * sheet — just a `cell → bounds | null` getter; any escalation lives in the provider.
@@ -70,6 +103,35 @@ export interface SelectionLayerProps extends LayerProps {
     singleAnchorStyle?: VisualSVGProps;
     /** The Ctrl/Cmd-drag remove rubber-band. Merged (slot-by-slot) over {@link DEFAULT_REMOVE_PREVIEW_STYLE}. */
     removePreviewStyle?: SelectionRangeStyle;
+    /** The Shift-drag insert I-beam. Merged over {@link DEFAULT_INSERT_BAR_STYLE}. */
+    insertBarStyle?: InsertBarStyle;
+    /**
+     * Whether a drop would be REFUSED - drawn as a refused I-beam (or ghost), and inert on release.
+     * Asked for every drop, insert or not; a copy INSERT is never refused, as it leaves no gap to
+     * resolve. Defaults to the geometry a grid can see on its own (`CoordUtils.classifyInsertCut`: a
+     * cut whose gap the insert would only half close, or a line dropped inside the block itself); a
+     * plain drop is then never refused.
+     *
+     * @remarks
+     * A model knows more than the grid does - a merge the shift would tear, a table it would split, a
+     * merged cell a drop would land across - so a host that has one should answer from it
+     * (`ICellRange.canInsertFrom`, `ICellRange.getDropTarget`), which is what keeps the preview honest
+     * about drops the grid could not have ruled out.
+     */
+    isDropRefused?: (from: RangeCoords, drop: MoveDrop) => boolean;
+    /**
+     * Adjust where a plain (non-insert) move drop lands before it drives the ghost, the tip and the
+     * callbacks - e.g. onto the whole of a merged cell a single cell is dropped onto, so the ghost shows
+     * what the drop will cover. Given the source and the pointer-derived drop, return the destination
+     * to use. Omit for no snapping.
+     */
+    snapMoveDestination?: (from: RangeCoords, drop: MoveDrop) => RangeCoords;
+    /**
+     * The mute drawn over the source while a **cut** (plain) move drag is in flight — see
+     * {@link DEFAULT_MOVE_SOURCE_STYLE}, which it merges over. `null` draws no mute, leaving the cursor
+     * as the only cut-vs-copy tell.
+     */
+    moveSourceStyle?: SelectionRangeStyle | null;
     /**
      * Stacked layers (fill, move, …) rendered when a single range is selected.
      */
@@ -86,21 +148,37 @@ export interface SelectionLayerProps extends LayerProps {
     enabledMove?: boolean;
     /**
      * Called when the single range is moved by its border — `from` is the original range, `to` the new
-     * one. The selection follows automatically; use this for the data side-effect (cut-move).
+     * one (`drop.to`, snapped when inserting). The selection follows automatically; use this for the data
+     * side-effect, which `drop` describes: a cut-move, a copy, or an insert along `drop.insert`.
+     */
+    onMove?: (from: RangeCoords, to: RangeCoords, e: React.PointerEvent, drop: MoveDrop) => void;
+    /**
+     * The move drag started (before any translation) — `from` is the range being moved. `cancel` aborts
+     * the drag as Escape would ({@link SelectionLayerProps.onMoveEnd} follows, nothing moved) — for a
+     * mode's chrome cancel.
      */
-    onMove?: (from: RangeCoords, to: RangeCoords, e: React.PointerEvent) => void;
-    /** The move drag started (before any translation) — `from` is the range being moved. */
-    onMoveStart?: (from: RangeCoords, e: React.PointerEvent) => void;
+    onMoveStart?: (from: RangeCoords, e: React.PointerEvent, drop: MoveDrop, cancel: () => void) => void;
     /**
-     * Live during the move drag — `to` is the in-flight translated range. `e` carries the current
-     * modifiers (Ctrl = copy, Shift = insert), so a consumer can reflect the mode (cursor/description).
+     * Live during the move drag — `to` is the in-flight destination and `drop` what a release would do.
+     * Fires on every change, INCLUDING a modifier pressed or released with the pointer standing still
+     * (that is the whole point: the mode must be reflected — cursor, status description — the instant
+     * the key goes down). Take the mode from `drop`; `e` is merely the last pointer event.
      */
-    onMoveUpdate?: (from: RangeCoords, to: RangeCoords, e: React.PointerEvent) => void;
+    onMoveUpdate?: (from: RangeCoords, to: RangeCoords, e: React.PointerEvent, drop: MoveDrop) => void;
     /**
      * The move drag ended (fires on release regardless of whether the range actually moved) — for teardown
      * of anything {@link SelectionLayerProps.onMoveStart}/`onMoveUpdate` set (e.g. clearing a drag mode).
      */
     onMoveEnd?: () => void;
+    /**
+     * The cursor to paint while the move grip is dragged — pass one derived from the live
+     * {@link MoveDrop} (`copy` while Ctrl is held, say) to show the drop mode under the pointer. The
+     * grip is pointer-captured for the duration, so this is the cursor the browser shows anywhere on
+     * screen, and it is the only place a mode cursor can come from during the drag.
+     *
+     * @defaultValue 'grabbing'
+     */
+    moveCursor?: string;
     /**
      * Enable the built-in fill handle on a single range (the Excel fill square at the bottom-right
      * corner; drag to fill). Opt-in (unlike the always-on move grip) because it adds a visible handle.
@@ -121,8 +199,11 @@ export interface SelectionLayerProps extends LayerProps {
      * to use. Omit for no snapping.
      */
     snapFillDestination?: (template: RangeCoords, destination: RangeCoords) => RangeCoords;
-    /** The fill drag started — `template` is the source range. */
-    onFillStart?: (template: RangeCoords, e: React.PointerEvent) => void;
+    /**
+     * The fill drag started — `template` is the source range. `cancel` aborts the drag as Escape would
+     * ({@link SelectionLayerProps.onFillEnd} follows, nothing filled) — for a mode's chrome cancel.
+     */
+    onFillStart?: (template: RangeCoords, e: React.PointerEvent, cancel: () => void) => void;
     /**
      * Live during the fill drag — `destination` is the in-flight fill range (incl. the template). Use it
      * to preview what will be filled (e.g. a value tooltip). The fill axis is `template` vs `destination`.
@@ -133,6 +214,17 @@ export interface SelectionLayerProps extends LayerProps {
      * anything {@link SelectionLayerProps.onFillPreview} set (e.g. closing the preview tooltip).
      */
     onFillEnd?: () => void;
+    /**
+     * A **right-button** fill drag was released — Excel's right-drag of the fill handle, which offers a
+     * menu of fills at the pointer instead of filling. Fires INSTEAD of {@link SelectionLayerProps.onFill}
+     * for that gesture, and the selection is NOT extended: nothing has been decided yet, so the consumer
+     * extends it (or not) once a menu entry is chosen. Supplying it is what enables the right-button drag;
+     * left-drag is untouched.
+     *
+     * The dashed fill preview stays up while the menu decides; call `done` once it has answered or closed
+     * without answering, and the preview clears.
+     */
+    onFillMenu?: (template: RangeCoords, destination: RangeCoords, e: React.PointerEvent, done: () => void) => void;
     /**
      * Resolve the destination for a **double-clicked** fill handle — Excel's "ride the rails" fill,
      * whose extent comes from the data flanking the template rather than from a drag. Return the
@@ -154,13 +246,34 @@ export interface SelectionLayerProps extends LayerProps {
      * {@link SelectionPointerOptions.onSelectionEnd}.
      */
     onSelectionEnd?: (e: React.PointerEvent) => void;
+    /**
+     * The pointer drag-select started (`'extend'` / `'remove'`) or ended (`null`) — for reflecting an
+     * in-flight selection somewhere this layer's own {@link SelectionLayerProps.renderTip} can't reach
+     * (the name box's live `nR x nC`). Read off the drag engine rather than a start/end callback pair,
+     * so it is balanced by construction: the `null` also arrives for an aborted drag (Escape /
+     * `pointercancel`), which never reaches a release.
+     */
+    onDragModeChange?: (dragMode: 'extend' | 'remove' | null) => void;
+    /**
+     * The active range is being grown by a drag this layer's own tap cannot see — a header drag, which
+     * writes through the model. The gesture tip shows for it as for a body drag-select, off the corner
+     * being pulled.
+     * @defaultValue false
+     */
+    externalDrag?: boolean;
     /**
      * Render a transient tip during a gesture — a drag-select ({@link SelectionGesture} `select`, live
-     * R×C), a move (`move`, the destination address), or a fill (`fill`, the preview). Return a falsy node
-     * for no tip (e.g. skip a 1×1 drag-select). The tip floats on the in-flight range (non-interactive).
+     * R×C), a move (`move`, the destination address), or a fill (`fill`, the preview). Return an empty
+     * node for no tip (e.g. skip a 1×1 drag-select). The tip is a {@link GestureTip}: it floats on the
+     * in-flight range in the tooltip group's bubble, and no hover tip opens while the gesture runs.
      */
     renderTip?: (gesture: SelectionGesture) => React.ReactNode;
-    /** Placement of the gesture tip relative to the in-flight range. @defaultValue `{ side: 'b', align: 'end' }` */
+    /**
+     * Fixed placement of the gesture tip relative to the in-flight range. By default the tip follows the
+     * gesture: off the corner a drag-select is pulling (the one opposite the anchor cell, or the touch grip
+     * held), trailing the edge a fill grows from, on the far side of an insert's I-beam, and at the
+     * bottom-right of a plain move.
+     */
     tipPlacement?: GridPlacement;
     /**
      * Disable the layer's **built-in keyboard** routing (arrows → {@link ISelection.navigate}, Tab/Enter

package/types/src/selection/SelectionStyle.d.ts

@@ -25,4 +25,37 @@ export declare const DEFAULT_MULTI_STYLE: SelectionRangeStyle;
 export declare const DEFAULT_ANCHOR_STYLE: VisualSVGProps;
 /** The transient rubber-band shown while Ctrl/Cmd-dragging to remove an area (fill + border stack). */
 export declare const DEFAULT_REMOVE_PREVIEW_STYLE: SelectionRangeStyle;
+/** The look of the insert I-beam — the `RangeInsertBar` shown while Shift-dragging the move grip. */
+export interface InsertBarStyle {
+    /** The bar color. */
+    color?: string;
+    /**
+     * The bar color when the drop would be REFUSED (`MoveDrop.refused`) - the theme's warning. A refused
+     * plain drop draws its ghost in it too.
+     */
+    refusedColor?: string;
+    /** Bar thickness in DEVICE px (the same currency as a border's `alignWidth`). */
+    alignWidth?: number;
+    /** How far each end cap reaches past the bar, per side, in DEVICE px. */
+    capExtent?: number;
+    /** How long the bar takes to travel to a new line, in ms. `0` places it instantly. */
+    transitionDuration?: number;
+    /** The curve it travels on - a hard decelerate reads as a snap onto the line. */
+    transitionEasing?: string;
+    /** How long the beam takes to grow into a new ORIENTATION, in ms. `0` shows it at once. */
+    axisDuration?: number;
+}
+/**
+ * The insert I-beam: the selection color, heavier than the selection outline so it reads as a drop
+ * target rather than a border. A drop the model would refuse draws in the theme's WARNING instead
+ * (the same token the remove rubber-band uses) - the gesture stays visible, it just says no.
+ */
+export declare const DEFAULT_INSERT_BAR_STYLE: InsertBarStyle;
+/**
+ * The **mute** laid over the SOURCE of a move (cut) drag — a scrim in the grid's own surface color,
+ * drawn under the selection visuals so it fades the cell content while the outline stays crisp. The
+ * content reads as already lifted out; a Ctrl (copy) drag draws no mute, so the two modes are
+ * distinguishable at a glance rather than by cursor alone.
+ */
+export declare const DEFAULT_MOVE_SOURCE_STYLE: SelectionRangeStyle;
 //# sourceMappingURL=SelectionStyle.d.ts.map

package/types/src/selection/SelectionTouchGrips.d.ts

@@ -6,10 +6,6 @@ import { ISelection } from './ISelection';
 export interface SelectionTouchGripsProps {
     /** The selection the touch handles read (for placement) and extend (via `modify`). */
     selection: ISelection;
-    /** The ring color (the fill is the surface/"window" color). @defaultValue the theme primary. */
-    color?: string;
-    /** Handle diameter (px). Touch-sized. @defaultValue 22 */
-    size?: number;
 }
 /**
  * Touch selection handles: round grips at the active range's corners (or edges, for a whole row/column)

package/types/src/selection/_SelectionUtils.d.ts

@@ -1,4 +1,10 @@
 import { SelectionRangeStyle } from './SelectionStyle';
+/**
+ * The surface cell a touch grip holds while it drags: the corner it pulls, as the placement a tip hangs
+ * off (`null` between drags). The grips and the selection layer are siblings, so the layer learns of
+ * the drag here rather than from its own pointer tap.
+ */
+export declare const GRIP_DRAG_KEY = "selection-grip-drag";
 /**
  * Merge a {@link SelectionRangeStyle} override over a base, slot-by-slot (each rectangle merges
  * independently).

package/types/src/selection/useDragCells.d.ts

@@ -1,5 +1,15 @@
 import { CellCoords } from '@sheetxl/utils';
 import { IGridPane } from '../surface';
+/**
+ * A drag engine's pane: the pane itself, or a getter for the CURRENT one.
+ *
+ * @remarks
+ * A getter is what a hook passes. Panes are rebuilt on structural changes — including any model change
+ * that invalidates the grid — and a drag is transient UI that must outlive that: an engine built per pane
+ * would drop the gesture in flight the moment a live edit (a reference picked into a field that writes
+ * per change) touched the model.
+ */
+export type DragCellsPane = IGridPane | (() => IGridPane);
 /**
  * Repeat interval (ms) for the held-still auto-scroll. While a drag is parked past the viewport edge no
  * pointer-move events fire, so the engine re-applies the drag at the last pointer position on this
@@ -36,6 +46,23 @@ export declare const edgeScrollPane: (pane: IGridPane, point: {
     x?: boolean;
     y?: boolean;
 }) => boolean;
+/**
+ * The modifier keys held during a drag — Excel's *mode* keys: Ctrl turns a move into a copy, Shift
+ * into an insert. Tracked by the engine off BOTH the pointer and the keyboard, so it stays true while
+ * the pointer stands still (pressing Ctrl fires no pointer event).
+ */
+export interface DragModifiers {
+    ctrlKey: boolean;
+    shiftKey: boolean;
+    altKey: boolean;
+    metaKey: boolean;
+}
+/** Nothing held — what a drag starts from unless its pointer-down says otherwise. */
+export declare const NO_DRAG_MODIFIERS: DragModifiers;
+/** Snapshot the modifier flags off any event that carries them (pointer, mouse, or keyboard). */
+export declare const readDragModifiers: (e: Partial<DragModifiers>) => DragModifiers;
+/** Whether two modifier snapshots describe the same held keys. */
+export declare const isSameDragModifiers: (a: DragModifiers, b: DragModifiers) => boolean;
 /**
  * The in-flight gesture returned by {@link DragCellsOptions.onStart}. It carries the *policy* — how a
  * given cell-drag mutates the model — while the engine owns the *mechanics* (pointer capture, `lastCell`
@@ -56,6 +83,25 @@ export interface DragCellsSession {
      * (no pointer event fires while the pointer is parked past the edge), so treat it as optional.
      */
     drag: (cell: CellCoords, e?: React.PointerEvent) => void;
+    /**
+     * The pointer is AT a position — fired on every move (including one that stays inside the cell it is
+     * already in) and on every held-still auto-scroll tick, right after any `drag` the same position
+     * triggered. For policies whose result is sub-cell, which the per-cell `drag` cannot express: a move
+     * drag's insert line snaps to the nearer HALF of the cell under the cursor, so it has to see the
+     * pointer cross a midpoint. `cell` is the cell resolved at that point; `e` is absent on an
+     * auto-scroll tick. Fires only when a cell resolved.
+     *
+     * It is called at pointer rate, so a consumer should report onward only what actually changed.
+     */
+    point?: (cell: CellCoords, clientX: number, clientY: number, e?: React.PointerEvent) => void;
+    /**
+     * The held modifier keys CHANGED mid-drag — fired on every press/release of Ctrl / Shift / Alt / Meta
+     * (never on start, and only on an actual change). Excel's mode keys take effect the instant they are
+     * pressed, even with the pointer standing still — and a key press fires no pointer event, so `drag`
+     * alone can never see it. Wire this to whatever reflects the mode (a status description, a cursor, a
+     * drop preview).
+     */
+    modifiers?: (mods: DragModifiers) => void;
     /**
      * The auto-scroll step: given the pointer's client `point`, scroll the viewport ONE cell toward any edge
      * the pointer is at (see {@link edgeScrollPane}), and return whether an edge is still engaged so the
@@ -78,7 +124,7 @@ export interface DragCellsSession {
      * Abort cleanup for a CANCELLED gesture — the OS/browser seized the pointer (`pointercancel`: a touch
      * became a system pan/zoom, a pen left range, a window blurred), OR the user pressed **Escape**
      * (Windows-style drag abort). The engine always runs the mechanical teardown (stop the auto-scroll
-     * timer, disarm the touch swallow, release capture); this hook is for the policy's own rollback —
+     * timer, release capture); this hook is for the policy's own rollback —
      * restore the pre-drag selection, clear a rubber-band / preview — WITHOUT committing, since a cancel is
      * an abort, not a release. {@link DragCellsSession.end} never runs on a cancel. The event is absent on
      * an Escape abort (no pointer event drives it).
@@ -139,7 +185,7 @@ export interface DragCellsController {
     onPointerUp: (e: React.PointerEvent) => void;
     /** Abort the in-flight drag (see {@link DragCellsResult.onPointerCancel}). */
     onPointerCancel: (e: React.PointerEvent) => void;
-    /** Stop the auto-scroll timer + disarm touch. Call on unmount (the hook wires this). */
+    /** Stop the auto-scroll timer. Call on unmount (the hook wires this). */
     dispose: () => void;
 }
 /**
@@ -164,7 +210,7 @@ export interface DragCellsController {
  * @param onDragModeChange Notified when the active session's `dragMode` changes (a hook turns this into
  *   React state); omit for a headless controller that doesn't surface it.
  */
-export declare const createDragCells: (pane: IGridPane, onStart: (cell: CellCoords, e: React.PointerEvent) => DragCellsSession | null, onDragModeChange?: (mode: string | null) => void) => DragCellsController;
+export declare const createDragCells: (pane: DragCellsPane, onStart: (cell: CellCoords, e: React.PointerEvent) => DragCellsSession | null, onDragModeChange?: (mode: string | null) => void) => DragCellsController;
 /** The headless controller behind {@link useWindowDragCells}. */
 export interface WindowDragCellsController {
     /**
@@ -173,7 +219,13 @@ export interface WindowDragCellsController {
      * `window` regardless, surviving the element repositioning / unmounting. Defaults to `e.currentTarget`.
      */
     start: (e: React.PointerEvent, cursorEl?: Element | null) => void;
-    /** Stop any in-flight gesture (drop the `window` listeners + timer + touch swallow). Call on unmount. */
+    /**
+     * Abort the in-flight gesture exactly as Escape does: the session's `cancel` rollback, no commit. A
+     * no-op between gestures. For a cancel offered by chrome (the status bar's ✕), which a phone needs
+     * because it has no Escape.
+     */
+    cancel: () => void;
+    /** Stop any in-flight gesture (drop the `window` listeners + timer). Call on unmount. */
     dispose: () => void;
 }
 /**
@@ -187,15 +239,16 @@ export interface WindowDragCellsController {
  * The source element is still pointer-captured (for its CURSOR only — see {@link WindowDragCellsController.start});
  * the actual move / up / cancel are `window` listeners, so a re-render or unmount of the handle never
  * interrupts the gesture. Consumers supply `onStart` policy exactly as for the tap engine, and get the
- * same held-still auto-scroll, touch arming, per-cell de-dup, and abort-on-cancel.
+ * same held-still auto-scroll, per-cell de-dup, and abort-on-cancel.
  */
-export declare function createWindowDragCells(pane: IGridPane, onStart: (cell: CellCoords, e: React.PointerEvent) => DragCellsSession | null, onDragModeChange?: (mode: string | null) => void, 
+export declare function createWindowDragCells(pane: DragCellsPane, onStart: (cell: CellCoords, e: React.PointerEvent) => DragCellsSession | null, onDragModeChange?: (mode: string | null) => void, 
 /** Override cell resolution (a touch grip resolves against the pane the finger is over). */
 resolveCell?: (clientX: number, clientY: number) => CellCoords | null): WindowDragCellsController;
 /**
  * The React hook over {@link createDragCells}: reads the pane from context, owns the `dragMode` state,
- * and stops the auto-scroll timer on unmount. `onStart` is read live through a ref, so a consumer's
- * closure over changing values (selection, options) needs no handler rebuild.
+ * and stops the auto-scroll timer on unmount. `onStart` and the pane are read live, so a consumer's
+ * closure over changing values (selection, options) needs no handler rebuild — and a pane rebuilt
+ * mid-drag does not end the drag (see {@link DragCellsPane}).
  */
 export declare const useDragCells: (onStart: (cell: CellCoords, e: React.PointerEvent) => DragCellsSession | null) => DragCellsResult;
 /** Handlers + transient `dragMode` produced by {@link useWindowDragCells}. */
@@ -206,13 +259,16 @@ export interface WindowDragCellsResult {
      * `currentTarget` other than that element (e.g. a grip below an interactive child).
      */
     start: (e: React.PointerEvent, cursorEl?: Element | null) => void;
+    /** Abort the in-flight gesture as Escape does (see {@link WindowDragCellsController.cancel}). */
+    cancel: () => void;
     /** The active session's `dragMode`, or `null` between drags (flips only on start / end). */
     dragMode: string | null;
 }
 /**
  * The React hook over {@link createWindowDragCells}: reads the pane from context, owns the `dragMode`
  * state, and disposes the gesture on unmount. For handle / grip flavors (fill, resize, move, touch grips)
- * whose element repositions or unmounts mid-drag. `onStart` is read live through a ref.
+ * whose element repositions or unmounts mid-drag. `onStart` and the pane are read live, as in
+ * {@link useDragCells}.
  */
 export declare const useWindowDragCells: (onStart: (cell: CellCoords, e: React.PointerEvent) => DragCellsSession | null) => WindowDragCellsResult;
 //# sourceMappingURL=useDragCells.d.ts.map

package/types/src/surface/GridPane.d.ts

@@ -35,6 +35,8 @@ export interface GridPaneDef {
     rowIndex: number;
     elemStage: React.ReactNode;
     refStage: IStageElement | null;
+    /** See {@link IGridPane.registerFocusTarget}. */
+    focusTarget?: (() => HTMLElement | null) | null;
     scrollOrientation: OrientationFlags;
     insets: Rectangle;
 }

package/types/src/surface/IGridPane.d.ts

@@ -6,9 +6,22 @@ import { IGridMetrics } from '../metrics';
  */
 export interface IGridPane {
     /**
-     * Sets focus to the view.
+     * Sets focus to the view: its surface, or its {@link getFocusTarget | focus target} when there is one.
      */
     focus(options?: FocusOptions): void;
+    /**
+     * Register a focus target: an element inside the pane that takes the pane's focus in place of its
+     * surface while `target` returns it. A key aimed at it is a key aimed at the surface. The latest
+     * registration wins.
+     *
+     * @param target Asked each time the pane is focused; `null` lets the surface take focus.
+     */
+    registerFocusTarget(target: () => HTMLElement | null): RemoveListener;
+    /**
+     * The element focusing the pane lands on in place of its surface right now, or `null` for the
+     * surface itself.
+     */
+    getFocusTarget(): HTMLElement | null;
     /**
      * Set pointer capture to the view.
      */
@@ -161,7 +174,7 @@ export interface IGridPane {
      * For the freeze STRUCTURE use {@link getAllPanes} — the `Top` / `Left` / `TopLeft` entries exist only
      * when frozen — and each frozen pane's {@link getPaneRange} is exactly its frozen cell band, so
      * `getPaneRange().colEnd + 1` / `.rowEnd + 1` gives the frozen column / row COUNT. The configured
-     * freeze count as a model value lives on `ISheetView.getFreezePanes().coords`.
+     * freeze count as a model value lives on `IWorksheetView.getFreezePanes().coords`.
      */
     getFreezeTopLeft(): TopLeft;
     /**

package/types/src/surface/SurfaceStateProvider.d.ts

@@ -36,7 +36,7 @@ export interface SurfaceStateProviderProps {
  *
  * 1. an explicit {@link SurfaceStateProviderProps.store} prop (override);
  * 2. a store **inherited** from an ancestor `SurfaceStateProvider` — so a wider parent (e.g. a
- *    `SheetElement` wrapping its top-left corner + both header `GridSurface`s + the main `GridSurface`)
+ *    `WorksheetElement` wrapping its top-left corner + both header `GridSurface`s + the main `GridSurface`)
  *    shares one scope across sibling surfaces, letting a layer keyed the same in a header and in the body
  *    read one cell;
  * 3. otherwise a **lazily-created own** store (the standalone default).

package/types/src/surface/getPrimaryPane.d.ts

@@ -0,0 +1,13 @@
+import { AnchorLocation } from '@sheetxl/utils';
+import { IGridPane } from './IGridPane';
+/**
+ * The pane to use when no particular pane is called for: the one that owns a once-per-grid job, or
+ * takes focus and scrolling with nothing else to go by. The center (scrolling) pane when there is
+ * one, else the first frozen pane.
+ *
+ * @remarks
+ * The center pane is not always there: a freeze larger than the view leaves it no room, and the grid
+ * builds no pane without room. `null` only while the grid has no panes at all (it has no size).
+ */
+export declare const getPrimaryPane: (panes: Readonly<Partial<Record<AnchorLocation, IGridPane>>>) => IGridPane | null;
+//# sourceMappingURL=getPrimaryPane.d.ts.map

package/types/src/surface/index.d.ts

@@ -1,4 +1,5 @@
 export * from './IGridPane';
+export * from './getPrimaryPane';
 export * from './IGridSurface';
 export * from './GridSurface';
 export * from './useGridPane';

package/types/src/surface/useSurfaceState.d.ts

@@ -1,4 +1,5 @@
 import { Dispatch, SetStateAction } from 'react';
+import { SurfaceStateStore } from './SurfaceStateProvider';
 /**
  * Like {@link React.useState}, but the cell is **keyed** and scoped to the enclosing {@link GridSurface},
  * so every pane that renders this layer reads/writes the SAME cell — writing it from the pane that owns a
@@ -19,4 +20,22 @@ import { Dispatch, SetStateAction } from 'react';
  * store, so it still behaves like ordinary local state.
  */
 export declare function useSurfaceState<T>(key: string, initialValue: T | (() => T)): [T, Dispatch<SetStateAction<T>>];
+/**
+ * The setter half of {@link useSurfaceState}, for a producer that writes a cell but never reads it. It does
+ * not subscribe, so writing the cell (e.g. on every move of a drag) does not re-render the producer.
+ *
+ * @param key The cell's key, as given to `useSurfaceState`.
+ * @param initialValue The value an updater function receives while the cell has never been written.
+ */
+export declare function useSurfaceStateSetter<T>(key: string, initialValue: T): Dispatch<SetStateAction<T>>;
+/**
+ * Read one {@link useSurfaceState} cell from a given store — for the component that OWNS the store and so
+ * sits above its {@link SurfaceStateProvider} (it passes the store to the provider and reads it here).
+ * Read-only; re-renders when the cell changes.
+ *
+ * @param store The store handed to the provider (from {@link createSurfaceStateStore}).
+ * @param key The cell's key, as given to `useSurfaceState`.
+ * @param initialValue The value while the cell has never been written.
+ */
+export declare function useSurfaceStateValue<T>(store: SurfaceStateStore, key: string, initialValue: T): T;
 //# sourceMappingURL=useSurfaceState.d.ts.map

package/types/src/svg/_Glide.d.ts

@@ -0,0 +1,9 @@
+/**
+ * How a moving range outline glides between cells. What travels with it — its corner handles, its
+ * gesture tip — rides the same timing, or it reads as trailing.
+ */
+export declare const RANGE_GLIDE: {
+    readonly duration: 60;
+    readonly easing: "ease-in-out";
+};
+//# sourceMappingURL=_Glide.d.ts.map

package/types/src/theme/GridTheme.d.ts

@@ -48,7 +48,7 @@ export interface GridThemeCSSOptions {
 /**
  * grid-react's theme stylesheet — the app baseline (utils-react `defaultTheme`, or a passed one) + the
  * `grid` / `header` surface overrides, compiled to the `data-sxl-theme-*` attribute matrix. Called by the
- * react `SheetElement` with neutral defaults into `@layer sxl-defaults` (so even a chromeless sheet is
+ * react `WorksheetElement` with neutral defaults into `@layer sxl-defaults` (so even a chromeless sheet is
  * themed), and by studio-mui with MUI-derived values into `sxl-app` on top; clients override in
  * `sxl-overrides`. Consumers just set `data-sxl-theme-*` attributes.
  */