@sheetxl/grid-react 0.7.22 → 0.7.23-beta.2

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/FillHandle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FillHandle.d.ts","sourceRoot":"","sources":["../../../../src/range/FillHandle.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAA+C,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAG/F,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,QAAQ,CAAC;AAG7C,OAAO,EAAc,KAAK,qBAAqB,EAAqB,MAAM,cAAc,CAAC;AAGzF;;;;;;;GAOG;AACH,MAAM,WAAW,eAAgB,SAAQ,cAAc;IACrD;;;OAGG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAClE;;;;;OAKG;IACH,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,WAAW,KAAK,WAAW,CAAC;IACnF,oFAAoF;IACpF,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IACjE,iGAAiG;IACjG,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAChE;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAC9C;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,KAAK,CAAC,SAAS,CAAC;CAClE;AA2DD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CA4FhD,CAAC"}

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/RangeRect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RangeRect.d.ts","sourceRoot":"","sources":["../../../../src/range/RangeRect.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAe,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAI/D,OAAO,EAAc,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAC5D,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,QAAQ,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,cAAc,EAAE,OAAO,CAAC;IAClG;;OAEG;IACH,KAAK,EAAE,WAAW,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,WAAW,CAAC;IACnB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,8CAAgB,cAAc,wCAyFlD,CAAC"}

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/RangeResizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RangeResizer.d.ts","sourceRoot":"","sources":["../../../../src/range/RangeResizer.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,QAAQ,CAAC;AAO7C,OAAO,EAAc,KAAK,YAAY,EAAE,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAGzF,uFAAuF;AACvF,eAAO,MAAM,gBAAgB,EAAE,SAAS,YAAY,EAA6B,CAAC;AAClF,gCAAgC;AAChC,eAAO,MAAM,gBAAgB,EAAE,SAAS,YAAY,EAAiD,CAAC;AAEtG;;;;;;GAMG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD;;;OAGG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,6CAA6C;IAC7C,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAClE,2DAA2D;IAC3D,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IACjE,+CAA+C;IAC/C,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAChE;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IACjD,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,KAAK,CAAC,SAAS,CAAC;IACjE,mGAAmG;IACnG,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,YAAY,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CA8EpD,CAAC"}

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/RangeStyle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RangeStyle.d.ts","sourceRoot":"","sources":["../../../../src/range/RangeStyle.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,QAAQ,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,cAIlC,CAAC"}

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/range/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/range/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC;AAC5B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC"}

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/DefaultSelection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DefaultSelection.d.ts","sourceRoot":"","sources":["../../../../src/selection/DefaultSelection.ts"],"names":[],"mappings":"AAAA,OAAO,EACoB,SAAS,EAAE,SAAS,EAC7C,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EACxD,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAI/C;;GAEG;AACH,MAAM,WAAW,4BAA4B;IAC3C,oEAAoE;IACpE,OAAO,CAAC,EAAE,eAAe,CAAC;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,WAAW,CAAC;CAC/B;AAiBD;;;;;;;;;;;GAWG;AACH,qBAAa,gBAAiB,YAAW,UAAU;IACjD,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;gBAEvC,OAAO,GAAE,4BAAiC;IAOtD,0CAA0C;IAC1C,YAAY,IAAI,eAAe;IAI/B,0CAA0C;IAC1C,YAAY,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI;IAMzC,sCAAsC;IACtC,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,GAAE,OAAe,EAAE,UAAU,GAAE,OAAe,EAAE,SAAS,GAAE,MAAU,GAAG,IAAI;IA+BjH,sCAAsC;IACtC,QAAQ,CAAC,IAAI,GAAE,SAAyB,EAAE,OAAO,GAAE,OAAe,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI;IA2B/F;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAQpB,0GAA0G;IAC1G,OAAO,CAAC,YAAY;IAKpB,oCAAoC;IACpC,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,EAAE,KAAK,GAAE,OAAO,CAAC,UAAU,CAAqB,GAAG,IAAI;IAuBvF,oCAAoC;IACpC,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,GAAE,UAAkB,GAAG,IAAI;IAmBxD,sCAAsC;IACtC,QAAQ,CAAC,aAAa,EAAE,WAAW,GAAG,IAAI;IAsD1C,wCAAwC;IACxC,SAAS,IAAI,UAAU;IAIvB,wCAAwC;IACxC,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC;CAI9C"}

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/ICellAnchor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ICellAnchor.d.ts","sourceRoot":"","sources":["../../../../src/selection/ICellAnchor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,WAAW;IAC1B,+FAA+F;IAC/F,SAAS,IAAI,UAAU,CAAC;IACxB,oDAAoD;IACpD,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC7C"}

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"ISelection.d.ts","sourceRoot":"","sources":["../../../../src/selection/ISelection.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,UAAU,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,eAAe,EACxF,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,UAAW,SAAQ,WAAW;IAC7C,+FAA+F;IAC/F,YAAY,IAAI,eAAe,CAAC;IAChC,4EAA4E;IAC5E,YAAY,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,CAAC;IAC1C;;;;;;;OAOG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjG;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;IAC1E;;;;;;;OAOG;IACH,MAAM,CAAC,IAAI,EAAE,OAAO,CAAC,UAAU,CAAC,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;IACrE;;;;OAIG;IACH,MAAM,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAClD;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;CACpC"}

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

