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

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/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

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

@@ -0,0 +1,50 @@
+import { default as React } from 'react';
+/**
+ * A tiny pub/sub keyed store scoped to a single {@link GridSurface}. It is the backing for
+ * {@link useSurfaceState} — state that conceptually belongs to the *view* (the surface) rather than to
+ * any one React component instance.
+ *
+ * @remarks
+ * The motivating case: a layer (e.g. `Draggable`, `FillHandle`) is
+ * rendered **once per pane** (Center / Top / Left / TopLeft), so a single logical layer is actually
+ * four separate React instances. Transient drag UI (a move ghost, a fill border) lives in component
+ * `useState`, so only the pane that captured the pointer updates — the frozen-pane copies stay stale.
+ * Hoisting that value into a per-surface store lets all four instances read/write one cell (by an
+ * explicit key), so every pane redraws its own (independently clipped) slice. The store lives for the
+ * life of the surface, so a split view / second view gets its own store and never bleeds.
+ */
+export interface SurfaceStateStore {
+    has(key: string): boolean;
+    get(key: string): unknown;
+    set(key: string, value: unknown): void;
+    subscribe(key: string, onChange: () => void): () => void;
+}
+export declare const createSurfaceStateStore: () => SurfaceStateStore;
+export declare const SurfaceStateContext: React.Context<SurfaceStateStore | null>;
+export interface SurfaceStateProviderProps {
+    /**
+     * Explicit store to provide, overriding both inheritance and lazy creation. Pass one to force a
+     * scope — a test, or a nested surface that wants its own transient state despite an ancestor.
+     * Memoize it (a fresh store every render resets the scope).
+     */
+    store?: SurfaceStateStore;
+    children: React.ReactNode;
+}
+/**
+ * Provides the {@link SurfaceStateStore} backing {@link useSurfaceState} to descendant panes/layers.
+ * It resolves the store itself, highest priority first:
+ *
+ * 1. an explicit {@link SurfaceStateProviderProps.store} prop (override);
+ * 2. a store **inherited** from an ancestor `SurfaceStateProvider` — so a wider parent (e.g. a
+ *    `SheetElement` wrapping its top-left corner + both header `GridSurface`s + the main `GridSurface`)
+ *    shares one scope across sibling surfaces, letting a layer keyed the same in a header and in the body
+ *    read one cell;
+ * 3. otherwise a **lazily-created own** store (the standalone default).
+ *
+ * So a {@link GridSurface} can unconditionally mount `<SurfaceStateProvider>` and get the right thing:
+ * its own isolated store when standalone (or under a split view / second view), the shared one when
+ * nested under a wider provider. Because inheritance is automatic, the common case is a bare
+ * `<SurfaceStateProvider>` with no props.
+ */
+export declare const SurfaceStateProvider: React.FC<SurfaceStateProviderProps>;
+//# sourceMappingURL=SurfaceStateProvider.d.ts.map

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

@@ -0,0 +1,37 @@
+import { RangeCoords, Bounds, TopLeft, Rectangle, SelectionTraversalUtils } from '@sheetxl/utils';
+import { ViewportMetrics } from '@sheetxl/utils-react';
+import { ItemSizer, IGridMetrics } from '../metrics';
+/** Clamp `value` into `[min, max]` (the one shared definition — don't re-inline per module). */
+export declare const clamp: (value: number, min: number, max: number) => number;
+/**
+ * Retrieves the indices of visible headers within a specified range.
+ * A header is considered visible if it is not hidden according to the `hiddenAt` callback.
+ *
+ * @param hiddenAt Callback to determine hidden headers at a given index.
+ * @param startIndex The starting index of the range to check.
+ * @param stopIndex The ending index of the range to check.
+ * @returns An array of visible header indices within the specified range.
+ */
+export declare const getVisibleHeaders: (hiddenAt: SelectionTraversalUtils.HiddenHeadersAt | undefined, startIndex: number, stopIndex: number) => number[];
+export declare const virtualScrollToBounds: (elementBounds: Bounds, viewport: ViewportMetrics, options?: globalThis.ScrollIntoViewOptions | boolean) => TopLeft | undefined;
+/**
+ * default implementation of hiddenAt. Uses layout and will scan zero length.
+ *
+ * Not very efficient as this just scans.
+ */
+export declare const calcHiddenAt: (index: number, reverse: boolean | undefined, sizer: ItemSizer, limit: number) => number;
+/**
+ * Clip `bounds` to `limitBounds` (with optional `insets`). Returns `null` when nothing survives —
+ * i.e. `bounds` is entirely outside `limitBounds`.
+ */
+export declare const clipBounds: (bounds: Bounds, limitBounds: Bounds, insets?: number) => Bounds | null;
+/**
+ * Returns the bounds for a range given a cellLayout and an optional adjustment
+ * The range or layout is not validated as this is expected to be a performant function
+ */
+export declare const getBoundsFromRange: (layout: IGridMetrics, range: RangeCoords, adjustment?: Partial<Rectangle>) => Bounds;
+/**
+ * Returns true if the x and y are bot within the bounds.
+ */
+export declare const isPointWithinBounds: (x: number, y: number, bounds: Bounds) => boolean;
+//# sourceMappingURL=_GridUtils.d.ts.map

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

