@sheetxl/grid-react 0.7.27 → 0.7.28-beta.2

package/types/src/metrics/useGridMetrics.d.ts

@@ -0,0 +1,67 @@
+import { ItemSizer, IGridMetrics } from './Types';
+/**
+ * One axis (rows OR columns) of the grid: maps an item index ⇄ its pixel offset.
+ *
+ * @remarks
+ * The public {@link IGridMetrics} is exactly four of these (`get(Col|Row)(Offset|Index)`); an axis is
+ * the per-direction half. `getOffset` returns the LEADING edge of an item; `getIndex` is its inverse
+ * (the item whose span contains a pixel offset). Both clamp gracefully outside the grid: a negative
+ * index/offset → `0`, an offset at/past the total extent → `count` (one past the last) — on BOTH the
+ * uniform and variable paths. On a run of zero-size (hidden) items — an equal-offset plateau —
+ * `getIndex` deterministically resolves to the LAST index of the run: the following sized item, the
+ * one whose span actually contains the pixel (a zero-size span contains nothing).
+ */
+export interface Axis {
+    /** Leading-edge pixel offset of `index` (0 for `index <= 0`). */
+    getOffset: ItemSizer;
+    /** Item index whose span contains pixel `offset` (0 at/under the origin, clamped to `count`). */
+    getIndex: ItemSizer;
+}
+/**
+ * Build an {@link Axis} from a fixed size or a per-index sizer.
+ *
+ * - **Uniform** (a `number`): closed-form arithmetic — no allocation, no cache, O(1) both ways. This
+ *   is the overwhelmingly common case (every default grid, every fixed row height) and the supported
+ *   large-grid mode.
+ * - **Variable** (an {@link ItemSizer}): offsets are MEASURED lazily and memoized in dense arrays
+ *   (indices fill sequentially from 0). The *search* over the already-measured prefix is O(log n)
+ *   (binary search, with an exponential probe to bracket a target past it) — but **measurement is
+ *   linear and cumulative**: a jump to index N measures and permanently caches every offset `0..N`
+ *   (O(N) time & memory on first touch; a far jump into a 1M-item axis walks ~1M sizer calls). This
+ *   path is the convenience tier for human-scale variable axes. Grids that need large *and* variable
+ *   don't use it — they pass a prebuilt {@link IGridMetrics} (e.g. the SDK's run-length metrics)
+ *   instead of a sizer. (GRID-CLEAN F1: documented as-is by design; no sublinear tree here.)
+ *
+ * Exported for tests (uniform/variable edge parity — GRID-CLEAN B4/B5); not part of the package API.
+ */
+export declare const createAxis: (count: number, size: ItemSizer | number) => Axis;
+export interface UseGridMetricOptions {
+    /**
+     * Number of columns in the grid.
+     */
+    columnCount: number;
+    /**
+     * Number of rows in the grid.
+     */
+    rowCount: number;
+    /**
+     * Row height: a fixed number (uniform) or a `(index) => number` sizer. Defaults to `20`.
+     */
+    getRowHeight?: ItemSizer | number;
+    /**
+     * Column width: a fixed number (uniform) or a `(index) => number` sizer. Defaults to `75`.
+     */
+    getColumnWidth?: ItemSizer | number;
+}
+/**
+ * Build an {@link IGridMetrics} (the index ⇄ offset mapping the surface needs) from a row/column
+ * count plus fixed sizes or per-index sizers.
+ *
+ * @remarks
+ * The returned object's IDENTITY changes only when the geometry inputs do (count or sizer) — never on
+ * scroll — which is exactly the signal the surface keys its pane recreation on. A `null` `props`
+ * yields `null` (the engine then falls back to its own default metrics). `IGridMetrics` is the entire
+ * consumed contract; nothing else is exposed.
+ */
+export declare const useGridMetrics: (props: UseGridMetricOptions | null) => IGridMetrics | null;
+//# sourceMappingURL=useGridMetrics.d.ts.map

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

