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

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

@@ -0,0 +1,65 @@
+import { default as React } from 'react';
+import { ThemeAttrs } from '@sheetxl/utils-react';
+import { IGridPane } from '../surface';
+import { StickyState } from './StickyAnchor';
+import { GridAnchor, GridPlacement, GridBoundary, GridWhenOff } from './useGridAnchor';
+/**
+ * Carry a grid float's theme **across the portal boundary**. A grid float portals into the shared,
+ * theme-free fullscreen root, where the grid's `--sxl-color-*` tokens do NOT cascade in (the CSS cascade
+ * doesn't cross a portal — unlike MUI content, which rides React context and so themes for free). Returns
+ * the `className` + `data-sxl-theme-*` attrs to put on the portaled element so the token rules resolve —
+ * the same mechanism `FloatPopper` uses for menus.
+ *
+ * Two parts, because the app themes with `@scope` (per-instance), not just global attribute rules:
+ * - **attrs** — the pane's live `mode` / `surface` (grid surface, and the grid's own mode even if it
+ *   differs from the app). These select WHICH token values apply.
+ * - **className** — the theme **scope class(es)** (the float surface's, plus the nearest token provider's
+ *   `scopeClass` when the instance is isolated). Without a scope class the portaled element is outside
+ *   every `@scope` root, so the `@scope (.cls){ :scope[mode][surface]{…} }` rules never match it and the
+ *   attrs alone resolve nothing. The class makes the portal a `:scope` root so those rules apply.
+ */
+export declare const useGridFloatTheme: (pane: IGridPane | null | undefined) => {
+    className?: string;
+    attrs: ThemeAttrs;
+};
+/**
+ * Props for {@link StickyFloat}.
+ */
+export interface StickyFloatProps {
+    /** WHERE to anchor — a grid coordinate (range / cell / bounds / edge / point). */
+    anchor: GridAnchor;
+    /** Which side + align the float attaches to. @defaultValue `{ side: 't', align: 'center' }` */
+    placement?: GridPlacement;
+    /** What happens when the anchor leaves the data area. @defaultValue 'hide' */
+    whenOff?: GridWhenOff;
+    /** Clip / clamp boundary. @defaultValue 'data' */
+    boundary?: GridBoundary;
+    /** Px overlap below which a geometried anchor reads as clipped. @defaultValue 0 */
+    minVisible?: number;
+    /** Gap (px) between the anchor edge and the float. @defaultValue 4 */
+    offset?: number;
+    /**
+     * Offset (px) along the anchor EDGE — only applies to `start` / `end` alignment (a centered float has
+     * no edge to slide along). Positive insets the float inward from the corner. @defaultValue 0
+     */
+    alignOffset?: number;
+    /** Controlled visibility (e.g. a hover tooltip). @defaultValue true */
+    open?: boolean;
+    /** Portal container. @defaultValue the fullscreen-aware root ({@link useFullscreenPortal}). */
+    container?: Element;
+    className?: string;
+    style?: React.CSSProperties;
+    /** @defaultValue 1250 (a below-modal band; see FLOATING-DESIGN §z-index). */
+    zIndex?: number;
+    /** The float content — a node, or a render function `(state) => node` (e.g. to react to `slid`). */
+    children?: React.ReactNode | ((state: StickyState) => React.ReactNode);
+}
+/**
+ * The ergonomic **floating label**: a {@link StickyAnchor} that renders its child in a **portal**
+ * (escaping the pane clip, so it can flow past the pane bounds — e.g. overhang a freeze line) anchored
+ * at the resolved point. The common case — `<StickyFloat anchor={{ range }}>A1:B4</StickyFloat>` —
+ * with no hand-written `createPortal`. For an in-grid (clipping) label, use `<StickyAnchor>` with a plain
+ * `<div>` child instead.
+ */
+export declare const StickyFloat: React.FC<StickyFloatProps>;
+//# sourceMappingURL=StickyFloat.d.ts.map

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

