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

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

@@ -0,0 +1,218 @@
+import { CellCoords } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+/**
+ * Repeat interval (ms) for the held-still auto-scroll. While a drag is parked past the viewport edge no
+ * pointer-move events fire, so the engine re-applies the drag at the last pointer position on this
+ * cadence; each tick scrolls one cell, which shifts the cell under the (fixed) point, continuing the drag.
+ */
+export declare const AUTO_SCROLL_INTERVAL_MS = 60;
+/**
+ * How close (client px) the pointer must get to a pane edge — on the INSIDE of the viewport, or past it —
+ * to engage the auto-scroll. Edge detection is by pointer POSITION, not by the resolved cell, because a
+ * TOUCH drag can never resolve a cell past the last visible one: a finger is pinned to the physical grid
+ * edge and can't roam into the empty space beyond the content the way a mouse cursor can. This band is
+ * sized so a fingertip at the edge falls inside it.
+ */
+export declare const EDGE_AUTO_SCROLL_MARGIN_PX = 24;
+/**
+ * The default {@link DragCellsSession.edgeScroll} for a body / picker drag: step the pane's viewport ONE
+ * cell toward whichever edge(s) the pointer sits within {@link EDGE_AUTO_SCROLL_MARGIN_PX} of (or past),
+ * on both axes. Returns whether an edge is still scrollable — so the held-still auto-scroll keeps ticking.
+ *
+ * @remarks
+ * Position/direction-based rather than "scroll the dragged cell into view": the latter only advances when
+ * the resolved cell is off-screen (reachable by a mouse roaming past the content, never by a finger). A
+ * fixed one-cell step per tick advances the viewport regardless, and the engine then extends to the cell
+ * newly revealed under the pointer. The step routes through the CENTER pane (a frozen pane can't move its
+ * frozen axis).
+ *
+ * @param axes restricts which axes may scroll — a whole-row/column touch grip extends only one axis, so
+ *   it passes e.g. `{ x: true, y: false }`. Omitted axes default to enabled (both).
+ */
+export declare const edgeScrollPane: (pane: IGridPane, point: {
+    x: number;
+    y: number;
+}, axes?: {
+    x?: boolean;
+    y?: boolean;
+}) => boolean;
+/**
+ * The in-flight gesture returned by {@link DragCellsOptions.onStart}. It carries the *policy* — how a
+ * given cell-drag mutates the model — while the engine owns the *mechanics* (pointer capture, `lastCell`
+ * de-dup, the held-still auto-scroll timer, and the public `dragMode` signal).
+ *
+ * @remarks
+ * `onStart` has already SEEDED the model for the down cell (and taken ownership of the down event —
+ * `stopPropagation` / `preventDefault` per its own policy); the session's callbacks then drive the drag:
+ * `drag` on each new cell, `edgeScroll` for the held-still edge auto-scroll, `end` on release, `cancel`
+ * on an OS-cancelled abort.
+ */
+export interface DragCellsSession {
+    /**
+     * Apply the in-flight update for a newly-entered `cell` — called once per DISTINCT cell during the
+     * drag (the engine de-dups moves within the same cell). Not called for the down cell (already seeded).
+     * `e` is the triggering pointer event when the move came from a real pointer (read live modifiers off
+     * it — e.g. a move-drag's Ctrl=copy / Shift=insert); it is ABSENT on a held-still auto-scroll tick
+     * (no pointer event fires while the pointer is parked past the edge), so treat it as optional.
+     */
+    drag: (cell: CellCoords, e?: React.PointerEvent) => void;
+    /**
+     * The auto-scroll step: given the pointer's client `point`, scroll the viewport ONE cell toward any edge
+     * the pointer is at (see {@link edgeScrollPane}), and return whether an edge is still engaged so the
+     * held-still timer keeps ticking. Called every tick (not gated on a distinct cell) — the drag EXTEND is
+     * separate (the engine's per-cell `drag`), so the two concerns don't fight: this steps the viewport, and
+     * the engine then extends to the cell newly under the pointer.
+     *
+     * Position/direction-based on purpose — a cell-based "is the dragged cell off-screen?" test can't fire
+     * on TOUCH (a finger can't leave the content). The header supplies a single-axis, sheet-routed version
+     * (its controlled viewport can't scroll itself); a body / picker drag uses the default.
+     * @defaultValue {@link edgeScrollPane} of the engine's pane (both axes).
+     */
+    edgeScroll?: (point: {
+        x: number;
+        y: number;
+    }) => boolean;
+    /** Finalize on pointer-up (e.g. a remove-drag's `deselect`, an `onSelectionEnd`, a refocus). */
+    end?: (e: React.PointerEvent) => void;
+    /**
+     * Abort cleanup for a CANCELLED gesture — the OS/browser seized the pointer (`pointercancel`: a touch
+     * became a system pan/zoom, a pen left range, a window blurred), OR the user pressed **Escape**
+     * (Windows-style drag abort). The engine always runs the mechanical teardown (stop the auto-scroll
+     * timer, disarm the touch swallow, release capture); this hook is for the policy's own rollback —
+     * restore the pre-drag selection, clear a rubber-band / preview — WITHOUT committing, since a cancel is
+     * an abort, not a release. {@link DragCellsSession.end} never runs on a cancel. The event is absent on
+     * an Escape abort (no pointer event drives it).
+     */
+    cancel?: (e?: React.PointerEvent) => void;
+    /**
+     * Take pointer capture and track the drag. `false` = a click-only gesture (e.g. a header right-click
+     * that positions the selection for the context menu): no capture, moves are ignored, but {@link end}
+     * still runs on the next pointer-up. @defaultValue true
+     */
+    capture?: boolean;
+    /**
+     * `stopPropagation` the move / up events while this drag is in flight, so a layer below never also acts
+     * on them. The down event is owned by `onStart` itself. @defaultValue true
+     */
+    captureEvents?: boolean;
+    /**
+     * A public label for the gesture, surfaced as {@link DragCellsResult.dragMode} between down and up (a
+     * layer shows a transient tip — e.g. live R×C — off it). Flips only on start / end, not per move.
+     */
+    dragMode?: string;
+}
+/**
+ * Options for {@link useDragCells} / {@link createDragCells}.
+ */
+export interface DragCellsOptions {
+    /**
+     * Begin a gesture at the `cell` under the pointer. SEED the model, take ownership of the down event
+     * (`stopPropagation` / `preventDefault` as the policy needs), and return a {@link DragCellsSession} to
+     * drive the drag — or `null` to not start one (a non-primary button, an intercepted right-click, …).
+     * The engine captures the pointer only for a returned session (unless {@link DragCellsSession.capture}
+     * is `false`).
+     */
+    onStart: (cell: CellCoords, e: React.PointerEvent) => DragCellsSession | null;
+}
+/** The spreadable handlers + the public `dragMode`, produced by {@link useDragCells}. */
+export interface DragCellsResult {
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerMove: (e: React.PointerEvent) => void;
+    onPointerUp: (e: React.PointerEvent) => void;
+    /**
+     * Abort the in-flight drag. Wire it onto the tap only if the host routes `pointercancel` — the engine
+     * ALSO listens natively on the captured element (a `pointercancel` fires there whether or not the host
+     * dispatches it), so this is a safe idempotent extra, not a requirement.
+     */
+    onPointerCancel: (e: React.PointerEvent) => void;
+    /**
+     * What the in-flight drag is doing — the active session's {@link DragCellsSession.dragMode}, or `null`
+     * between drags. Flips only on down / up so a layer can show a transient tip without re-rendering on
+     * every pointer move.
+     */
+    dragMode: string | null;
+}
+/** The headless controller behind {@link useDragCells}. */
+export interface DragCellsController {
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerMove: (e: React.PointerEvent) => void;
+    onPointerUp: (e: React.PointerEvent) => void;
+    /** Abort the in-flight drag (see {@link DragCellsResult.onPointerCancel}). */
+    onPointerCancel: (e: React.PointerEvent) => void;
+    /** Stop the auto-scroll timer + disarm touch. Call on unmount (the hook wires this). */
+    dispose: () => void;
+}
+/**
+ * The **shared cell-drag engine** — the axis-agnostic mechanics every pointer selection needs: pointer
+ * capture, per-cell de-dup, the held-still auto-scroll timer, and the public `dragMode` signal. It holds
+ * NO range math: an {@link DragCellsOptions.onStart} adapter supplies the policy as a
+ * {@link DragCellsSession}. Used by the body selection, the header selection, and the range picker's draw
+ * — each a thin adapter over this one engine (so all three get identical auto-scroll for free).
+ *
+ * @remarks
+ * This is the **tap driver**: the consumer spreads `onPointerDown` / `onPointerMove` / `onPointerUp`
+ * (and, if the host routes it, `onPointerCancel`) onto a Stage tap; the engine captures the pointer on
+ * that tap's element so move / up keep firing when the drag leaves the viewport. The handle / grip
+ * flavors, whose element repositions or unmounts mid-drag, use {@link createWindowDragCells} instead —
+ * same session, `window`-tracked.
+ *
+ * A plain (non-hook) factory so a headless controller (e.g. the header's `createHeaderSelectionPointer`,
+ * unit-tested with a fake pane) can build on it directly. The React hook is {@link useDragCells}.
+ * `onStart` is captured at creation; a caller that needs live values reads them through a ref inside its
+ * `onStart` closure (as the hook does).
+ *
+ * @param onDragModeChange Notified when the active session's `dragMode` changes (a hook turns this into
+ *   React state); omit for a headless controller that doesn't surface it.
+ */
+export declare const createDragCells: (pane: IGridPane, onStart: (cell: CellCoords, e: React.PointerEvent) => DragCellsSession | null, onDragModeChange?: (mode: string | null) => void) => DragCellsController;
+/** The headless controller behind {@link useWindowDragCells}. */
+export interface WindowDragCellsController {
+    /**
+     * Begin a `window`-driven gesture from a pointer-down on the source element. `cursorEl` is captured
+     * (pointer-capture) purely so the browser paints ITS cursor for the whole drag — the gesture tracks on
+     * `window` regardless, surviving the element repositioning / unmounting. Defaults to `e.currentTarget`.
+     */
+    start: (e: React.PointerEvent, cursorEl?: Element | null) => void;
+    /** Stop any in-flight gesture (drop the `window` listeners + timer + touch swallow). Call on unmount. */
+    dispose: () => void;
+}
+/**
+ * The **window-driven** cell-drag engine — same {@link DragCellsSession} policy and shared mechanics as
+ * {@link createDragCells}, but the gesture tracks on `window` listeners instead of a Stage tap's element
+ * capture. Use it when the element that starts the drag repositions or unmounts mid-gesture: a fill /
+ * resize handle culled under an edge auto-scroll, a move grip whose source range scrolls off in ghost
+ * mode. Element capture on such an element would silently drop the drag; `window` tracking is immune.
+ *
+ * @remarks
+ * The source element is still pointer-captured (for its CURSOR only — see {@link WindowDragCellsController.start});
+ * the actual move / up / cancel are `window` listeners, so a re-render or unmount of the handle never
+ * interrupts the gesture. Consumers supply `onStart` policy exactly as for the tap engine, and get the
+ * same held-still auto-scroll, touch arming, per-cell de-dup, and abort-on-cancel.
+ */
+export declare function createWindowDragCells(pane: IGridPane, onStart: (cell: CellCoords, e: React.PointerEvent) => DragCellsSession | null, onDragModeChange?: (mode: string | null) => void, 
+/** Override cell resolution (a touch grip resolves against the pane the finger is over). */
+resolveCell?: (clientX: number, clientY: number) => CellCoords | null): WindowDragCellsController;
+/**
+ * The React hook over {@link createDragCells}: reads the pane from context, owns the `dragMode` state,
+ * and stops the auto-scroll timer on unmount. `onStart` is read live through a ref, so a consumer's
+ * closure over changing values (selection, options) needs no handler rebuild.
+ */
+export declare const useDragCells: (onStart: (cell: CellCoords, e: React.PointerEvent) => DragCellsSession | null) => DragCellsResult;
+/** Handlers + transient `dragMode` produced by {@link useWindowDragCells}. */
+export interface WindowDragCellsResult {
+    /**
+     * Begin a window-driven gesture. Spread as the source element's `onPointerDown`. Pass a `cursorEl` (the
+     * element whose cursor should paint for the drag) when the pointer-down may be dispatched with a
+     * `currentTarget` other than that element (e.g. a grip below an interactive child).
+     */
+    start: (e: React.PointerEvent, cursorEl?: Element | null) => void;
+    /** The active session's `dragMode`, or `null` between drags (flips only on start / end). */
+    dragMode: string | null;
+}
+/**
+ * The React hook over {@link createWindowDragCells}: reads the pane from context, owns the `dragMode`
+ * state, and disposes the gesture on unmount. For handle / grip flavors (fill, resize, move, touch grips)
+ * whose element repositions or unmounts mid-drag. `onStart` is read live through a ref.
+ */
+export declare const useWindowDragCells: (onStart: (cell: CellCoords, e: React.PointerEvent) => DragCellsSession | null) => WindowDragCellsResult;
+//# sourceMappingURL=useDragCells.d.ts.map

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