@@ -0,0 +1,129 @@
+import { CellCoords, RangeCoords } from '@sheetxl/utils';
+/** Which corner (`tl`/`tr`/`bl`/`br`) or edge-midpoint (`t`/`b`/`l`/`r`) of the range to sit on. */
+export type HandleAnchor = 'tl' | 'tr' | 'bl' | 'br' | 't' | 'b' | 'l' | 'r';
+/**
+ * Resolved info passed to {@link DragHandleProps.renderHandle}.
+ */
+export interface DragHandleRenderProps {
+    /** The corner/edge this handle sits on. */
+    anchor: HandleAnchor;
+    /** Resolved size (px). */
+    size: number;
+    /** Resolved cursor (anchor-derived unless overridden). */
+    cursor: string;
+    /** Resolved background color — handy as a theme color for custom marks. */
+    background: string;
+    /** Whether the pointer is currently over the handle (for a hover affordance). */
+    hovered: boolean;
+    /**
+     * **Spread onto your handle element** — this wires placement, pointer-capture, cursor, and the
+     * drag events. Without it the handle won't drag. Only pointer-DOWN is on the element; the drag's
+     * move/up are attached to `window` for the gesture's duration (so it survives the handle
+     * repositioning under an edge auto-scroll).
+     */
+    handleProps: {
+        onPointerDown: (e: React.PointerEvent) => void;
+        onPointerEnter?: (e: React.PointerEvent) => void;
+        onPointerLeave?: (e: React.PointerEvent) => void;
+        style: React.CSSProperties;
+    };
+}
+/**
+ * Props for {@link DragHandle}.
+ */
+export interface DragHandleProps {
+    /** The range the handle is anchored to; it sits on the {@link DragHandleProps.anchor} corner. */
+    range: RangeCoords;
+    /** Which corner/edge of `range` to position on. */
+    anchor: HandleAnchor;
+    /** Visual size (px) of the handle. @defaultValue 8 */
+    size?: number;
+    /** Cursor while hovering/dragging. @defaultValue an anchor-appropriate resize cursor. */
+    cursor?: string;
+    /**
+     * Cursor to show **only while a drag is in flight** (the pointer-capture target's cursor holds for
+     * the whole drag, even off the handle / off-window). Use it to swap the idle affordance for a neutral
+     * "manipulating" cursor — e.g. {@link RangeResizer} flips its directional resize cursors to
+     * `grabbing` so a corner drag doesn't keep implying you can still resize that way. Omit to keep
+     * {@link DragHandleProps.cursor} for the whole gesture (the fill / table-resize handles, which want
+     * their crosshair/resize cursor throughout).
+     */
+    dragCursor?: string;
+    /** Default-dot background, and the theme color handed to {@link DragHandleProps.renderHandle}. */
+    background?: string;
+    /** Drag started; `cell` is under the pointer at press. */
+    onDragStart?: (cell: CellCoords, e: React.PointerEvent) => void;
+    /** The pointer moved to a new cell during the drag (`from` = press cell, `to` = current). */
+    onDragMove?: (from: CellCoords, to: CellCoords, e: React.PointerEvent) => void;
+    /** Drag ended (`from` = press cell, `to` = last cell). */
+    onDragEnd?: (from: CellCoords, to: CellCoords, e: React.PointerEvent) => void;
+    /**
+     * The drag was **aborted** — the user pressed Escape, or the OS cancelled the pointer (`pointercancel`).
+     * Fires INSTEAD of {@link DragHandleProps.onDragEnd} (nothing is committed). Use it to tear down any
+     * in-flight preview a flavor set in `onDragStart`/`onDragMove` (e.g. the fill's dashed preview) without
+     * applying it. Event-less — an Escape abort has no pointer event.
+     */
+    onDragCancel?: () => void;
+    /** The pointer entered (`true`) / left (`false`) the handle — for a hover affordance on the host. */
+    onHoverChange?: (hovered: boolean) => void;
+    /**
+     * Style merged onto the default dot **only while hovered** — e.g. {@link RangeResizer} recolors
+     * the thumb's border from the window color to the stroke color, so it appears to "grow" on hover
+     * (Excel-style). Use the same shorthand property as the base `style` (e.g. `border`) to avoid a
+     * React shorthand/longhand warning. Ignored for headless `renderHandle` consumers (they get
+     * {@link DragHandleRenderProps.hovered} to wire their own).
+     */
+    hoverStyle?: React.CSSProperties;
+    /**
+     * Glide the handle to its new position (transition `left`/`top`) when `range` changes — pair with
+     * {@link RangeRect}'s `animatedTransition` so the corners track a move-drag's gliding outline
+     * instead of jumping. @defaultValue false
+     */
+    animatedTransition?: boolean;
+    /**
+     * Pin the handle centre INSIDE the pane's viewport instead of letting it sit at the range's true
+     * anchored corner. When that corner is far off-grid — e.g. a whole-row / whole-column fill selection
+     * whose corner is at the last column / row — this keeps the handle visible and reachable. When the
+     * range no longer intersects this pane at all, the handle is not rendered.
+     *
+     * Clamp a **single axis** to track the range along the other: `'y'` pins the vertical position but
+     * lets `x` follow the range (a whole-column `tr` handle — pinned to the top, scrolls with the column);
+     * `'x'` pins the horizontal but lets `y` follow (a whole-row `bl` handle — pinned to the left, scrolls
+     * with the row). `true` clamps both. @defaultValue false
+     */
+    clampToView?: boolean | 'x' | 'y';
+    /**
+     * Render the handle **element** yourself (headless): return your element with `handleProps` spread
+     * onto it — that wires placement, pointer-capture, cursor, and events. Replaces the default dot and
+     * `children`. Use it for a configured look — e.g. an Excel table-resize tick.
+     */
+    renderHandle?: (props: DragHandleRenderProps) => React.ReactNode;
+    /** Static content inside the default dot. Ignored when `renderHandle` is set. */
+    children?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    /**
+     * Keep the currently-focused element focused across the drag (`preventDefault` on pointer-down, which
+     * suppresses the compat `mousedown` that would otherwise move focus to the grid's `tabIndex` Stage).
+     * Used by the reference-range picker so dragging a handle doesn't blur the formula editor's textarea —
+     * it preserves whatever had focus rather than stealing it. @defaultValue false
+     */
+    preserveFocus?: boolean;
+}
+/**
+ * A generic, draggable handle anchored to a corner/edge of a grid range. It owns only the **gesture
+ * mechanics** — placement, pointer capture, and cell hit-testing with edge auto-scroll — and reports
+ * the drag in **cell terms** (`from` → `to`). It holds no range math: flavors (fill, table-resize,
+ * touch-extend) own the cell→model conversion and any preview.
+ *
+ * @remarks
+ * The handle centre is placed with the shared {@link ReactUtils.edgeCenter} rule — the same one
+ * gridlines and cell borders use — so it lands on the boundary device-crisply and flush with the
+ * selection outline. It's a real DOM element (not a Stage responder): it captures the pointer on its
+ * own element so move/up survive leaving the handle, and it `stopPropagation`s pointer-down so the
+ * selection layer underneath does not also begin a gesture. Provide
+ * {@link DragHandleProps.renderHandle} to render the element yourself (spread the supplied
+ * `handleProps`).
+ */
+export declare const DragHandle: React.FC<DragHandleProps>;
+//# sourceMappingURL=DragHandle.d.ts.map

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