@@ -0,0 +1,59 @@
+import { VirtualDivPlacement } from './LayerTypes';
+export interface VirtualDivProps extends React.HTMLAttributes<HTMLDivElement>, VirtualDivPlacement {
+    /**
+     * Skip device-pixel edge alignment. By default the box edges are snapped to the
+     * device grid (so content stays crisp and adjacent boxes sharing an edge resolve to
+     * the same pixel — no seam). Turn off for a raw, unaligned box.
+     *
+     * @defaultValue false
+     */
+    disableAlign?: boolean;
+    /**
+     * Extend the right/bottom edges by 1 device px so the box covers all four of its
+     * gridline pixels (a gridline paints the boundary PIXEL `[B, B+1]`). Adjacent boxes
+     * then overlap by 1px at the shared boundary — intended, like Excel cell fills.
+     *
+     * @defaultValue false
+     */
+    coverGridlines?: boolean;
+    /**
+     * Render an aligned **border** of this many DEVICE px instead of a fill. The edges are placed on
+     * the boundary centerline (`edgeCenter`, leading straddles / trailing grows outward) — the same
+     * rule as gridlines and {@link RectangleSVG} — so the border lines up with the selection rectangle
+     * exactly. The box is `border-box`; set the color via `style.borderColor`.
+     *
+     * @remarks
+     * This is the HTML-`border-box` counterpart of {@link RectangleSVG}'s stroke. Use it for a
+     * **content-hosting** box that needs a matching border (the cell editor: the content auto-insets
+     * inside the border). For a pure outline/fill overlay, prefer {@link RectangleSVG}/`RangeRect`.
+     */
+    alignWidth?: number;
+    /**
+     * Keep the element mounted (positioned off-screen) instead of culling to `null` when off-screen.
+     * For always-mounted content such as the cell editor, whose input must never unmount.
+     *
+     * @defaultValue false
+     */
+    keepMounted?: boolean;
+}
+/**
+ * A **VirtualDiv**: a `<div>` whose bounds are driven by the grid metrics. Place it at a `range`
+ * (cell coordinates), `bounds` (grid-space pixels), or `fill` (the whole view); it resolves the
+ * placement via the current pane, culls when off-screen, and device-aligns its edges — then hosts
+ * any content (CSS background/gradient/pattern for fills, children like images / widgets /
+ * movables, or SVG shape leaves like {@link RectangleSVG}).
+ *
+ * Everything you know about divs applies — pointer events, focus (`tabIndex`), refs, CSS, children —
+ * and means what it always means. It is **hittable by default**, exactly like a real div; a
+ * decoration opts out with `style.pointerEvents:'none'` (never a hit target; a child shape can
+ * re-enable `pointer-events` on its stroke to opt back in). Its handlers are ordinary native props
+ * that fire **at its layer's turn** in the ordered bubble (law 3: layers on top hear events first —
+ * when the hit is inside this box the native dispatch IS its layer's turn; when the box sits in a
+ * lower layer under the pointer, the Stage invokes its positional handlers at that slot). Call
+ * `event.stopPropagation()` to consume — there is no auto-consume and no passthrough flag. Render
+ * it inside a {@link Layer} (which is what gives it — and everything inside it — its layer
+ * membership); with frozen panes each pane instantiates one. For multiple ranges, map it in the
+ * consumer (one per range).
+ */
+export declare const VirtualDiv: import('react').NamedExoticComponent<VirtualDivProps & import('react').RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=VirtualDiv.d.ts.map

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

