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

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

@@ -22,6 +22,8 @@ export interface DragHandleRenderProps {
      * repositioning under an edge auto-scroll).
      */
     handleProps: {
+        /** The handle's identifying class(es) — `drag-handle` plus whatever the flavor tagged it with. */
+        className?: string;
         onPointerDown: (e: React.PointerEvent) => void;
         onDoubleClick?: (e: React.MouseEvent) => void;
         onPointerEnter?: (e: React.PointerEvent) => void;
@@ -52,8 +54,11 @@ export interface DragHandleProps {
     dragCursor?: string;
     /** Default-dot background, and the theme color handed to {@link DragHandleProps.renderHandle}. */
     background?: string;
-    /** Drag started; `cell` is under the pointer at press. */
-    onDragStart?: (cell: CellCoords, e: React.PointerEvent) => void;
+    /**
+     * Drag started; `cell` is under the pointer at press. `cancel` aborts this drag as Escape would
+     * ({@link DragHandleProps.onDragCancel} follows) — hand it to chrome that offers a way out.
+     */
+    onDragStart?: (cell: CellCoords, e: React.PointerEvent, cancel: () => void) => void;
     /** The pointer moved to a new cell during the drag (`from` = press cell, `to` = current). */
     onDragMove?: (from: CellCoords, to: CellCoords, e: React.PointerEvent) => void;
     /** Drag ended (`from` = press cell, `to` = last cell). */
@@ -108,6 +113,10 @@ export interface DragHandleProps {
     renderHandle?: (props: DragHandleRenderProps) => React.ReactNode;
     /** Static content inside the default dot. Ignored when `renderHandle` is set. */
     children?: React.ReactNode;
+    /**
+     * Extra class(es) for the handle element. Joined with the `drag-handle` tag every handle carries,
+     * so a flavor names itself (`fill-handle`, `resize-handle`) without losing the generic hook.
+     */
     className?: string;
     style?: React.CSSProperties;
     /**
@@ -117,6 +126,14 @@ export interface DragHandleProps {
      * it preserves whatever had focus rather than stealing it. @defaultValue false
      */
     preserveFocus?: boolean;
+    /**
+     * Also start a drag from the **secondary** (right) button — Excel's right-drag of the fill handle,
+     * which offers a menu on release instead of filling. The drag callbacks receive the event, so a
+     * consumer tells the two apart by `e.button`. The `contextmenu` the button raises (on press on some
+     * platforms, on release on others) is swallowed for the gesture's duration: the drag IS the intent.
+     * @defaultValue false
+     */
+    secondaryButton?: boolean;
 }
 /**
  * A generic, draggable handle anchored to a corner/edge of a grid range. It owns only the **gesture

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

@@ -1,4 +1,102 @@
-import { RangeCoords } from '@sheetxl/utils';
+import { RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+import { DragModifiers } from '../selection/useDragCells';
+/**
+ * Where an **insert**-style drop would land: the dragged block placed at `origin`, with the cells there
+ * stepping aside along `axis`. `origin`'s edge on that axis is the grid line the I-beam is drawn on.
+ *
+ * @remarks
+ * An insert re-anchors where a move does not. A move keeps the grab offset (grab A1:C3 by C3 and the
+ * block stays under your hand); an insert has no "under whatever you grabbed" to preserve — it goes at
+ * the line you are pointing at, so the block's top-left is the thing that must land there. Same reason
+ * the I-beam starts at the pointer's cell rather than trailing off to one side of it.
+ */
+export interface DragInsert {
+    /** `Row` — the cells shift down (a horizontal beam); `Column` — they shift right (a vertical one). */
+    axis: RangeAxis;
+    /**
+     * Where the block's TOP-LEFT lands. On the cross axis it is the cell under the pointer (the
+     * re-anchor); on `axis` it is the grid line nearest the pointer, which may be the FAR side of that
+     * cell — an index of `n` meaning the line before row/column `n`, so the two readings coincide.
+     */
+    origin: CellCoords;
+}
+/**
+ * The in-flight drag's live state, reported alongside the translated range.
+ *
+ * @remarks
+ * `mods` is the reason this exists: a modifier pressed with the pointer standing still changes what
+ * 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).
+ */
+export interface DragMoveInfo {
+    /** The live Ctrl / Shift / Alt / Meta state (Excel: Ctrl = copy, Shift = insert). */
+    mods: DragModifiers;
+    /**
+     * Where an insert-style (Shift) drop would land, resolved from the pointer's position within its
+     * cell (see {@link insertAt}). Tracked whether or not Shift is down, so the I-beam appears the
+     * instant it goes down. `null` only when the pane could not resolve the pointer. {@link insertRange}
+     * 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
+ * of the drop geometry ({@link insertRange} is the second: this picks the LINE, that places the block
+ * on it). Two rules that are deliberately NOT symmetric:
+ *
+ * - the pointer's **horizontal** position within the cell picks the axis: within
+ *   {@link INSERT_COLUMN_BAND} of a vertical edge it is a column insert, anywhere in the middle half a
+ *   row insert. So rows are the easy, default direction and columns are aimed for — you go for a
+ *   column edge to get one. Skipped entirely when `forced` names the axis (a whole row / column);
+ * - the line then snaps to the **nearest** grid line on that axis, which may be the far side of the
+ *   cell (below it / to the right of it), not only its leading edge. A forced axis is therefore a
+ *   straight 50/50 across the cell, the axis pick no longer taking a cut of it.
+ *
+ * The cross axis re-anchors to the pointer's own cell, so the beam always starts where you point.
+ *
+ * @remarks
+ * Both measured proportionally (a fraction of the cell), which is how Excel behaves across cell sizes
+ * — and necessary anyway: a row is typically a third the height of a column's width, so any pixel
+ * threshold would behave differently at every zoom and row height.
+ *
+ * A MERGE is IGNORED: the line falls on the true cell under the pointer, exactly as if the merge
+ * weren't there. It has to be resolved here rather than taken from the drag's cell, which is a
+ * merge's top-left (what `getCellFromPointer` reports, and the right answer for a move destination) —
+ * measured against that anchor the fractions describe a box the pointer is nowhere near, and the far
+ * line lands one cell in from it, which is how the beam ends up drawn against the top-left corner of
+ * a merge instead of under the cursor. Snapping to the merge's outer edge instead is no better: the
+ * beam then jumps to a far edge the pointer isn't near. A line that falls INSIDE a merge is a drop
+ * the model refuses, which the preview already says in its own way — see `MoveDrop.refused`.
+ */
+export declare const insertAt: (pane: IGridPane, cell: CellCoords, clientX: number, clientY: number, forced: RangeAxis | null, prior: DragInsert | null) => DragInsert | null;
+/**
+ * Where an **insert** drop of `range` lands: the block placed at {@link DragInsert.origin} — its
+ * top-left RE-ANCHORED on the pointer's own cell across the insert axis, and on the snapped grid line
+ * along it (existing cells shifting from there). Clamped into `bounds`, which can pull a block back so
+ * it still fits at the far edge.
+ *
+ * Unlike a move — which keeps the offset of wherever you grabbed the block — an insert drops the grab
+ * offset entirely: it goes where you are pointing. The same function drives the I-beam, the tip and
+ * the commit, so what is drawn is what lands.
+ */
+export declare const insertRange: (range: RangeCoords, insert: DragInsert, bounds: RangeCoords) => RangeCoords;
 /**
  * Props for {@link Draggable}.
  */
@@ -42,22 +140,44 @@ 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) => 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.
+     *
+     * @remarks
+     * Fires when the destination changes AND when the modifiers do (Ctrl / Shift pressed or released with
+     * the pointer standing still) — the two are one signal on purpose: everything a consumer reflects
+     * during a drag (a mode description, a cursor, a drop preview) depends on both, and splitting them
+     * into two callbacks is how one of the pair ends up stale. Since a modifier change fires no pointer
+     * event, `e` is then the last one the POINTER produced: read the modifiers off `info.mods`, not `e`.
      */
-    onDragMove?: (range: RangeCoords, e: React.PointerEvent) => void;
-    /** Drag released: commit the translated range. */
-    onDragEnd?: (range: RangeCoords, e: React.PointerEvent) => void;
+    onDragMove?: (range: RangeCoords, e: React.PointerEvent, info: DragMoveInfo) => void;
+    /** Drag released: commit the translated range. `info` carries the modifiers held at the drop. */
+    onDragEnd?: (range: RangeCoords, e: React.PointerEvent, info: DragMoveInfo) => void;
     /**
      * Render a **ghost** at the in-flight translated range while a drag is in progress (nothing is rendered
      * when idle). `Draggable` owns the preview state internally, so the consumer doesn't have to stash it
      * — return e.g. a faded {@link RangeRect} to trail the pointer while the original stays put (the
      * cut-move pattern). For a "live" feel (content follows the pointer) wire `onDragMove → range` instead.
+     *
+     * `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) => React.ReactNode;
+    renderMove?: (range: RangeCoords, info: DragMoveInfo) => 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`
+     * while Ctrl is held, say) to make the drop mode visible under the pointer.
+     *
+     * @defaultValue 'grabbing'
+     */
+    dragCursor?: string;
     /**
      * Keep the current focus across a move drag (`preventDefault` on pointer-down, suppressing the compat
      * `mousedown` that would move focus to the grid's `tabIndex` Stage). Used by the reference-range picker
@@ -74,6 +194,11 @@ export interface DraggableProps {
      * name, so the nearest one is still reported but rarely means anything.
      */
     onEdgeDoubleClick?: (range: RangeCoords, edge: RangeEdge, e: React.PointerEvent) => void;
+    /**
+     * Extra class(es) for the grip box. Joined with the `drag-grip` tag every grip carries, so a
+     * flavor names itself (`move-grip`) without losing the generic hook.
+     */
+    className?: string;
 }
 /** Which border of a range a gesture landed on. */
 export type RangeEdge = 'top' | 'bottom' | 'left' | 'right';

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

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { RangeCoords } from '@sheetxl/utils';
+import { CellCoords, RangeCoords } from '@sheetxl/utils';
 import { VisualSVGProps } from '../svg';
 import { DragHandleRenderProps } from './DragHandle';
 /**
@@ -16,8 +16,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
@@ -29,6 +32,16 @@ export interface FillHandleProps extends VisualSVGProps {
     onDragMove?: (range: RangeCoords, e: React.PointerEvent) => void;
     /** Drag released: commit the fill to this destination range. Fires only when there IS a fill. */
     onDragEnd?: (range: RangeCoords, e: React.PointerEvent) => void;
+    /**
+     * Released from a **secondary-button** (right) drag: offer a menu of fills at the pointer instead
+     * of committing one — Excel's right-drag of the fill handle. Fires INSTEAD of
+     * {@link FillHandleProps.onDragEnd} for that gesture (then {@link FillHandleProps.onDragDone} as
+     * usual); supplying it is what enables the right-button drag at all. Left-drag is untouched.
+     *
+     * The dashed preview STAYS on the release — the fill is still being decided — until `done` is
+     * called: once the menu has answered, or closed without answering. A new drag clears it regardless.
+     */
+    onMenu?: (range: RangeCoords, e: React.PointerEvent, done: () => void) => void;
     /**
      * The drag finished — fires on **every** release after a press (unlike {@link FillHandleProps.onDragEnd},
      * which fires only when a fill was drawn) AND on an abort (Escape / OS pointercancel). Use it for
@@ -49,6 +62,23 @@ export interface FillHandleProps extends VisualSVGProps {
      */
     renderHandle?: (props: DragHandleRenderProps) => React.ReactNode;
 }