@@ -0,0 +1,86 @@
+import { RangeCoords } from '@sheetxl/utils';
+/**
+ * Props for {@link Draggable}.
+ */
+export interface DraggableProps {
+    /**
+     * The range the wrapped content occupies (controlled). The drag's "from"; the result range comes out
+     * via `onDrag*`.
+     */
+    range?: RangeCoords;
+    /**
+     * The content to make movable — any visual ({@link RangeRect}, `RangeResizer`, …), rendered at
+     * `range` and grabbable. `Draggable` draws nothing itself; the visuals are all composed children.
+     */
+    children?: React.ReactNode;
+    /**
+     * Where you can grab to move: the whole rectangle (`entire`, the default) or only its **border ring**
+     * (`edges` — interior clicks fall through, for a selection whose interior is for selecting/editing).
+     *
+     * @defaultValue 'entire'
+     */
+    grip?: 'entire' | 'edges';
+    /**
+     * Grab slack in device px. For `grip: 'edges'` it's the border-ring hit thickness (centered on the
+     * border, so half reaches outside the range). For `grip: 'entire'` the whole rectangle is grabbable
+     * and this pads the hit area OUTWARD by the same amount, so you can grab just past the edge too.
+     *
+     * @defaultValue 10
+     */
+    hitSize?: number;
+    /**
+     * The pointer entered (`true`) or left (`false`) the grip's hit area — the border ring for
+     * `grip: 'edges'`, the whole (outward-padded) rectangle for `grip: 'entire'`. Use it to render a
+     * hover affordance on the composed visual, e.g. Excel thickening the move border on hover. Fires only
+     * on a real enter/leave, not on every move.
+     */
+    onHoverChange?: (hovered: boolean) => void;
+    /**
+     * The drag began (`true`) / ended (`false`) — fires on every press/release, even a press with no
+     * movement (unlike `onDragEnd`, which only fires on an actual translation). Separate from
+     * {@link DraggableProps.onHoverChange} because pointer-capture suppresses the grip's hover events
+     * mid-drag; use this to keep a drag affordance (e.g. the thickened move border) lit for the whole drag.
+     */
+    onDragStateChange?: (dragging: boolean) => void;
+    /** Drag started; `range` is the original. */
+    onDragStart?: (range: RangeCoords, e: React.PointerEvent) => void;
+    /**
+     * 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.
+     */
+    onDragMove?: (range: RangeCoords, e: React.PointerEvent) => void;
+    /** Drag released: commit the translated range. */
+    onDragEnd?: (range: RangeCoords, e: React.PointerEvent) => 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.
+     */
+    renderMove?: (range: RangeCoords) => React.ReactNode;
+    /**
+     * 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
+     * so dragging a range doesn't blur the formula editor's textarea. @defaultValue false
+     */
+    preserveFocus?: boolean;
+}
+/**
+ * A **"make draggable" wrapper**: it makes its `children` movable (translate — same size, new location)
+ * and reports the translated range via `onDrag*`. It owns ONLY the gesture (pointer-capture +
+ * cell-delta translate + edge auto-scroll); it draws nothing. The consumer composes the visuals and
+ * decides what a drag means:
+ *
+ * - **Live** — `onDragMove` → update `range`; the wrapped child follows the pointer (e.g. a picker, or
+ *   any draggable `RangeRect`). This is the default feel.
+ * - **Ghost** — pass `renderMove`; `Draggable` tracks the in-flight range internally and hands it to
+ *   your callback to render a second, faded layer, while the original stays put and commits on
+ *   `onDragEnd` (e.g. a selection's cut-move). No preview state to manage in the consumer.
+ *
+ * @remarks
+ * The grip is the whole rectangle ({@link DraggableProps.grip} = `entire`) by default, or just its
+ * border ring (`edges`). Drawn first so child handles (resize corners) layered above stay grabbable;
+ * `stopPropagation` keeps a layer beneath from also reacting.
+ */
+export declare const Draggable: React.FC<DraggableProps>;
+//# sourceMappingURL=Draggable.d.ts.map

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

