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

package/types/src/header/useHeaderSelectionPointer.d.ts

@@ -0,0 +1,122 @@
+import { RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+import { ISelection, DragCellsController } from '../selection';
+/**
+ * Options for {@link useHeaderSelectionPointer} / {@link createHeaderSelectionPointer}.
+ */
+export interface HeaderSelectionPointerOptions {
+    /** The header's axis. A column header selects entire columns; a row header, entire rows. */
+    axis: RangeAxis;
+    /**
+     * The **body** entire range (full rows × full columns). The header projects every gesture across the
+     * opposite axis using this — `pane.getTotalRange()` on a header pane only covers the header strip, so
+     * it must be supplied (typically `sheet.getEntireRange().getCoords()`).
+     */
+    entireRange: RangeCoords;
+    /**
+     * Allow Ctrl/Cmd-click to append additional header ranges (multi-select). When `false` a modifier
+     * click is treated as a plain replace.
+     *
+     * @defaultValue true
+     */
+    allowMulti?: boolean;
+    /**
+     * **Point (reference-picking) mode.** A no-modifier click/drag re-scopes the **active** reference in
+     * place (or **appends** a new one when the caret isn't on a reference, i.e. `rangeIndex < 0`),
+     * preserving the formula's other references — instead of the default `'clear'` that replaces the whole
+     * selection. Used by the header reference picker (`SheetReferenceHeaderLayer`) while editing a formula
+     * or a chart's data ranges. The gesture is also `stopPropagation`d so a primary header selection
+     * registered below this overlay never also runs its clobbering replace.
+     *
+     * @defaultValue false
+     */
+    replaceActive?: boolean;
+    /**
+     * Keep the current focus on pointer-down instead of letting the click steal it to the `tabIndex` Stage.
+     * On for a picker overlay used while editing a formula — a header pick must not blur the editor's
+     * textarea (mirrors the body draw picker's `preventDefault`). @defaultValue false
+     */
+    preserveFocus?: boolean;
+    /**
+     * Scroll a header cell into view during a drag (including the held-still auto-scroll). Given the header
+     * cell's axis coord — `{ colIndex }` for a column header, `{ rowIndex }` for a row header.
+     *
+     * @remarks
+     * **Must** be supplied for auto-scroll to work on a real sheet: a header `GridSurface` has a controlled
+     * viewport (it mirrors the body) and cannot scroll itself, so the scroll has to route through the sheet
+     * (`sheet.scrollTo`) — exactly like `SelectionLayer`'s `scrollIntoView`. When omitted the header falls
+     * back to scrolling its own pane, which is correct only for a standalone header / the unit tests.
+     */
+    scrollIntoView?: (coords: Partial<CellCoords>) => void;
+    /**
+     * Intercept pointer-down before any selection change. Return `false` to cancel (e.g. a right-click on
+     * an already fully-selected header, so the context menu keeps the existing multi-selection).
+     */
+    onPointerDownInterceptor?: (e: React.PointerEvent, cell: CellCoords) => boolean | void;
+    /** Called once at the start of a pointer gesture (before the selection changes). */
+    onDragStart?: () => void;
+    /** Called at the end of a pointer gesture. */
+    onDragEnd?: (e: React.PointerEvent) => void;
+    /** Called on pointer-up, after {@link HeaderSelectionPointerOptions.onDragEnd} (e.g. refocus the grid). */
+    onPointerUp?: (e: React.PointerEvent) => void;
+}
+/** Handlers to spread onto a `Layer` tap for header selection. */
+export interface HeaderSelectionPointerResult {
+    onPointerDown: (e: React.PointerEvent) => void;
+    onPointerMove: (e: React.PointerEvent) => void;
+    onPointerUp: (e: React.PointerEvent) => void;
+}
+/**
+ * The entire-axis **start** corner for a header `cell`: the header index on the header axis, the body's
+ * entire-range start on the opposite axis (so a column header spans from the top row).
+ */
+export declare const headerEntireStart: (cell: CellCoords, axis: RangeAxis, entire: RangeCoords) => CellCoords;
+/** The entire-axis **end** corner for a header `cell` (mirror of {@link headerEntireStart}). */
+export declare const headerEntireEnd: (cell: CellCoords, axis: RangeAxis, entire: RangeCoords) => CellCoords;
+/**
+ * The **active cell** for a header gesture: the header index on the header axis, anchored to the first
+ * visible body row/column on the opposite axis — so the active cell (and the editor that follows it)
+ * lands at the top-left of the visible body, not at row/column 0.
+ */
+export declare const headerAnchorCell: (cell: CellCoords, axis: RangeAxis, visible: RangeCoords) => CellCoords;
+/**
+ * The entire-axis **range** spanning header cells `a`..`b` (only their header-axis index is used; the
+ * opposite axis always spans the body's entire range). The selection range is decoupled from the
+ * viewport-anchored active cell — which is why the header cannot use `ISelection.modify` (that ties the
+ * range to the anchor).
+ */
+export declare const headerRange: (a: CellCoords, b: CellCoords, axis: RangeAxis, entire: RangeCoords) => RangeCoords;
+/**
+ * The header selection pointer controller — the headless core of {@link useHeaderSelectionPointer},
+ * separated so the gesture→model logic is testable with a real {@link ISelection} and a fake pane (no
+ * React). Translates header pointer gestures into entire-axis selections written through `ISelection`:
+ *
+ * - **click / drag** → replace with the entire row/column(s) under the pointer.
+ * - **Shift + click/drag** → extend the active range from the first-clicked header.
+ * - **Ctrl/Cmd + click/drag** → append a new entire row/column range (when `allowMulti`).
+ *
+ * In {@link HeaderSelectionPointerOptions.replaceActive} (point) mode the plain click/drag instead
+ * re-scopes the ACTIVE reference in place (or appends when the caret isn't on one), the gesture is
+ * `stopPropagation`d, and writes go through an index-pinned `commitAt` (the body picker's `commitRange`).
+ *
+ * The drag *mechanics* (pointer capture, per-cell de-dup, held-still auto-scroll) come from the shared
+ * {@link createDragCells} engine; this controller only supplies the header *policy* (the entire-axis seed
+ * / drag / end). Unlike the body's `useSelectionPointer` it never calls `modify`/`append`: each gesture
+ * computes the full entire-axis range (which is NOT anchored to the active cell) and `setSelection`s it,
+ * keeping the viewport-anchored active cell. `getOptions` is read on every event so live values (entire
+ * range, callbacks) need no controller rebuild.
+ */
+export declare const createHeaderSelectionPointer: (selection: ISelection | null, pane: IGridPane, getOptions: () => HeaderSelectionPointerOptions) => DragCellsController;
+/**
+ * The header selection pointer hook: the header-axis counterpart to the body's `useSelectionPointer`.
+ * Reads the pane from context and drives the shared {@link ISelection} model, projecting every gesture
+ * to entire rows/columns and anchoring the active cell to the visible body. See
+ * {@link createHeaderSelectionPointer} for the gesture semantics.
+ *
+ * @remarks
+ * Options are read live through a ref, so changing `entireRange` / callbacks does not rebuild the
+ * handlers — the controller is memoized on `(selection, pane)` only. The engine's auto-scroll timer is
+ * stopped on unmount.
+ */
+export declare const useHeaderSelectionPointer: (selection: ISelection | null, options: HeaderSelectionPointerOptions) => HeaderSelectionPointerResult;
+//# sourceMappingURL=useHeaderSelectionPointer.d.ts.map

package/types/src/index.d.ts

@@ -0,0 +1,13 @@
+export * from './metrics';
+export * from './svg';
+export * from './layer';
+export * from './range';
+export * from './surface';
+export * from './cell';
+export * from './selection';
+export * from './editor';
+export * from './header';
+export * from './grid';
+export * from './list';
+export * from './theme';
+//# sourceMappingURL=index.d.ts.map

package/types/src/layer/HoverTipLayer.d.ts

@@ -0,0 +1,74 @@
+import { default as React } from 'react';
+import { CellCoords, RangeCoords } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+import { LayerProps } from './Layer';
+import { StickyState } from './StickyAnchor';
+import { HoverTipProps } from './useHoverIntent';
+import { GridPlacement, GridWhenOff, GridBoundary } from './useGridAnchor';
+/** A hit returned by a {@link HoverTipLayerProps.probe} — the range to anchor on plus arbitrary payload. */
+export interface HoverTarget<T = unknown> {
+    /** The range the tip anchors to (e.g. the cell's own range, or an enclosing table). */
+    range: RangeCoords;
+    /**
+     * Stable identity for dedupe — the tip re-opens only when this changes (a `pointermove` storm within
+     * one target is a no-op). Defaults to the range's coords.
+     */
+    key?: string;
+    /** Payload passed to the render-prop (the message, the table, …). */
+    data: T;
+}
+/** The context passed to a {@link HoverTipLayerProps} render-prop. */
+export interface HoverTipRender<T = unknown> {
+    /** The anchored range. */
+    range: RangeCoords;
+    /** The probe payload. */
+    data: T;
+    /** Spread onto the tip element to keep it open while hovered (`pointer-events:auto` + enter/leave). */
+    tipProps: HoverTipProps;
+    /** The resolved sticky state (e.g. `state.scrollIntoView()`). */
+    state: StickyState;
+}
+/**
+ * Props for {@link HoverTipLayer}.
+ */
+export interface HoverTipLayerProps<T = unknown> extends Omit<LayerProps, 'children'> {
+    /** Class for the floated tip container. */
+    className?: string;
+    /** Style for the floated tip container. */
+    style?: React.CSSProperties;
+    /** Probe the hovered cell → a {@link HoverTarget} (range + data), or `null` when nothing should show. */
+    probe: (coords: CellCoords, pane: IGridPane) => HoverTarget<T> | null;
+    /** Which side of the range the tip attaches to. @defaultValue `{ side: 't' }` */
+    placement?: GridPlacement;
+    /** Gap (px) perpendicular to the edge. @defaultValue 6 */
+    offset?: number;
+    /** Offset (px) along the edge (only `start` / `end` align). @defaultValue 0 */
+    alignOffset?: number;
+    /** Dwell (ms) before the tip shows. @defaultValue 300 */
+    openDelay?: number;
+    /** Grace (ms) before the tip hides (bridges the gap to the tip). @defaultValue 150 */
+    closeDelay?: number;
+    /** What happens when the anchor leaves the data area. @defaultValue 'hide' */
+    whenOff?: GridWhenOff;
+    /** Clip / clamp boundary. @defaultValue 'data' */
+    boundary?: GridBoundary;
+    /** @defaultValue 1250 */
+    zIndex?: number;
+    /**
+     * Edge-triggered hard dismissal: when this transitions truthy the current tip closes **immediately**
+     * (bypassing `closeDelay`) — e.g. the anchored cell entered edit mode. It does not hold the tip
+     * closed; a subsequent hover re-opens it normally.
+     */
+    dismiss?: boolean;
+    /** Render the tip. **Spread `tipProps`** on the returned element so hovering it keeps the tip open. */
+    children: (info: HoverTipRender<T>) => React.ReactNode;
+}
+/**
+ * The reusable **hover-tooltip layer**: sweeps the pointer over cells (a {@link Layer} tap +
+ * `getCellFromPointer`), asks a {@link HoverTipLayerProps.probe} whether the hovered cell has something
+ * to show, and — via the shared hover intent ({@link useHoverIntent}) — floats a {@link StickyFloat} tip
+ * (with flip / shift). The probe supplies the anchor range + payload; the render-prop draws the tip and
+ * keeps it open on hover. This is the shared engine behind `CellErrorLayer`, a table tip, etc.
+ */
+export declare const HoverTipLayer: <T>(props: HoverTipLayerProps<T>) => React.ReactElement;
+//# sourceMappingURL=HoverTipLayer.d.ts.map

package/types/src/layer/Layer.d.ts

@@ -0,0 +1,92 @@
+import { IGridPane } from '../surface';
+/**
+ * What a {@link Layer} contributes to the subtree it hosts, read with {@link useLayer}.
+ */
+export interface LayerHandle {
+    /**
+     * The layer's **z-slot** — its position in the grid's normalized layer list (react declaration
+     * order with explicit-`zIndex` overrides already folded in by `normalizeLayers`), i.e. the
+     * "effective z" a dev means by *visual order*, **not** any raw `zIndex` prop. Nested content (a
+     * command scope) registers at it so keystroke / command dispatch follows the visual stack. Derived
+     * purely from the React list — no DOM, and stable across remounts (it's the LIST position, not
+     * when a responder registered).
+     */
+    zIndex: number;
+    /** The enclosing grid pane (null outside a pane — e.g. in a portal). */
+    pane: IGridPane | null;
+}
+/**
+ * Read the enclosing {@link Layer}'s slot: `{ zIndex, pane }`.
+ */
+export declare const useLayer: () => LayerHandle;
+/**
+ * The event-tap handler props a {@link Layer} accepts — the layer's own handlers, fired as the
+ * **boundary of its z-slot**: when the event's target is inside this layer they fire natively as
+ * the outermost step of the subtree bubble; for every other layer's turn the Stage invokes them at
+ * this layer's slot in the walk (strict z order — keys and pointers alike). Consume an event with
+ * `event.stopPropagation()` (the one-bubble law's single consume signal). The events are real:
+ * `event.target` is the actual element under the pointer, and
+ * `pane.getCellFromPointer(e.clientX, e.clientY)` resolves the cell.
+ */
+export interface LayerEventProps {
+    onPointerDown?: (event: React.PointerEvent) => void;
+    onPointerMove?: (event: React.PointerEvent) => void;
+    onPointerUp?: (event: React.PointerEvent) => void;
+    onPointerLeave?: (event: React.PointerEvent) => void;
+    onMouseDown?: (event: React.MouseEvent) => void;
+    onMouseEnter?: (event: React.MouseEvent) => void;
+    onMouseLeave?: (event: React.MouseEvent) => void;
+    onMouseMove?: (event: React.MouseEvent) => void;
+    onMouseOut?: (event: React.MouseEvent) => void;
+    onMouseOver?: (event: React.MouseEvent) => void;
+    onMouseUp?: (event: React.MouseEvent) => void;
+    onDoubleClick?: (event: React.MouseEvent) => void;
+    onKeyDown?: (event: React.KeyboardEvent) => void;
+    onKeyPress?: (event: React.KeyboardEvent) => void;
+    onKeyUp?: (event: React.KeyboardEvent) => void;
+    onFocus?: (event: React.FocusEvent) => void;
+    onBlur?: (event: React.FocusEvent) => void;
+    onContextMenu?: (event: React.MouseEvent) => void;
+}
+/**
+ * Props for {@link Layer}.
+ */
+export interface LayerProps extends LayerEventProps {
+    /**
+     * Explicit stacking override, read by `normalizeLayers` **off the grid-child element** to sort the
+     * layer list (higher sorts later = on top; omitted ⇒ declaration order). It is honored ONLY at the
+     * grid-children level — the layer's actual dispatch slot always comes from the resulting order
+     * index (via {@link LayerOrderContext}), never from this raw number, so paint order and event
+     * order can never disagree.
+     */
+    zIndex?: number;
+    /** Class for the layer's boundary div (devtools identification). */
+    className?: string;
+    /**
+     * The layer's content — {@link VirtualDiv}s, `RangeRect`s, floats — hosted inside the layer's
+     * boundary div. Children stack by DOM order within the layer (law 1).
+     */
+    children?: React.ReactNode;
+}
+/**
+ * A **Layer**: the containment boundary of one z-slot. It renders a single invisible, view-sized
+ * `<div>` (law 2: never paints, never a hit target — `pointer-events:none`; children opt back in)
+ * whose DOM presence is what gives every element inside it its **layer membership**: the dispatch
+ * resolves an event's layer by ancestry, so anything you host — VirtualDivs, plain elements,
+ * third-party widgets — participates in the z-order automatically.
+ *
+ * - **z-slot** — the layer's position in the grid's stack. It orders painting (DOM order of the
+ *   sorted list) *and* event dispatch: the whole grid follows ONE rule — layers on top get events
+ *   first, keys and pointers alike (law 3).
+ * - **event tap** — the layer's own handlers (`onPointerMove`, `onKeyDown`, …): the boundary of its
+ *   slot. When the event's target is inside this layer they fire natively as the outermost step of
+ *   the layer's own subtree bubble ("standard child eventing" ends at the layer); for every other
+ *   layer's turn the Stage invokes them at this slot in the walk. Consume with
+ *   `event.stopPropagation()`.
+ *
+ * Layers exist only as direct children of a `GridSurface` / `Grid` (law 4: the stack is flat) — a
+ * composite feature is a component that renders exactly one Layer at its root. Dev-enforced: a
+ * Layer errors when nested inside another Layer.
+ */
+export declare const Layer: import('react').MemoExoticComponent<(props: LayerProps) => import("react").JSX.Element>;
+//# sourceMappingURL=Layer.d.ts.map

package/types/src/layer/LayerTypes.d.ts

@@ -0,0 +1,47 @@
+import { RangeCoords, Bounds } from '@sheetxl/utils';
+/**
+ * The placement core shared by {@link VirtualDiv} and the shape leaves: WHERE to place — a `range`
+ * (resolved via the pane), explicit `bounds`, or `fill` (the whole view) — and how much off-screen
+ * slack to keep. Exactly one of `range` | `bounds` | `fill` must be provided.
+ */
+export interface VirtualDivPlacement {
+    /**
+     * The range to place at. Resolved to absolute bounds via the current pane. Provide this OR
+     * {@link bounds} OR {@link fill}.
+     */
+    range?: RangeCoords;
+    /**
+     * Explicit absolute bounds to place at (already resolved). Provide this OR {@link range} OR
+     * {@link fill}.
+     */
+    bounds?: Bounds;
+    /**
+     * Size to the view (the pane), never culled. For full-view content: a background wash, a canvas
+     * host, a pointer-capture surface, a container that needs real CSS (`overflow`, `opacity`,
+     * `filter`, a scroll-carrying transform) applied to a whole group. Provide this OR {@link range}
+     * OR {@link bounds}.
+     */
+    fill?: boolean;
+    /**
+     * View-pixel slack for the off-screen cull. A negative value extends outside the viewport, keeping
+     * a just-off-screen box visible.
+     */
+    clipInsets?: number;
+}
+/**
+ * The layers of a `GridSurface` / `Grid`, bottom → top — an ordinary React node, or an array of
+ * them. Each child renders exactly one {@link Layer} at its root (dev-enforced) and reads its pane
+ * from context ({@link useGridPane}):
+ *
+ * @example
+ * <GridSurface><MyLayer /></GridSurface>
+ *
+ * @remarks
+ * Structurally this is just `React.ReactNode` (an array of nodes is itself a node); the name only
+ * documents intent at the `children` site.
+ *
+ * For the rare case that needs the pane to build the element itself (rather than reading it from
+ * context inside the component), call {@link useGridPane} from a small wrapper component.
+ */
+export type LayerNode = React.ReactNode | (React.ReactNode[]);
+//# sourceMappingURL=LayerTypes.d.ts.map

package/types/src/layer/RangePrompt.d.ts

@@ -0,0 +1,42 @@
+import { default as React } from 'react';
+import { RangeCoords } from '@sheetxl/utils';
+import { StickyState } from './StickyAnchor';
+import { GridPlacement } from './useGridAnchor';
+/**
+ * Props for {@link RangePrompt}.
+ */
+export interface RangePromptProps {
+    /** The range the prompt is pinned to. */
+    range: RangeCoords;
+    /** Where the prompt attaches relative to the range. @defaultValue `{ side: 't', align: 'start' }` */
+    placement?: GridPlacement;
+    /** Gap (px) perpendicular to the edge. @defaultValue 8 */
+    offset?: number;
+    /** Offset (px) along the edge (only `start` / `end` align). @defaultValue 0 */
+    alignOffset?: number;
+    /** Label for the out-of-view goto pill. @defaultValue the range's A1 address (e.g. `E11:H15`) */
+    address?: string;
+    /**
+     * Called by the out-of-view "Go to range" affordance. Defaults to `state.scrollIntoView()` (grid-level
+     * reveal); provide to also select at the sheet level (`sheet.getRange(addr).select()`).
+     */
+    onGoto?: (state: StickyState) => void;
+    /** Called by the small cancel (×) button. The host unmounts the layer in response. */
+    onCancel?: () => void;
+    /** @defaultValue 1250 */
+    zIndex?: number;
+    className?: string;
+    style?: React.CSSProperties;
+    /** The client prompt content (option buttons, the AI question UI, …). A node or `(state) => node`. */
+    children?: React.ReactNode | ((state: StickyState) => React.ReactNode);
+}
+/**
+ * A **persistent prompt pinned to a range** — the "presence" flavor of {@link StickyFloat} (always open,
+ * not hover). While the range is in view it renders the client content (injectable option buttons — e.g.
+ * an AI question about the range) with a small **cancel** (×). When the range scrolls **out of view** it
+ * clamps to the edge and swaps to a compact **arrow + "Go to range"** pill (which reveals it via
+ * `state.scrollIntoView()`, or your `onGoto`). Controlled: the host mounts / unmounts it (cancel calls
+ * `onCancel`).
+ */
+export declare const RangePrompt: React.FC<RangePromptProps>;
+//# sourceMappingURL=RangePrompt.d.ts.map

package/types/src/layer/Stage.d.ts

@@ -0,0 +1,147 @@
+import { RemoveListener } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+/**
+ * A handler in the dispatch walk. Receives the React synthetic event and the owning pane.
+ * Call `event.stopPropagation()` to consume the event — lower layers and the pane/app then do
+ * not see it (the one-bubble law's single consume signal).
+ */
+export type StageEventHandler = (event: React.SyntheticEvent, pane: IGridPane) => void;
+/**
+ * A {@link Layer} tap's registration with the Stage.
+ *
+ * @remarks
+ * The Stage is the convergence hub: every Layer registers one tap and the Stage offers each event
+ * down the walk in slot order (higher first), then registration (render) order, stopping when one
+ * consumes.
+ */
+export interface StageResponder {
+    /**
+     * The layer's dispatch **slot** — its derived order index in the grid's normalized layer list
+     * (see `LayerOrderContext`). Higher is offered the event first; ties break by registration
+     * (render) order REVERSED, so the later-declared layer (which paints on top) is offered first.
+     */
+    zIndex?: number;
+    /**
+     * Live accessor for the layer's boundary div. The dispatch resolves an event's **layer
+     * membership** by ancestry against these elements (which layer does the target belong to?) — the
+     * point of the Layer being a real div. Optional for element-less responders (the pane command
+     * terminal, `addReactEventListener` shims), which have no membership to resolve.
+     */
+    getElement?: () => Element | null;
+    /**
+     * Returns the current handler for a native event type (`'pointerdown'`, `'keydown'`,
+     * …), or `undefined`. Called per-dispatch, so it always sees the latest closures — a
+     * responder is registered once (not per render) and handler identity may change freely.
+     */
+    getHandler: (type: string) => StageEventHandler | undefined;
+}
+/**
+ * A geometried box's registration with the Stage (a {@link VirtualDiv}). Unlike a
+ * {@link StageResponder} (a Layer's zero-geometry tap), a box owns a real DOM element, so the
+ * DOM-driven dispatch can map a hit element to its box, resolve the boxes under the pointer, and
+ * skip the native target (whose handlers already fired in the "up your subtree" phase).
+ *
+ * @remarks
+ * Kept in a SEPARATE registry from the tap chain on purpose: there can be very many boxes
+ * (e.g. one fill per cell), and the tap chain is sorted on every event — boxes must not
+ * inflate that hot path. The dispatch resolves boxes geometrically (the DOM already stacks them),
+ * not by iterating this set per event.
+ */
+export interface LayerRegistration {
+    /**
+     * The box's enclosing Layer's dispatch **slot** (from `LayerOrderContext`). Interleaves the box
+     * with the Layer taps in the single walk: a box fires between the taps of the layers above and
+     * below its own.
+     */
+    zIndex?: number;
+    /** Live accessor for the box's DOM element (null while culled / unmounted). */
+    getElement: () => Element | null;
+    /**
+     * Per-type handler accessor (as {@link StageResponder.getHandler}). The DOM-driven dispatch uses
+     * it to invoke a box that is BELOW the native target (so it did not receive the event natively;
+     * the hit box fires its own handlers natively — the up phase). Boxes with no handlers omit it.
+     */
+    getHandler?: (type: string) => StageEventHandler | undefined;
+    /**
+     * Whether this box currently has any event handlers. Drives the dispatch fast-path: when NO
+     * registered box has handlers (the entire normal grid — fills / borders / selection visuals),
+     * the geometried pass is skipped entirely, so it adds zero per-event cost.
+     */
+    hasHandlers?: boolean;
+}
+/**
+ * The event types a {@link VirtualDiv}'s registered handlers are invoked for on **other layers'
+ * turns** (a box below the hit layer, under the pointer). These are the positional, bubbling
+ * events. A box's handlers are ordinary native props — they fire natively when the box is on the
+ * event's target chain (its own layer's turn, phase 2); this registry map covers the pass-through
+ * case (phase 3). Relational (`enter`/`leave`), focus, and key events are targeted — the DOM's own
+ * delivery is already correct, so boxes never receive them positionally (Layer taps do, via the
+ * ordered walk).
+ */
+export declare const WALKED_EVENT_TYPE_TO_PROP: Record<string, string>;
+/** The walk-dispatched box prop names (values of {@link WALKED_EVENT_TYPE_TO_PROP}). */
+export declare const WALKED_EVENT_PROPS: string[];
+/**
+ * The event types the **three-phase dispatch** fully orders (law 3: layers on top hear events
+ * first — keys and pointers alike): the positional walked types PLUS keys. For these:
+ * - **phase 1** — a native CAPTURE listener on the Stage offers the event to the taps of every
+ *   layer ABOVE the hit layer (top first), before the native dispatch runs;
+ * - **phase 2** — the native dispatch runs the hit layer's own subtree, exactly as React does
+ *   (inner content, then any boxes on the chain, then the layer's own boundary handlers);
+ * - **phase 3** — the Stage's bubble handlers continue the walk strictly BELOW the hit layer
+ *   (under-pointer boxes + taps, in slot order).
+ * `stopPropagation()` anywhere ends the whole bubble. Everything else (enter/leave/focus/blur) is
+ * stage-relational: a single unbounded tap walk.
+ */
+export declare const ORDERED_EVENT_TYPES: readonly string[];
+export interface IStageAttributes {
+    /**
+     * Add a listener for a single event type to the stage. Primarily grid-internal plumbing —
+     * external callers use {@link IGridPane.addReactEventListener} (which delegates here); layers
+     * use {@link Layer} taps instead.
+     */
+    addReactEventListener(type: string, listener: (event: React.SyntheticEvent) => void, listenerPane?: (event: React.SyntheticEvent, pane: IGridPane) => void): RemoveListener;
+    isStage(): true;
+}
+export interface IStageElement extends HTMLDivElement, IStageAttributes {
+}
+/**
+ * @internal
+ * The responder registry the Stage implementation also provides. Deliberately kept off the public
+ * {@link IStageElement} — Layers join the dispatch walk via their tap, which reaches
+ * this through {@link IStageElementInternal}.
+ */
+export interface IStageResponderHost {
+    /** Register a (non-visual, broadcast) responder in the responder chain. Returns a remover. */
+    registerResponder(responder: StageResponder): RemoveListener;
+    /**
+     * Register a geometried layer (a {@link Layer}). Returns a remover. Stored
+     * apart from the responder chain (see {@link LayerRegistration}); consumed by the DOM-driven
+     * dispatch, not by the per-event responder fan-out.
+     */
+    registerLayer(layer: LayerRegistration): RemoveListener;
+}
+/** @internal Stage element augmented with the responder registry (used by `Layer` / `useLayerResponder`). */
+export interface IStageElementInternal extends IStageElement, IStageResponderHost {
+}
+/**
+ * @internal
+ * Resolve a pane's Stage element WITH the responder registry (grid-internal; the registry is
+ * deliberately off the public pane API — external callers get {@link IGridPane.addReactEventListener}).
+ * The pane's surface element IS its Stage, brand-checked via `isStage` so a non-stage host (e.g. a
+ * static-border stub pane) resolves to `null` and the caller skips registration.
+ */
+export declare const getStageInternal: (pane: IGridPane | null | undefined) => IStageElementInternal | null;
+export interface StageProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * Ref for the HTMLDivElement
+     */
+    ref?: React.Ref<IStageElement>;
+}
+/**
+ * Stage
+ *
+ * Internally used to distinguish the main grid area.
+ */
+export declare const Stage: import('react').NamedExoticComponent<Omit<StageProps, "ref"> & import('react').RefAttributes<IStageElement>>;
+//# sourceMappingURL=Stage.d.ts.map