@@ -0,0 +1,37 @@
+import { RangeCoords } from '@sheetxl/utils';
+import { LayerNode } from './LayerTypes';
+/** Content key for a range — stable across object identity (dedupe / memo / hover-target keys). */
+export declare const rangeKey: (r: RangeCoords) => string;
+/**
+ * A layer's **derived stacking order** — its index in the normalized layer list, i.e. the react list
+ * order with explicit-`zIndex` overrides already folded in (see {@link normalizeLayers}). This is the
+ * "effective z" a dev means by *visual order* — **not** the raw `zIndex` prop. The {@link Layer} at
+ * each slot registers its event tap at it, and descendant command scopes read it (via `useLayer`) so
+ * keystroke / command dispatch follows the visual stack. Derived purely from the React list — **no
+ * DOM, no registration timing**.
+ */
+export declare const LayerOrderContext: import('react').Context<number>;
+/**
+ * Whether the current subtree is inside a {@link Layer}. Backs the flat-stack law (law 4): a `Layer`
+ * dev-errors when it finds itself already inside one, and a {@link VirtualDiv} dev-warns when it is
+ * NOT inside one. Purely a dev-time diagnostic — no runtime behavior branches on it.
+ */
+export declare const LayerScopeContext: import('react').Context<boolean>;
+/**
+ * Normalize the layers (the grid's children) for rendering: sort by `zIndex` and stamp each with its
+ * **derived order index** (its position in the sorted list = its effective z). A non-array passes
+ * through unchanged.
+ *
+ * @remarks
+ * Ordering matches the CSS model: sort by `zIndex` **ascending** (higher paints later = on top); a layer
+ * without a `zIndex` counts as `0`, and `Array.prototype.sort` is stable so same-`zIndex` layers keep
+ * **declaration order** — exactly as `z-index: auto` behaves. The `zIndex` is read off the top-level
+ * child element (a `<Layer zIndex>` or a composite forwarding one) — this is the ONLY place z is
+ * honored; a Layer's dispatch slot always comes from the resulting order index. Each sorted layer is
+ * wrapped in a {@link LayerOrderContext} carrying its index, so its `Layer` (and any descendant command
+ * scope) reads its effective stacking order — the react-list analog of CSS paint order. That index is
+ * stable across remounts / effect re-runs (it is the LIST position, not when a responder registered)
+ * and needs **no DOM**. Keyed by the element's own key so a reorder re-slots (not remounts).
+ */
+export declare const normalizeLayers: (layers: LayerNode) => React.ReactNode;
+//# sourceMappingURL=_Utils.d.ts.map

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