@@ -0,0 +1,54 @@
+import { default as React } from 'react';
+import { RangeCoords } from '@sheetxl/utils';
+import { VisualSVGProps } from '../svg';
+import { DragHandleRenderProps } from './DragHandle';
+/**
+ * Props for {@link FillHandle}. Follows the shared **RangeHandle** contract: a controlled `range`
+ * (the fill template/source) in, the fill **destination** range out via `onDrag*`. The destination
+ * includes the template; the fill direction is `compare(range, destination)` if a consumer needs it.
+ * Extends {@link VisualSVGProps} (like {@link RangeRectProps} / {@link RangeResizerProps}) so the
+ * dashed preview's paint props — `stroke`, `strokeWidth`, … — are passed directly; the handle inherits
+ * {@link DEFAULT_HANDLE_STYLE} for whatever you don't set, and the handle color follows `stroke`.
+ */
+export interface FillHandleProps extends VisualSVGProps {
+    /**
+     * The template (source) range being filled from. Optional because `SelectionLayer` injects it when
+     * `enableFill` is set (or via a `singleLayer` slot); required in practice for standalone use.
+     */
+    range?: RangeCoords;
+    /** Drag started; `range` is the template. */
+    onDragStart?: (range: RangeCoords, e: React.PointerEvent) => void;
+    /**
+     * Adjust the raw destination before it drives the preview + `onDrag*` — e.g. snap the fill edge to a
+     * merged-cell boundary so the dashed preview and the committed fill agree (and never land on an
+     * illegal interval). Given the template and the pointer-derived destination, return the destination to
+     * use. Applied on every move; omit for no snapping.
+     */
+    snapDestination?: (template: RangeCoords, destination: RangeCoords) => RangeCoords;
+    /** Live during the drag: the in-progress destination range (incl. the template). */
+    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;
+    /**
+     * 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
+     * teardown that must run regardless — closing a preview tooltip, clearing a drag mode. Event-less on an
+     * Escape abort, hence the optional event.
+     */
+    onDragDone?: (e?: React.PointerEvent) => void;
+    /**
+     * Render the fill handle **element** yourself (headless) — forwarded to {@link DragHandle.renderHandle}.
+     * Replaces the default dot. Use it for a custom fill mark (e.g. the Excel fill square).
+     */
+    renderHandle?: (props: DragHandleRenderProps) => React.ReactNode;
+}
+/**
+ * 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
+ * and clamp into view) and freeze-pane de-duplication — plus the single-axis fill geometry and the
+ * dashed preview, reporting the destination range via the RangeHandle `onDrag*` callbacks. Selection
+ * extension + the actual data fill are the consumer's job (via `onDragEnd`) — this layer is
+ * selection-agnostic.
+ */
+export declare const FillHandle: React.FC<FillHandleProps>;
+//# sourceMappingURL=FillHandle.d.ts.map

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