@@ -0,0 +1,70 @@
+import { RangeCoords } from '@sheetxl/utils';
+import { ISelection } from './ISelection';
+/**
+ * Options for {@link useSelectionPointer}.
+ */
+export interface SelectionPointerOptions {
+    /**
+     * Allow Ctrl/Cmd-dragging over an already-selected area to remove it.
+     *
+     * @defaultValue true
+     */
+    allowDeselect?: boolean;
+    /**
+     * Allow Ctrl/Cmd to append (and, with {@link SelectionPointerOptions.allowDeselect}, remove)
+     * additional ranges. When `false` the selection is held to a **single range** (the modifier is
+     * treated as a plain replace) — for single-rectangle range pickers like precedents / chart data
+     * ranges, where multi-range selection is meaningless.
+     *
+     * @defaultValue true
+     */
+    allowMulti?: boolean;
+    /**
+     * Fired when a selection pointer interaction **ends** (pointer-up after a click or drag on the grid).
+     * A consumer uses it for "act on the range the user just selected" — e.g. the format painter applies
+     * the copied format to the just-selected destination. Command-free; view-side only.
+     */
+    onSelectionEnd?: (e: React.PointerEvent) => void;
+}
+/**
+ * Handlers + transient drag state produced by {@link useSelectionPointer}, to spread onto an
+ * a `Layer` tap.
+ */
+export interface SelectionPointerResult {
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerMove: (e: React.PointerEvent) => void;
+    onPointerUp: (e: React.PointerEvent) => void;
+    /**
+     * The rubber-band rectangle to render while a Ctrl/Cmd remove-drag is in progress, else `null`.
+     * The layer renders this; the actual removal is applied to the model on pointer-up.
+     */
+    removePreview: RangeCoords | null;
+    /**
+     * What the in-flight pointer drag is doing — `'extend'` (a drag-select growing the active range),
+     * `'remove'` (Ctrl/Cmd remove-drag), or `null` (no drag). Flips only on down / up (not per move), so a
+     * layer can show a transient tip (e.g. live R×C) without re-rendering on every pointer move.
+     */
+    dragMode: 'extend' | 'remove' | null;
+}
+/**
+ * The body selection pointer controller. Translates raw pointer gestures into {@link ISelection} intents
+ * and **holds no range math itself** — every mutation is a model call (`setSelection` / `modify` /
+ * `append` / `deselect`). The drag *mechanics* (pointer capture, per-cell de-dup, held-still auto-scroll)
+ * live in the shared {@link useDragCells} engine; this hook is just the body's policy adapter over it,
+ * plus the remove-drag rubber-band (the one piece of React state a drag renders).
+ *
+ * @remarks
+ * View-coupled by nature: {@link useDragCells} reads the pane for hit-testing and drives directional
+ * auto-scroll, so it lives in grid-react, not the sdk. It is the single mouse path (touch will fold into
+ * the same handlers later).
+ *
+ * Gestures:
+ * - **Click + drag** → new selection at the cell, drag extends it.
+ * - **Shift + click/drag** → extend the active range from the existing anchor.
+ * - **Ctrl/Cmd + click/drag on empty** → append a new range, drag extends it.
+ * - **Ctrl/Cmd + click/drag on selected** → remove-drag (rubber-band), applied on release.
+ *
+ * The Stage element is pointer-captured for the drag so move / up keep firing past the viewport edge.
+ */
+export declare const useSelectionPointer: (selection: ISelection, options?: SelectionPointerOptions) => SelectionPointerResult;
+//# sourceMappingURL=useSelectionPointer.d.ts.map