@@ -0,0 +1,11 @@
+export * from './LayerTypes';
+export * from './Layer';
+export * from './VirtualDiv';
+export type { GridAnchor, GridPlacement, GridWhenOff, GridBoundary, GridFloatSide, GridAlign, GridSlide } from './useGridAnchor';
+export * from './StickyAnchor';
+export * from './StickyFloat';
+export * from './useHoverIntent';
+export * from './useRangeHover';
+export * from './HoverTipLayer';
+export * from './RangePrompt';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,157 @@
+import { CellCoords, RangeCoords, Bounds, Point, AnchorLocation } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+/**
+ * A viewport edge (used by `edge` anchors and reported by {@link GridAnchorResolved.clampedTo}).
+ */
+export type GridFloatSide = 't' | 'l' | 'r' | 'b';
+/** Alignment along the anchored edge (which end the anchor pixel sits at). */
+export type GridAlign = 'start' | 'center' | 'end';
+/**
+ * WHERE the float attaches to the range — the `side` it sits on plus the `align` along that edge.
+ * This picks a **single anchor pixel** (a corner / edge-midpoint) which decides pane ownership and
+ * clip (that one pixel is in exactly one pane), while positioning still uses the whole range rect.
+ * Maps to a Floating UI `Placement` at the `FloatPopper` boundary (`t-start` → `top-start`, …).
+ */
+export interface GridPlacement {
+    side: GridFloatSide;
+    /** @defaultValue 'center' */
+    align?: GridAlign;
+}
+/**
+ * What happens when **no pane owns the anchor pixel** (it scrolled off the data area).
+ *
+ * - `'hide'` — not rendered (touch handles once their range is gone; ephemeral tooltips). Default.
+ * - `'clamp'` — project the pixel onto the nearest data edge and slide it there (sticky / presence);
+ *   the owner becomes the pane under the clamped pixel and {@link GridAnchorResolved.slid} is set.
+ */
+export type GridWhenOff = 'hide' | 'clamp';
+/**
+ * How far the anchor pixel was pushed to stay in frame (the `clamp` fallback). Handed to the sticky
+ * child so it can render differently when slid — an arrow toward the true (off-frame) anchor, etc.
+ */
+export interface GridSlide {
+    /** Client-px offset applied to the anchor to clamp it into the boundary. */
+    dx: number;
+    dy: number;
+    /** Magnitude of the push (`hypot(dx, dy)`). */
+    distance: number;
+    /** The edge it slid to — the direction of the true, off-frame anchor. */
+    direction: GridFloatSide;
+}
+/**
+ * WHERE a grid float is anchored — a **grid coordinate**, resolved live to a client rect via the
+ * pane. The float tracks it across scroll / zoom / resize / freeze.
+ *
+ * - `range` — a cell range (the primary "virtual range" case).
+ * - `cell` — a single cell.
+ * - `bounds` — pane **view-relative** bounds (same space `getBoundsFromRange` returns).
+ * - `edge` — the midpoint of a viewport edge (touch handles / scrollbars).
+ * - `point` — a **client-px** point (drag readouts that follow the pointer).
+ */
+export type GridAnchor = {
+    range: RangeCoords;
+} | {
+    cell: CellCoords;
+} | {
+    bounds: Bounds;
+} | {
+    edge: GridFloatSide;
+} | {
+    point: Point;
+};
+/**
+ * The clip / clamp boundary — a **rect fed to the positioning math**, NOT a DOM parent. This is how
+ * "don't slide under the headers" is expressed: clamp to the data viewport.
+ *
+ * - `'data'` — the union of the panes' cell areas (headers excluded). Default.
+ * - `'pane'` — just the resolving pane's cell area.
+ * - `'grid'` — currently the same as `'data'` (until a surface/header rect is threaded).
+ * - a {@link Bounds} — an explicit **client-px** rect.
+ */
+export type GridBoundary = 'data' | 'pane' | 'grid' | Bounds;
+/** A `DOMRect`-shaped plain object (works in Floating UI and in Node tests without a DOM). */
+export interface GridAnchorRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    top: number;
+    left: number;
+    right: number;
+    bottom: number;
+}
+/** The full resolution of a {@link GridAnchor} at a moment in time. */
+export interface GridAnchorResolved {
+    /** The anchor's client rect (what Floating UI positions against). */
+    rect: GridAnchorRect;
+    /** True when the anchor is fully outside {@link boundaryRect}. */
+    clipped: boolean;
+    /** The clip / clamp boundary in client px. */
+    boundaryRect: GridAnchorRect;
+    /** When clipped, which side the anchor is off (for `clamp` / presence); else `null`. */
+    clampedTo: GridFloatSide | null;
+    /**
+     * The single anchor pixel (client px) the `placement` picks out — the corner / edge-midpoint that
+     * decides ownership + clip. For a straddling range this pixel lives in exactly one pane.
+     */
+    anchorPoint: Point;
+    /** The pane (by anchor location) that owns the anchor pixel — the single render owner. */
+    owner: AnchorLocation | null;
+    /** Set (non-null) only under the `clamp` fallback when the anchor slid to stay in frame. */
+    slid: GridSlide | null;
+    /**
+     * The anchor's range has **no visible portion** (fully scrolled off) — independent of `whenOff`. Unlike
+     * {@link clipped} (which `clamp` forces false), this stays true under `clamp`, so a presence can tell
+     * "partially obstructed / clamped" (still show) from "off-screen" (show a goto affordance).
+     */
+    outOfView: boolean;
+}
+/** The hook result: stable live accessors + render-time snapshot values. */
+export interface UseGridAnchorResult {
+    /**
+     * A Floating UI **virtual reference** with **stable identity** — its `getBoundingClientRect` reads
+     * the anchor **live** on every call (Floating UI's `autoUpdate` invokes it between React renders).
+     */
+    reference: {
+        getBoundingClientRect: () => DOMRect;
+    };
+    /** Live accessor for the boundary rect (for `shift`/`flip`/`hide` limiters). */
+    getBoundaryRect: () => DOMRect;
+    /** Render-time snapshot: anchor outside the boundary. Updates each scroll frame (pane re-render). */
+    clipped: boolean;
+    /** Render-time snapshot: which side the anchor is off, when clipped. */
+    clampedTo: GridFloatSide | null;
+    /** Render-time snapshot: the placement's anchor pixel (client px). */
+    anchorPoint: Point;
+    /** Render-time snapshot: the pane (by anchor location) that owns the anchor pixel. */
+    owner: AnchorLocation | null;
+    /** Render-time snapshot: the slide applied by the `clamp` fallback (else `null`). */
+    slid: GridSlide | null;
+    /** Render-time snapshot: the range is fully scrolled off (stays true under `clamp`; see resolved). */
+    outOfView: boolean;
+    /** The pane the anchor resolves against (null outside a `GridPaneProvider`). */
+    pane: IGridPane | null;
+}
+/** @internal The shared placement default (`StickyAnchor` and the resolver must agree on it). */
+export declare const DEFAULT_PLACEMENT: GridPlacement;
+/**
+ * Resolve a {@link GridAnchor} to a client rect + clip state against a boundary. **Pure** (given a
+ * pane) — no React, no live DOM beyond `getBoundingClientRect`, so it is directly unit-testable with a
+ * fake {@link IGridPane}. Shared by {@link useGridAnchor} (the live closures call this per frame).
+ */
+export declare const resolveGridAnchor: (pane: IGridPane | null, anchor: GridAnchor, boundary?: GridBoundary, minVisible?: number, placement?: GridPlacement, whenOff?: GridWhenOff) => GridAnchorResolved;
+/**
+ * Bridge a {@link GridAnchor} (grid coordinate) to a **live Floating UI virtual reference** plus clip
+ * state. The pane already re-renders every layer on scroll (so the snapshot values update per frame),
+ * and the returned {@link UseGridAnchorResult.reference} reads live on each `getBoundingClientRect`
+ * call so `autoUpdate` keeps the float glued between renders. No hidden measure element, no
+ * scroll-parent walk. Read the pane from context, or pass one explicitly.
+ */
+export declare const useGridAnchor: (anchor: GridAnchor, options?: {
+    pane?: IGridPane;
+    boundary?: GridBoundary;
+    minVisible?: number;
+    placement?: GridPlacement;
+    whenOff?: GridWhenOff;
+}) => UseGridAnchorResult;
+//# sourceMappingURL=useGridAnchor.d.ts.map

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

