@sheetxl/grid-react 0.7.28-beta.4 → 0.8.0-beta.2

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