@@ -0,0 +1,36 @@
+import { RangeCoords } from '@sheetxl/utils';
+import { VirtualDivProps } from '../layer';
+import { VisualSVGProps } from '../svg';
+/**
+ * Props for {@link RangeRect}: a thin range→bounds wrapper that places the {@link RectangleSVG}
+ * **shape** at a grid range — it resolves the range to bounds via the pane, culls off-screen,
+ * optionally cuts a `hole`, and forwards every visual prop straight through. The SVG sibling of
+ * {@link VirtualDiv} (which hosts HTML content at a range).
+ */
+export interface RangeRectProps extends Omit<VirtualDivProps, 'fill'>, Omit<VisualSVGProps, 'style'> {
+    /**
+     * The range to outline / fill. Resolved to absolute bounds via the current pane.
+     */
+    range: RangeCoords;
+    /**
+     * A range cut out of the FILL (evenodd hole) — e.g. the active cell in a selection. The range
+     * counterpart of {@link RectangleSVG}'s `hole` (which takes resolved bounds); `RangeRect` resolves
+     * it against the pane. The hole belongs to THIS range (the consumer decides which range gets it).
+     */
+    hole?: RangeCoords;
+    /**
+     * View-pixel slack for the off-screen cull. Defaults to half the stroke width. This is the one
+     * concern {@link RectangleSVG} can't express (it has no pane and does no culling).
+     */
+    clipInsets?: number;
+}
+/**
+ * Places one device-aligned {@link RectangleSVG} at a grid range. Resolves the range to bounds via
+ * the current pane, culls when off-screen, cuts an optional `hole`, and hands the raw bounds + all
+ * visual props to {@link RectangleSVG} (which snaps + paints). It knows about ranges and the pane;
+ * the painting/snapping is RectangleSVG's job. A pure decoration — composed from the two primitives
+ * (a view-sized, pointer-transparent {@link VirtualDiv} hosting the shape), shipped because it
+ * encodes non-obvious geometry.
+ */
+export declare const RangeRect: import('react').MemoExoticComponent<(props: RangeRectProps) => import("react").JSX.Element | null>;
+//# sourceMappingURL=RangeRect.d.ts.map

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