+/**
+ * The destination range when filling `template` toward `to`. Excel-style single axis: extend along
+ * whichever direction the pointer reaches furthest beyond the template, clamped to `bounds`. The
+ * destination includes the template.
+ *
+ * A pointer INSIDE the template shrinks it instead — Excel's drag of the fill handle back over the
+ * source, which vacates the cells past the pointer. Only the edges the handle sits on can move, the
+ * bottom and the right, along whichever axis the pointer pulled furthest from the corner; a whole-row
+ * or whole-column template has no such edge on its long axis and shrinks only on the other. Returns
+ * `null` when `to` is the handle's own corner (nothing to fill or vacate).
+ */
+export declare const resolveFillDestination: (template: RangeCoords, to: CellCoords, bounds: RangeCoords) => RangeCoords | null;
+/**
+ * The cells a shrinking `destination` vacates from `template` — the strip past its bottom or right
+ * edge — or `null` for an outward fill.
+ */
+export declare const vacatedByFill: (template: RangeCoords, destination: RangeCoords) => RangeCoords | null;
 /**
  * The fill layer: a {@link DragHandle} at a corner of the `range` (bottom-right by default). It owns
  * the handle placement — including the whole-row/column special-casing (pin to bottom-left / top-right

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

@@ -0,0 +1,91 @@
+import { RangeAxis, RangeCoords } from '@sheetxl/utils';
+/**
+ * Props for {@link RangeInsertBar}.
+ */
+export interface RangeInsertBarProps {
+    /**
+     * The range the insert lands on — the block's destination. Its LEADING edge on {@link axis} is the
+     * grid line the bar is drawn at (`insertRange` produces exactly this), and its other axis is the
+     * extent the bar spans, so the bar shows how wide the incoming block is.
+     */
+    range: RangeCoords;
+    /**
+     * Which way the existing cells shift: `Row` draws a horizontal bar on the range's top edge (cells
+     * shift down), `Column` a vertical bar on its left edge (cells shift right).
+     */
+    axis: RangeAxis;
+    /** The bar color. @defaultValue the grid primary. */
+    color?: string;
+    /**
+     * Bar thickness in DEVICE px — the same currency as a selection outline's `alignWidth`, so a bar and
+     * a border of the same number read as the same weight at any dpr.
+     *
+     * @defaultValue 3
+     */
+    alignWidth?: number;
+    /**
+     * How far each end cap reaches past the bar, per side, in DEVICE px. `0` draws a plain bar.
+     *
+     * @defaultValue 3
+     */
+    capExtent?: number;
+    /**
+     * How long the bar takes to travel to a new line, in ms. `0` places it instantly.
+     *
+     * @defaultValue 100
+     */
+    transitionDuration?: number;
+    /**
+     * The curve it travels on. The default is a hard decelerate — most of the distance is covered in
+     * the first third, then it settles — which is what reads as SNAPPING onto a gridline rather than
+     * sliding to a stop near one.
+     *
+     * @defaultValue `cubic-bezier(0.16, 1, 0.3, 1)`
+     */
+    transitionEasing?: string;
+    /**
+     * How long the beam takes to TURN, in ms — the outgoing orientation drawing in and the incoming one
+     * drawing out, together. `0` turns instantly. Shorter than
+     * {@link RangeInsertBarProps.transitionDuration} on purpose: a turn is a change of meaning (rows
+     * step aside, not columns), so it wants to read as a flip rather than as travel.
+     *
+     * @defaultValue 70
+     */
+    axisDuration?: number;
+}
+/**
+ * The **insert I-beam**: the Excel bar shown while Shift-dragging a range, marking the grid line the
+ * block will be inserted at (rather than dropped over). Drawn as a heavy line with a short cap at each
+ * end — the serifs are what separate "inserting AT this line" from "a border of something".
+ *
+ * @remarks
+ * Three device-aligned boxes rather than an SVG path: each is snapped independently, so the bar sits
+ * on the boundary pixel exactly like a gridline or a selection edge, at any dpr or zoom. It is placed
+ * from the destination range alone ({@link RangeInsertBarProps.range}) — the same range the drop
+ * commits — so the drawing and the operation can never disagree.
+ *
+ * The bar is clipped to the pane (a whole-column insert spans millions of pixels, and a box that size
+ * is a compositing tax for ink nobody can see), and an end cap is drawn only where the block's real
+ * end is on screen — a cap at a clipped edge would claim an end that isn't there.
+ *
+ * It GLIDES between lines: the three boxes transition their placement and their size together, on one
+ * duration and one curve, so they travel as a single object, and the color rides the same timing (a
+ * drop turning refused fades rather than blinks).
+ *
+ * A change of AXIS is a TURN, and both orientations are always mounted to draw it: each keeps its own
+ * shape forever and shows or hides by scaling, so the outgoing beam draws in while the incoming one
+ * draws out and something is on screen the whole way. They scale about the corner they SHARE — the
+ * destination's top-left, where a row beam starts running right and a column beam starts running
+ * down — so the pair reads as one beam swinging around that point, which is the part a rotation would
+ * have sold. That pivot is stated in PANE coordinates: these boxes lay out at the pane origin and
+ * move by transform, so their transform-origin is measured from the pane's corner, and a pivot stated
+ * relative to the box would scale the placement along with the beam and fly it in from the top-left.
+ *
+ * Two things this deliberately does NOT do. It does not interpolate one orientation into the other:
+ * width and height would cross and a bar whose width and height cross is a box at the halfway point,
+ * which smears. And it does not cut the old one and grow the new one, which leaves a moment with no
+ * beam at all — read as a flicker. (A real rotation is not something one transition can express: the
+ * orientations differ in LENGTH as well as angle.)
+ */
+export declare const RangeInsertBar: import('react').MemoExoticComponent<(props: RangeInsertBarProps) => import("react").JSX.Element | null>;
+//# sourceMappingURL=RangeInsertBar.d.ts.map

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

@@ -6,8 +6,10 @@
  */
 export * from './RangeStyle';
 export * from './RangeRect';
+export * from './RangeInsertBar';
 export * from './DragHandle';
 export * from './Draggable';
 export * from './RangeResizer';
 export * from './FillHandle';
+export * from './useDoubleClick';
 //# sourceMappingURL=index.d.ts.map

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)