@sheetxl/grid-react 0.7.28-beta.4 → 0.8.0-beta.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/grid-react",
   "description": "Grid React - Advanced grid component for React",
-  "version": "0.7.28-beta.4",
+  "version": "0.8.0-beta.2",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -42,8 +42,8 @@
   ],
   "dependencies": {
     "@floating-ui/react-dom": "^2.1.9",
-    "@sheetxl/utils": "^0.7.28-beta.4",
-    "@sheetxl/utils-react": "^0.7.28-beta.4",
+    "@sheetxl/utils": "^0.8.0-beta.2",
+    "@sheetxl/utils-react": "^0.8.0-beta.2",
     "clsx": "^2.1.1",
     "react-merge-refs": "^3.0.2",
     "react-use": "^17.6.1",

package/types/src/cell/CellRenderer.d.ts

@@ -1,14 +1,25 @@
 import { Bounds, CellCoords, RangeCoords } from '@sheetxl/utils';
-import { IGridPane } from '../surface';
 export interface CellRendererProps<T = any> extends React.HTMLAttributes<HTMLElement>, React.Attributes {
     /**
      * A value to render.
      */
     value: T;
     /**
-     * The view that is rendering a collection of cells.
+     * The zoom {@link CellRendererProps.bounds} were measured at.
+     *
+     * @defaultValue 1
+     *
+     * @remarks
+     * A renderer is handed the zoom, never the pane it came from: everything it needs to draw one cell
+     * is data (the value, the bounds, the scale), so it stays a pure function of its props and can be
+     * rendered anywhere a caller can supply bounds — a preview, a tooltip, a cell drawn outside its own
+     * column. A renderer that genuinely needs the live view (hover, scroll) reads it from context with
+     * `useGridPane`.
+     *
+     * The bounds already have the zoom applied; this is for what CSS pixels do not carry — an unscaled
+     * inset, a glyph size, a stroke width the renderer picks itself.
      */
-    pane: IGridPane;
+    zoom?: number;
     /**
      * The range bounds relative to the current viewport and zoom.
      */

package/types/src/editor/DefaultEditable.d.ts

@@ -40,6 +40,12 @@ export interface IEditable<C, D = string, A = EditCommitArgs> {
     getSession(): EditSession<C, D, A> | null;
     /** Subscribe to session changes (start/stop only). Returns an unsubscribe. */
     subscribe(listener: () => void): () => void;
+    /**
+     * Subscribe to commits the model REFUSED by throwing (an expected refusal such as "You can't change
+     * part of an array", or a real fault). The edit stays open either way; this is the seam through
+     * which the reason reaches a host that can show it. Returns an unsubscribe.
+     */
+    subscribeCommitError(listener: (error: unknown) => void): () => void;
     /** Begin an edit on `coords`. Returns `false` (and does nothing) if the cell is not editable. */
     startEdit(coords: CellCoords, options?: StartEditOptions<D>): boolean;
     /** Commit the current edit. On success clears the session; returns whether it succeeded. */
@@ -100,12 +106,15 @@ export declare class DefaultEditable<C, D = string, A = EditCommitArgs> implemen
     private readonly unsubscribeAnchor;
     private current;
     private readonly listeners;
+    private readonly commitErrorListeners;
     constructor(anchor: ICellAnchor, createEdit: CreateEdit<C, D, A>, options?: DefaultEditableOptions);
     private onAnchorChange;
     /** @inheritdoc IEditable.getAnchor */
     getAnchor(): ICellAnchor;
     /** @inheritdoc IEditable.subscribe */
     subscribe(listener: () => void): () => void;
+    /** @inheritdoc IEditable.subscribeCommitError */
+    subscribeCommitError(listener: (error: unknown) => void): () => void;
     /** @inheritdoc IEditable.getSession */
     getSession(): EditSession<C, D, A> | null;
     /** @inheritdoc IEditable.startEdit */

package/types/src/editor/EditSession.d.ts

@@ -49,6 +49,11 @@ export interface EditModel<C, D = string, A = EditCommitArgs> {
 export interface EditSessionInit<C, D = string, A = EditCommitArgs> extends EditModel<C, D, A> {
     /** The cell being edited. */
     coords: CellCoords;
+    /**
+     * Hears the error a THROWING model write rejected the commit with (see {@link EditModel.commit}).
+     * The rejection itself only keeps the edit open; this is how the reason reaches whoever can show it.
+     */
+    onCommitError?: (error: unknown) => void;
 }
 /**
  * Options applied when an edit begins (`DefaultEditable.startEdit` → the `EditSession` constructor).
@@ -96,6 +101,7 @@ export interface CommitContext<D = string, A = EditCommitArgs> {
  */
 export declare class EditSession<C, D = string, A = EditCommitArgs> implements ICellAnchor {
     private readonly commitFn;
+    private readonly onCommitError?;
     private state;
     private readonly listeners;
     private readonly commitListeners;

package/types/src/editor/EditState.d.ts

@@ -20,6 +20,12 @@ export interface EditCommitArgs {
      * Excel's `Ctrl+Enter`. The active cell does not move (the leave-key does not navigate/traverse).
      */
     broadcast?: boolean;
+    /**
+     * Array-enter the value over the **current selection** — Excel's `Ctrl+Shift+Enter`: one formula
+     * at the selection's top-left whose result is fitted to the selection's extent, rather than
+     * spilling from the active cell. The active cell does not move.
+     */
+    arrayFixed?: boolean;
 }
 /**
  * A text selection range within the editor input. Mirrors the `HTMLTextAreaElement` selection API.

package/types/src/editor/EditorInput.d.ts

@@ -67,7 +67,8 @@ export interface EditorInputProps<C, D = string> {
      * (a rejected/invalid value) the input keeps the session open and stops the key so the selection
      * does not move away.
      *
-     * `args` carries the commit "signal" — e.g. {@link EditCommitArgs.broadcast} for a Ctrl+Enter fill.
+     * `args` carries the commit "signal" — e.g. {@link EditCommitArgs.broadcast} for a Ctrl+Enter fill,
+     * {@link EditCommitArgs.arrayFixed} for a Ctrl+Shift+Enter array entry.
      */
     onCommit(args?: EditCommitArgs): boolean;
     /** Cancel/revert the edit. */

package/types/src/editor/useEditorKeymap.d.ts

@@ -54,6 +54,17 @@ export interface EditorKeymapProps {
      */
     setCaret?(caret: number): void;
 }
+/**
+ * The commit "signal" a leave key carries: `Ctrl+Shift+Enter` array-enters over the selection
+ * ({@link EditCommitArgs.arrayFixed}), `Ctrl+Enter` fills it ({@link EditCommitArgs.broadcast}), and
+ * anything else is a plain commit (`undefined`). Both modified forms keep the active cell put.
+ */
+export declare const commitArgsFromKey: (e: {
+    which: number;
+}, native: {
+    ctrlKey: boolean;
+    shiftKey: boolean;
+}) => EditCommitArgs | undefined;
 /**
  * The shared spreadsheet editor keymap, as a `<textarea>` `onKeyDown` handler. Both the default and
  * the cell-aware inputs use it so the interaction contract stays identical:

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

@@ -55,8 +55,12 @@ export interface HeaderSelectionPointerOptions {
     onPointerDownInterceptor?: (e: React.PointerEvent, cell: CellCoords) => boolean | void;
     /** Called once at the start of a pointer gesture (before the selection changes). */
     onDragStart?: () => void;
-    /** Called at the end of a pointer gesture. */
-    onDragEnd?: (e: React.PointerEvent) => void;
+    /**
+     * Called at the end of a pointer gesture — on release AND on an abort (Escape / OS `pointercancel`),
+     * so whatever {@link HeaderSelectionPointerOptions.onDragStart} armed is always disarmed. The event is
+     * absent on an abort.
+     */
+    onDragEnd?: (e?: React.PointerEvent) => void;
     /** Called on pointer-up, after {@link HeaderSelectionPointerOptions.onDragEnd} (e.g. refocus the grid). */
     onPointerUp?: (e: React.PointerEvent) => void;
 }

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

@@ -0,0 +1,18 @@
+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 StickyFloat}, 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.
+ *
+ * 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/HoverTipLayer.d.ts

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

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

@@ -0,0 +1,146 @@
+import { default as React } from 'react';
+import { CellCoords, RangeCoords } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+import { ICellAnchor } from '../selection/ICellAnchor';
+import { LayerProps } from './Layer';
+import { StickyState } from './StickyAnchor';
+import { HoverTipProps } from './useHoverIntent';
+import { GridPlacement, GridWhenOff, GridBoundary } from './useGridAnchor';
+/**
+ * How the layer decides WHICH range is floating.
+ *
+ * - `'hover'` — the pointer, through the shared hover intent (open / close delays, keep-open-on-float).
+ * - `'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
+ * 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. */
+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;
+    /**
+     * Stable identity for dedupe — the float re-opens only when this changes (a `pointermove` storm
+     * within one target is a no-op). Defaults to the range's coords.
+     */
+    key?: string;
+    /** Payload passed to the render-prop (the message, the validation, the table, …). */
+    data: T;
+    /**
+     * Where this target's float attaches, for a layer whose targets do not all belong on one side.
+     * Defaults to the layer's {@link RangeFloatLayerProps.placement}.
+     */
+    placement?: GridPlacement;
+}
+/** The context passed to a {@link RangeFloatLayerProps} render-prop. */
+export interface RangeFloatRender<T = unknown> {
+    /** The anchored range. */
+    range: RangeCoords;
+    /** The probe payload. */
+    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.
+     */
+    floatProps: HoverTipProps;
+    /** The resolved sticky state (e.g. `state.scrollIntoView()`, `state.slid`). */
+    state: StickyState;
+}
+/**
+ * Props for {@link RangeFloatLayer}.
+ */
+export interface RangeFloatLayerProps<T = unknown> extends Omit<LayerProps, 'children'> {
+    /** Class for the floated container. */
+    className?: string;
+    /** 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
+     * 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).
+     */
+    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.
+     */
+    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`.
+     */
+    dismiss?: boolean;
+    /** Which side of the range the float attaches to. @defaultValue `{ side: 't' }` */
+    placement?: GridPlacement;
+    /** Gap (px) perpendicular to the edge. @defaultValue 6 */
+    offset?: number;
+    /** Offset (px) along the edge (only `start` / `end` align). @defaultValue 0 */
+    alignOffset?: number;
+    /** Dwell (ms) before a hovered float shows. @defaultValue 300 */
+    openDelay?: number;
+    /** Grace (ms) before a hovered float hides (bridges the gap to the float). @defaultValue 150 */
+    closeDelay?: number;
+    /** What happens when the anchor leaves the data area. @defaultValue 'hide' */
+    whenOff?: GridWhenOff;
+    /** Where the float may live. @defaultValue 'data' */
+    boundary?: GridBoundary;
+    /** @defaultValue 1250 */
+    zIndex?: number;
+    /** 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.
+ *
+ * @remarks
+ * This is the **float half** of the grid's two mechanisms. A `CellTileDiv` covers everything whose
+ * content is a function of the cell alone — clicks and hover styling included — as a cached DOM
+ * snapshot. A float is for content that depends on transient UI state (selection, hover, open/closed)
+ * 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:
+ *
+ * ```tsx
+ * <RangeFloatLayer activateOn="hover" probe={probeError}>
+ *   {({ data, floatProps }) => <div {...floatProps}>{data.message}</div>}
+ * </RangeFloatLayer>
+ *
+ * <RangeFloatLayer activateOn="selection" selection={selection} probe={probeList}>
+ *   {({ 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/StickyAnchor.d.ts

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { Bounds, Point, AnchorLocation } from '@sheetxl/utils';
 import { IGridPane } from '../surface';
-import { GridAnchor, GridPlacement, GridBoundary, GridWhenOff, GridSlide } from './useGridAnchor';
+import { GridAnchor, GridAnchorReference, GridPlacement, GridBoundary, GridWhenOff, GridSlide } from './useGridAnchor';
 /**
  * The state a {@link StickyAnchor} publishes to its child. Carries the resolved `anchorPoint` (+ owner /
  * clip / slide state) so the child alone decides how to render:
@@ -14,9 +14,7 @@ import { GridAnchor, GridPlacement, GridBoundary, GridWhenOff, GridSlide } from
  */
 export interface StickyState {
     /** Client-space Floating UI virtual reference (stable identity; reads live). */
-    reference: {
-        getBoundingClientRect: () => DOMRect;
-    };
+    reference: GridAnchorReference;
     /** Client-space boundary rect (for `flip`/`shift`/`hide` limiters). */
     getBoundaryRect: () => DOMRect;
     /** The placement's anchor pixel (client px). */

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

@@ -32,7 +32,10 @@ export interface StickyFloatProps {
     placement?: GridPlacement;
     /** What happens when the anchor leaves the data area. @defaultValue 'hide' */
     whenOff?: GridWhenOff;
-    /** Clip / clamp boundary. @defaultValue 'data' */
+    /**
+     * 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;

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

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

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

@@ -60,15 +60,18 @@ export type GridAnchor = {
     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.
+ * 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`)
+ * where `flip` / `shift` may land the float. 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).
+ * - `'viewport'` — the browser viewport: 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' | Bounds;
+export type GridBoundary = 'data' | 'pane' | 'grid' | 'viewport' | Bounds;
 /** A `DOMRect`-shaped plain object (works in Floating UI and in Node tests without a DOM). */
 export interface GridAnchorRect {
     x: number;
@@ -106,15 +109,29 @@ export interface GridAnchorResolved {
      */
     outOfView: boolean;
 }
+/**
+ * The Floating UI **virtual reference** for a grid anchor. Stable identity (so `autoUpdate` subscribes
+ * once), but both members read **live**.
+ */
+export interface GridAnchorReference {
+    /** The anchor's client rect, read live on every call (`autoUpdate` calls it between React renders). */
+    getBoundingClientRect: () => DOMRect;
+    /**
+     * The pane element. `autoUpdate` unwraps a virtual reference to *this* element and gates **every**
+     * DOM-side trigger on it — ancestor `scroll`, the `observeMove` layout-shift detector, element resize.
+     * Without it only the window `resize` listener survives, which is why the float used to need a 60fps
+     * `animationFrame` poll. A **getter**: the pane element only exists after mount, and resolving it
+     * lazily keeps this object's identity stable.
+     */
+    readonly contextElement?: Element;
+}
 /** 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;
-    };
+    reference: GridAnchorReference;
     /** 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). */

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

@@ -26,10 +26,11 @@ export interface UseRangeHoverResult {
  *
  * @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).
+ * a {@link Layer} tap); it never consumes the event. Because a grid child renders per pane, the pointer
+ * is seen by whichever pane it is over while the tip renders on the pane owning the anchor — which for
+ * a range straddling a freeze is a DIFFERENT pane. The aimed target is therefore brokered through
+ * {@link useSurfaceState}, so every pane copy runs its intent off the same signal and the owner is
+ * armed no matter where the pointer is.
  */
 export declare const useRangeHover: (range: RangeCoords, options?: UseHoverIntentOptions) => UseRangeHoverResult;
 //# sourceMappingURL=useRangeHover.d.ts.map

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

@@ -1,7 +1,14 @@
 import { default as React } from 'react';
 import { ISelection } from '../selection';
+import { ListProps } from './List';
 export interface CheckboxListAttributes {
     isCheckboxList: () => true;
+    /** The highlighted row, or `-1` when the list is empty. */
+    getHighlightIndex: () => number;
+    /** Move the highlight `delta` rows (clamped to the list) and bring it into view. */
+    moveHighlight: (delta: number) => void;
+    /** Toggle the selected rows, as Space does: the anchor's opposite, applied to every one of them. */
+    toggleHighlighted: () => void;
 }
 export interface ICheckboxListElement extends HTMLDivElement, CheckboxListAttributes {
 }
@@ -41,6 +48,10 @@ export interface CheckboxListProps extends React.HTMLAttributes<HTMLDivElement>
     selection?: ISelection;
     /** Content cache-bust; bump when checked state changes without `isChecked`'s identity changing. */
     cacheToken?: unknown;
+    /** See `ListSurfaceProps.autoFocus`. */
+    autoFocus?: boolean;
+    /** See `ListSurfaceProps.viewport`. */
+    viewport?: ListProps['viewport'];
     /** Ref for the Element. */
     ref?: React.Ref<ICheckboxListElement>;
 }

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

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { ISelection } from '../selection';
+import { ListSurface } from './ListSurface';
 export interface ListAttributes {
     isList: () => true;
 }
@@ -36,20 +37,28 @@ export interface ListProps extends React.HTMLAttributes<HTMLDivElement> {
      * *rendered* content changed without `renderItem`'s identity changing.
      */
     cacheToken?: unknown;
+    /** See `ListSurfaceProps.scrollTo`. */
+    scrollTo?: {
+        row: number;
+    } | null;
+    /** See `ListSurfaceProps.autoFocus`. */
+    autoFocus?: boolean;
+    /** See `ListSurfaceProps.viewport`. */
+    viewport?: React.ComponentProps<typeof ListSurface>['viewport'];
     /** 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).
+ * A virtualized **list** of arbitrary React content, built on {@link ListSurface} — which is the
+ * grid's own machinery (a `CellLayer` for the items and a `SelectionLayer` for the active-row
+ * highlight + Arrow keys) dressed as a list.
  *
  * @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.
+ * See {@link CheckboxList} for the checkbox-list specialization and {@link PickList} for the
+ * single-choice text list.
  */
 export declare const List: React.ForwardRefExoticComponent<Omit<ListProps, "ref"> & React.RefAttributes<IListElement>>;
 //# sourceMappingURL=List.d.ts.map