@@ -0,0 +1,68 @@
+import { RangeCoords } from '@sheetxl/utils';
+import { VisualSVGProps } from '../svg';
+import { HandleAnchor, DragHandleRenderProps } from './DragHandle';
+/** The four corner handles (chart series / formula precedent rectangles use these). */
+export declare const RESIZE_ANCHORS_4: readonly HandleAnchor[];
+/** Corners + edge midpoints. */
+export declare const RESIZE_ANCHORS_8: readonly HandleAnchor[];
+/**
+ * Props for {@link RangeResizer}. Follows the shared **RangeHandle** contract: a controlled
+ * `range` in, the resized range out via `onDrag*`. Extends {@link VisualSVGProps} (like
+ * {@link RangeRectProps}) so the outline's paint props — `stroke`, `fill`, `strokeWidth`,
+ * `animatedStroke`, `animatedTransition`, … — are passed directly; the handles inherit
+ * {@link DEFAULT_HANDLE_STYLE} for whatever you don't set. The grip color follows `stroke`.
+ */
+export interface RangeResizerProps extends VisualSVGProps {
+    /**
+     * The range being resized (controlled). Optional because `SelectionLayer` injects it when used as a
+     * `singleLayer` slot; required in practice for standalone use.
+     */
+    range?: RangeCoords;
+    /**
+     * Which handles to show. @defaultValue {@link RESIZE_ANCHORS_8}. Pass {@link RESIZE_ANCHORS_4} for
+     * corners-only (chart series / formula precedents).
+     */
+    anchors?: readonly HandleAnchor[];
+    /** Drag started; `range` is the original. */
+    onDragStart?: (range: RangeCoords, e: React.PointerEvent) => void;
+    /** Live during the drag: the in-progress resized range. */
+    onDragMove?: (range: RangeCoords, e: React.PointerEvent) => void;
+    /** Drag released: commit the resized range. */
+    onDragEnd?: (range: RangeCoords, e: React.PointerEvent) => void;
+    /**
+     * The resize was **aborted** — the user pressed Escape, or the OS cancelled the pointer. Fires INSTEAD
+     * of {@link RangeResizerProps.onDragEnd}. The local preview is cleared automatically; because a resize
+     * commits live via `onDragMove`, a consumer that mutates its model each move should restore the
+     * pre-drag range here (Windows-style abort). Event-less — an Escape abort has no pointer event.
+     */
+    onDragCancel?: () => void;
+    /**
+     * The pointer entered (`true`) or left (`false`) a resize grip — aggregated across all handles (only
+     * one is ever hovered at a time). Lets a consumer emphasize the outline while a corner is hovered (e.g.
+     * Excel thickening the border). Ignored for headless `renderHandle` consumers, which wire their own.
+     */
+    onHandleHoverChange?: (hovered: boolean) => void;
+    /** Handle size (px). @defaultValue 8 */
+    size?: number;
+    /**
+     * Render each corner/edge grip yourself (headless) — forwarded to {@link DragHandle}'s `renderHandle`
+     * per anchor (use `DragHandleRenderProps.anchor` to differentiate). Replaces the default grips.
+     */
+    renderHandle?: (props: DragHandleRenderProps) => React.ReactNode;
+    /** Keep the current focus across a handle drag (forwarded to {@link DragHandle.preserveFocus}). */
+    preserveFocus?: boolean;
+}
+/**
+ * A draggable, resizable rectangle: an outlined range with {@link DragHandle} grips on the requested
+ * corners/edges — the interaction used to re-scope a **chart series** or a **formula precedent**.
+ * Each grip is the same `DragHandle` primitive; this layer supplies the per-anchor edge-move
+ * semantics and the live preview, delegating the committed value to
+ * {@link RangeResizerProps.onDragEnd}.
+ *
+ * @remarks
+ * Controlled: render with the current `range` and update it from `onDragEnd`. Dragging an edge/corner
+ * past its opposite flips the rectangle (Excel-style), bottoming out at a 1x1 — at which point the
+ * grip you're holding has effectively become the opposite grip.
+ */
+export declare const RangeResizer: React.FC<RangeResizerProps>;
+//# sourceMappingURL=RangeResizer.d.ts.map

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

@@ -0,0 +1,8 @@
+import { VisualSVGProps } from '../svg';
+/**
+ * The flat outline (fill + border, no inner ring) for the resize/fill handle layers
+ * (`RangeResizer` / {@link FillHandle}), which draw ONE rectangle. Colors compose from the grid
+ * `accent` (same knob as selection); the literals are the fallbacks so a bare grid renders unchanged.
+ */
+export declare const DEFAULT_HANDLE_STYLE: VisualSVGProps;
+//# sourceMappingURL=RangeStyle.d.ts.map

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