@@ -0,0 +1,49 @@
+/**
+ * Options for {@link useHoverIntent}.
+ */
+export interface UseHoverIntentOptions {
+    /** Dwell (ms) over a target before opening — kills pass-through flicker. @defaultValue 300 */
+    openDelay?: number;
+    /** Grace (ms) after leaving before closing — lets the pointer cross the gap to the float. @defaultValue 150 */
+    closeDelay?: number;
+}
+/** Props to spread onto the floated element so hovering IT keeps the float open. */
+export interface HoverTipProps {
+    onPointerEnter: () => void;
+    onPointerLeave: () => void;
+    style: React.CSSProperties;
+}
+/**
+ * The result of {@link useHoverIntent}.
+ */
+export interface UseHoverIntentResult {
+    /** Whether the float should be shown. */
+    open: boolean;
+    /**
+     * Aim the intent at a target, or `null` for "nothing hovered". Idempotent per key: calling with the
+     * SAME key (e.g. every `pointermove` within one cell) does NOT restart the open timer. Changing the
+     * key while open re-aims without closing.
+     */
+    setTarget: (key: string | null) => void;
+    /**
+     * Spread onto the floated element so hovering IT keeps the float open (bridges the anchor→float
+     * gap). Sets `pointer-events: auto` and cancels / reschedules the close on enter / leave.
+     */
+    tipProps: HoverTipProps;
+    /**
+     * Close the float **immediately**, bypassing the `closeDelay` grace — for a hard dismissal (e.g. the
+     * anchored cell entered edit mode) rather than the pointer merely wandering off.
+     */
+    close: () => void;
+}
+/**
+ * The reusable **hover-intent state machine** behind a hover tooltip — delays + keep-open-on-tip-hover,
+ * with NO hit-testing of its own. Feed it a target key via {@link UseHoverIntentResult.setTarget}
+ * (`null` = nothing) and it debounces open / close; spread {@link UseHoverIntentResult.tipProps} on the
+ * float so moving onto the float itself keeps it open.
+ *
+ * {@link useRangeHover} wraps this with a pointer responder against a fixed range; a dynamic consumer
+ * (e.g. an error layer discovering the hovered cell) drives `setTarget` itself.
+ */
+export declare const useHoverIntent: (options?: UseHoverIntentOptions) => UseHoverIntentResult;
+//# sourceMappingURL=useHoverIntent.d.ts.map

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

