@sheetxl/grid-react 0.7.21 → 0.7.23-beta.1

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

@@ -0,0 +1 @@
+{"version":3,"file":"useSelectionPointer.d.ts","sourceRoot":"","sources":["../../../../src/selection/useSelectionPointer.ts"],"names":[],"mappings":"AAEA,OAAO,EAA+B,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAI/E,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAC/C,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAC/C,WAAW,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAC7C;;;OAGG;IACH,aAAa,EAAE,WAAW,GAAG,IAAI,CAAC;IAClC;;;;OAIG;IACH,QAAQ,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAAC;CACtC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,mBAAmB,GAC9B,WAAW,UAAU,EACrB,UAAU,uBAAuB,KAChC,sBAuHF,CAAC"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"GridPane.d.ts","sourceRoot":"","sources":["../../../../src/surface/GridPane.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1 @@
+{"version":3,"file":"GridPaneProvider.d.ts","sourceRoot":"","sources":["../../../../src/surface/GridPaneProvider.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,EAAqC,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE7F,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe;UAAyB,SAAS;SAAgB,CAAC;AAE/E,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,SAAS,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;CAC3B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAWxD,CAAC"}

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"GridSurface.d.ts","sourceRoot":"","sources":["../../../../src/surface/GridSurface.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAsC/B,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAA+B,MAAM,gBAAgB,CAAC;AAMvG;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,+FAg7BrB,CAAC"}

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

@@ -0,0 +1,288 @@
+import { default as React } from 'react';
+import { CellCoords, RangeCoords, OrientationFlags, TopLeft, Point, Rectangle, Bounds, Size, AnchorLocation, RemoveListener } from '@sheetxl/utils';
+import { IGridMetrics } from '../metrics';
+/**
+ * Describes a virtualize handle to a view section of a grid.
+ */
+export interface IGridPane {
+    /**
+     * Sets focus to the view.
+     */
+    focus(options?: FocusOptions): void;
+    /**
+     * Set pointer capture to the view.
+     */
+    setPointerCapture(pointerId: number): void;
+    /**
+     * Release pointer capture from the view.
+     */
+    releasePointerCapture(pointerId: number): void;
+    /**
+     * The anchor for the view.
+     */
+    getAnchor(): AnchorLocation;
+    /**
+     * Allow for dimensions to be determined for various cells.
+     * The `IGridMetrics` is inclusive of the zoom.
+     */
+    getMetrics(): IGridMetrics;
+    /**
+     * The LIVE visible range of THIS pane — exactly the cells on screen right now. Changes as the pane
+     * scrolls. Same span as {@link getVisibleRows} / {@link getVisibleColumns}.
+     *
+     * @remarks
+     * One of three range concepts, from narrowest to widest:
+     * - {@link getVisibleRange} — this pane, on screen now (scroll-dependent).
+     * - {@link getPaneRange} — this pane's full structural coverage (scroll-independent).
+     * - {@link getTotalRange} — the whole grid, all panes.
+     */
+    getVisibleRange(): Readonly<RangeCoords>;
+    /**
+     * The visible (non-hidden) rows as {@link SpanSize} tracks (index + geometry), in order — so a
+     * caller iterates position + width in one pass; the array position is the visible ordinal.
+     *
+     * @param from Optional start index — overrides the viewport with a FRESH scan of exactly `[from, to]`
+     * (e.g. an overscan buffer, which extends past the viewport). Hidden runs are still skipped; the
+     * range is NOT clamped to the viewport. Caller keeps it within the grid.
+     * @param to Optional (inclusive) end index. Both `from` and `to` must be supplied to override.
+     */
+    getVisibleRows(from?: number, to?: number): readonly SpanSize[];
+    /**
+     * The visible (non-hidden) columns as {@link SpanSize} tracks (index + geometry), in order.
+     *
+     * @param from Optional start index — overrides the viewport with a custom range (see {@link getVisibleRows}).
+     * @param to Optional (inclusive) end index.
+     */
+    getVisibleColumns(from?: number, to?: number): readonly SpanSize[];
+    /**
+     * The geometry of ONE column by index (random access), or `null` for an out-of-grid index. Backed by
+     * the metrics cache — window-independent, so it also resolves off-viewport (overscan) tracks. Prefer
+     * {@link getVisibleColumns} when iterating; use this for the odd lookup (e.g. a merge boundary).
+     */
+    getColumnSize(index: number): SpanSize | null;
+    /**
+     * The geometry of ONE row by index (random access), or `null` for an out-of-grid index. See
+     * {@link getColumnSize}.
+     */
+    getRowSize(index: number): SpanSize | null;
+    /**
+     * Clip a rectangle against the viewport, culling to `null` when it falls fully outside — the
+     * clip/cull primitive. Pair with {@link getBoundsFromRange} for the common "range → visible bounds"
+     * path: `toClipBounds(getBoundsFromRange(range), insets)`.
+     *
+     * @param bounds The (view-relative) rect to clip. Defaults to the full pane bounds.
+     * @param insets Slack in view pixels. A negative inset extends OUTSIDE the viewport, so elements
+     *   that visually 'flow' off the edge (e.g. a selection with an outward-growing border) are not
+     *   culled while still partly visible.
+     *
+     * @remarks
+     * Returns `null` when nothing survives the clip (the rect is entirely off-screen).
+     */
+    toClipBounds(bounds?: Bounds, insets?: number | Bounds): Bounds | null;
+    /**
+     * ABSOLUTE → VIEW: map a rect from scroll-independent content space into this pane's view space
+     * (subtract the pane's scroll offset, then apply zoom). The inverse of {@link toAbsoluteBounds}.
+     *
+     * @remarks
+     * A distinct axis from {@link getBoundsFromRange} / {@link toClipBounds}, which already live in view
+     * space. This pair exists for content anchored in ABSOLUTE space — a floating movable (image / chart
+     * / shape) whose position must survive scroll & zoom. Use this to render such a movable at its current
+     * on-screen spot; use {@link toAbsoluteBounds} to persist a drag result back to the model. Cells never
+     * need it (they are range-derived, hence already view-space).
+     */
+    toPaneBounds(bounds: Bounds): Bounds;
+    /**
+     * VIEW → ABSOLUTE: map a rect from this pane's view space back into scroll-independent content space
+     * (undo zoom, then add the pane's scroll offset). The inverse of {@link toPaneBounds}.
+     *
+     * @remarks
+     * See {@link toPaneBounds}. Used to store a movable's live (view-space) drag/resize result as
+     * scroll-independent model bounds, so it stays anchored as the grid scrolls or zooms.
+     */
+    toAbsoluteBounds(bounds: Bounds): Bounds;
+    /**
+     * Additional inside padding.
+     */
+    getInsets(): Rectangle;
+    /**
+     * Returns the cell as a range.
+     *
+     * @remarks
+     * If this cell spans this will return a range later than 1.
+     * Note - This may return ranges for Cells if if they are not the top left.
+     */
+    getRangeFromCell(coords: CellCoords): RangeCoords;
+    /**
+     * The view-relative bounds of a range — the raw geometry primitive (never clipped, never `null`).
+     *
+     * @param range The range to measure. Defaults to the visible cell range.
+     * @param adjustment Optional per-edge pixel offset of the returned rect (each edge moves
+     *   independently — this is NOT an inset, which would shrink symmetrically).
+     *
+     * @remarks
+     * Bounds are relative to the view (they move with scroll), NOT absolute. This resolves ANY
+     * range, including one entirely off-screen (e.g. an overscan/buffer cell), so callers that must
+     * place off-viewport content use it directly. For "geometry only if visible" (clipped to the pane,
+     * culled to `null` when off-screen) compose with {@link toClipBounds}:
+     * `toClipBounds(getBoundsFromRange(range), insets)`.
+     */
+    getBoundsFromRange(range?: RangeCoords, adjustment?: Partial<Rectangle>): Bounds;
+    /**
+     * Scroll the cell coords into view.
+     * If the coord does not have an index it will only scroll in a single direction.
+     */
+    scrollCellCoordsIntoView(coords: Partial<CellCoords>, options?: globalThis.ScrollIntoViewOptions | boolean): Promise<Partial<TopLeft>>;
+    /**
+     * Scroll to the specified top/left.
+     * @param options
+     */
+    scrollTo(options?: ScrollToOptions): void;
+    /**
+     * Indicate the allowable scroll directions.
+     */
+    getScrollOrientation(): OrientationFlags;
+    /**
+     * Returns the current scroll top/left for the view.
+     */
+    getScrollTopLeft(): TopLeft;
+    /**
+     * The pane's scroll baseline at the viewport TARGET — {@link getScrollTopLeft} plus any in-flight
+     * scroll (an animated glide, or an applied-but-not-yet-ticked instant target). Frame-invariant math
+     * (chaining PageDowns under key repeat, paging during a glide) must baseline here: the rendered
+     * position can lag the authoritative target by a frame or a whole animation.
+     */
+    getScrollTarget?(): TopLeft;
+    /**
+     * The frozen region's pixel offset for this pane (`{ left, top }`, view px). Like
+     * {@link getScrollTopLeft}, this is a pixel `TopLeft` — NOT a cell count. `{ left: 0, top: 0 }` when
+     * nothing is frozen on that axis.
+     *
+     * @remarks
+     * For the freeze STRUCTURE use {@link getAllPanes} — the `Top` / `Left` / `TopLeft` entries exist only
+     * when frozen — and each frozen pane's {@link getPaneRange} is exactly its frozen cell band, so
+     * `getPaneRange().colEnd + 1` / `.rowEnd + 1` gives the frozen column / row COUNT. The configured
+     * freeze count as a model value lives on `ISheetView.getFreezePanes().coords`.
+     */
+    getFreezeTopLeft(): TopLeft;
+    /**
+     * Useful for internal rendering.
+     *
+     * @remarks
+     * The cell layout will account for zoom factors already.
+     */
+    getZoom(): number;
+    /**
+     * Returns the range for the entire GridSurface.
+     */
+    getTotalRange(): Readonly<RangeCoords>;
+    /**
+     * The size of the surface  for all grid panes.
+     */
+    getSurfaceSize(): Size;
+    /**
+     * Returns the total size of all rendered values in pixels.
+     */
+    getTotalSize(): Size;
+    /**
+     * The STRUCTURAL range of THIS pane — the full band of cells the pane is responsible for, scroll-
+     * independent (most of it is usually off-screen). The center/scrolling pane spans
+     * `[freezeLeft..columnCount-1] × [freezeTop..rowCount-1]`; a frozen pane spans its frozen band.
+     *
+     * @remarks
+     * NOT the visible range — see {@link getVisibleRange} for the on-screen cells, and
+     * {@link getTotalRange} for the whole grid across all panes.
+     */
+    getPaneRange(): RangeCoords;
+    /**
+     * The STRUCTURAL pixel rectangle of THIS pane within the surface — scroll-independent (a frozen-left
+     * pane sits at `x: 0`; the center pane starts at the freeze width). The pixel-space analog of
+     * {@link getPaneRange}.
+     *
+     * @remarks
+     * NOT view-relative and NOT clipped — it is the pane's own box on the surface. For a range's
+     * geometry use {@link getBoundsFromRange}; for the whole-surface / content sizes see
+     * {@link getSurfaceSize} / {@link getTotalSize}.
+     */
+    getPaneBounds(): Bounds;
+    /**
+     * Convert a CLIENT coordinate (browser-viewport pixels, e.g. a pointer event's `clientX`/`clientY`)
+     * into a point in this pane's view space — the same space {@link getBoundsFromRange} returns — so the
+     * result can be hit-tested directly against a range's bounds.
+     *
+     * @param clientX Client x, as from `PointerEvent.clientX`.
+     * @param clientY Client y, as from `PointerEvent.clientY`.
+     *
+     * @remarks
+     * The usual use is turning a DOM pointer event into grid space to find what is under the pointer
+     * (context menus, tooltips, hover). Passing `(0, 0)` is a useful special case: it yields the offset
+     * between client space and this pane's view space, so a view-space rect can be mapped back to
+     * on-screen (client) coordinates.
+     */
+    getPanePointFromPointer(clientX: number, clientY: number): Point | null;
+    /**
+     * Returns the coords at the offset.
+     *
+     * @param x The x offset relative to the view
+     * @param y The y offset relative to the view
+     * @param actualCell Don't return the topLeft of a merge. Default value `false`.
+     */
+    getCellFromPointer(x: number, y: number, actualCell?: boolean): CellCoords | null;
+    /**
+     * Hit-test a client (absolute) point to the pane under it.
+     *
+     * @remarks
+     * May return a DIFFERENT pane than this one (e.g. a frozen pane the pointer is over), or `null`
+     * when the point is outside every pane (off the surface). Frozen panes do not overlap the center,
+     * so a point in the scroll region resolves to the center pane and a point in a frozen gutter to
+     * that frozen pane.
+     */
+    getPaneFromPointer(clientX: number, clientY: number): IGridPane | null;
+    /**
+     * Invalidate the current view.
+     */
+    invalidate(): void;
+    /**
+     * All grid panes currently mounted, keyed by {@link AnchorLocation}.
+     * Callable from ANY pane, so a single pane handle can reach its siblings.
+     *
+     * @remarks
+     * The `Center` (scrolling) pane is always present; the `Top` / `Left` / `TopLeft` panes exist only
+     * when the grid has frozen rows and/or columns. Use it to reach the scrolling pane
+     * (`getAllPanes()[AnchorLocation.Center]`), to walk every pane (e.g. hit-test across the freeze
+     * split), or to detect whether the grid is frozen (more than one entry).
+     */
+    getAllPanes(): Readonly<Partial<Record<AnchorLocation, IGridPane>>>;
+    /**
+     * Add a listener for a single event type to the pane's event dispatch (e.g. a custom header
+     * renderer listening for `pointermove` hover). Returns a remover — hold it and call it on
+     * teardown; no other bookkeeping needed.
+     *
+     * @param type The native event type (`'pointermove'`, `'keydown'`, …).
+     * @param listener Receives the React synthetic event.
+     * @param listenerPane Optional variant that also receives the pane the event dispatched on.
+     *
+     * @remarks
+     * The listener joins the pane's z-ordered dispatch walk as an element-less responder (it has no
+     * layer membership). Registering while the pane's element is unmounted returns a no-op remover.
+     */
+    addReactEventListener(type: string, listener: (event: React.SyntheticEvent) => void, listenerPane?: (event: React.SyntheticEvent, pane: IGridPane) => void): RemoveListener;
+    /**
+     * Contains the div element for the pane — the pane's focusable surface (event root).
+     */
+    getElement(): HTMLElement | null;
+}
+/**
+ * The geometry of a single row/column track: its index, its leading-edge pixel `offset` (VIEW-relative
+ * — moves with scroll) and its pixel `size` (0 for a hidden track). The visible-ordinal is the position
+ * in {@link IGridPane.getVisibleColumns}/{@link IGridPane.getVisibleRows}; it is deliberately NOT stored
+ * here (an ordinal is only meaningful relative to a specific visible enumeration — see useBorders).
+ */
+export interface SpanSize {
+    /** The row/column index this span describes. */
+    index: number;
+    /** Leading-edge pixel offset, view-relative. */
+    offset: number;
+    /** Pixel extent; 0 for a hidden track. */
+    size: number;
+}
+//# sourceMappingURL=IGridPane.d.ts.map

package/types/src/surface/IGridPane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IGridPane.d.ts","sourceRoot":"","sources":["../../../../src/surface/IGridPane.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,141 @@
+import { CellCoords, RangeCoords, TopLeft, FixedEdge, AnchorLocation } from '@sheetxl/utils';
+import { IViewport } from '@sheetxl/utils-react';
+import { IGridMetrics } from '../metrics';
+import { LayerNode } from '../layer';
+import { LineSVGProps } from '../svg';
+import { IGridPane } from './IGridPane';
+export interface GridSurfaceProps extends React.HTMLAttributes<HTMLDivElement>, React.RefAttributes<IGridSurface> {
+    /**
+     * Number of columns in the grid.
+     */
+    columnCount: number;
+    /**
+     * Number of rows in the grid.
+     */
+    rowCount: number;
+    /**
+     * The metric for calculating cell positions. The surface is metrics-only; the size-convenience
+     * (`getRowHeight` / `getColumnWidth`) lives on {@link Grid}.
+     */
+    metrics?: IGridMetrics | null;
+    /**
+     * The scroll viewport — a single {@link IViewport} object (position + zoom + bounds + sizes +
+     * ticker). Pass the SAME instance to a wrapping `ScrollPane` and they stay in sync through it.
+     *
+     * @remarks
+     * Use a `Viewport` for a normal grid. For per-axis sharing — a sheet header that follows
+     * the main grid, or split peers sharing one axis — pass an `AxisViewport` composed from the relevant
+     * controllers. When omitted, GridSurface creates and owns its own (standalone, non-scrolling without
+     * a wrapper). A passed-in viewport's lifecycle (dispose) belongs to the caller.
+     */
+    viewport?: IViewport;
+    /**
+     * Returns the cell as a range. If this cell is merged this will be reflected.
+     *
+     * @remarks
+     * Slightly more sophisticated than rowSpan and colSpan because it allows for queries that are not on the top/left.
+     */
+    getRangeFromCell?: (coords: CellCoords) => RangeCoords;
+    /**
+     * Will skip rendering for this row and the adjacent rows in the given direction.
+     */
+    hiddenRowsAt?: (rowIndex: number, forward?: boolean) => number;
+    /**
+     * Will skip rendering for this columns and the adjacent columns in the given direction.
+     */
+    hiddenColumnsAt?: (colIndex: number, forward?: boolean) => number;
+    /**
+     * Number of frozen left columns, or a {@link FixedEdge} whose `offset` is the frozen-region scroll
+     * in zoom-independent (base) px (scaled to screen px internally by the current zoom).
+     */
+    freezeLeft?: number | FixedEdge;
+    /**
+     * Number of frozen top rows, or a {@link FixedEdge} whose `offset` is the frozen-region scroll in
+     * zoom-independent (base) px (scaled to screen px internally by the current zoom).
+     */
+    freezeTop?: number | FixedEdge;
+    /**
+     * Allow for customization of freezeLeftDivider
+     */
+    propsFreezeLeft?: Partial<LineSVGProps>;
+    /**
+     * Allow for customization of freezeTopDivider
+     */
+    propsFreezeTop?: Partial<LineSVGProps>;
+    /**
+     * Call only once when the renders for the first time.
+     */
+    onFirstRender?: (grid: IGridSurface) => void;
+    /**
+     * The layers, as children, bottom → top. Each layer is an ordinary React node that reads its pane
+     * from context ({@link useGridPane}), so the children are just JSX rendered once per pane
+     * (`<GridSurface><Layer>…</Layer></GridSurface>`). A layer with a `zIndex` sorts within the stack.
+     * For the rare layer that must be BUILT from the pane, call
+     * {@link useGridPane} from a small wrapper component.
+     */
+    children?: LayerNode;
+    /**
+     * Wraps each pane's layers (inside its `GridPaneProvider`), once per pane. The default is the
+     * identity (children pass through). The seam for **per-pane** context that must sit *outside*
+     * the layers yet *inside* the pane — e.g. a consumer injecting a per-pane feature context (such
+     * as a command scope) so layers can contribute to it. Kept a render callback so `grid-react`
+     * stays free of any command/feature import: the pane is passed in, the consumer supplies the
+     * wrapper.
+     *
+     * @param pane The pane whose layers are being wrapped (one call per pane; up to 4 with freeze).
+     * @param children The pane's layers (already normalized + provider-wrapped).
+     */
+    wrapPane?: (pane: IGridPane, children: React.ReactNode) => React.ReactNode;
+}
+/**
+ * The imperative API of a {@link GridSurface}, exposed on its {@link IGridSurface} handle.
+ */
+export interface IGridSurfaceAttributes {
+    /**
+     * Invalidate and re-render the grid, dropping cached pane/cell output.
+     *
+     * @remarks
+     * Use after a change the surface cannot observe through its props. {@link IGrid} widens this to
+     * accept a cell or range to invalidate only a subset.
+     */
+    invalidate: () => void;
+    /**
+     * Scroll a cell into view.
+     *
+     * @remarks
+     * When `coords` omits an index it scrolls only along the axis that is provided.
+     *
+     * @returns The clamped scroll position that was applied.
+     */
+    scrollCellCoordsIntoView: (coords: Partial<CellCoords>, options?: globalThis.ScrollIntoViewOptions | boolean) => Promise<Partial<TopLeft>>;
+    /**
+     * Returns the pane at the given client coordinates. A point over a frozen pane returns that frozen
+     * pane; otherwise the center (scrolling) pane is returned.
+     */
+    getPaneFromClient: (x: number, y: number) => IGridPane;
+    /**
+     * Returns the pane that owns the given cell.
+     *
+     * @remarks
+     * Prefers the last-focused pane and falls back to the center pane. Used to support goto/navigation.
+     */
+    getPaneFromCell: (coords: CellCoords) => IGridPane;
+    /**
+     * Returns the pane at the given anchor location, or `null` when that pane is not present in the
+     * current freeze layout. With **no argument**, returns the pane focus would land on — the
+     * last-focused pane, else the center (primary scrolling) pane — the pane analog of
+     * {@link IGridSurfaceAttributes.focus} (`focusLastPane`), so a consumer can name "the grid's
+     * active pane" without knowing the freeze geometry.
+     */
+    getPane: (anchor?: AnchorLocation) => IGridPane | null;
+    /**
+     * Registers a callback fired the next time the pane layout changes. Fires at most once.
+     */
+    onPaneChangeOnce: (callback: () => void) => void;
+}
+/**
+ * Type returned via ref property
+ */
+export interface IGridSurface extends HTMLDivElement, IGridSurfaceAttributes {
+}
+//# sourceMappingURL=IGridSurface.d.ts.map