@@ -0,0 +1,13 @@
+/**
+ * **Range** primitives: the pane-aware {@link RangeRect} (an SVG rectangle at a range) plus the
+ * controlled drag handles (move / resize / fill) and the generic {@link DragHandle}. The selection
+ * layer composes these; the drag handles in turn share `selection/`'s window-driven cell-drag engine
+ * (`useWindowDragCells`) for their gesture mechanics — capture, de-dup, edge auto-scroll, touch, cancel.
+ */
+export * from './RangeStyle';
+export * from './RangeRect';
+export * from './DragHandle';
+export * from './Draggable';
+export * from './RangeResizer';
+export * from './FillHandle';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,59 @@
+import { Direction, RangeAxis, CellCoords, RangeCoords, SelectionCoords } from '@sheetxl/utils';
+import { ISelection } from './ISelection';
+/**
+ * Options for {@link SelectionConstructionOptions}.
+ */
+export interface SelectionConstructionOptions {
+    /** Initial selection. Defaults to a single active cell at `0,0`. */
+    initial?: SelectionCoords;
+    /**
+     * Bounds used to clamp {@link DefaultSelection.navigate}. The dumb tier's stand-in for the sheet's
+     * entire range. Defaults to non-negative / unbounded.
+     */
+    getBounds?: () => RangeCoords;
+}
+/**
+ * The default in-memory {@link ISelection} for examples and the basic grid. Its {@link ICellAnchor}
+ * anchor is `selection.cell`, so a single instance drives both the selection layer (as `ISelection`)
+ * and the editor (as the read-only anchor). The real app adapts an sdk `IRangeSelection` to
+ * {@link ISelection} instead.
+ *
+ * @remarks
+ * Dumb on purpose: it has no merge / hidden awareness; navigation just steps one cell, clamped to
+ * the {@link SelectionConstructionOptions.getBounds} port. Smart navigation lives in the sdk model.
+ * Methods are plain (unbound) — consumers read it via `useBoundSyncExternalStore`, which calls
+ * `subscribe`/the snapshot selector on the instance, so no per-method binding is needed.
+ */
+export declare class DefaultSelection implements ISelection {
+    private _coords;
+    private readonly _getBounds;
+    private readonly listeners;
+    constructor(options?: SelectionConstructionOptions);
+    /** @inheritdoc ISelection.getSelection */
+    getSelection(): SelectionCoords;
+    /** @inheritdoc ISelection.setSelection */
+    setSelection(next: SelectionCoords): void;
+    /** @inheritdoc ISelection.navigate */
+    navigate(direction: Direction, select?: boolean, contentful?: boolean, increment?: number): void;
+    /** @inheritdoc ISelection.traverse */
+    traverse(axis?: RangeAxis, reverse?: boolean, region?: RangeCoords): void;
+    /**
+     * The index of the active range, or `-1` when there are no ranges. A `rangeIndex < 0` (or out of
+     * bounds) WITH ranges resolves to the LAST range — the same convention `SelectionLayer` renders with,
+     * so `modify` and the visuals agree on which range is "active" in that (anomalous) state.
+     */
+    private _activeIndex;
+    /** The active range (see {@link _activeIndex}), or the anchor as a 1x1 range when nothing is selected. */
+    private _activeRange;
+    /** @inheritdoc ISelection.modify */
+    modify(cell: Partial<CellCoords>, pivot?: Partial<CellCoords>): void;
+    /** @inheritdoc ISelection.append */
+    append(start: CellCoords, end?: CellCoords): void;
+    /** @inheritdoc ISelection.deselect */
+    deselect(rangeToRemove: RangeCoords): void;
+    /** @inheritdoc ICellAnchor.getCoords */
+    getCoords(): CellCoords;
+    /** @inheritdoc ICellAnchor.subscribe */
+    subscribe(listener: () => void): (() => void);
+}
+//# sourceMappingURL=DefaultSelection.d.ts.map

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

@@ -0,0 +1,21 @@
+import { CellCoords } from '@sheetxl/utils';
+/**
+ * An **observable thing located at a cell** — the read+observe anchor the editor follows.
+ *
+ * @remarks
+ * The base of the anchor hierarchy and the decoupling seam between selection and the editor. A
+ * consumer given an `ICellAnchor` can read the cell (`getCoords`) and be notified when it changes
+ * (`subscribe`), but **cannot move it** — there is no setter, so navigation stays with the selection.
+ *
+ * Two kinds of thing satisfy it: the selection's **moving** active cell ({@link ISelection} extends
+ * this, so a single instance drives both the selection layer and the editor), and a **fixed-cell**
+ * thing whose `coords` never move (an `EditSession`, observable on its edit state). The editor reads
+ * its anchor through this view (`getCoords`/`subscribe`) and never navigates.
+ */
+export interface ICellAnchor {
+    /** The cell this thing is located at. Safe in event handlers (always current, never stale). */
+    getCoords(): CellCoords;
+    /** Subscribe to changes. Returns an unsubscribe. */
+    subscribe(listener: () => void): () => void;
+}
+//# sourceMappingURL=ICellAnchor.d.ts.map

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

