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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/grid-react",
   "description": "Grid React - Advanced grid component for React",
-  "version": "0.8.0-beta.1",
+  "version": "0.8.0-beta.3",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -42,8 +42,8 @@
   ],
   "dependencies": {
     "@floating-ui/react-dom": "^2.1.9",
-    "@sheetxl/utils": "^0.8.0-beta.1",
-    "@sheetxl/utils-react": "^0.8.0-beta.1",
+    "@sheetxl/utils": "^0.8.0-beta.3",
+    "@sheetxl/utils-react": "^0.8.0-beta.3",
     "clsx": "^2.1.1",
     "react-merge-refs": "^3.0.2",
     "react-use": "^17.6.1",

package/types/src/cell/CellRenderer.d.ts

@@ -1,14 +1,25 @@
 import { Bounds, CellCoords, RangeCoords } from '@sheetxl/utils';
-import { IGridPane } from '../surface';
 export interface CellRendererProps<T = any> extends React.HTMLAttributes<HTMLElement>, React.Attributes {
     /**
      * A value to render.
      */
     value: T;
     /**
-     * The view that is rendering a collection of cells.
+     * The zoom {@link CellRendererProps.bounds} were measured at.
+     *
+     * @defaultValue 1
+     *
+     * @remarks
+     * A renderer is handed the zoom, never the pane it came from: everything it needs to draw one cell
+     * is data (the value, the bounds, the scale), so it stays a pure function of its props and can be
+     * rendered anywhere a caller can supply bounds — a preview, a tooltip, a cell drawn outside its own
+     * column. A renderer that genuinely needs the live view (hover, scroll) reads it from context with
+     * `useGridPane`.
+     *
+     * The bounds already have the zoom applied; this is for what CSS pixels do not carry — an unscaled
+     * inset, a glyph size, a stroke width the renderer picks itself.
      */
-    pane: IGridPane;
+    zoom?: number;
     /**
      * The range bounds relative to the current viewport and zoom.
      */

package/types/src/editor/DefaultEditable.d.ts

@@ -40,6 +40,12 @@ export interface IEditable<C, D = string, A = EditCommitArgs> {
     getSession(): EditSession<C, D, A> | null;
     /** Subscribe to session changes (start/stop only). Returns an unsubscribe. */
     subscribe(listener: () => void): () => void;
+    /**
+     * Subscribe to commits the model REFUSED by throwing (an expected refusal such as "You can't change
+     * part of an array", or a real fault). The edit stays open either way; this is the seam through
+     * which the reason reaches a host that can show it. Returns an unsubscribe.
+     */
+    subscribeCommitError(listener: (error: unknown) => void): () => void;
     /** Begin an edit on `coords`. Returns `false` (and does nothing) if the cell is not editable. */
     startEdit(coords: CellCoords, options?: StartEditOptions<D>): boolean;
     /** Commit the current edit. On success clears the session; returns whether it succeeded. */
@@ -100,12 +106,15 @@ export declare class DefaultEditable<C, D = string, A = EditCommitArgs> implemen
     private readonly unsubscribeAnchor;
     private current;
     private readonly listeners;
+    private readonly commitErrorListeners;
     constructor(anchor: ICellAnchor, createEdit: CreateEdit<C, D, A>, options?: DefaultEditableOptions);
     private onAnchorChange;
     /** @inheritdoc IEditable.getAnchor */
     getAnchor(): ICellAnchor;
     /** @inheritdoc IEditable.subscribe */
     subscribe(listener: () => void): () => void;
+    /** @inheritdoc IEditable.subscribeCommitError */
+    subscribeCommitError(listener: (error: unknown) => void): () => void;
     /** @inheritdoc IEditable.getSession */
     getSession(): EditSession<C, D, A> | null;
     /** @inheritdoc IEditable.startEdit */

package/types/src/editor/EditSession.d.ts

@@ -49,6 +49,11 @@ export interface EditModel<C, D = string, A = EditCommitArgs> {
 export interface EditSessionInit<C, D = string, A = EditCommitArgs> extends EditModel<C, D, A> {
     /** The cell being edited. */
     coords: CellCoords;
+    /**
+     * Hears the error a THROWING model write rejected the commit with (see {@link EditModel.commit}).
+     * The rejection itself only keeps the edit open; this is how the reason reaches whoever can show it.
+     */
+    onCommitError?: (error: unknown) => void;
 }
 /**
  * Options applied when an edit begins (`DefaultEditable.startEdit` → the `EditSession` constructor).
@@ -96,6 +101,7 @@ export interface CommitContext<D = string, A = EditCommitArgs> {
  */
 export declare class EditSession<C, D = string, A = EditCommitArgs> implements ICellAnchor {
     private readonly commitFn;
+    private readonly onCommitError?;
     private state;
     private readonly listeners;
     private readonly commitListeners;

package/types/src/editor/EditState.d.ts

@@ -20,6 +20,12 @@ export interface EditCommitArgs {
      * Excel's `Ctrl+Enter`. The active cell does not move (the leave-key does not navigate/traverse).
      */
     broadcast?: boolean;
+    /**
+     * Array-enter the value over the **current selection** — Excel's `Ctrl+Shift+Enter`: one formula
+     * at the selection's top-left whose result is fitted to the selection's extent, rather than
+     * spilling from the active cell. The active cell does not move.
+     */
+    arrayFixed?: boolean;
 }
 /**
  * A text selection range within the editor input. Mirrors the `HTMLTextAreaElement` selection API.

package/types/src/editor/EditorInput.d.ts

@@ -67,7 +67,8 @@ export interface EditorInputProps<C, D = string> {
      * (a rejected/invalid value) the input keeps the session open and stops the key so the selection
      * does not move away.
      *
-     * `args` carries the commit "signal" — e.g. {@link EditCommitArgs.broadcast} for a Ctrl+Enter fill.
+     * `args` carries the commit "signal" — e.g. {@link EditCommitArgs.broadcast} for a Ctrl+Enter fill,
+     * {@link EditCommitArgs.arrayFixed} for a Ctrl+Shift+Enter array entry.
      */
     onCommit(args?: EditCommitArgs): boolean;
     /** Cancel/revert the edit. */

package/types/src/editor/useEditorKeymap.d.ts

@@ -54,6 +54,17 @@ export interface EditorKeymapProps {
      */
     setCaret?(caret: number): void;
 }
+/**
+ * The commit "signal" a leave key carries: `Ctrl+Shift+Enter` array-enters over the selection
+ * ({@link EditCommitArgs.arrayFixed}), `Ctrl+Enter` fills it ({@link EditCommitArgs.broadcast}), and
+ * anything else is a plain commit (`undefined`). Both modified forms keep the active cell put.
+ */
+export declare const commitArgsFromKey: (e: {
+    which: number;
+}, native: {
+    ctrlKey: boolean;
+    shiftKey: boolean;
+}) => EditCommitArgs | undefined;
 /**
  * The shared spreadsheet editor keymap, as a `<textarea>` `onKeyDown` handler. Both the default and
  * the cell-aware inputs use it so the interaction contract stays identical:

package/types/src/header/useHeaderSelectionPointer.d.ts

@@ -55,8 +55,12 @@ export interface HeaderSelectionPointerOptions {
     onPointerDownInterceptor?: (e: React.PointerEvent, cell: CellCoords) => boolean | void;
     /** Called once at the start of a pointer gesture (before the selection changes). */
     onDragStart?: () => void;
-    /** Called at the end of a pointer gesture. */
-    onDragEnd?: (e: React.PointerEvent) => void;
+    /**
+     * Called at the end of a pointer gesture — on release AND on an abort (Escape / OS `pointercancel`),
+     * so whatever {@link HeaderSelectionPointerOptions.onDragStart} armed is always disarmed. The event is
+     * absent on an abort.
+     */
+    onDragEnd?: (e?: React.PointerEvent) => void;
     /** Called on pointer-up, after {@link HeaderSelectionPointerOptions.onDragEnd} (e.g. refocus the grid). */
     onPointerUp?: (e: React.PointerEvent) => void;
 }

package/types/src/layer/GridFloatPanel.d.ts

@@ -0,0 +1,18 @@
+import { default as React } from 'react';
+import { FloatPanelProps } from '@sheetxl/utils-react';
+/**
+ * A **float stack panel positioned by the grid**: pass {@link renderGridFloatPanel} as a
+ * `useFloatStack` `renderFloatPanel`, and a {@link GridAnchor} (a cell or range) as its `anchor`.
+ *
+ * @remarks
+ * The stack keeps what it does for every popup — the portal, light-dismiss, Escape, focus restore and
+ * stacking. The position comes from {@link StickyFloat}, the engine grid buttons and labels use, so the
+ * popup moves with its cell as the grid scrolls (which no DOM event reports), flips against the same
+ * boundary, and closes once its cell has scrolled out of view.
+ *
+ * The stack's `propsPopper` `placement` and `offsets` are read as the grid placement and offset.
+ */
+export declare const GridFloatPanel: React.FC<FloatPanelProps>;
+/** {@link GridFloatPanel} as a `useFloatStack` `renderFloatPanel`. */
+export declare const renderGridFloatPanel: (props: FloatPanelProps) => React.ReactElement;
+//# sourceMappingURL=GridFloatPanel.d.ts.map

package/types/src/layer/RangeFloatLayer.d.ts

@@ -29,6 +29,11 @@ export interface RangeFloatTarget<T = unknown> {
     key?: string;
     /** Payload passed to the render-prop (the message, the validation, the table, …). */
     data: T;
+    /**
+     * Where this target's float attaches, for a layer whose targets do not all belong on one side.
+     * Defaults to the layer's {@link RangeFloatLayerProps.placement}.
+     */
+    placement?: GridPlacement;
 }
 /** The context passed to a {@link RangeFloatLayerProps} render-prop. */
 export interface RangeFloatRender<T = unknown> {

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

@@ -4,6 +4,7 @@ export * from './VirtualDiv';
 export type { GridAnchor, GridAnchorReference, GridPlacement, GridWhenOff, GridBoundary, GridFloatSide, GridAlign, GridSlide } from './useGridAnchor';
 export * from './StickyAnchor';
 export * from './StickyFloat';
+export * from './GridFloatPanel';
 export * from './useHoverIntent';
 export * from './useRangeHover';
 export * from './RangeFloatLayer';

package/types/src/list/CheckboxList.d.ts

@@ -1,7 +1,14 @@
 import { default as React } from 'react';
 import { ISelection } from '../selection';
+import { ListProps } from './List';
 export interface CheckboxListAttributes {
     isCheckboxList: () => true;
+    /** The highlighted row, or `-1` when the list is empty. */
+    getHighlightIndex: () => number;
+    /** Move the highlight `delta` rows (clamped to the list) and bring it into view. */
+    moveHighlight: (delta: number) => void;
+    /** Toggle the selected rows, as Space does: the anchor's opposite, applied to every one of them. */
+    toggleHighlighted: () => void;
 }
 export interface ICheckboxListElement extends HTMLDivElement, CheckboxListAttributes {
 }
@@ -41,6 +48,10 @@ export interface CheckboxListProps extends React.HTMLAttributes<HTMLDivElement>
     selection?: ISelection;
     /** Content cache-bust; bump when checked state changes without `isChecked`'s identity changing. */
     cacheToken?: unknown;
+    /** See `ListSurfaceProps.autoFocus`. */
+    autoFocus?: boolean;
+    /** See `ListSurfaceProps.viewport`. */
+    viewport?: ListProps['viewport'];
     /** Ref for the Element. */
     ref?: React.Ref<ICheckboxListElement>;
 }

package/types/src/list/List.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { ISelection } from '../selection';
+import { ListSurface } from './ListSurface';
 export interface ListAttributes {
     isList: () => true;
 }
@@ -36,6 +37,14 @@ export interface ListProps extends React.HTMLAttributes<HTMLDivElement> {
      * *rendered* content changed without `renderItem`'s identity changing.
      */
     cacheToken?: unknown;
+    /** See `ListSurfaceProps.scrollTo`. */
+    scrollTo?: {
+        row: number;
+    } | null;
+    /** See `ListSurfaceProps.autoFocus`. */
+    autoFocus?: boolean;
+    /** See `ListSurfaceProps.viewport`. */
+    viewport?: React.ComponentProps<typeof ListSurface>['viewport'];
     /** Ref for the Element. */
     ref?: React.Ref<IListElement>;
 }
@@ -48,8 +57,8 @@ export interface ListProps extends React.HTMLAttributes<HTMLDivElement> {
  * The List's whole state is its {@link ListProps.selection}; it has no per-item callbacks and no notion
  * of "checked" or "toggle". Pointer selection is the `SelectionLayer`'s job (it hit-tests the pointer),
  * so the cells are inert, transparent content; the keyboard is the caller's via {@link ListProps.onKeyDown}.
- * See {@link CheckboxList} for the checkbox-list specialization, and `SheetValueList` in
- * `@sheetxl/react` for the sheet-backed one (real cells, so values format like the sheet).
+ * See {@link CheckboxList} for the checkbox-list specialization and {@link PickList} for the
+ * single-choice text list.
  */
 export declare const List: React.ForwardRefExoticComponent<Omit<ListProps, "ref"> & React.RefAttributes<IListElement>>;
 //# sourceMappingURL=List.d.ts.map

package/types/src/list/ListSearch.d.ts

@@ -0,0 +1,31 @@
+import { default as React } from 'react';
+/**
+ * Props for {@link ListSearch}.
+ */
+export interface ListSearchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange'> {
+    /** The search text. */
+    value: string;
+    /** The search text changed — including to `''` when Escape clears it. */
+    onChange: (value: string) => void;
+    /** Escape on an empty field: the search has nothing left to clear, so the host closes. */
+    onClose?: () => void;
+    /** Ref for the input. */
+    ref?: React.Ref<HTMLInputElement>;
+}
+/**
+ * The rows of `items` whose `text` contains `query`, ignoring case. An empty query keeps every row.
+ */
+export declare const filterByText: <T extends {
+    text: string;
+}>(items: readonly T[], query: string) => readonly T[];
+/**
+ * The **search field** shown above a list ({@link PickList}, `CheckboxList`): a plain input that
+ * narrows the rows as typed. Filtering itself is the host's, with {@link filterByText}.
+ *
+ * @remarks
+ * Escape clears the text first and closes only when there is none left, so a mistyped search is
+ * one key from a full list and two from a closed one. Every other key is the host's through
+ * `onKeyDown`, which is how the arrows and Enter reach the list while the field keeps focus.
+ */
+export declare const ListSearch: React.ForwardRefExoticComponent<Omit<ListSearchProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
+//# sourceMappingURL=ListSearch.d.ts.map

package/types/src/list/ListSurface.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { Viewport } from '@sheetxl/utils-react';
 import { CellLayerProps, CellRendererProps } from '../cell';
 import { LayerEventProps } from '../layer';
 import { ISelection } from '../selection';
@@ -48,6 +49,26 @@ export interface ListSurfaceProps extends React.HTMLAttributes<HTMLDivElement> {
     propsLayer?: LayerEventProps;
     /** Take focus on mount, so the Arrow keys work without a click first. @defaultValue false */
     autoFocus?: boolean;
+    /**
+     * Whether the vertical scrollbar (and its gutter) is drawn. `'auto'` draws it only while the rows
+     * overflow the box — a list that fits has nothing to scroll and the gutter would only widen it,
+     * and one squeezed by its host (a popup capped to the window) scrolls as a plain list does.
+     * @defaultValue 'auto'
+     */
+    showScrollbar?: boolean | 'auto';
+    /**
+     * Bring `row` into view. Read by identity: a new object scrolls again, the same object does not, so
+     * a caller keeps one per intent (the row highlighted on open, the row a key moved to). The scroll
+     * waits for the surface to have a size, so it can be set before the first paint.
+     */
+    scrollTo?: {
+        row: number;
+    } | null;
+    /**
+     * The scroll state, when the caller owns it — a host that sizes the list itself (`setSizes`) or
+     * drives its scroll. A private one is created when omitted.
+     */
+    viewport?: Viewport;
     /** Opaque content cache-bust forwarded to the `CellLayer`. */
     cacheToken?: unknown;
     /** Ref for the Element. */
@@ -60,11 +81,10 @@ export interface ListSurfaceProps extends React.HTMLAttributes<HTMLDivElement> {
  *
  * @remarks
  * Not a list *component*: it renders no row content of its own, has no notion of an item, and adds no
- * padding — {@link ListSurfaceProps.renderCell} owns the whole row box. It exists because there are
- * two kinds of list ({@link List}, whose rows are arbitrary React, and `@sheetxl/react`'s
- * `SheetValueList`, whose rows are real sheet cells) and they differ ONLY in that renderer. Everything
- * they share — the viewport, the measured single column, the selection styling and its rationale, the
- * layer order — is here, once.
+ * padding — {@link ListSurfaceProps.renderCell} owns the whole row box. It exists because the lists
+ * built on it ({@link List}, whose rows are arbitrary React, and {@link PickList}, whose rows are text)
+ * differ ONLY in that renderer. Everything they share — the viewport, the measured single column, the
+ * selection styling and its rationale, the layer order — is here, once.
  *
  * The single column tracks the measured content width, so a row spans the full list; scrolling is
  * vertical only.

package/types/src/list/PickList.d.ts

@@ -0,0 +1,71 @@
+import { default as React } from 'react';
+import { Viewport } from '@sheetxl/utils-react';
+/** One row of a {@link PickList}: what it shows. */
+export interface PickListItem {
+    /** The row's text. */
+    text: string;
+}
+export interface PickListAttributes {
+    isPickList: () => true;
+    /** The highlighted row, or `-1` when the list is empty. */
+    getHighlightIndex: () => number;
+    /** Move the highlight `delta` rows (clamped to the list) and bring it into view. */
+    moveHighlight: (delta: number) => void;
+    /** Choose the highlighted row, as Enter does. `false` when there is none. */
+    chooseHighlighted: () => boolean;
+}
+export interface IPickListElement extends HTMLDivElement, PickListAttributes {
+}
+/**
+ * Props for {@link PickList}.
+ */
+export interface PickListProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** The rows, in the order shown. */
+    items: readonly PickListItem[];
+    /** A row was chosen — clicked, or Enter/Space on the highlighted row. */
+    onChoose?: (index: number, item: PickListItem) => void;
+    /**
+     * The row highlighted when the list (re)appears — the current value's, so a pick from the keyboard
+     * starts from it. Out of range, or omitted, highlights the first row. Re-read when `items` changes.
+     */
+    highlightIndex?: number;
+    /** Uniform row height in px. @defaultValue 24 */
+    itemHeight?: number;
+    /**
+     * Rows shown before the list scrolls. The list is as tall as its rows up to this many; a caller's
+     * `style.maxHeight` caps it further (a popup fit to the space left). @defaultValue 8
+     */
+    visibleRows?: number;
+    /**
+     * Width (px) the rows need, when the caller already knows it. Otherwise it is measured from the
+     * widest `text` in the list's own font (see {@link PickListProps.measureText}).
+     */
+    contentWidth?: number;
+    /**
+     * How to measure a row's text, in px. @defaultValue a canvas measure in the font `style` names
+     * (or the browser default when it names none).
+     */
+    measureText?: (text: string) => number;
+    /** Render a row's content. @defaultValue the text, clipped with an ellipsis. */
+    renderItem?: (item: PickListItem, index: number) => React.ReactNode;
+    /** Take focus on mount, so the Arrow keys work without a click first. @defaultValue false */
+    autoFocus?: boolean;
+    /** The scroll state, when the caller owns it (see `ListSurfaceProps.viewport`). */
+    viewport?: Viewport;
+    /** Ref for the Element. */
+    ref?: React.Ref<IPickListElement>;
+}
+/**
+ * A single-choice **pick list** of text rows over {@link ListSurface}: a dropdown's menu.
+ *
+ * @remarks
+ * The list's whole state is which row is highlighted; choosing is a callback. One row is always
+ * highlighted (the current value's on open, then wherever the keys or the pointer put it), Arrow keys
+ * move it, Enter or Space choose it, a click chooses the clicked row. The width follows the widest
+ * row's text; the height follows the rows up to {@link PickListProps.visibleRows}, then scrolls.
+ *
+ * A host with its own input (a search field above the list) drives the highlight through the element's
+ * {@link PickListAttributes} rather than moving focus into the list.
+ */
+export declare const PickList: React.ForwardRefExoticComponent<Omit<PickListProps, "ref"> & React.RefAttributes<IPickListElement>>;
+//# sourceMappingURL=PickList.d.ts.map

package/types/src/list/_measureText.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The CSS `font` shorthand a box's style resolves to, for measuring text the way that box draws it.
+ * Falls back to a plain sans-serif at the browser's default size when the style names no font.
+ */
+export declare const fontFromStyle: (style?: React.CSSProperties | null) => string;
+/**
+ * The width (px) of `text` drawn in `font` (a CSS `font` shorthand).
+ *
+ * @remarks
+ * Measured on a shared offscreen canvas. Where no 2-D context exists (a non-DOM test host) the width
+ * is estimated from the font size, so a caller sizing a box never sees `0` or `NaN`.
+ */
+export declare const measureTextWidth: (text: string, font: string) => number;
+//# sourceMappingURL=_measureText.d.ts.map

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

@@ -1,4 +1,6 @@
 export * from './ListSurface';
 export * from './List';
 export * from './CheckboxList';
+export * from './PickList';
+export * from './ListSearch';
 //# sourceMappingURL=index.d.ts.map

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;
@@ -108,6 +110,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 +123,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,86 @@
-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;
+}
+/**
+ * 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}.
  */
@@ -43,21 +125,39 @@ export interface DraggableProps {
      */
     onDragStateChange?: (dragging: boolean) => void;
     /** Drag started; `range` is the original. */
-    onDragStart?: (range: RangeCoords, e: React.PointerEvent) => void;
+    onDragStart?: (range: RangeCoords, e: React.PointerEvent, info: DragMoveInfo) => 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 +174,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';