@sheetxl/grid-react 0.8.0-beta.2 → 0.8.0-beta.21

package/types/src/range/Draggable.d.ts

@@ -29,6 +29,12 @@ export interface DragInsert {
  * the drop will DO, and no pointer event carries that. Read the modifiers from here, never off the
  * event handed to the same callback (which is the last one the *pointer* fired).
  */
+/** What {@link DraggableProps.renderMove} is handed. */
+export interface DragMoveRenderProps {
+    /** The in-flight range. */
+    range: RangeCoords;
+    info: DragMoveInfo;
+}
 export interface DragMoveInfo {
     /** The live Ctrl / Shift / Alt / Meta state (Excel: Ctrl = copy, Shift = insert). */
     mods: DragModifiers;
@@ -39,6 +45,22 @@ export interface DragMoveInfo {
      * turns it into a destination range.
      */
     insert: DragInsert | null;
+    /**
+     * Where the block was grabbed, fixed at the press. `null` only when the pane could not resolve the
+     * pointer.
+     */
+    grab: DragGrab | null;
+}
+/**
+ * Where a drag took hold of its block: the border nearest the press and the cell it pressed. A move keeps
+ * the grab offset, so the same cell of the translated block stays under the pointer — translate
+ * `cell` by the drag's delta to find it.
+ */
+export interface DragGrab {
+    /** The border nearest the press. With `grip: 'entire'` it is still the nearest, though seldom meant. */
+    edge: RangeEdge;
+    /** The cell of the source range that was pressed (clamped into it: the ring reaches just outside). */
+    cell: CellCoords;
 }
 /**
  * The insert a drop would perform from the pointer's position, as Excel resolves it — the first half
@@ -124,8 +146,12 @@ export interface DraggableProps {
      * mid-drag; use this to keep a drag affordance (e.g. the thickened move border) lit for the whole drag.
      */
     onDragStateChange?: (dragging: boolean) => void;
-    /** Drag started; `range` is the original. */
-    onDragStart?: (range: RangeCoords, e: React.PointerEvent, info: DragMoveInfo) => void;
+    /**
+     * Drag started; `range` is the original. `cancel` aborts this drag as Escape would
+     * ({@link DraggableProps.onDragStateChange} `false` follows, nothing committed) — hand it to chrome
+     * that offers a way out.
+     */
+    onDragStart?: (range: RangeCoords, e: React.PointerEvent, info: DragMoveInfo, cancel: () => void) => void;
     /**
      * The translated range during the drag. Wire it to update `range` (the content follows the pointer —
      * "live"), or to position a composed ghost preview. `Draggable` itself stays silent.
@@ -149,7 +175,7 @@ export interface DraggableProps {
      * `info` re-renders the preview on a modifier change, so the ghost can become an insert I-beam the
      * moment Shift goes down.
      */
-    renderMove?: (range: RangeCoords, info: DragMoveInfo) => React.ReactNode;
+    renderMove?: (props: DragMoveRenderProps) => React.ReactNode;
     /**
      * The cursor painted for the duration of the drag. The grip's element is pointer-captured, so ITS
      * cursor is the one the browser shows once a drag is in flight — pass a mode-derived cursor (`copy`

package/types/src/range/FillHandle.d.ts

@@ -2,6 +2,7 @@ import { default as React } from 'react';
 import { CellCoords, RangeCoords } from '@sheetxl/utils';
 import { VisualSVGProps } from '../svg';
 import { DragHandleRenderProps } from './DragHandle';
+import { RangeGlide } from './RangeGlide';
 /**
  * Props for {@link FillHandle}. Follows the shared **RangeHandle** contract: a controlled `range`
  * (the fill template/source) in, the fill **destination** range out via `onDrag*`. The destination
@@ -16,8 +17,11 @@ export interface FillHandleProps extends VisualSVGProps {
      * `enableFill` is set (or via a `singleLayer` slot); required in practice for standalone use.
      */
     range?: RangeCoords;
-    /** Drag started; `range` is the template. */
-    onDragStart?: (range: RangeCoords, e: React.PointerEvent) => void;
+    /**
+     * Drag started; `range` is the template. `cancel` aborts this drag as Escape would
+     * ({@link FillHandleProps.onDragDone} follows, no fill) — hand it to chrome that offers a way out.
+     */
+    onDragStart?: (range: RangeCoords, e: React.PointerEvent, cancel: () => void) => void;
     /**
      * Adjust the raw destination before it drives the preview + `onDrag*` — e.g. snap the fill edge to a
      * merged-cell boundary so the dashed preview and the committed fill agree (and never land on an
@@ -58,6 +62,11 @@ export interface FillHandleProps extends VisualSVGProps {
      * Replaces the default dot. Use it for a custom fill mark (e.g. the Excel fill square).
      */
     renderHandle?: (props: DragHandleRenderProps) => React.ReactNode;
+    /**
+     * The glide the template's outline is drawn with, so the handle rides its corner frame by frame
+     * instead of arriving first. See {@link DragHandleProps.glide}.
+     */
+    glide?: RangeGlide | null;
 }
 /**
  * The destination range when filling `template` toward `to`. Excel-style single axis: extend along

package/types/src/range/RangeGlide.d.ts

@@ -0,0 +1,160 @@
+import { Bounds, RangeCoords, TopLeft } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+/**
+ * What a {@link RangeGlide} travels to: a range, plus the cell cut out of its fill (a selection's
+ * active cell), which travels on the same clock.
+ */
+export interface RangeGlideTarget {
+    range: RangeCoords;
+    hole?: RangeCoords;
+}
+/**
+ * One frame of a glide: the rectangle to draw and its hole, in a pane's VIEW space (the space
+ * `IGridPane.getBoundsFromRange` returns).
+ */
+export interface RangeGlideFrame {
+    outer: Bounds;
+    hole?: Bounds;
+    /**
+     * Where `outer` is heading: the target's box, clamped as `outer` is. Whatever is anchored to the
+     * target travels by `outer`'s offset from it.
+     */
+    to: Bounds;
+}
+/**
+ * The geometry a glide resolves through: one pane's view. A glide keeps no pixels of its own - the
+ * target is a range and the start point is absolute (content) space - so every pane that draws it
+ * asks through its own view, and a scroll mid-glide moves the frame with the cells.
+ */
+export interface RangeGlideView {
+    /** A range's box in view space. */
+    boundsOf(range: RangeCoords): Bounds;
+    /** Absolute (content) space → view space. */
+    toView(bounds: Bounds): Bounds;
+    /** View space → absolute (content) space. */
+    toAbsolute(bounds: Bounds): Bounds;
+    /** The view's visible box (view space). */
+    getViewport(): Bounds;
+    /** Where the view is scrolling to; a change mid-glide that the glide did not start with stops it. */
+    getScrollTarget(): TopLeft;
+    /** Device pixel ratio, for keeping a moving box's size steady. */
+    getDevicePixelRatio(): number;
+}
+/**
+ * Timing of a {@link RangeGlide}.
+ */
+export interface RangeGlideOptions {
+    /** How long a glide takes, in ms. `0` never glides. @defaultValue 60 */
+    duration?: number;
+    /**
+     * How far into the glide its first frame is drawn, in ms. The clock starts on the first animation
+     * frame, not when the target changes: the change usually lands inside the work it causes (a render
+     * of everything that reads the selection), and a clock running through that work would spend the
+     * glide where nothing paints and show it as a jump. @defaultValue one 60Hz frame
+     */
+    frameLead?: number;
+    /**
+     * How long a glide takes when it starts from inside another one - a held arrow key, a drag. Shorter,
+     * so a stream of retargets keeps up instead of trailing. @defaultValue 60% of `duration`
+     */
+    retargetDuration?: number;
+    /** Progress (0..1) → eased progress (0..1). @defaultValue ease-out quad */
+    easing?: (t: number) => number;
+    /** The clock. @defaultValue `performance.now` */
+    now?: () => number;
+    /** Schedule the next frame. @defaultValue `requestAnimationFrame` */
+    requestFrame?: (callback: () => void) => number;
+    /** Cancel a scheduled frame. @defaultValue `cancelAnimationFrame` */
+    cancelFrame?: (handle: number) => void;
+    /** Whether motion is reduced (no glides). @defaultValue the `prefers-reduced-motion` media query */
+    isReducedMotion?: () => boolean;
+}
+/**
+ * Interpolate `from` → `to` at eased progress `e`, edge by edge. Edges shared by both ends are
+ * returned unchanged; with one `e` for a box and its hole, a hole inside its box at both ends stays
+ * inside it throughout.
+ */
+export declare const lerpGlideBounds: (from: Bounds, to: Bounds, e: number, dpr: number) => Bounds;
+/**
+ * How far a frame is from where it is heading, at the edge something hangs off — the offset that
+ * carries a thing anchored to the target (a handle on its corner, a tip off its side) along with the
+ * frame. `side` and `align` name the edge as a grid placement does: `side` the edge, `align` the point
+ * along it.
+ */
+export declare const glideOffset: (frame: RangeGlideFrame, side: "t" | "b" | "l" | "r", align?: "start" | "center" | "end") => {
+    dx: number;
+    dy: number;
+};
+/**
+ * The {@link RangeGlideView} of a grid pane.
+ */
+export declare const paneGlideView: (pane: IGridPane) => RangeGlideView;
+/**
+ * A glide between ranges on one clock: the animation of a selection moving, growing or shrinking from
+ * one range to the next. Everything that travels with the range - its outline, its fill and hole, its
+ * handles, its tip - reads the same frame, so they move in lockstep.
+ *
+ * @remarks
+ * A glide holds ranges and one start point, not pixels: the target is a range and the start is in
+ * absolute (content) space, and each frame is resolved through the view that asks for it. So a glide
+ * is shared by every pane of a surface (one per frozen pane, each drawing its own clipped slice), and
+ * a scroll mid-glide carries the frame with the cells instead of dragging it. A scroll the glide did
+ * not start with - the user's wheel - ends it.
+ *
+ * It renders nothing. Readers {@link subscribe} and pull {@link frame} for their view on each tick;
+ * `frame` is `null` when settled, which means: draw the target as rendered.
+ */
+export declare class RangeGlide {
+    private readonly _duration;
+    private readonly _frameLead;
+    private readonly _retargetDuration;
+    private readonly _easing;
+    private readonly _now;
+    private readonly _requestFrame;
+    private readonly _cancelFrame;
+    private readonly _isReducedMotion;
+    private _target;
+    /** Where the glide started, in absolute space; `null` when settled. */
+    private _from;
+    private _start;
+    private _length;
+    /** Eased progress of the glide in flight. */
+    private _progress;
+    /** The view the glide started in, watched for a scroll it did not start with. */
+    private _view;
+    private _scrollBase;
+    private _handle;
+    private readonly _listeners;
+    constructor(options?: RangeGlideOptions);
+    /** The range the glide is heading to (or rests at). */
+    getTarget(): RangeGlideTarget | null;
+    /** A glide is in flight. */
+    isGliding(): boolean;
+    /**
+     * Head to `target`. The same target again does nothing, so every pane drawing one selection can
+     * call this on each render and only the first change counts. With `animate` the glide starts from
+     * what is drawn now - mid-flight, from the frame in flight; otherwise it jumps.
+     *
+     * @param view The view of the caller, used to capture the start point and watch for a user scroll.
+     * @returns Whether the target changed.
+     */
+    retarget(target: RangeGlideTarget, view: RangeGlideView, animate: boolean): boolean;
+    /** Jump to the target now. */
+    finish(): void;
+    /**
+     * The frame to draw in `view` now, or `null` when settled (draw the target as rendered). A glide
+     * whose start is nowhere near the view - a jump to the far end of the data - draws no frame.
+     */
+    frame(view: RangeGlideView): RangeGlideFrame | null;
+    /** Listen for frames (each tick, and on start and settle). Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * What is drawn now, in absolute space: the frame in flight, else the target at rest. Unclamped, so
+     * it is the same whichever pane asks - a frozen pane the range is not in included.
+     */
+    private _shownAbsolute;
+    private readonly _tick;
+    private _settle;
+    private _notify;
+}
+//# sourceMappingURL=RangeGlide.d.ts.map

package/types/src/range/RangeRect.d.ts

@@ -1,6 +1,7 @@
 import { RangeCoords } from '@sheetxl/utils';
 import { VirtualDivProps } from '../layer';
 import { VisualSVGProps } from '../svg';
+import { RangeGlide } from './RangeGlide';
 /**
  * Props for {@link RangeRect}: a thin range→bounds wrapper that places the {@link RectangleSVG}
  * **shape** at a grid range — it resolves the range to bounds via the pane, culls off-screen,
@@ -23,6 +24,12 @@ export interface RangeRectProps extends Omit<VirtualDivProps, 'fill'>, Omit<Visu
      * concern {@link RectangleSVG} can't express (it has no pane and does no culling).
      */
     clipInsets?: number;
+    /**
+     * Draw the frames of this glide while it is in flight; at rest, `range` and `hole` as given. The glide
+     * must be heading to `range` (and to `hole`, when there is one) - the caller retargets it. Every
+     * rectangle reading one glide moves on one clock.
+     */
+    glide?: RangeGlide | null;
 }
 /**
  * Places one device-aligned {@link RectangleSVG} at a grid range. Resolves the range to bounds via

package/types/src/range/RangeResizer.d.ts

@@ -1,6 +1,7 @@
 import { RangeCoords } from '@sheetxl/utils';
 import { VisualSVGProps } from '../svg';
 import { HandleAnchor, DragHandleRenderProps } from './DragHandle';
+import { RangeGlide } from './RangeGlide';
 /** The four corner handles (chart series / formula precedent rectangles use these). */
 export declare const RESIZE_ANCHORS_4: readonly HandleAnchor[];
 /** Corners + edge midpoints. */