@@ -0,0 +1,128 @@
+import { default as React } from 'react';
+import { VisualSVGProps } from '../svg';
+import { HandleAnchor, DragHandleRenderProps } from '../range';
+import { LayerProps } from '../layer';
+import { ISelection } from './ISelection';
+/**
+ * The range-reference palette, in rotation order. The default {@link RangesPickerLayer} look cycles `stroke`
+ * through this so each range gets its own color — `PICKER_COLORS[i % length]` — and the fill is derived
+ * automatically (a low-alpha tint of the same color).
+ *
+ * These are the shared `--sxl-color-series-*` theme tokens (the SAME hues the formula editor colors reference
+ * text with, so a range's text and its rectangle match), so they follow light/dark automatically. The literal
+ * fallback keeps a bare (un-themed) grid — storybook / SDK-free reference use — colored.
+ */
+export declare const PICKER_COLORS: readonly string[];
+/**
+ * Props for {@link RangesPickerLayer}. It **renders a {@link Layer}** at its root (extends
+ * {@link LayerProps}: `zIndex`, tap handlers), so a consumer stacks it like any layer. The shared
+ * base outline look for every range is {@link RangesPickerLayerProps.rangeStyle}, with
+ * {@link RangesPickerLayerProps.getRangeStyle} overriding per range (default: cycle `stroke`
+ * through the {@link PICKER_COLORS}).
+ */
+export interface RangesPickerLayerProps extends LayerProps {
+    /** Shared base outline look for every range (`stroke`, `strokeWidth`, …), merged UNDER `getRangeStyle`. */
+    rangeStyle?: VisualSVGProps;
+    /**
+     * The selection model this layer renders + edits (like {@link SelectionLayer}, and typically a
+     * `SheetSelection` over an sdk `IRangeSelection.createSelection()`). It reads the model's
+     * {@link SelectionCoords} — one resizable + movable rectangle per range, the `rangeIndex` range
+     * **active** — and writes every move / resize / draw back through `setSelection`, setting
+     * `rangeIndex` to the edited range so a text-backed model can rewrite exactly that reference.
+     *
+     * @remarks
+     * Unlike {@link SelectionLayer} it renders *only ranges* (never an anchor cell — Excel doesn't draw
+     * the formula's home). A gesture over an empty picker (or a click while the caret isn't on a reference)
+     * APPENDS a new range, so it doubles as the "insert a new reference" surface.
+     */
+    selection: ISelection;
+    /**
+     * Per-range outline props, merged over the layer's shared base ({@link VisualSVGProps}). Receives the
+     * range `index` and whether it's `active`. Defaults to cycling `stroke` through {@link PICKER_COLORS}
+     * (`PICKER_COLORS[index % length]`). The layer still derives the fill (a low-alpha tint of `stroke`
+     * unless you set `fill`), the active animation, and the hover/drag emphasis on top of what you return.
+     *
+     * Return `null` to OMIT that range from this layer entirely — no outline, no resize/move handles, not
+     * interactive. The model (`selection`) is untouched; this is a per-INSTANCE render filter, not a data
+     * filter. Lets a consumer share one multi-range model across several layers and have each show only
+     * the subset relevant to it (e.g. a formula's references split across per-sheet panes) with no index
+     * remapping — writes still go back through `selection.setSelection` at the range's real, unfiltered
+     * index, since the model itself was never filtered.
+     */
+    getRangeStyle?: (index: number, active: boolean) => VisualSVGProps | null;
+    /**
+     * Which resize handles to show. @defaultValue {@link RESIZE_ANCHORS_4} (corners). Pass
+     * {@link RESIZE_ANCHORS_8} for corners + edge midpoints.
+     */
+    anchors?: readonly HandleAnchor[];
+    /** Enable the move grip (drag the border to relocate a range, keeping its size). @defaultValue false */
+    enabledMove?: boolean;
+    /**
+     * Don't claim the grid-wide **draw** gesture — the pointer-drag over empty grid that re-scopes the
+     * **active** range from scratch. Ranges stay movable/resizable via their border + corners.
+     * @defaultValue false
+     */
+    disableDraw?: boolean;
+    /**
+     * Allow Ctrl/Cmd+click (and drag) on the draw surface to **append** a brand-new range even while a
+     * range is active — the multi-range pick gesture (Excel point mode's Ctrl+click; a text-backed
+     * consumer renders the appended range after a `,` separator). Set `false` for a picker whose value
+     * is a single rectangle (a chart series / table range field): the modifier is then ignored and the
+     * gesture is a plain draw. There is deliberately no Ctrl+click *deselect* counterpart (unlike the
+     * body selection's `useSelectionPointer`) — Excel does not remove a reference by clicking it.
+     *
+     * @defaultValue true
+     */
+    allowMulti?: boolean;
+    /** Resize handle size (px). @defaultValue 8 */
+    size?: number;
+    /**
+     * Animate the **active** range's outline with a marching-ants stroke (the others stay static).
+     *
+     * @defaultValue false
+     */
+    animated?: boolean;
+    /**
+     * Render the resize corner grips yourself (headless) — forwarded to {@link RangeResizer}'s
+     * `renderHandle` per anchor. Replaces the default grips.
+     */
+    renderHandle?: (props: DragHandleRenderProps) => React.ReactNode;
+    /**
+     * Keep whatever had focus across a drag (draw / move / resize) rather than letting the gesture move
+     * focus to the grid's `tabIndex` Stage. The picker is used *while editing a formula*, so a handle drag
+     * must not blur the editor's textarea — it preserves the existing focus (nothing to restore). Turn off
+     * only for a picker used outside an editor. @defaultValue true
+     */
+    preserveFocus?: boolean;
+    /**
+     * Called when a rectangle gesture (draw / move / resize) starts (`true`) and ends (`false`) — one
+     * aggregated signal across all of them. Lets a host react to "a reference drag is in progress" as a whole,
+     * e.g. the formula editor hiding its hint popup for the duration. `index` is the range being moved/resized
+     * (so a host can highlight exactly that reference), or `null` for a DRAW (no existing range yet) / idle.
+     */
+    onDragActiveChange?: (active: boolean, index: number | null) => void;
+}
+/**
+ * The default per-range look: cycle the stroke through {@link PICKER_COLORS}. Exported so a consumer
+ * wrapping {@link RangesPickerLayerProps.getRangeStyle} (e.g. to add a per-instance visibility filter —
+ * see that prop's doc) can fall back to it instead of reimplementing the color cycle.
+ */
+export declare const defaultRangeStyle: (index: number) => VisualSVGProps;
+/**
+ * A **multi-rectangle** range picker — each rectangle resizable + movable — used to re-scope a set of
+ * **formula references** or a **chart's data ranges**. Like {@link SelectionLayer} it binds to an
+ * {@link ISelection} model, but it renders *only ranges* (never an anchor cell — Excel doesn't draw the
+ * formula's home).
+ *
+ * @remarks
+ * Each range is a {@link RangeResizer} (outline + corners) wrapped in a {@link Draggable}
+ * (border-ring move), colored from {@link RangesPickerLayerProps.getRangeStyle} (default: cycle
+ * {@link PICKER_COLORS}). The model's `rangeIndex` range is **active** — the grid draw re-scopes it and it
+ * animates; interacting with a range makes it active. Every gesture writes back through
+ * `selection.setSelection`, setting `rangeIndex` to the edited range. A draw while the caret isn't on a
+ * reference (`rangeIndex < 0`) APPENDS a new range instead (insert / draw-from-empty). Shift+draw
+ * EXTENDS the active range from its start corner; Ctrl/Cmd+draw appends a new range even while one is
+ * active (gated by {@link RangesPickerLayerProps.allowMulti}).
+ */
+export declare const RangesPickerLayer: React.FC<RangesPickerLayerProps>;
+//# sourceMappingURL=RangesPickerLayer.d.ts.map

package/types/src/selection/RangesPickerLayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RangesPickerLayer.d.ts","sourceRoot":"","sources":["../../../../src/selection/RangesPickerLayer.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAU/B,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,QAAQ,CAAC;AAC7C,OAAO,EACsC,KAAK,YAAY,EAAE,KAAK,qBAAqB,EACzF,MAAM,UAAU,CAAC;AAClB,OAAO,EAAqB,KAAK,UAAU,EAAE,MAAM,UAAU,CAAC;AAE9D,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAkB/C;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAG1C,CAAC;AAKF;;;;;;GAMG;AACH,MAAM,WAAW,sBAAuB,SAAQ,UAAU;IACxD,2GAA2G;IAC3G,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,SAAS,EAAE,UAAU,CAAC;IACtB;;;;;;;;;;;;OAYG;IACH,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,cAAc,GAAG,IAAI,CAAC;IAC1E;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAClC,wGAAwG;IACxG,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,KAAK,CAAC,SAAS,CAAC;IACjE;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;OAKG;IACH,kBAAkB,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;CACtE;AAUD;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,cAEhD,CAAC;AAEH;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,iBAAiB,EAAE,KAAK,CAAC,EAAE,CAAC,sBAAsB,CAyM9D,CAAC"}