@@ -0,0 +1,65 @@
+import { CellCoords, Direction, RangeAxis, RangeCoords, SelectionCoords } from '@sheetxl/utils';
+import { ICellAnchor } from './ICellAnchor';
+/**
+ * An **observable store** of a full {@link SelectionCoords} — the active cell plus the selected
+ * ranges and the active range index. The SelectionCoords-level extension of {@link ICellAnchor},
+ * whose anchor is the active cell.
+ *
+ * @remarks
+ * This is the single source of truth the selection layer renders and the pointer controller writes.
+ * It exposes the minimal mutation surface the layer needs — a raw {@link ISelection.setSelection}
+ * write plus {@link ISelection.navigate} (the one logical-move intent).
+ *
+ * Extends {@link ICellAnchor}: the active cell ({@link SelectionCoords.cell}) is the anchor and
+ * `subscribe` notifies on any change, so a single instance drives both the selection layer (as
+ * `ISelection`) and the editor (as the read-only {@link ICellAnchor}).
+ *
+ * `getSelection` MUST return a stable reference while unchanged.
+ */
+export interface ISelection extends ICellAnchor {
+    /** The current selection. Stable ref while unchanged. Safe in event handlers (never stale). */
+    getSelection(): SelectionCoords;
+    /** Replace the selection. No-op if logically equal to the current value. */
+    setSelection(next: SelectionCoords): void;
+    /**
+     * Move the active cell in `direction`. With `select`, extend the active range instead of moving
+     * (the anchor stays fixed). `contentful` jumps to the next data edge (Ctrl+Arrow); `increment`
+     * moves that many cells at once (the page step — the caller passes a view-derived amount).
+     * Implementation-defined intelligence (bounds, merges, hidden, contentful) — dumb in
+     * {@link DefaultSelection}, sheet-backed in the sdk adapter (mirrors the sdk
+     * `IRangeSelection.navigate(direction, select?, contentful?, incrementAmount?)`).
+     */
+    navigate(direction: Direction, select?: boolean, contentful?: boolean, increment?: number): void;
+    /**
+     * Cycle the **active cell** to the next cell *within the current selection* — the Tab/Enter
+     * traversal. Unlike {@link ISelection.navigate} it never changes which ranges are selected (it only
+     * moves the active cell, and the active range index): it wraps at a range edge, visits each cell
+     * once, and jumps to the next range when stepping off the last corner. On a single cell (no range)
+     * it falls back to a one-cell move — unless a `region` is supplied, in which case a bare cursor
+     * **wraps within that region** (a table's data range) instead of moving off it. `Row` axis ⇒ Tab
+     * (→, reverse = ←); `Column` axis ⇒ Enter (↓, reverse = ↑). Implementation-defined intelligence
+     * (merges, hidden) — dumb in {@link DefaultSelection}, sheet-backed in the sdk adapter.
+     */
+    traverse(axis?: RangeAxis, reverse?: boolean, region?: RangeCoords): void;
+    /**
+     * Replace the active range with the box spanning `pivot`..`cell`. `pivot` defaults to the current
+     * anchor — so a drag or Shift+click passes only `cell`. Partial coords fall back to the active
+     * range's bounds (modifying only a row extends rows while keeping columns). The anchor is kept,
+     * unless the new range no longer contains it (an explicit off-anchor `pivot`, e.g. a touch grip on
+     * the opposite corner, can drag the range off the anchor) — then it snaps to the nearest corner so
+     * the anchor always lies within the active range.
+     */
+    modify(cell: Partial<CellCoords>, pivot?: Partial<CellCoords>): void;
+    /**
+     * Add a new range spanning `start`..`end` to the selection (the Ctrl/Cmd-click gesture). If there
+     * were no ranges, one is first seeded from the current anchor. The appended range becomes active
+     * and its start becomes the anchor.
+     */
+    append(start: CellCoords, end?: CellCoords): void;
+    /**
+     * Remove `range` from the selection, splitting any intersecting range around it (the
+     * Ctrl/Cmd-click-on-selected gesture). The active cell/range is preserved where possible.
+     */
+    deselect(range: RangeCoords): void;
+}
+//# sourceMappingURL=ISelection.d.ts.map