@@ -0,0 +1,7 @@
+export * from './IGridPane';
+export * from './IGridSurface';
+export * from './GridSurface';
+export * from './useGridPane';
+export * from './useSurfaceState';
+export * from './SurfaceStateProvider';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,31 @@
+import { IGridPane } from './IGridPane';
+/**
+ * Hook to access the current GridPane from context
+ *
+ * @throws Error if called outside of a GridPaneProvider
+ *
+ * @example
+ * ```tsx
+ * function MyLayer() {
+ *   const pane = useGridPane();
+ *   const bounds = pane.getRangeBounds(myRange);
+ *   return <div>...</div>;
+ * }
+ * ```
+ */
+export declare function useGridPane(): IGridPane;
+/**
+ * Hook to optionally access the current GridPane from context
+ * Returns null if not within a GridPaneProvider
+ *
+ * @example
+ * ```tsx
+ * function MyDiv({ pane: propPane, ...props }) {
+ *   const contextPane = useGridPaneOptional();
+ *   const pane = propPane ?? contextPane;
+ *   // Use pane...
+ * }
+ * ```
+ */
+export declare function useGridPaneOptional(): IGridPane | null;
+//# sourceMappingURL=useGridPane.d.ts.map

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

@@ -0,0 +1,22 @@
+import { Dispatch, SetStateAction } from 'react';
+/**
+ * Like {@link React.useState}, but the cell is **keyed** and scoped to the enclosing {@link GridSurface},
+ * so every pane that renders this layer reads/writes the SAME cell — writing it from the pane that owns a
+ * drag re-renders the frozen-pane copies too (each draws its own clipped slice). Use it for transient,
+ * view-scoped layer UI (a move ghost, a fill border, marching ants, a drag-insert line).
+ *
+ * @param key - A stable identifier for this piece of shared state, **unique within the surface**.
+ *   Identity is an explicit key, not call position: two mirrored panes are separate React trees (each
+ *   gets its own fiber, and client `useId` is only a mount-order counter), so there is no positional
+ *   identity to collapse across them. This is the same idea as a React `key`, a Redux slice, or a store
+ *   key. For a **singleton** use a constant (`'movable-drag'`); for **multi-instance** state (e.g. one
+ *   mover per range) compose the model's identity into the key (`` `range-move:${rangeKey}` ``) so the
+ *   same logical instance shares across panes while distinct instances stay separate.
+ * @param initialValue - The initial value (or a lazy initializer), exactly like `useState`.
+ *
+ * @remarks
+ * Outside a {@link GridSurface} (e.g. a standalone test) it transparently falls back to a per-instance
+ * store, so it still behaves like ordinary local state.
+ */
+export declare function useSurfaceState<T>(key: string, initialValue: T | (() => T)): [T, Dispatch<SetStateAction<T>>];
+//# sourceMappingURL=useSurfaceState.d.ts.map

package/types/src/svg/LineSVG.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+import { ShapeProps } from './Types';
+export interface LineSVGProps extends React.SVGProps<SVGSVGElement>, ShapeProps {
+    linePoints: number[];
+    propsPath?: React.SVGProps<SVGPathElement>;
+}
+/**
+ * A **shape**: an SVG polyline painted within the given `bounds` (used for gridlines). Like
+ * {@link RectangleSVG}, it takes resolved bounds and knows nothing about ranges or the pane — a
+ * **layer** would place it. (Shapes take bounds and paint; layers are pane-aware.)
+ */
+export declare const LineSVG: (props: LineSVGProps) => React.JSX.Element | null;
+//# sourceMappingURL=LineSVG.d.ts.map