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

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

@@ -0,0 +1,93 @@
+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';
+/**
+ * Props for {@link ListSurface}.
+ */
+export interface ListSurfaceProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Number of rows. */
+    itemCount: number;
+    /**
+     * Render one row, as a grid cell — the `CellLayer` renderer, so the row is handed its bounds, its
+     * pane (zoom) and its resolved `value`. The cell is positioned and clipped by the tiling engine.
+     */
+    renderCell: (props: CellRendererProps) => React.ReactNode;
+    /**
+     * Resolve the visible rows to render (and their `value`). Omit to render every visible row with no
+     * pre-resolved value — `renderCell` then derives its content from the row index.
+     */
+    getVisibleCells?: CellLayerProps['getVisibleCells'];
+    /**
+     * Uniform row height in px. Also the list's natural height (`itemCount * itemHeight`) unless
+     * `style.height` overrides it. @defaultValue 24
+     */
+    itemHeight?: number;
+    /**
+     * Width the **column** should be, in px — the list sizes itself to this PLUS its own chrome (the
+     * vertical scrollbar's gutter), so the column actually ends up this wide.
+     *
+     * @remarks
+     * The distinction matters because the natural thing to pass — a measured content width, e.g.
+     * `ICellRange.getBestFit().width` — describes the column, not the box. Setting it as the box's
+     * `width` instead silently hands the gutter's worth of pixels back, and content sized to fit
+     * exactly then does not. Omit to size from `style` and let the column take what is left.
+     */
+    contentWidth?: number;
+    /**
+     * The selection model — the active-row highlight + Arrow-key navigation. The surface's *state*.
+     * Owned by the caller (so it can read what's selected); a private one is created when omitted.
+     */
+    selection?: ISelection;
+    /**
+     * Event taps installed as the list's TOP layer — so they are offered keys and pointers before the
+     * built-in Arrow navigation and before the selection's own hit test. Handle Space/Enter here (the
+     * grid would otherwise consume them) and `stopPropagation` to override; anything you don't consume
+     * falls through to navigation.
+     */
+    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. */
+    ref?: React.Ref<HTMLDivElement>;
+}
+/**
+ * The **list chrome**: a virtualized single-column `GridSurface` wearing the grid's own layers — a
+ * `CellLayer` for the rows and a `SelectionLayer` for the active-row highlight + Arrow keys — dressed
+ * so it reads as a list rather than a grid.
+ *
+ * @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 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.
+ */
+export declare const ListSurface: React.ForwardRefExoticComponent<Omit<ListSurfaceProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=ListSurface.d.ts.map

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,3 +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';

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