package/types/src/layer/StickyAnchor.d.ts

@@ -0,0 +1,83 @@
+import { default as React } from 'react';
+import { Bounds, Point, AnchorLocation } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+import { GridAnchor, GridPlacement, GridBoundary, GridWhenOff, GridSlide } from './useGridAnchor';
+/**
+ * The state a {@link StickyAnchor} publishes to its child. Carries the resolved `anchorPoint` (+ owner /
+ * clip / slide state) so the child alone decides how to render:
+ *
+ * - a **render-prop** child self-positions — e.g. a portal that escapes the clip and flows past the
+ *   pane bounds (this is what {@link StickyFloat} does for you);
+ * - a plain **node** ("just a div") is positioned INLINE by StickyAnchor, clipping with the pane.
+ *
+ * `StickyAnchor` itself is portal-agnostic; it only resolves the anchor and positions inline divs.
+ */
+export interface StickyState {
+    /** Client-space Floating UI virtual reference (stable identity; reads live). */
+    reference: {
+        getBoundingClientRect: () => DOMRect;
+    };
+    /** Client-space boundary rect (for `flip`/`shift`/`hide` limiters). */
+    getBoundaryRect: () => DOMRect;
+    /** The placement's anchor pixel (client px). */
+    anchorPoint: Point;
+    /** Pane-relative range bounds (for an in-grid child) — only meaningful on the owner pane, else null. */
+    bounds: Bounds | null;
+    /** The pane that owns the anchor pixel (null when clipped off every pane). */
+    owner: AnchorLocation | null;
+    /** Whether THIS instance's pane is the owner — the child self-gates on it (render once / correct pane). */
+    isOwner: boolean;
+    /** Anchor outside the boundary. */
+    clipped: boolean;
+    /** The clamp slide (distance/direction) when `whenOff: 'clamp'` pushed it in-frame, else null. */
+    slid: GridSlide | null;
+    /**
+     * The anchored range is **fully scrolled off** (no visible portion) — stays true under `whenOff:
+     * 'clamp'` (unlike {@link clipped}), so a presence can distinguish "partially obstructed / clamped"
+     * (keep showing) from "off-screen" (show a goto affordance).
+     */
+    outOfView: boolean;
+    /** The resolved placement. */
+    placement: GridPlacement;
+    /** This instance's pane (null outside a `GridPaneProvider`). */
+    pane: IGridPane | null;
+    /**
+     * Scroll the anchor's top-left cell into view — the grid-level "reveal" for a render-prop child (e.g.
+     * a clamped Presence label whose click should bring its range back on-screen). No-op for anchors
+     * without a cell (`bounds` / `edge` / `point`) or outside a pane. This is reveal only; selection lives
+     * a layer up (`sheet.getRange(addr).select()`).
+     */
+    scrollIntoView: (options?: globalThis.ScrollIntoViewOptions | boolean) => Promise<unknown>;
+}
+/** Read the enclosing {@link StickyAnchor}'s state. Throws outside one. */
+export declare const useSticky: () => StickyState;
+/** Read the enclosing {@link StickyAnchor}'s state, or null outside one. */
+export declare const useStickyOptional: () => StickyState | null;
+/**
+ * Props for {@link StickyAnchor}.
+ */
+export interface StickyAnchorProps {
+    /** WHERE to anchor — a grid coordinate (range / cell / bounds / edge / point). */
+    anchor: GridAnchor;
+    /** Which side + align of the anchor the float attaches to (picks the single anchor pixel). */
+    placement?: GridPlacement;
+    /** Clip / clamp boundary (client-space math input, not a DOM parent). @defaultValue 'data' */
+    boundary?: GridBoundary;
+    /** What happens when the anchor pixel leaves the data area. @defaultValue 'hide' */
+    whenOff?: GridWhenOff;
+    /** Px overlap below which a geometried anchor reads as clipped. @defaultValue 0 */
+    minVisible?: number;
+    /** The child — a node, or a render function `(state) => node`. Reads state via {@link useSticky} too. */
+    children?: React.ReactNode | ((state: StickyState) => React.ReactNode);
+}
+/**
+ * A **sticky** grid layer: it resolves an {@link GridAnchor} (via {@link useGridAnchor}) to a live
+ * anchor point and positions its child there. A plain `<div>` child is placed **inline** (clips with
+ * the pane); a **render-prop** child self-positions (e.g. a portal — see {@link StickyFloat}). It owns
+ * no portal and knows nothing about Floating UI.
+ *
+ * Rendered per pane like any layer; each instance publishes its own `isOwner`, so only the owner pane
+ * renders the child (once).
+ */
+export declare const StickyAnchor: React.FC<StickyAnchorProps>;
+//# sourceMappingURL=StickyAnchor.d.ts.map