package/types/src/surface/GridPane.d.ts

@@ -0,0 +1,85 @@
+import { default as React } from 'react';
+import { AnchorLocation, CellCoords, RangeCoords, OrientationFlags, TopLeft, Point, Rectangle } from '@sheetxl/utils';
+import { IViewport } from '@sheetxl/utils-react';
+import { IGridMetrics } from '../metrics';
+import { IGridPane } from './IGridPane';
+import { IStageElement } from '../layer/Stage';
+/**
+ * Per-axis dimensions for a single pane (one entry for the scrolling pane, one for the frozen pane).
+ *
+ * @remarks
+ * The structural fields (minCoord/maxCoord/minBounds/maxBounds/maxVirtualBounds/freezeOffset) are
+ * scroll-independent; minIndex/maxIndex/metrics/visibleIndices/scrollOffset vary with scroll and are
+ * read live per-frame.
+ */
+export interface GridPaneDimensions {
+    minIndex: number;
+    maxIndex: number;
+    minCoord: number;
+    maxCoord: number;
+    visibleIndices: (from?: number, to?: number) => readonly number[];
+    minBounds: number;
+    maxBounds: number;
+    metrics: IGridMetrics;
+    maxVirtualBounds: number;
+    scrollOffset: number;
+    freezeOffset: number;
+}
+/**
+ * Static description of a pane: where it sits in the freeze grid, its scroll orientation, its insets,
+ * and the {@link Stage} element/ref that backs it. Stable across scroll.
+ */
+export interface GridPaneDef {
+    anchor: AnchorLocation;
+    columnIndex: number;
+    rowIndex: number;
+    elemStage: React.ReactNode;
+    refStage: IStageElement | null;
+    scrollOrientation: OrientationFlags;
+    insets: Rectangle;
+}
+/**
+ * Everything {@link createGridPane} needs from the surrounding `GridSurface` to build an
+ * {@link IGridPane}.
+ *
+ * @remarks
+ * Most fields are values/factories computed before pane creation. A few (`getSurfacePointFromPointer`,
+ * `scrollTo`, `scrollCellCoordsIntoView`, `getAllPanes`) are defined *after* the panes in the surface
+ * render and must be passed as call-time wrappers (they are only invoked later, never during pane
+ * creation).
+ */
+export interface GridPaneDeps {
+    /** Structural row dimensions (scroll-0 snapshot). */
+    rowDims: readonly GridPaneDimensions[];
+    /** Structural column dimensions (scroll-0 snapshot). */
+    columnDims: readonly GridPaneDimensions[];
+    /** Live row dimensions for a given scrollTop. */
+    computeRowDims: (scrollTop: number) => readonly GridPaneDimensions[];
+    /** Live column dimensions for a given scrollLeft. */
+    computeColumnDims: (scrollLeft: number) => readonly GridPaneDimensions[];
+    viewport: IViewport;
+    zoom: number;
+    containerWidth: number;
+    containerHeight: number;
+    getRangeFromCell: (coords: CellCoords) => RangeCoords;
+    invalidate: () => void;
+    /** The full grid range, shared by all panes. */
+    totalRange: RangeCoords;
+    getSurfacePointFromPointer: (clientX: number, clientY: number) => Point | null;
+    scrollTo: (options?: ScrollToOptions | number[]) => void;
+    scrollCellCoordsIntoView: (coords: Partial<CellCoords>, options?: globalThis.ScrollIntoViewOptions | boolean, anchor?: AnchorLocation) => Promise<Partial<TopLeft>>;
+    getAllPanes: () => Readonly<Partial<Record<AnchorLocation, IGridPane>>>;
+}
+/**
+ * Build the {@link IGridPane} handle for a single {@link GridPaneDef}.
+ *
+ * @returns The pane, or `null` for a degenerate (empty) freeze pane.
+ *
+ * @remarks
+ * Pure factory — no hooks, no JSX. The pane OBJECT is stable across scroll; its volatile geometry is
+ * recomputed live per-frame via `getFrame()` (memoized on the viewport snapshot).
+ */
+export declare const createGridPane: (def: GridPaneDef, deps: GridPaneDeps) => IGridPane | null;
+export declare const createTranslatedMetrics: (base: IGridMetrics, scrollPoint: Partial<TopLeft>, point?: Partial<Point>) => IGridMetrics;
+export declare const EmptyPanes: readonly GridPaneDimensions[];
+//# sourceMappingURL=GridPane.d.ts.map