@@ -9,7 +10,7 @@ export declare const RESIZE_ANCHORS_8: readonly HandleAnchor[];
  * Props for {@link RangeResizer}. Follows the shared **RangeHandle** contract: a controlled
  * `range` in, the resized range out via `onDrag*`. Extends {@link VisualSVGProps} (like
  * {@link RangeRectProps}) so the outline's paint props — `stroke`, `fill`, `strokeWidth`,
- * `animatedStroke`, `animatedTransition`, … — are passed directly; the handles inherit
+ * `animatedStroke`, … — are passed directly; the handles inherit
  * {@link DEFAULT_HANDLE_STYLE} for whatever you don't set. The grip color follows `stroke`.
  */
 export interface RangeResizerProps extends VisualSVGProps {
@@ -51,6 +52,11 @@ export interface RangeResizerProps extends VisualSVGProps {
     renderHandle?: (props: DragHandleRenderProps) => React.ReactNode;
     /** Keep the current focus across a handle drag (forwarded to {@link DragHandle.preserveFocus}). */
     preserveFocus?: boolean;
+    /**
+     * Draw the outline and its grips from this glide's frames while it is in flight, on one clock. The
+     * glide must be heading to `range`.
+     */
+    glide?: RangeGlide | null;
 }
 /**
  * A draggable, resizable rectangle: an outlined range with {@link DragHandle} grips on the requested

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

@@ -5,6 +5,8 @@
  * (`useWindowDragCells`) for their gesture mechanics — capture, de-dup, edge auto-scroll, touch, cancel.
  */
 export * from './RangeStyle';
+export * from './RangeGlide';
+export * from './useRangeGlide';
 export * from './RangeRect';
 export * from './RangeInsertBar';
 export * from './DragHandle';

package/types/src/range/useRangeGlide.d.ts

@@ -0,0 +1,11 @@
+import { RangeGlide, RangeGlideOptions } from './RangeGlide';
+/**
+ * The {@link RangeGlide} shared by every pane of the surface under `key` - one clock for one logical
+ * range (a selection), so each pane's copy, and everything that travels with the range, reads the same
+ * frame. Never re-renders: readers subscribe to the glide itself.
+ *
+ * @param key Unique within the surface. `null` returns `null` (no glide).
+ * @param options Timing, read when the glide is first created under `key`.
+ */
+export declare const useRangeGlide: (key: string | null, options?: RangeGlideOptions) => RangeGlide | null;
+//# sourceMappingURL=useRangeGlide.d.ts.map

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

@@ -55,7 +55,10 @@ export interface RangesPickerLayerProps extends LayerProps {
      * {@link RESIZE_ANCHORS_8} for corners + edge midpoints.
      */
     anchors?: readonly HandleAnchor[];
-    /** Enable the move grip (drag the border to relocate a range, keeping its size). @defaultValue false */
+    /**
+     * Enable the move grip (drag the border to relocate a range, keeping its size). The moved range glides
+     * from cell to cell, its corner grips with it. @defaultValue false
+     */
     enabledMove?: boolean;
     /**
      * Don't claim the grid-wide **draw** gesture — the pointer-drag over empty grid that re-scopes the

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

@@ -51,11 +51,27 @@ export interface MoveDrop {
     /**
      * 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). The
-     * preview draws the I-beam in the refused color instead, and `onMove` never fires.
+     * - 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;
 }
+/**
+ * How a selection glides from one range to the next — see {@link SelectionLayerProps.animate}.
+ */
+export interface SelectionAnimateOptions {
+    /**
+     * Names the selection's glide within the surface. Every pane drawing ONE selection must share it, and
+     * two selections drawn on one surface must not, so a host that swaps the model underneath (a sheet
+     * switch) puts the model's identity in it: a new key starts at rest rather than gliding in from the
+     * last model's range.
+     * @defaultValue 'selection'
+     */
+    key?: string;
+    /** How long a glide takes, in ms. @defaultValue 60 */
+    duration?: number;
+}
 /**
  * Props for {@link SelectionLayer}.
  */
@@ -105,16 +121,26 @@ export interface SelectionLayerProps extends LayerProps {
     /** 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, and inert on release. 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).
+     * 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 -
-     * so a host that has one should answer from it (`ICellRange.canInsertFrom`), which is what keeps
-     * the beam honest about drops the grid could not have ruled out.
+     * 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
@@ -141,8 +167,12 @@ export interface SelectionLayerProps extends LayerProps {
      * 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. */
-    onMoveStart?: (from: 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.
+     */
+    onMoveStart?: (from: RangeCoords, e: React.PointerEvent, drop: MoveDrop, cancel: () => void) => void;
     /**
      * 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
@@ -184,8 +214,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`.
@@ -236,13 +269,26 @@ export interface SelectionLayerProps extends LayerProps {
      * `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
@@ -261,6 +307,16 @@ export interface SelectionLayerProps extends LayerProps {
      * @defaultValue true
      */
     anchorHole?: boolean;
+    /**
+     * Glide the single-range selection from one range to the next — moving, growing and shrinking edge by
+     * edge, its active-cell cutout on the same clock — instead of jumping. Edges that don't change stay
+     * put, a scroll during a glide carries it with the cells, and a scroll the user starts ends it. A
+     * multi-range selection, and the selection a move or fill commits, jump. Off under
+     * `prefers-reduced-motion`.
+     *
+     * @defaultValue false
+     */
+    animate?: boolean | SelectionAnimateOptions;
 }
 /**
  * The selection layer: renders the selection (single-range "rich" treatment vs multi-range), routes

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

@@ -29,7 +29,10 @@ export declare const DEFAULT_REMOVE_PREVIEW_STYLE: SelectionRangeStyle;
 export interface InsertBarStyle {
     /** The bar color. */
     color?: string;
-    /** The bar color when the drop would be REFUSED (`MoveDrop.refused`) - the theme's warning. */
+    /**
+     * 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;

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

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { RangeGlide } from '../range';
 import { ISelection } from './ISelection';
 /**
  * Props for {@link SelectionTouchGrips}.
@@ -6,10 +7,11 @@ 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;
+    /**
+     * The glide the selection is drawn with (the `SelectionLayer`'s, by its `animate` key), so the grips
+     * ride its frames on the outline's corners instead of arriving first.
+     */
+    glide?: RangeGlide | null;
 }
 /**
  * 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
@@ -114,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).
@@ -175,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;
 }
 /**
@@ -200,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 {
     /**
@@ -209,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;
 }
 /**
@@ -223,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}. */
@@ -242,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;
 }