@sheetxl/grid-react 0.8.0-beta.2 → 0.8.0-beta.20

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

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

@@ -0,0 +1,73 @@
+import { default as React } from 'react';
+import { FloatPopperProps } from '@sheetxl/utils-react';
+import { StickyState } from './StickyAnchor';
+import { GridAnchor, GridPlacement, GridBoundary, GridWhenOff, GridWhenPartial } from './useGridAnchor';
+/** The lifecycle a {@link StickyPortal} reports — {@link FloatPopper}'s. */
+export type StickyPortalLifecycle = Pick<FloatPopperProps, 'onMount' | 'onOpening' | 'onOpen' | 'onClosing' | 'onClose'>;
+/**
+ * Props for {@link StickyPortal}.
+ */
+export interface StickyPortalProps extends StickyPortalLifecycle {
+    /** 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;
+    /**
+     * 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;
+    /**
+     * Where the float may LIVE — one rect, resolved by {@link GridBoundary}: it is both the anchor's
+     * clip / clamp boundary and the rect `flip` / `shift` collide against. @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 (`useFullscreenPortal`). */
+    container?: Element;
+    className?: string;
+    style?: React.CSSProperties;
+    /** The stacking band — a number, or a `zIndexVar` expression. @defaultValue `zIndexVar('grid')` */
+    zIndex?: number | string;
+    /**
+     * Whose theme the float wears: the anchor's (`'anchor'` — a grid label themes with its grid, even where
+     * the grid's mode differs from the app's) or the app's (`'provider'` — chrome, such as a gesture
+     * readout). @defaultValue 'anchor'
+     */
+    themeFrom?: 'provider' | 'anchor';
+    /**
+     * Drawn **instead of** the child while the anchored range has no visible portion (`state.outOfView`) —
+     * the presence left behind under `whenOff: 'clamp'`: an edge marker, a "go to range" pill. Without it
+     * the child itself is drawn, clamped to the edge.
+     */
+    renderOffscreen?: (state: StickyState) => React.ReactNode;
+    /** 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 **portal renderer** of the grid float family: a {@link StickyAnchor} whose child is drawn by
+ * {@link FloatPopper} at the resolved anchor, in a **portal** (escaping the pane clip, so it can flow past
+ * the pane bounds — e.g. overhang a freeze line). The common case — `<StickyPortal anchor={{ range }}>
+ * A1:B4</StickyPortal>` — with no hand-written positioner. For an in-grid (clipping) label, use
+ * `<StickyAnchor>` with a plain `<div>` child instead.
+ *
+ * @remarks
+ * The resolver (`StickyAnchor`) decides WHERE — the owner pane, the live client rect, the boundary and the
+ * clip / clamp / slide state; the positioner (`FloatPopper`, the same one app menus use) decides how the
+ * box fits there. Both kinds of grid float — a persistent `RangeFloat` and a hover `RangeTooltip` — are
+ * one of these; what differs is who opens and closes them.
+ */
+export declare const StickyPortal: React.FC<StickyPortalProps>;
+//# sourceMappingURL=StickyPortal.d.ts.map

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

@@ -0,0 +1,104 @@
+import { default as React } from 'react';
+import { RenderSlotFn } from '@sheetxl/utils-react';
+import { GridPlacement } from './useGridAnchor';
+import { HoverTipProps } from './useHoverIntent';
+/**
+ * The dwell timing of the tooltip group — MUI's model.
+ */
+export interface TooltipTiming {
+    /** Dwell (ms) over a target before the first tip shows. @defaultValue 300 */
+    enterDelay: number;
+    /** Dwell (ms) while the group is **armed** (a tip closed within {@link armedFor}) — the next tip is instant. @defaultValue 0 */
+    enterNextDelay: number;
+    /** The window (ms) after a close in which the next open is fast — MUI's hysteresis. @defaultValue 800 */
+    armedFor: number;
+    /** The linger (ms) after leaving before a tip hides — lets the pointer cross onto an interactive tip, and a tip does not vanish the moment the pointer leaves the grid. @defaultValue 400 */
+    leaveDelay: number;
+}
+export declare const DEFAULT_TOOLTIP_TIMING: TooltipTiming;
+/** What the host's tooltip bubble is handed. */
+export interface TooltipRenderProps {
+    /** The tip's content. */
+    children: React.ReactNode;
+    /** The edge the tip hangs on — for an arrow. */
+    placement: GridPlacement;
+    /** Whether the tip stays open while the pointer is on it (and so takes the pointer at all). */
+    interactive: boolean;
+    /** Spread onto the bubble root: the keep-open handlers and the element registration. */
+    tipProps: HoverTipProps;
+    className?: string;
+    style?: React.CSSProperties;
+}
+/** The bubble around a tip's content — the host's chrome, arrow and theme. */
+export type RenderTooltip = RenderSlotFn<TooltipRenderProps>;
+/**
+ * A tip registered with its {@link TooltipGroup}. One per `useHoverIntent`; the per-pane copies of a
+ * layer share a `key`, so they count as one tip.
+ */
+export interface TooltipClient {
+    /** Identity: the copies of one tip share it; two tips on the same cell do not. */
+    readonly key: string;
+    /**
+     * A gesture tip holds the group: hover tips may not open while it is up. It is not closed by a press
+     * or Escape, and its close does not arm the group.
+     */
+    readonly gesture: boolean;
+    /** The tip's element once mounted — a pointerdown inside it does not close it. */
+    getElement(): Element | null;
+    /** Close now, no grace (the group took the slot, or the user pressed elsewhere or hit Escape). */
+    forceClose(): void;
+}
+/**
+ * The single-open coordinator: at most one tip (by key) is up at a time, the next open is fast for
+ * {@link TooltipTiming.armedFor} after a close, a gesture tip preempts hover, and a pointerdown outside
+ * an open hover tip or Escape closes it (a gesture tip closes with its gesture). No other key and no
+ * selection change closes a tip; a layer's owner closes one for its own reasons through `dismiss`. Owned
+ * by the top {@link TooltipProvider} (or one that `isolate`s); a built-in default serves a tree with no
+ * provider.
+ */
+export interface TooltipGroup {
+    /** `client` is opening: every client open on another key closes first, with no grace. */
+    claim(client: TooltipClient): void;
+    /** `client` closed. The group arms when the last client on the open key releases. */
+    release(client: TooltipClient): void;
+    /** A tip closed less than `armedFor` ms ago. */
+    isArmed(armedFor: number): boolean;
+    /** A gesture tip is up. */
+    isHeld(): boolean;
+    /** Close every open tip now. */
+    closeAll(): void;
+}
+export declare const createTooltipGroup: () => TooltipGroup;
+/** The ambient tooltip configuration a tip reads. */
+export interface TooltipSurface {
+    timing: TooltipTiming;
+    /** The host's bubble; `undefined` = the grid's plain default. */
+    renderTooltip?: RenderTooltip;
+    group: TooltipGroup;
+}
+/**
+ * The ambient {@link TooltipSurface}. Works with no provider: MUI timing, the plain bubble and a shared
+ * default group.
+ */
+export declare const useTooltipSurface: () => TooltipSurface;
+export interface TooltipProviderProps {
+    /** Override any of the dwell timings; the rest are inherited. */
+    timing?: Partial<TooltipTiming>;
+    /** The bubble tips in this subtree open in. Inherited when omitted. */
+    renderTooltip?: RenderTooltip;
+    /**
+     * Own a separate single-open group for this subtree instead of sharing the enclosing one. The top
+     * provider (no enclosing one) always owns a group.
+     */
+    isolate?: boolean;
+    children?: React.ReactNode;
+}
+/**
+ * Configures the grid's tooltips for a subtree: the dwell timing, the bubble (`renderTooltip`, the way
+ * `FloatProvider` takes `renderFloatPanel`) and the single-open group. Nested providers override only
+ * what they are given and inherit the rest; a hook outside any provider gets the built-in defaults.
+ */
+export declare const TooltipProvider: React.FC<TooltipProviderProps>;
+/** The grid's default bubble — used when no provider supplies `renderTooltip`. */
+export declare const defaultRenderTooltip: RenderTooltip;
+//# sourceMappingURL=TooltipProvider.d.ts.map

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

@@ -2,6 +2,8 @@ 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;
+/** Where a cell's hover tip stacks: over the grid's other floats, and under any menu. */
+export declare const GRID_TIP_Z_INDEX: 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
@@ -18,11 +20,15 @@ export declare const LayerOrderContext: import('react').Context<number>;
  */
 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.
+ * Normalize the layers (the grid's children) for rendering: flatten nested arrays, 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
+ * Nested arrays are flattened first, so a host's array of layers placed as one entry among the
+ * built-in ones still gives each of its layers its own `zIndex` and its own slot. A flattened layer
+ * keeps its own key, so keys must be unique across the whole stack, not only within their array.
+ *
  * 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

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

@@ -1,13 +1,15 @@
 export * from './LayerTypes';
 export * from './Layer';
 export * from './VirtualDiv';
-export type { GridAnchor, GridAnchorReference, GridPlacement, GridWhenOff, GridBoundary, GridFloatSide, GridAlign, GridSlide } from './useGridAnchor';
+export type { GridAnchor, GridAnchorReference, GridPlacement, GridWhenOff, GridWhenPartial, GridPartialPolicy, GridBoundary, GridFloatSide, GridAlign, GridSlide } from './useGridAnchor';
 export * from './StickyAnchor';
-export * from './StickyFloat';
+export * from './StickyPortal';
 export * from './GridFloatPanel';
+export * from './TooltipProvider';
 export * from './useHoverIntent';
-export * from './useRangeHover';
 export * from './RangeFloatLayer';
-export * from './HoverTipLayer';
+export * from './RangeTooltipLayer';
+export * from './GestureTip';
 export * from './RangePrompt';
+export * from './RangeTooltip';
 //# sourceMappingURL=index.d.ts.map

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

@@ -25,6 +25,27 @@ export interface GridPlacement {
  *   the owner becomes the pane under the clamped pixel and {@link GridAnchorResolved.slid} is set.
  */
 export type GridWhenOff = 'hide' | 'clamp';
+/**
+ * What a float does on ONE axis while the range is **partly obstructed** — in view, but the edge the
+ * float hangs on is not (scrolled under a frozen pane, a header, or the window edge).
+ *
+ * - `'slide'` — the anchor pixel rides the visible edge, over the obstruction, until the range is
+ *   fully out ({@link GridAnchorResolved.slid} reports how far).
+ * - `'flip'` — the float moves to the **opposite edge of the range** when that edge is in view (the
+ *   resolved {@link GridAnchorResolved.placement} reports it); slides when neither edge is. Meaningless
+ *   for a `center` align, which slides.
+ * - `'hide'` — the range counts as out of view as soon as the anchored edge is obstructed.
+ */
+export type GridPartialPolicy = 'slide' | 'flip' | 'hide';
+/**
+ * The {@link GridPartialPolicy} per axis: `side` governs the axis the float sits on (its `side`), `align`
+ * the axis it is aligned along.
+ * @defaultValue `{ side: 'flip', align: 'slide' }`
+ */
+export interface GridWhenPartial {
+    side?: GridPartialPolicy;
+    align?: GridPartialPolicy;
+}
 /**
  * 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.
@@ -61,14 +82,18 @@ export type GridAnchor = {
 };
 /**
  * The clip / clamp boundary — a **rect fed to the positioning math**, NOT a DOM parent. One prop, one
- * meaning: *where may this thing live*. It governs the anchor's clip / clamp AND (via `StickyFloat`)
+ * meaning: *where may this thing live*. It governs the anchor's clip / clamp AND (via `StickyPortal`)
  * where `flip` / `shift` may land the float. This is how "don't slide under the headers" is expressed:
  * clamp to the data viewport.
  *
+ * Every grid-derived boundary is further cut to the **browser window** (the layout viewport): a float
+ * the grid does not obscure can still run off the screen, so the edge is always the grid edge ∩ the
+ * window edge. An explicit {@link Bounds} is used verbatim.
+ *
  * - `'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).
- * - `'viewport'` — the browser viewport: the opt-out, for a float that may cover grid chrome.
+ * - `'viewport'` — the browser window alone: the opt-out, for a float that may cover grid chrome.
  * - a {@link Bounds} — an explicit **client-px** rect.
  */
 export type GridBoundary = 'data' | 'pane' | 'grid' | 'viewport' | Bounds;
@@ -105,9 +130,15 @@ export interface GridAnchorResolved {
     /**
      * 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).
+     * "partially obstructed / clamped" (still show) from "off-screen" (show a goto affordance). A
+     * `whenPartial: 'hide'` axis also sets it once its edge is obstructed.
      */
     outOfView: boolean;
+    /**
+     * The placement **actually used** — the requested one, or its opposite on an axis a
+     * `whenPartial: 'flip'` moved to the range's other edge. What the float positions by.
+     */
+    placement: GridPlacement;
 }
 /**
  * The Floating UI **virtual reference** for a grid anchor. Stable identity (so `autoUpdate` subscribes
@@ -134,6 +165,11 @@ export interface UseGridAnchorResult {
     reference: GridAnchorReference;
     /** Live accessor for the boundary rect (for `shift`/`flip`/`hide` limiters). */
     getBoundaryRect: () => DOMRect;
+    /**
+     * Live accessor for the placement's anchor pixel (client px) — the live counterpart of
+     * {@link anchorPoint}, for a child that positions itself on the point between React renders.
+     */
+    getAnchorPoint: () => Point;
     /** 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. */
@@ -146,17 +182,21 @@ export interface UseGridAnchorResult {
     slid: GridSlide | null;
     /** Render-time snapshot: the range is fully scrolled off (stays true under `clamp`; see resolved). */
     outOfView: boolean;
+    /** Render-time snapshot: the placement actually used (see {@link GridAnchorResolved.placement}). */
+    placement: GridPlacement;
     /** 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;
+/** @internal The shared partial-obstruction default: today's behavior made explicit. */
+export declare const DEFAULT_WHEN_PARTIAL: Required<GridWhenPartial>;
 /**
  * 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;
+export declare const resolveGridAnchor: (pane: IGridPane | null, anchor: GridAnchor, boundary?: GridBoundary, minVisible?: number, placement?: GridPlacement, whenOff?: GridWhenOff, whenPartial?: GridWhenPartial) => 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),
@@ -170,5 +210,6 @@ export declare const useGridAnchor: (anchor: GridAnchor, options?: {
     minVisible?: number;
     placement?: GridPlacement;
     whenOff?: GridWhenOff;
+    whenPartial?: GridWhenPartial;
 }) => UseGridAnchorResult;
 //# sourceMappingURL=useGridAnchor.d.ts.map

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

@@ -2,13 +2,39 @@
  * Options for {@link useHoverIntent}.
  */
 export interface UseHoverIntentOptions {
-    /** Dwell (ms) over a target before opening — kills pass-through flicker. @defaultValue 300 */
+    /**
+     * Dwell (ms) over a target before opening — kills pass-through flicker.
+     * @defaultValue the tooltip group's `enterDelay` (300), or its `enterNextDelay` (0) while armed
+     */
     openDelay?: number;
-    /** Grace (ms) after leaving before closing — lets the pointer cross the gap to the float. @defaultValue 150 */
+    /**
+     * Grace (ms) after leaving before closing — lets the pointer cross the gap to the float.
+     * @defaultValue the tooltip group's `leaveDelay` (400)
+     */
     closeDelay?: number;
+    /**
+     * Join the grid's tooltip group: one tip open at a time, a fast re-open while armed, closed by a
+     * pointerdown outside it or Escape, refused while a gesture tip or a popup is up. `false` for a hover-opened float that is not
+     * a tooltip — a table toolbar, a note's box — which must survive a tip opening beside it.
+     * @defaultValue true
+     */
+    group?: boolean;
+    /**
+     * The tip's identity in the group. A layer rendered once per pane passes one name so its copies count
+     * as ONE tip (they aim and open in lockstep); two layers on the same cell must differ.
+     * @defaultValue this hook instance
+     */
+    name?: string;
+    /**
+     * A gesture readout: opens at once (no dwell) and holds the group, so no hover tip can open until it
+     * closes. @defaultValue false
+     */
+    gesture?: boolean;
 }
 /** Props to spread onto the floated element so hovering IT keeps the float open. */
 export interface HoverTipProps {
+    /** Registers the element with the tooltip group, so a press inside an interactive tip does not close it. */
+    ref: React.RefCallback<Element>;
     onPointerEnter: () => void;
     onPointerLeave: () => void;
     style: React.CSSProperties;
@@ -37,13 +63,14 @@ export interface UseHoverIntentResult {
     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.
+ * The **hover-intent state machine** behind a tip — the per-tip client of the grid's tooltip group
+ * ({@link TooltipProvider}): dwell / grace timing, keep-open-on-tip-hover, and the group's rules
+ * (single open, armed re-open, gesture and popup preempt hover, closed by a press outside it or Escape). It does NO
+ * hit-testing: feed it a target key via {@link UseHoverIntentResult.setTarget} (`null` = nothing) and
+ * spread {@link UseHoverIntentResult.tipProps} on the float.
  *
- * {@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.
+ * `RangeFloatLayer` drives it from a probe; a dynamic consumer (a layer discovering the hovered note)
+ * drives `setTarget` itself.
  */
 export declare const useHoverIntent: (options?: UseHoverIntentOptions) => UseHoverIntentResult;
 //# sourceMappingURL=useHoverIntent.d.ts.map

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

@@ -15,11 +15,22 @@ export interface ICheckboxListElement extends HTMLDivElement, CheckboxListAttrib
 /**
  * Props for {@link CheckboxList}.
  */
+/** What {@link CheckboxListProps.renderCheckbox} is handed. */
+export interface CheckboxRenderProps {
+    checked: boolean;
+    /** Set for the `(Select All)` tri-state when only some rows are checked. */
+    indeterminate?: boolean;
+}
 export interface CheckboxListProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Number of rows. */
     itemCount: number;
     /** Whether the item at `index` is checked. */
     isChecked: (index: number) => boolean;
+    /**
+     * Whether the item at `index` is partly checked: a row standing for several values (a group)
+     * with some of them checked. Drawn as the tri-state; the row still toggles to `!isChecked`.
+     */
+    isIndeterminate?: (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.
@@ -32,16 +43,21 @@ export interface CheckboxListProps extends React.HTMLAttributes<HTMLDivElement>
      * `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;
+    renderCheckbox?: (props: CheckboxRenderProps) => 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.
+     * filtered list are the filtered ones, so it's "Select all (filtered)" automatically. It sits
+     * above the rows, outside the scroll, so it never leaves the view.
      */
     selectAllLabel?: React.ReactNode;
+    /** The header's accessible name and tooltip, when its label does not say what it is (a count). */
+    selectAllTitle?: string;
+    /** The Select All row's own attributes (a surface, a class), over its defaults. */
+    propsSelectAll?: React.HTMLAttributes<HTMLDivElement>;
     /** Uniform row height in px. @defaultValue 24 */
     itemHeight?: number;
     /** Selection model (highlight + Arrow nav). Created internally if omitted. */

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

@@ -9,6 +9,20 @@ export interface ListSearchProps extends Omit<React.InputHTMLAttributes<HTMLInpu
     onChange: (value: string) => void;
     /** Escape on an empty field: the search has nothing left to clear, so the host closes. */
     onClose?: () => void;
+    /**
+     * The name of the clear button shown in the field while it holds text (its tooltip and
+     * accessible name). Without one the button is unnamed, not absent.
+     */
+    clearLabel?: string;
+    /**
+     * In place of the search glyph inside the field: a control over the search itself (a menu of
+     * its options, drawn with {@link ListSearchGlyph}). The default is the glyph alone.
+     */
+    glyph?: React.ReactNode;
+    /** Shown before the field, on its line: an action over the rows in view. */
+    leading?: React.ReactNode;
+    /** Shown after the field, on its line: an action on the typed text (an Add). */
+    trailing?: React.ReactNode;
     /** Ref for the input. */
     ref?: React.Ref<HTMLInputElement>;
 }
@@ -18,14 +32,21 @@ export interface ListSearchProps extends Omit<React.InputHTMLAttributes<HTMLInpu
 export declare const filterByText: <T extends {
     text: string;
 }>(items: readonly T[], query: string) => readonly T[];
+/** The search glyph: a magnifier, drawn in the current color. */
+export declare const ListSearchGlyph: (props: {
+    className?: string;
+}) => React.ReactElement;
 /**
  * The **search field** shown above a list ({@link PickList}, `CheckboxList`): a plain input that
- * narrows the rows as typed. Filtering itself is the host's, with {@link filterByText}.
+ * narrows the rows as typed, a search glyph before the text and a clear button after it while
+ * there is text. Filtering itself is the host's, with {@link filterByText}.
  *
  * @remarks
  * Escape clears the text first and closes only when there is none left, so a mistyped search is
- * one key from a full list and two from a closed one. Every other key is the host's through
- * `onKeyDown`, which is how the arrows and Enter reach the list while the field keeps focus.
+ * one key from a full list and two from a closed one. The clear button does the first of those
+ * without taking the focus, as the next thing typed is usually another search. Every other key
+ * is the host's through `onKeyDown`, which is how the arrows and Enter reach the list while the
+ * field keeps focus.
  */
 export declare const ListSearch: React.ForwardRefExoticComponent<Omit<ListSearchProps, "ref"> & React.RefAttributes<HTMLInputElement>>;
 //# sourceMappingURL=ListSearch.d.ts.map

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

@@ -5,6 +5,11 @@ export interface PickListItem {
     /** The row's text. */
     text: string;
 }
+/** What {@link PickListProps.renderItem} is handed. */
+export interface PickListItemRenderProps {
+    item: PickListItem;
+    index: number;
+}
 export interface PickListAttributes {
     isPickList: () => true;
     /** The highlighted row, or `-1` when the list is empty. */
@@ -47,7 +52,7 @@ export interface PickListProps extends React.HTMLAttributes<HTMLDivElement> {
      */
     measureText?: (text: string) => number;
     /** Render a row's content. @defaultValue the text, clipped with an ellipsis. */
-    renderItem?: (item: PickListItem, index: number) => React.ReactNode;
+    renderItem?: (props: PickListItemRenderProps) => React.ReactNode;
     /** Take focus on mount, so the Arrow keys work without a click first. @defaultValue false */
     autoFocus?: boolean;
     /** The scroll state, when the caller owns it (see `ListSurfaceProps.viewport`). */

package/types/src/range/DragHandle.d.ts

@@ -1,4 +1,5 @@
 import { CellCoords, RangeCoords } from '@sheetxl/utils';
+import { RangeGlide } from './RangeGlide';
 /** Which corner (`tl`/`tr`/`bl`/`br`) or edge-midpoint (`t`/`b`/`l`/`r`) of the range to sit on. */
 export type HandleAnchor = 'tl' | 'tr' | 'bl' | 'br' | 't' | 'b' | 'l' | 'r';
 /**
@@ -24,6 +25,8 @@ export interface DragHandleRenderProps {
     handleProps: {
         /** The handle's identifying class(es) — `drag-handle` plus whatever the flavor tagged it with. */
         className?: string;
+        /** The handle element, which a glide moves frame by frame. Any element type takes it. */
+        ref: (element: HTMLElement | null) => void;
         onPointerDown: (e: React.PointerEvent) => void;
         onDoubleClick?: (e: React.MouseEvent) => void;
         onPointerEnter?: (e: React.PointerEvent) => void;
@@ -54,8 +57,11 @@ export interface DragHandleProps {
     dragCursor?: string;
     /** Default-dot background, and the theme color handed to {@link DragHandleProps.renderHandle}. */
     background?: string;
-    /** Drag started; `cell` is under the pointer at press. */
-    onDragStart?: (cell: CellCoords, e: React.PointerEvent) => void;
+    /**
+     * Drag started; `cell` is under the pointer at press. `cancel` aborts this drag as Escape would
+     * ({@link DragHandleProps.onDragCancel} follows) — hand it to chrome that offers a way out.
+     */
+    onDragStart?: (cell: CellCoords, e: React.PointerEvent, cancel: () => void) => void;
     /** The pointer moved to a new cell during the drag (`from` = press cell, `to` = current). */
     onDragMove?: (from: CellCoords, to: CellCoords, e: React.PointerEvent) => void;
     /** Drag ended (`from` = press cell, `to` = last cell). */
@@ -85,11 +91,12 @@ export interface DragHandleProps {
      */
     hoverStyle?: React.CSSProperties;
     /**
-     * Glide the handle to its new position (transition `left`/`top`) when `range` changes — pair with
-     * {@link RangeRect}'s `animatedTransition` so the corners track a move-drag's gliding outline
-     * instead of jumping. @defaultValue false
+     * Ride this glide's frames while it is in flight — the same clock as a {@link RangeRect} given the
+     * same glide, so the handle stays on the outline's corner. The glide must be heading to `range`. A
+     * handle pinned to the view ({@link DragHandleProps.clampToView}) hides until the glide lands: its
+     * pinned edge has no place along the way.
      */
-    animatedTransition?: boolean;
+    glide?: RangeGlide | null;
     /**
      * Pin the handle centre INSIDE the pane's viewport instead of letting it sit at the range's true
      * anchored corner. When that corner is far off-grid — e.g. a whole-row / whole-column fill selection