@@ -0,0 +1,29 @@
+/**
+ * Options for {@link useLayerResponder}.
+ */
+export interface UseLayerResponderOptions {
+    /** Live accessor for the box's DOM element (null while culled / unmounted). */
+    getElement: () => Element | null;
+    /**
+     * The box's spread props (`...rest`). Its event handlers (`onPointerDown`, …) are exposed to the
+     * Stage so the box can be invoked when it sits BELOW the native target (where its own handlers
+     * did not fire natively). The handlers stay native on the element too — for the hit case (the
+     * "up your subtree" phase of the one-bubble law).
+     *
+     * (`any`: a JSX spread bag — heterogeneous by nature; only `function`-valued walked-event props
+     * are ever read, guarded by a `typeof` check.)
+     */
+    handlerProps?: Record<string, any>;
+}
+/**
+ * Registers a geometried box ({@link VirtualDiv}) with its pane's Stage so the DOM-driven dispatch
+ * can resolve the box a hit element belongs to, interleave it with the layer taps at its **layer's
+ * slot** (read from {@link LayerOrderContext}), and invoke boxes below the native target.
+ *
+ * @remarks
+ * Registration lives in a registry SEPARATE from the tap chain (see `Stage.LayerRegistration`); the
+ * latest accessors are read through a ref so the registration is stable for the box's life. Call it
+ * unconditionally (before any early `return null`).
+ */
+export declare const useLayerResponder: ({ getElement, handlerProps }: UseLayerResponderOptions) => void;
+//# sourceMappingURL=useLayerResponder.d.ts.map

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

@@ -0,0 +1,18 @@
+import { Bounds } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+import { VirtualDivPlacement } from './LayerTypes';
+/** The resolved placement: the pane, the RAW (pre-snap) bounds, and whether it's fully off-screen. */
+export interface Placement {
+    pane: IGridPane;
+    raw: Bounds;
+    /** True when fully off-screen. The caller decides whether to cull (`return null`) or keep mounted. */
+    culled: boolean;
+}
+/**
+ * Resolve a {@link VirtualDivPlacement} against the current pane: range → bounds (or explicit
+ * bounds, or the pane box for `fill`), plus the off-screen cull flag. Returns `null` when there is
+ * no pane or no placement to resolve. Shared by {@link VirtualDiv} / {@link RangeRect} so the
+ * resolve-and-cull logic lives once.
+ */
+export declare const usePlacement: ({ range, bounds, fill, clipInsets }: VirtualDivPlacement) => Placement | null;
+//# sourceMappingURL=usePlacement.d.ts.map

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

