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

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';
 /**
@@ -29,6 +29,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 +59,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,43 @@ 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). The
+     * preview draws the I-beam in the refused color instead, and `onMove` never fires.
+     */
+    refused?: boolean;
+}
 /**
  * Props for {@link SelectionLayer}.
  */
@@ -41,7 +73,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 +102,25 @@ 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, 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).
+     *
+     * @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.
+     */
+    isDropRefused?: (from: RangeCoords, drop: MoveDrop) => boolean;
+    /**
+     * 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 +137,33 @@ 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) => void;
+    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) => void;
+    onMoveStart?: (from: RangeCoords, e: React.PointerEvent, drop: MoveDrop) => 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.
@@ -133,6 +196,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,6 +228,14 @@ 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;
     /**
      * 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

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

@@ -25,4 +25,34 @@ 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. */
+    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/useDragCells.d.ts

@@ -36,6 +36,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 +73,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