@sheetxl/grid-react 0.8.0-beta.1 → 0.8.0-beta.10

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

@@ -0,0 +1,69 @@
+import { default as React } from 'react';
+import { GridAnchor, GridPlacement, GridBoundary } from './useGridAnchor';
+/**
+ * A gesture readout anchored to a DOM element rather than to the grid — a scrollbar thumb, which lives
+ * outside every pane. The element moves with the drag and no DOM event says so, so the readout is
+ * repositioned each time it renders: the owner re-renders it as the gesture moves (as it changes the text).
+ */
+export interface GestureTipElementAnchor {
+    element: Element;
+}
+/**
+ * How a {@link GestureTip} travels between positions.
+ */
+export interface GestureTipGlide {
+    /** How long a move takes, in ms. `0` jumps. */
+    duration: number;
+    /** The CSS easing it travels on. @defaultValue 'ease-in-out' */
+    easing?: string;
+}
+/**
+ * Props for {@link GestureTip}.
+ */
+export interface GestureTipProps {
+    /**
+     * The gesture is in flight. While it is, the tip holds the tooltip group — no hover tip opens — even
+     * when there is nothing to say (`children` empty).
+     */
+    active: boolean;
+    /** What the readout anchors to — the in-flight range, a frame's bounds, or a dragged element. */
+    anchor: GridAnchor | GestureTipElementAnchor;
+    /** Which side + align of the anchor the readout sits on. @defaultValue `{ side: 'b', align: 'end' }` */
+    placement?: GridPlacement;
+    /** Gap (px) between the anchor and the readout. @defaultValue 8 */
+    offset?: number;
+    /** Offset (px) along the anchored edge (only `start` / `end` align). @defaultValue 0 */
+    alignOffset?: number;
+    /**
+     * Glide to each new position instead of jumping. Pass the timing of an anchor that glides itself (a
+     * move ghost) so the readout travels with it. Where it first appears is never animated.
+     * @defaultValue none — a readout jumps with its gesture
+     */
+    glide?: GestureTipGlide;
+    /** Where the readout may live (a grid anchor only). @defaultValue 'data' */
+    boundary?: GridBoundary;
+    /**
+     * Whose theme the readout wears. A readout is chrome, so the app's — even over a grid in another mode.
+     * @defaultValue 'provider'
+     */
+    themeFrom?: 'provider' | 'anchor';
+    /**
+     * The tip's identity in the tooltip group. A layer rendered once per pane passes one name so its
+     * copies count as one tip.
+     * @defaultValue this instance
+     */
+    name?: string;
+    className?: string;
+    /** The readout. Empty draws nothing (the group is still held while {@link active}). */
+    children?: React.ReactNode;
+}
+/**
+ * The readout a gesture shows while it runs — a drag-select's size, a move's destination, a fill's
+ * value, a frame's size, a header's size, the row a scrollbar thumb is at. A tooltip of the gesture
+ * kind: it opens with the gesture (no dwell), holds the tooltip group so no hover tip opens beside it,
+ * closes when the gesture ends, and takes no pointer (the gesture owns it). Drawn in the group's
+ * bubble, in the tooltip band and the app's theme; on a grid anchor, `clamp`ed so it stays on screen
+ * when the anchor runs off the grid.
+ */
+export declare const GestureTip: React.FC<GestureTipProps>;
+//# sourceMappingURL=GestureTip.d.ts.map

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

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+import { FloatPanelProps } from '@sheetxl/utils-react';
+/**
+ * A **float stack panel positioned by the grid**: pass {@link renderGridFloatPanel} as a
+ * `useFloatStack` `renderFloatPanel`, and a {@link GridAnchor} (a cell or range) as its `anchor`.
+ *
+ * @remarks
+ * The stack keeps what it does for every popup — the portal, light-dismiss, Escape, focus restore and
+ * stacking. The position comes from {@link StickyPortal}, the engine grid buttons and labels use, so the
+ * popup moves with its cell as the grid scrolls (which no DOM event reports), flips against the same
+ * boundary, and closes once its cell has scrolled out of view. It sits in the popup band, above the
+ * grid's other floats (its buttons and labels).
+ *
+ * The stack's `propsPopper` `placement` and `offsets` are read as the grid placement and offset.
+ */
+export declare const GridFloatPanel: React.FC<FloatPanelProps>;
+/** {@link GridFloatPanel} as a `useFloatStack` `renderFloatPanel`. */
+export declare const renderGridFloatPanel: (props: FloatPanelProps) => React.ReactElement;
+//# sourceMappingURL=GridFloatPanel.d.ts.map

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