@@ -0,0 +1,35 @@
+import { RangeCoords } from '@sheetxl/utils';
+import { UseHoverIntentOptions, HoverTipProps } from './useHoverIntent';
+/**
+ * The result of {@link useRangeHover}.
+ */
+export interface UseRangeHoverResult {
+    /** Whether a hover tooltip for the range should be shown (after the intent delays). */
+    open: boolean;
+    /** Spread onto the floated tip so hovering it keeps the tooltip open (see {@link HoverTipProps}). */
+    tipProps: HoverTipProps;
+}
+/**
+ * Tracks the pointer over a **fixed grid range** and drives hover-tooltip intent: returns `open` (with
+ * open / close delays) plus `tipProps` to keep the tip open while the pointer is on it. Pair with
+ * {@link StickyFloat} for the label:
+ *
+ * ```tsx
+ * const { open, tipProps } = useRangeHover(range);
+ * <StickyFloat anchor={{ range }} placement={{ side: 't' }} offset={6} open={open}>
+ *   <div {...tipProps}>Value must be a positive number</div>
+ * </StickyFloat>
+ * ```
+ *
+ * Must be called inside a grid (needs pane context). For a **dynamic** target (an error layer that
+ * discovers whichever hovered cell has errors), drive {@link useHoverIntent} directly instead.
+ *
+ * @remarks
+ * Registers a passive `pointermove` / `pointerleave` responder on the pane's Stage (mirrors
+ * a {@link Layer} tap); it never consumes the event. Because a grid child renders per pane, the tip
+ * resolves on the pane owning the anchor — for a range that straddles panes the open state follows the
+ * pointer's pane, which can differ from the owner (a known v1 limitation; small / single-cell ranges,
+ * the common error-tooltip case, are unaffected).
+ */
+export declare const useRangeHover: (range: RangeCoords, options?: UseHoverIntentOptions) => UseRangeHoverResult;
+//# sourceMappingURL=useRangeHover.d.ts.map

package/types/src/list/CheckboxList.d.ts

@@ -0,0 +1,63 @@
+import { default as React } from 'react';
+import { ISelection } from '../selection';
+export interface CheckboxListAttributes {
+    isCheckboxList: () => true;
+}
+export interface ICheckboxListElement extends HTMLDivElement, CheckboxListAttributes {
+}
+/**
+ * Props for {@link CheckboxList}.
+ */
+export interface CheckboxListProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Number of rows. */
+    itemCount: number;
+    /** Whether the item at `index` is checked. */
+    isChecked: (index: number) => boolean;
+    /**
+     * Set `indices` to `checked`. Called with a single index on a click, every selected row on a keyboard
+     * toggle (Space/Enter), and every row from `(Select All)`. The caller maps `index` to its own store.
+     */
+    onCheckedChange: (indices: number[], checked: boolean) => void;
+    /** The value/label content for `index`. */
+    renderValue: (index: number) => React.ReactNode;
+    /**
+     * Render the checkbox **control** (visual only — the row owns the toggle, so it's forced
+     * `pointerEvents:none`). `indeterminate` is set for the `(Select All)` tri-state. Override to use a
+     * styled control (MUI etc.). @defaultValue a native checkbox.
+     */
+    renderCheckbox?: (checked: boolean, indeterminate?: boolean) => React.ReactNode;
+    /**
+     * Render a divider between the `(Select All)` header and the list, or elsewhere as needed.
+     */
+    renderDivider?: () => React.ReactNode;
+    /**
+     * Show a tri-state **(Select All)** header with this label. It operates over *all* rows — which in a
+     * filtered list are the filtered ones, so it's "Select all (filtered)" automatically.
+     */
+    selectAllLabel?: React.ReactNode;
+    /** Uniform row height in px. @defaultValue 24 */
+    itemHeight?: number;
+    /** Selection model (highlight + Arrow nav). Created internally if omitted. */
+    selection?: ISelection;
+    /** Content cache-bust; bump when checked state changes without `isChecked`'s identity changing. */
+    cacheToken?: unknown;
+    /** Ref for the Element. */
+    ref?: React.Ref<ICheckboxListElement>;
+}
+/**
+ * A **checkbox list** on top of {@link List}: a virtualized multi-select with a checkbox per row and an
+ * optional tri-state `(Select All)` header.
+ *
+ * @remarks
+ * Owns the toggle behavior — the part worth not re-deriving:
+ * - **Click** (anywhere on a row) toggles that one row, and selects it.
+ * - **Space / Enter** toggles every *selected* row using the **anchor** (active cell) as the template:
+ *   if the anchor is checked the whole selection clears, otherwise it sets — so a mixed multi-selection
+ *   goes uniform rather than checkerboarding.
+ * - **(Select All)** sets every row to the opposite of the all-checked state.
+ *
+ * Checked state is the caller's store (`isChecked` / `onCheckedChange`), orthogonal to the selection.
+ * Styling is the caller's via {@link CheckboxListProps.renderValue} / {@link CheckboxListProps.renderCheckbox}.
+ */
+export declare const CheckboxList: React.ForwardRefExoticComponent<Omit<CheckboxListProps, "ref"> & React.RefAttributes<ICheckboxListElement>>;
+//# sourceMappingURL=CheckboxList.d.ts.map