package/types/src/surface/GridPaneProvider.d.ts

@@ -0,0 +1,37 @@
+import { default as React } from 'react';
+import { ViewportStore } from '@sheetxl/utils-react';
+import { IGridPane } from './IGridPane';
+/**
+ * Context for providing IGridPane to descendant components.
+ *
+ * @remarks
+ * The value is a `{ pane }` wrapper (not the bare pane) so the provider can hand descendants a NEW
+ * identity on each scroll — the pane object itself is stable across scroll, but layers
+ * must still re-render to re-read its scroll-dependent geometry. The wrapper changes identity when
+ * the pane changes (structural) OR the viewport scrolls.
+ */
+export declare const GridPaneContext: React.Context<{
+    pane: IGridPane;
+} | null>;
+export interface PaneProviderProps {
+    pane: IGridPane;
+    /**
+     * The scroll store. When provided, the provider subscribes and re-renders its consumers on every
+     * scroll (the panes are stable, so this is what makes layers re-read live geometry). Optional so a
+     * standalone `GridPaneProvider` (e.g. in a test) still works — it just won't track scroll.
+     */
+    viewport?: ViewportStore;
+    children: React.ReactNode;
+}
+/**
+ * Provider component that makes IGridPane available to all descendant layers
+ *
+ * @example
+ * ```tsx
+ * <GridPaneProvider pane={pane} viewport={viewport}>
+ *   <Layer x={100} y={100} width={200} height={100} />
+ * </GridPaneProvider>
+ * ```
+ */
+export declare const GridPaneProvider: React.FC<PaneProviderProps>;
+//# sourceMappingURL=GridPaneProvider.d.ts.map

package/types/src/surface/GridSurface.d.ts

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+import { GridSurfaceProps, IGridSurface } from './IGridSurface';
+/**
+ * GridSurface for rendering layers into virtual panels using
+ * IGridMetrics.
+ *
+ * @remarks
+ * * To support scrolling, wrap it in a `ScrollPane` and pass both the same {@link IViewport}.
+ */
+export declare const GridSurface: React.NamedExoticComponent<Omit<GridSurfaceProps, "ref"> & React.RefAttributes<IGridSurface>>;
+//# sourceMappingURL=GridSurface.d.ts.map