@@ -62,6 +62,12 @@ export interface LayerProps extends LayerEventProps {
     zIndex?: number;
     /** Class for the layer's boundary div (devtools identification). */
     className?: string;
+    /**
+     * Style for the layer's boundary div — e.g. `display: 'none'` or `opacity` to hide or fade a layer.
+     * The boundary's own placement (`position`, `inset`, `pointer-events: none`) comes from the grid;
+     * overriding it here breaks the layer's containment.
+     */
+    style?: React.CSSProperties;
     /**
      * 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).

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

@@ -5,20 +5,21 @@ import { ICellAnchor } from '../selection/ICellAnchor';
 import { LayerProps } from './Layer';
 import { StickyState } from './StickyAnchor';
 import { HoverTipProps } from './useHoverIntent';
-import { GridPlacement, GridWhenOff, GridBoundary } from './useGridAnchor';
+import { GridPlacement, GridWhenOff, GridWhenPartial, GridBoundary } from './useGridAnchor';
 /**
- * How the layer decides WHICH range is floating.
+ * How {@link RangeFloatLayer} decides WHICH range is floating.
  *
- * - `'hover'` — the pointer, through the shared hover intent (open / close delays, keep-open-on-float).
+ * - `'hover'` — the pointer, through the tooltip group's hover intent (its timing, single-open rule and
+ *   keep-open-on-float); `RangeTooltipLayer` is this, with the group's bubble.
  * - `'selection'` — the active cell of {@link RangeFloatLayerProps.selection}, with no delay: a resting
  *   affordance, not a transient tip.
  *
  * Pass an array to accept EITHER (`['hover','selection']` — not an AND; each one opens the float on its
- * own). Omit entirely and drive {@link RangeFloatLayerProps.target} yourself (gesture-driven action
+ * own). Omit entirely and drive {@link RangeFloatOptions.target} yourself (gesture-driven action
  * popups — paste options, autofill options).
  */
 export type RangeFloatActivation = 'hover' | 'selection';
-/** A hit from a {@link RangeFloatLayerProps.probe} — the range to anchor on plus arbitrary payload. */
+/** A hit from a probe — the range to anchor on plus arbitrary payload. */
 export interface RangeFloatTarget<T = unknown> {
     /** The range the float anchors to (e.g. the cell's own range, a merge, or an enclosing table). */
     range: RangeCoords;
@@ -29,8 +30,18 @@ export interface RangeFloatTarget<T = unknown> {
     key?: string;
     /** Payload passed to the render-prop (the message, the validation, the table, …). */
     data: T;
+    /**
+     * Where this target's float attaches, for a float whose targets do not all belong on one side.
+     * Defaults to the float's {@link RangeFloatOptions.placement}.
+     */
+    placement?: GridPlacement;
+    /**
+     * Offset (px) along the edge for this target, for a float whose offset depends on the anchor (e.g.
+     * a fraction of its width). Defaults to the float's {@link RangeFloatOptions.alignOffset}.
+     */
+    alignOffset?: number;
 }
-/** The context passed to a {@link RangeFloatLayerProps} render-prop. */
+/** The context passed to a range float's render-prop. */
 export interface RangeFloatRender<T = unknown> {
     /** The anchored range. */
     range: RangeCoords;
@@ -38,55 +49,52 @@ export interface RangeFloatRender<T = unknown> {
     data: T;
     /**
      * Spread onto the floated element. Supplies `pointer-events: auto` (a layer's box never takes the
-     * pointer, so content must opt back in) and — under `'hover'` — the enter/leave handlers that keep
-     * the float open while the pointer is on it.
+     * pointer, so content must opt back in) and — for a hovered float — the enter/leave handlers that
+     * keep it open while the pointer is on it.
      */
     floatProps: HoverTipProps;
     /** The resolved sticky state (e.g. `state.scrollIntoView()`, `state.slid`). */
     state: StickyState;
 }
 /**
- * Props for {@link RangeFloatLayer}.
+ * How a range float takes part in the UI around it.
+ *
+ * - `'none'` — takes no pointer at all: a label, a readout, a prompt box.
+ * - `'pointer'` — takes the pointer, and its presses, keys, clipboard, context menu and wheel stop at
+ *   the float: the float is portaled out of the pane, but React events bubble the React TREE, which
+ *   would carry them to the grid's own handlers. A button, a chevron, a toolbar.
+ * - `'focus'` — `'pointer'`, and the float can hold the caret: while focus is inside it stays on its
+ *   target whatever the pointer does; Escape or a press anywhere outside it (a cell, a menu button, a
+ *   right-click) closes it, focus returns to the grid, and {@link RangeFloatOptions.onDismiss} is told.
+ *   "Outside" is judged by the React tree, so a menu the float opens in a portal of its own is inside.
+ *   A card with a text field.
  */
-export interface RangeFloatLayerProps<T = unknown> extends Omit<LayerProps, 'children'> {
-    /** Class for the floated container. */
-    className?: string;
+export type RangeFloatInteractive = 'none' | 'pointer' | 'focus';
+/**
+ * What every range float takes, however it is activated: placement, dismissal, hover timing,
+ * interactivity and the render-prop.
+ */
+export interface RangeFloatOptions<T = unknown> {
     /** Style for the floated container. */
     style?: React.CSSProperties;
     /**
-     * What makes a float appear. Omit to drive {@link target} yourself.
-     * @defaultValue none (controlled)
-     */
-    activateOn?: RangeFloatActivation | readonly RangeFloatActivation[];
-    /**
-     * Identity for the hover state this layer brokers across its per-pane copies. Defaults to the
+     * Identity for the hover state brokered across the float's per-pane copies. Defaults to the host
      * layer's z-slot, which is already unique per grid child — pass one only when a SINGLE grid child
-     * hosts more than one `RangeFloatLayer` (they would otherwise share a cell and fight).
+     * hosts more than one range float (they would otherwise share a cell and fight).
      */
     name?: string;
     /**
-     * Ask whether a cell has something to float — the anchor range + payload, or `null` for nothing.
-     * Called with the hovered cell (`'hover'`) and with the selection's active cell (`'selection'`), so
-     * one probe serves both. Not needed when {@link target} is controlled.
-     */
-    probe?: (coords: CellCoords, pane: IGridPane) => RangeFloatTarget<T> | null;
-    /**
-     * The selection to follow for `activateOn: 'selection'`. An {@link ICellAnchor} rather than a full
-     * selection — the layer only ever reads the active cell and subscribes to it.
-     */
-    selection?: ICellAnchor;
-    /**
-     * Controlled target: supply it (including `null`) and the layer floats exactly what you say,
-     * ignoring `activateOn` / `probe`. The escape hatch for gesture-driven popups whose lifetime is the
-     * action's, not the pointer's.
+     * Controlled target: supply it (including `null`) and the float shows exactly what you say, ignoring
+     * hover and selection. The escape hatch for gesture-driven popups whose lifetime is the action's,
+     * not the pointer's.
      */
     target?: RangeFloatTarget<T> | null;
     /**
-     * Hard close. Under `'hover'` it is **edge-triggered**: the float drops now, bypassing `closeDelay`,
-     * and a later hover re-opens normally. Under `'selection'` there is no gesture to re-arm it, so it
-     * reads as a **level**: the float stays closed while this holds and returns when it clears (e.g. the
-     * anchored cell is in edit mode). Ignored when {@link target} is controlled — the lifetime is yours
-     * there, so close it by passing `null`.
+     * Hard close. For a hovered float it is **edge-triggered**: the float drops now, bypassing
+     * `closeDelay`, and a later hover re-opens normally. For the selection there is no gesture to re-arm
+     * it, so it reads as a **level**: the float stays closed while this holds and returns when it clears
+     * (e.g. the anchored cell is in edit mode). Ignored when {@link target} is controlled — the lifetime
+     * is yours there, so close it by passing `null`.
      */
     dismiss?: boolean;
     /** Which side of the range the float attaches to. @defaultValue `{ side: 't' }` */
@@ -95,24 +103,111 @@ export interface RangeFloatLayerProps<T = unknown> extends Omit<LayerProps, 'chi
     offset?: number;
     /** Offset (px) along the edge (only `start` / `end` align). @defaultValue 0 */
     alignOffset?: number;
-    /** Dwell (ms) before a hovered float shows. @defaultValue 300 */
+    /** Dwell (ms) before a hovered float shows. @defaultValue the tooltip group's `enterDelay` (300; 0 while armed) */
     openDelay?: number;
-    /** Grace (ms) before a hovered float hides (bridges the gap to the float). @defaultValue 150 */
+    /** Grace (ms) before a hovered float hides (bridges the gap to the float). @defaultValue the group's `leaveDelay` (400) */
     closeDelay?: number;
+    /**
+     * A hovered float joins the grid's tooltip group (one tip at a time, closed by any press or key).
+     * `false` for a hover-opened float that is not a tooltip — a toolbar — which must survive a tip
+     * opening beside it and a press on its own buttons.
+     * @defaultValue true
+     */
+    group?: boolean;
+    /**
+     * Keep a hover-opened float up although the pointer has left it — while something it opened (its
+     * dropdown) is open and has the pointer. It shows the last hovered target, and closes once released
+     * unless the pointer is back on the range or the float.
+     * @defaultValue false
+     */
+    hold?: boolean;
     /** What happens when the anchor leaves the data area. @defaultValue 'hide' */
     whenOff?: GridWhenOff;
+    /** Per-axis policy while the range is partly obstructed. @defaultValue `{ side: 'flip', align: 'slide' }` */
+    whenPartial?: GridWhenPartial;
     /** Where the float may live. @defaultValue 'data' */
     boundary?: GridBoundary;
-    /** @defaultValue 1250 */
-    zIndex?: number;
+    /** The stacking band. @defaultValue `zIndexVar('grid')` */
+    zIndex?: number | string;
+    /** How the float takes the pointer and the focus. @defaultValue 'pointer' */
+    interactive?: RangeFloatInteractive;
+    /**
+     * A `'focus'` float closed itself — Escape, or a press outside it. A controlled
+     * {@link target} should be cleared here.
+     */
+    onDismiss?: () => void;
     /** Render the float. **Spread `floatProps`** on the returned element. */
     children: (info: RangeFloatRender<T>) => React.ReactNode;
 }
 /**
- * The **range float layer**: content anchored to a range that portals out of the pane clip. It owns
- * the three things every such float needs — **anchoring** (a {@link StickyFloat} on the probed range),
- * **activation** (what makes it appear) and **dismissal**. What it draws is entirely the consumer's:
- * a tooltip, a button, a toolbar, an action popup.
+ * Props for {@link VirtualRangeFloat}.
+ */
+export interface VirtualRangeFloatProps<T = unknown> extends RangeFloatOptions<T> {
+    /**
+     * What the pointer is over, as the HOST layer's own tap found it — `null` for nothing, omit for a
+     * float hover does not drive. Report it from the pane the pointer is in; the copies in the other
+     * panes need not repeat it (the hover is brokered across them, so the copy that owns the anchor
+     * draws).
+     */
+    hovered?: RangeFloatTarget<T> | null;
+    /**
+     * The selection to follow: its active cell, through {@link probe}. An {@link ICellAnchor} rather than
+     * a full selection — only the active cell is read and subscribed to.
+     */
+    selection?: ICellAnchor;
+    /** Ask whether the selection's active cell has something to float. Needed with {@link selection}. */
+    probe?: (coords: CellCoords, pane: IGridPane) => RangeFloatTarget<T> | null;
+}
+/**
+ * A **range float** that is not a layer: content anchored to a range that portals out of the pane clip,
+ * placed inside a host layer. It owns **anchoring** (a {@link StickyPortal} on the range), the hover
+ * **intent** (dwell, grace, keep-open-on-float, `hold`, the tooltip group), the selection follow, and
+ * **dismissal**; the host owns its one tap and reports what the pointer is over as {@link
+ * VirtualRangeFloatProps.hovered}. So a composite layer (a table's chrome) can float its toolbar
+ * without a second layer, and {@link RangeFloatLayer} is this plus a probing tap.
+ *
+ * ```tsx
+ * <Layer onPointerMove={(e) => setHovered(probeAt(e))} onPointerLeave={() => setHovered(null)}>
+ *   {outlines}
+ *   <VirtualRangeFloat hovered={hovered} group={false}>
+ *     {({ data, floatProps }) => <Toolbar {...floatProps} table={data} />}
+ *   </VirtualRangeFloat>
+ * </Layer>
+ * ```
+ *
+ * When hover and selection both drive it, hover is the transient override and selection the resting
+ * state: while the pointer holds a target the float shows that one, and falls back to the selection's
+ * when the pointer leaves.
+ */
+export declare const VirtualRangeFloat: <T>(props: VirtualRangeFloatProps<T>) => React.ReactElement | null;
+/**
+ * Props for {@link RangeFloatLayer}.
+ */
+export interface RangeFloatLayerProps<T = unknown> extends Omit<LayerProps, 'children' | 'zIndex'>, RangeFloatOptions<T> {
+    /** Class for the layer. */
+    className?: string;
+    /**
+     * What makes a float appear. Omit to drive {@link RangeFloatOptions.target} yourself.
+     * @defaultValue none (controlled)
+     */
+    activateOn?: RangeFloatActivation | readonly RangeFloatActivation[];
+    /**
+     * Ask whether a cell has something to float — the anchor range + payload, or `null` for nothing.
+     * Called with the hovered cell (`'hover'`) and with the selection's active cell (`'selection'`), so
+     * one probe serves both. Not needed when {@link RangeFloatOptions.target} is controlled.
+     */
+    probe?: (coords: CellCoords, pane: IGridPane) => RangeFloatTarget<T> | null;
+    /**
+     * The selection to follow for `activateOn: 'selection'`. An {@link ICellAnchor} rather than a full
+     * selection — the layer only ever reads the active cell and subscribes to it.
+     */
+    selection?: ICellAnchor;
+}
+/**
+ * The **range float layer**: a {@link VirtualRangeFloat} as a layer of its own, whose tap probes the
+ * hovered cell. It owns the three things every such float needs — **anchoring**, **activation** (what
+ * makes it appear) and **dismissal**. What it draws is entirely the consumer's: a tooltip, a button, a
+ * toolbar, an action popup.
  *
  * @remarks
  * This is the **float half** of the grid's two mechanisms. A `CellTileDiv` covers everything whose
@@ -121,7 +216,8 @@ export interface RangeFloatLayerProps<T = unknown> extends Omit<LayerProps, 'chi
  * or that must leave the cell box. "Only on the active cell" is the expensive predicate: it would
  * dirty a tile per selection move, which is exactly why it belongs here.
  *
- * Activation is pluggable and the rest of the layer is identical across the choices:
+ * A layer that already draws chrome for the same thing (a table's outline and handles) hosts a
+ * {@link VirtualRangeFloat} itself instead — layers do not nest.
  *
  * ```tsx
  * <RangeFloatLayer activateOn="hover" probe={probeError}>
@@ -132,10 +228,6 @@ export interface RangeFloatLayerProps<T = unknown> extends Omit<LayerProps, 'chi
  *   {({ range, floatProps }) => <Chevron {...floatProps} onPointerDown={() => open(range)} />}
  * </RangeFloatLayer>
  * ```
- *
- * When either can activate it, hover is the transient override and selection is the resting state:
- * while the pointer holds a target the float shows that one, and it falls back to the selection's when
- * the pointer leaves.
  */
 export declare const RangeFloatLayer: <T>(props: RangeFloatLayerProps<T>) => React.ReactElement;
 //# sourceMappingURL=RangeFloatLayer.d.ts.map

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

@@ -23,20 +23,20 @@ export interface RangePromptProps {
     onGoto?: (state: StickyState) => void;
     /** Called by the small cancel (×) button. The host unmounts the layer in response. */
     onCancel?: () => void;
-    /** @defaultValue 1250 */
-    zIndex?: number;
+    /** @defaultValue `zIndexVar('grid')` */
+    zIndex?: number | string;
     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`).
+ * A **persistent prompt pinned to a range** — a preset of {@link StickyPortal} (always open, `clamp`ed,
+ * with a `renderOffscreen`). While the range is in view it renders the client content (injectable option
+ * buttons — e.g. an AI question about the range) on a card 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/RangeTooltip.d.ts

@@ -0,0 +1,123 @@
+import { default as React } from 'react';
+import { CellCoords, RangeCoords } from '@sheetxl/utils';
+import { LayerProps } from './Layer';
+import { StickyState } from './StickyAnchor';
+import { HoverTipProps } from './useHoverIntent';
+import { GridPlacement } from './useGridAnchor';
+/** What a tip's content is rendered from, when {@link RangeTooltipProps.content} is a function. */
+export interface RangeTooltipContentInfo {
+    /** The anchored range. */
+    range: RangeCoords;
+    /** The resolved sticky state (e.g. `state.scrollIntoView()`, `state.placement`). */
+    state: StickyState;
+    /**
+     * Spread onto the content's root to keep the tip open while hovered. Already on the bubble when the
+     * tip draws one; only a `bubble: false` tip spreads it itself.
+     */
+    tipProps: HoverTipProps;
+}
+/**
+ * Props for {@link RangeTooltip}.
+ */
+export interface RangeTooltipProps {
+    /** The range the tip hangs on. */
+    range: RangeCoords;
+    /** The tip: a node, or a function of the anchored range and the float's state. */
+    content: React.ReactNode | ((info: RangeTooltipContentInfo) => React.ReactNode);
+    /** Which side of the range the tip attaches to. @defaultValue `{ side: 't' }` */
+    placement?: GridPlacement;
+    /** Gap (px) between the range and the tip. @defaultValue 6 */
+    offset?: number;
+    /** Offset (px) along the edge (only `start` / `end` align). @defaultValue 0 */
+    alignOffset?: number;
+    /**
+     * The tip stays open while the pointer is on it, so its content can be clicked (a card with
+     * buttons). Otherwise it takes no pointer at all. @defaultValue false
+     */
+    interactive?: boolean;
+    /**
+     * Draw the content in the group's bubble (the host's `renderTooltip`, or the grid's plain one).
+     * `false` renders the content bare — the consumer draws its own chrome and spreads `tipProps`.
+     * @defaultValue true
+     */
+    bubble?: boolean;
+    /** Reserved for what the tip is anchored to. A tip on a range takes none. */
+    children?: never;
+}
+/** A registered tip. */
+export interface RangeTooltipEntry {
+    /** The registration's identity. */
+    id: string;
+    /** Registration order; the later of two equal ranges wins. */
+    order: number;
+    props: RangeTooltipProps;
+}
+/**
+ * The tips declared under one {@link RangeTooltipProvider}: what {@link RangeTooltip} registers with
+ * and {@link RangeTooltipHost} probes.
+ */
+export interface RangeTooltipRegistry {
+    /** Registers a tip. The returned function withdraws it. */
+    add(id: string, props: RangeTooltipProps): () => void;
+    /** Replaces a registered tip's props. */
+    set(id: string, props: RangeTooltipProps): void;
+    /** The registered tip by id, or `null`. */
+    get(id: string): RangeTooltipEntry | null;
+    /** How many tips are registered. */
+    size(): number;
+    /**
+     * The tip at a cell: the smallest registered range covering it, and the latest registered among
+     * equals. `null` when none covers it.
+     */
+    find(coords: CellCoords): RangeTooltipEntry | null;
+    /** Called after every change. The returned function unsubscribes. */
+    subscribe(listener: () => void): () => void;
+    /** A counter that moves on every change — a snapshot for `useSyncExternalStore`. */
+    version(): number;
+}
+export declare const createRangeTooltipRegistry: () => RangeTooltipRegistry;
+/** The registry the nearest {@link RangeTooltipProvider} owns, or `null` outside any. */
+export declare const useRangeTooltipRegistry: () => RangeTooltipRegistry | null;
+export interface RangeTooltipProviderProps {
+    /**
+     * Own a separate registry for this subtree instead of sharing the enclosing one. A provider with no
+     * enclosing one always owns a registry.
+     */
+    isolate?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * Collects the {@link RangeTooltip}s declared under it for the {@link RangeTooltipHost} of the grid
+ * inside it. A grid provides one of its own, so a tip among a grid's children needs none; a tip
+ * declared elsewhere in the app needs a provider around both it and the grid.
+ */
+export declare const RangeTooltipProvider: React.FC<RangeTooltipProviderProps>;
+/**
+ * A **tooltip on a range**, declared where it is wanted: hover any cell of the range and the tip opens
+ * beside it, in the tooltip group of the grid (its timing, its one-open rule, its bubble). It draws
+ * nothing itself; the grid's {@link RangeTooltipHost} draws every declared tip from one layer.
+ *
+ * ```tsx
+ * <Grid …>
+ *   <RangeTooltip range={{ rowStart: 3, colStart: 2, rowEnd: 8, colEnd: 5 }} content="Q3 figures" />
+ * </Grid>
+ * ```
+ *
+ * @remarks
+ * Reach for {@link RangeTooltipLayer} instead when the tips are derived from data (an error on
+ * whichever cells have one) rather than declared one by one. Where two declared ranges overlap, the
+ * smaller wins, and the later declared among equals. A tip's identity is its element: content may
+ * change without the open tip closing. The anchor is the `range`; `children` is reserved for an
+ * anchor that is drawn.
+ */
+export declare const RangeTooltip: (props: RangeTooltipProps) => null;
+export interface RangeTooltipHostProps extends Omit<LayerProps, 'children'> {
+    className?: string;
+}
+/**
+ * The layer that draws the {@link RangeTooltip}s of the nearest {@link RangeTooltipProvider}: one tap,
+ * one probe over the registered ranges, one client of the tooltip group. A grid mounts it at the top of
+ * its stack; it draws nothing where no tip is declared.
+ */
+export declare const RangeTooltipHost: React.MemoExoticComponent<(props: RangeTooltipHostProps) => React.JSX.Element>;
+//# sourceMappingURL=RangeTooltip.d.ts.map

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

@@ -0,0 +1,53 @@
+import { default as React } from 'react';
+import { CellCoords, RangeCoords } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+import { StickyState } from './StickyAnchor';
+import { HoverTipProps } from './useHoverIntent';
+import { RangeFloatTarget, RangeFloatLayerProps } from './RangeFloatLayer';
+/** The context passed to a {@link RangeTooltipLayerProps} render-prop. */
+export interface RangeTooltipRender<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).
+     * Already on the bubble when the layer draws one; only a `bubble: false` tip spreads it itself.
+     */
+    tipProps: HoverTipProps;
+    /** The resolved sticky state (e.g. `state.scrollIntoView()`). */
+    state: StickyState;
+}
+/**
+ * Props for {@link RangeTooltipLayer}.
+ */
+export interface RangeTooltipLayerProps<T = unknown> extends Omit<RangeFloatLayerProps<T>, 'activateOn' | 'selection' | 'target' | 'probe' | 'children' | 'zIndex' | 'group' | 'hold' | 'interactive' | 'onDismiss'> {
+    /** Probe the hovered cell → a {@link RangeFloatTarget} (range + data), or `null` when nothing should show. */
+    probe: (coords: CellCoords, pane: IGridPane) => RangeFloatTarget<T> | null;
+    /**
+     * The tip stays open while the pointer is on it, so its content can be clicked (a card with
+     * buttons). Otherwise it takes no pointer at all. @defaultValue false
+     */
+    interactive?: boolean;
+    /**
+     * Draw the content in the group's bubble (the host's `renderTooltip`, or the grid's plain one).
+     * `false` renders the content bare — the consumer draws its own chrome and spreads `tipProps`.
+     * @defaultValue true
+     */
+    bubble?: boolean;
+    /** Render the tip's content. */
+    children: (info: RangeTooltipRender<T>) => React.ReactNode;
+}
+/**
+ * The **tooltip kind** of range float: transient, opened by hovering a cell the probe recognizes, one
+ * at a time grid-wide. A preset of {@link RangeFloatLayer} (`activateOn: 'hover'`) whose hover intent is
+ * the tooltip group's client — so it inherits the group's timing, single-open rule, armed re-open, and
+ * closes on any press or key — drawn in the group's bubble, in the tooltip band.
+ *
+ * @remarks
+ * Reach for `RangeFloatLayer` directly when the float is activated by the selection, driven by a
+ * gesture, or is something other than a tip. A tip is never focusable: anything that takes the caret
+ * is a persistent float.
+ */
+export declare const RangeTooltipLayer: <T>(props: RangeTooltipLayerProps<T>) => React.ReactElement;
+//# sourceMappingURL=RangeTooltipLayer.d.ts.map

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

@@ -1,13 +1,13 @@
 import { default as React } from 'react';
 import { Bounds, Point, AnchorLocation } from '@sheetxl/utils';
 import { IGridPane } from '../surface';
-import { GridAnchor, GridAnchorReference, GridPlacement, GridBoundary, GridWhenOff, GridSlide } from './useGridAnchor';
+import { GridAnchor, GridAnchorReference, GridPlacement, GridBoundary, GridWhenOff, GridWhenPartial, 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);
+ *   pane bounds (this is what {@link StickyPortal} 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.
@@ -17,8 +17,10 @@ export interface StickyState {
     reference: GridAnchorReference;
     /** Client-space boundary rect (for `flip`/`shift`/`hide` limiters). */
     getBoundaryRect: () => DOMRect;
-    /** The placement's anchor pixel (client px). */
+    /** The placement's anchor pixel (client px) — a render-time snapshot. */
     anchorPoint: Point;
+    /** Live accessor for the anchor pixel (client px); stable identity, reads between renders. */
+    getAnchorPoint: () => 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). */
@@ -35,7 +37,10 @@ export interface StickyState {
      * (keep showing) from "off-screen" (show a goto affordance).
      */
     outOfView: boolean;
-    /** The resolved placement. */
+    /**
+     * The placement **actually used**: the requested one, or its opposite on an axis that
+     * {@link StickyAnchorProps.whenPartial} flipped to the range's other visible edge.
+     */
     placement: GridPlacement;
     /** This instance's pane (null outside a `GridPaneProvider`). */
     pane: IGridPane | null;
@@ -63,6 +68,11 @@ export interface StickyAnchorProps {
     boundary?: GridBoundary;
     /** What happens when the anchor pixel leaves the data area. @defaultValue 'hide' */
     whenOff?: GridWhenOff;
+    /**
+     * What happens, per axis, while the range is partly obstructed — in view, but the anchored edge is
+     * not. @defaultValue `{ side: 'flip', align: 'slide' }`
+     */
+    whenPartial?: GridWhenPartial;
     /** 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. */
@@ -71,7 +81,7 @@ export interface StickyAnchorProps {
 /**
  * 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
+ * the pane); a **render-prop** child self-positions (e.g. a portal — see {@link StickyPortal}). 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