package/types/src/list/List.d.ts

@@ -0,0 +1,55 @@
+import { default as React } from 'react';
+import { ISelection } from '../selection';
+export interface ListAttributes {
+    isList: () => true;
+}
+export interface IListElement extends HTMLDivElement, ListAttributes {
+}
+/**
+ * Props for {@link List}.
+ */
+export interface ListProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Number of rows. */
+    itemCount: number;
+    /**
+     * Content for the item at `index`. Called only for the *visible* rows (virtualized), so real
+     * interactive controls — checkboxes, buttons — are fine here. `index` is the row index (for a
+     * filtered list this is the *view* index — map it to your source store yourself).
+     */
+    renderItem: (index: number) => React.ReactNode;
+    /** Uniform row height in px. @defaultValue 24 */
+    itemHeight?: number;
+    /**
+     * The selection model — the active-row highlight + Arrow-key navigation. The List's *state*. Owned
+     * by the caller (so it can read what's selected); a private one is created when omitted.
+     */
+    selection?: ISelection;
+    /**
+     * Key events over the list. Forwarded into the grid's keyboard layer (so it fires even for keys the
+     * grid would otherwise consume, like Enter) — runs before the built-in Arrow navigation, so handle
+     * Space/Enter here and `stopPropagation` to override. Read {@link ListProps.selection} to act on the
+     * selected rows; Arrows you don't handle fall through to navigation.
+     */
+    onKeyDown?: (e: React.KeyboardEvent) => void;
+    /**
+     * Opaque content cache-bust forwarded to the `CellLayer`. Bump (new identity) when an item's
+     * *rendered* content changed without `renderItem`'s identity changing.
+     */
+    cacheToken?: unknown;
+    /** Ref for the Element. */
+    ref?: React.Ref<IListElement>;
+}
+/**
+ * A virtualized **list** built on `GridSurface` with the grid's own layers — a `CellLayer` for the
+ * items and a `SelectionLayer` for the active-row highlight + Arrow keys (the same shape as the editor
+ * demo: a model passed to layers as props).
+ *
+ * @remarks
+ * The List's whole state is its {@link ListProps.selection}; it has no per-item callbacks and no notion
+ * of "checked" or "toggle". Pointer selection is the `SelectionLayer`'s job (it hit-tests the pointer),
+ * so the cells are inert, transparent content; the keyboard is the caller's via {@link ListProps.onKeyDown}.
+ * The active row fills (no Excel anchor hole) and carries an inset ring, since the anchor is the live
+ * Space/scroll target. See {@link CheckboxList} for the checkbox-list specialization.
+ */
+export declare const List: React.ForwardRefExoticComponent<Omit<ListProps, "ref"> & React.RefAttributes<IListElement>>;
+//# sourceMappingURL=List.d.ts.map

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

@@ -0,0 +1,3 @@
+export * from './List';
+export * from './CheckboxList';
+//# sourceMappingURL=index.d.ts.map

package/types/src/metrics/Types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A function that returns the size of an item given its index.
+ */
+export type ItemSizer = (index: number) => number;
+export interface IGridMetrics {
+    /**
+     * Returns the offset given an index.
+     */
+    getColOffset: ItemSizer;
+    /**
+     * Returns the index given an offset.
+     */
+    getColIndex: ItemSizer;
+    /**
+     * Returns the offset given an index.
+     */
+    getRowOffset: ItemSizer;
+    /**
+     * Returns the index given an offset.
+     */
+    getRowIndex: ItemSizer;
+}
+//# sourceMappingURL=Types.d.ts.map

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

@@ -0,0 +1,3 @@
+export * from './Types';
+export * from './useGridMetrics';
+//# sourceMappingURL=index.d.ts.map