@sheetxl/grid-react 0.7.22 → 0.7.23-beta.2

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"useHoverIntent.d.ts","sourceRoot":"","sources":["../../../../src/layer/useHoverIntent.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,8FAA8F;IAC9F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+GAA+G;IAC/G,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,oFAAoF;AACpF,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,cAAc,EAAE,MAAM,IAAI,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,yCAAyC;IACzC,IAAI,EAAE,OAAO,CAAC;IACd;;;;OAIG;IACH,SAAS,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAC;IACxC;;;OAGG;IACH,QAAQ,EAAE,aAAa,CAAC;IACxB;;;OAGG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAID;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,GAAI,UAAS,qBAA0B,KAAG,oBAwDpE,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"useLayerResponder.d.ts","sourceRoot":"","sources":["../../../../src/layer/useLayerResponder.ts"],"names":[],"mappings":"AAWA;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,+EAA+E;IAC/E,UAAU,EAAE,MAAM,OAAO,GAAG,IAAI,CAAC;IACjC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CACpC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,GAAI,8BAA8B,wBAAwB,KAAG,IAqC1F,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"usePlacement.d.ts","sourceRoot":"","sources":["../../../../src/layer/usePlacement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzD,OAAO,EAAE,KAAK,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAExD,sGAAsG;AACtG,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,sGAAsG;IACtG,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,qCAAqC,mBAAmB,KAAG,SAAS,GAAG,IAkCnG,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"useRangeHover.d.ts","sourceRoot":"","sources":["../../../../src/layer/useRangeHover.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAK9D,OAAO,EACW,KAAK,qBAAqB,EAAE,KAAK,aAAa,EAC/D,MAAM,kBAAkB,CAAC;AAK1B;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,IAAI,EAAE,OAAO,CAAC;IACd,qGAAqG;IACrG,QAAQ,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,aAAa,GAAI,OAAO,WAAW,EAAE,UAAS,qBAA0B,KAAG,mBA+BvF,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"CheckboxList.d.ts","sourceRoot":"","sources":["../../../../src/list/CheckboxList.tsx"],"names":[],"mappings":"AAAA,OAAO,KAEN,MAAM,OAAO,CAAC;AAMf,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAIjE,MAAM,WAAW,sBAAsB;IACrC,cAAc,EAAE,MAAM,IAAI,CAAC;CAC5B;AAED,MAAM,WAAW,oBAAqB,SAAQ,cAAc,EAAE,sBAAsB;CAAG;AAEvF;;GAEG;AACH,MAAM,WAAW,iBAAkB,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IAC7E,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC;;;OAGG;IACH,eAAe,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC/D,2CAA2C;IAC3C,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,CAAC,SAAS,CAAC;IAChD;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,OAAO,KAAK,KAAK,CAAC,SAAS,CAAC;IAChF;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,KAAK,CAAC,SAAS,CAAC;IACtC;;;OAGG;IACH,cAAc,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACjC,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB,mGAAmG;IACnG,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2BAA2B;IAC3B,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;CACvC;AAqBD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,YAAY,6GA2GvB,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"List.d.ts","sourceRoot":"","sources":["../../../../src/list/List.tsx"],"names":[],"mappings":"AAAA,OAAO,KAEN,MAAM,OAAO,CAAC;AAYf,OAAO,EAC6B,KAAK,UAAU,EAClD,MAAM,cAAc,CAAC;AAqBtB,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,YAAa,SAAQ,cAAc,EAAE,cAAc;CAAG;AAEvE;;GAEG;AACH,MAAM,WAAW,SAAU,SAAQ,KAAK,CAAC,cAAc,CAAC,cAAc,CAAC;IACrE,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,KAAK,CAAC,SAAS,CAAC;IAC/C,iDAAiD;IACjD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,SAAS,CAAC,EAAE,UAAU,CAAC;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI,CAAC;IAC7C;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,2BAA2B;IAC3B,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,6FAyGf,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/list/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,gBAAgB,CAAC"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"Types.d.ts","sourceRoot":"","sources":["../../../../src/metrics/Types.ts"],"names":[],"mappings":"AACA;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B;;OAEG;IACH,YAAY,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,WAAW,EAAE,SAAS,CAAC;IACvB;;OAEG;IACH,YAAY,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,WAAW,EAAE,SAAS,CAAC;CACxB"}

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

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

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/metrics/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,kBAAkB,CAAC"}

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

@@ -0,0 +1,67 @@
+import { ItemSizer, IGridMetrics } from './Types';
+/**
+ * One axis (rows OR columns) of the grid: maps an item index ⇄ its pixel offset.
+ *
+ * @remarks
+ * The public {@link IGridMetrics} is exactly four of these (`get(Col|Row)(Offset|Index)`); an axis is
+ * the per-direction half. `getOffset` returns the LEADING edge of an item; `getIndex` is its inverse
+ * (the item whose span contains a pixel offset). Both clamp gracefully outside the grid: a negative
+ * index/offset → `0`, an offset at/past the total extent → `count` (one past the last) — on BOTH the
+ * uniform and variable paths. On a run of zero-size (hidden) items — an equal-offset plateau —
+ * `getIndex` deterministically resolves to the LAST index of the run: the following sized item, the
+ * one whose span actually contains the pixel (a zero-size span contains nothing).
+ */
+export interface Axis {
+    /** Leading-edge pixel offset of `index` (0 for `index <= 0`). */
+    getOffset: ItemSizer;
+    /** Item index whose span contains pixel `offset` (0 at/under the origin, clamped to `count`). */
+    getIndex: ItemSizer;
+}
+/**
+ * Build an {@link Axis} from a fixed size or a per-index sizer.
+ *
+ * - **Uniform** (a `number`): closed-form arithmetic — no allocation, no cache, O(1) both ways. This
+ *   is the overwhelmingly common case (every default grid, every fixed row height) and the supported
+ *   large-grid mode.
+ * - **Variable** (an {@link ItemSizer}): offsets are MEASURED lazily and memoized in dense arrays
+ *   (indices fill sequentially from 0). The *search* over the already-measured prefix is O(log n)
+ *   (binary search, with an exponential probe to bracket a target past it) — but **measurement is
+ *   linear and cumulative**: a jump to index N measures and permanently caches every offset `0..N`
+ *   (O(N) time & memory on first touch; a far jump into a 1M-item axis walks ~1M sizer calls). This
+ *   path is the convenience tier for human-scale variable axes. Grids that need large *and* variable
+ *   don't use it — they pass a prebuilt {@link IGridMetrics} (e.g. the SDK's run-length metrics)
+ *   instead of a sizer. (GRID-CLEAN F1: documented as-is by design; no sublinear tree here.)
+ *
+ * Exported for tests (uniform/variable edge parity — GRID-CLEAN B4/B5); not part of the package API.
+ */
+export declare const createAxis: (count: number, size: ItemSizer | number) => Axis;
+export interface UseGridMetricOptions {
+    /**
+     * Number of columns in the grid.
+     */
+    columnCount: number;
+    /**
+     * Number of rows in the grid.
+     */
+    rowCount: number;
+    /**
+     * Row height: a fixed number (uniform) or a `(index) => number` sizer. Defaults to `20`.
+     */
+    getRowHeight?: ItemSizer | number;
+    /**
+     * Column width: a fixed number (uniform) or a `(index) => number` sizer. Defaults to `75`.
+     */
+    getColumnWidth?: ItemSizer | number;
+}
+/**
+ * Build an {@link IGridMetrics} (the index ⇄ offset mapping the surface needs) from a row/column
+ * count plus fixed sizes or per-index sizers.
+ *
+ * @remarks
+ * The returned object's IDENTITY changes only when the geometry inputs do (count or sizer) — never on
+ * scroll — which is exactly the signal the surface keys its pane recreation on. A `null` `props`
+ * yields `null` (the engine then falls back to its own default metrics). `IGridMetrics` is the entire
+ * consumed contract; nothing else is exposed.
+ */
+export declare const useGridMetrics: (props: UseGridMetricOptions | null) => IGridMetrics | null;
+//# sourceMappingURL=useGridMetrics.d.ts.map

package/types/src/metrics/useGridMetrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useGridMetrics.d.ts","sourceRoot":"","sources":["../../../../src/metrics/useGridMetrics.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AAK5D;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,IAAI;IACnB,iEAAiE;IACjE,SAAS,EAAE,SAAS,CAAC;IACrB,iGAAiG;IACjG,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,EAAE,MAAM,SAAS,GAAG,MAAM,KAAG,IAgFpE,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IACjB;;OAEG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAClC;;OAEG;IACH,cAAc,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,oBAAoB,GAAG,IAAI,KAAG,YAAY,GAAG,IAkBlF,CAAC"}

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

@@ -0,0 +1,129 @@
+import { CellCoords, RangeCoords } from '@sheetxl/utils';
+/** 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';
+/**
+ * Resolved info passed to {@link DragHandleProps.renderHandle}.
+ */
+export interface DragHandleRenderProps {
+    /** The corner/edge this handle sits on. */
+    anchor: HandleAnchor;
+    /** Resolved size (px). */
+    size: number;
+    /** Resolved cursor (anchor-derived unless overridden). */
+    cursor: string;
+    /** Resolved background color — handy as a theme color for custom marks. */
+    background: string;
+    /** Whether the pointer is currently over the handle (for a hover affordance). */
+    hovered: boolean;
+    /**
+     * **Spread onto your handle element** — this wires placement, pointer-capture, cursor, and the
+     * drag events. Without it the handle won't drag. Only pointer-DOWN is on the element; the drag's
+     * move/up are attached to `window` for the gesture's duration (so it survives the handle
+     * repositioning under an edge auto-scroll).
+     */
+    handleProps: {
+        onPointerDown: (e: React.PointerEvent) => void;
+        onPointerEnter?: (e: React.PointerEvent) => void;
+        onPointerLeave?: (e: React.PointerEvent) => void;
+        style: React.CSSProperties;
+    };
+}
+/**
+ * Props for {@link DragHandle}.
+ */
+export interface DragHandleProps {
+    /** The range the handle is anchored to; it sits on the {@link DragHandleProps.anchor} corner. */
+    range: RangeCoords;
+    /** Which corner/edge of `range` to position on. */
+    anchor: HandleAnchor;
+    /** Visual size (px) of the handle. @defaultValue 8 */
+    size?: number;
+    /** Cursor while hovering/dragging. @defaultValue an anchor-appropriate resize cursor. */
+    cursor?: string;
+    /**
+     * Cursor to show **only while a drag is in flight** (the pointer-capture target's cursor holds for
+     * the whole drag, even off the handle / off-window). Use it to swap the idle affordance for a neutral
+     * "manipulating" cursor — e.g. {@link RangeResizer} flips its directional resize cursors to
+     * `grabbing` so a corner drag doesn't keep implying you can still resize that way. Omit to keep
+     * {@link DragHandleProps.cursor} for the whole gesture (the fill / table-resize handles, which want
+     * their crosshair/resize cursor throughout).
+     */
+    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;
+    /** 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). */
+    onDragEnd?: (from: CellCoords, to: CellCoords, e: React.PointerEvent) => void;
+    /**
+     * The drag was **aborted** — the user pressed Escape, or the OS cancelled the pointer (`pointercancel`).
+     * Fires INSTEAD of {@link DragHandleProps.onDragEnd} (nothing is committed). Use it to tear down any
+     * in-flight preview a flavor set in `onDragStart`/`onDragMove` (e.g. the fill's dashed preview) without
+     * applying it. Event-less — an Escape abort has no pointer event.
+     */
+    onDragCancel?: () => void;
+    /** The pointer entered (`true`) / left (`false`) the handle — for a hover affordance on the host. */
+    onHoverChange?: (hovered: boolean) => void;
+    /**
+     * Style merged onto the default dot **only while hovered** — e.g. {@link RangeResizer} recolors
+     * the thumb's border from the window color to the stroke color, so it appears to "grow" on hover
+     * (Excel-style). Use the same shorthand property as the base `style` (e.g. `border`) to avoid a
+     * React shorthand/longhand warning. Ignored for headless `renderHandle` consumers (they get
+     * {@link DragHandleRenderProps.hovered} to wire their own).
+     */
+    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
+     */
+    animatedTransition?: boolean;
+    /**
+     * 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
+     * whose corner is at the last column / row — this keeps the handle visible and reachable. When the
+     * range no longer intersects this pane at all, the handle is not rendered.
+     *
+     * Clamp a **single axis** to track the range along the other: `'y'` pins the vertical position but
+     * lets `x` follow the range (a whole-column `tr` handle — pinned to the top, scrolls with the column);
+     * `'x'` pins the horizontal but lets `y` follow (a whole-row `bl` handle — pinned to the left, scrolls
+     * with the row). `true` clamps both. @defaultValue false
+     */
+    clampToView?: boolean | 'x' | 'y';
+    /**
+     * Render the handle **element** yourself (headless): return your element with `handleProps` spread
+     * onto it — that wires placement, pointer-capture, cursor, and events. Replaces the default dot and
+     * `children`. Use it for a configured look — e.g. an Excel table-resize tick.
+     */
+    renderHandle?: (props: DragHandleRenderProps) => React.ReactNode;
+    /** Static content inside the default dot. Ignored when `renderHandle` is set. */
+    children?: React.ReactNode;
+    className?: string;
+    style?: React.CSSProperties;
+    /**
+     * Keep the currently-focused element focused across the drag (`preventDefault` on pointer-down, which
+     * suppresses the compat `mousedown` that would otherwise move focus to the grid's `tabIndex` Stage).
+     * Used by the reference-range picker so dragging a handle doesn't blur the formula editor's textarea —
+     * it preserves whatever had focus rather than stealing it. @defaultValue false
+     */
+    preserveFocus?: boolean;
+}
+/**
+ * A generic, draggable handle anchored to a corner/edge of a grid range. It owns only the **gesture
+ * mechanics** — placement, pointer capture, and cell hit-testing with edge auto-scroll — and reports
+ * the drag in **cell terms** (`from` → `to`). It holds no range math: flavors (fill, table-resize,
+ * touch-extend) own the cell→model conversion and any preview.
+ *
+ * @remarks
+ * The handle centre is placed with the shared {@link ReactUtils.edgeCenter} rule — the same one
+ * gridlines and cell borders use — so it lands on the boundary device-crisply and flush with the
+ * selection outline. It's a real DOM element (not a Stage responder): it captures the pointer on its
+ * own element so move/up survive leaving the handle, and it `stopPropagation`s pointer-down so the
+ * selection layer underneath does not also begin a gesture. Provide
+ * {@link DragHandleProps.renderHandle} to render the element yourself (spread the supplied
+ * `handleProps`).
+ */
+export declare const DragHandle: React.FC<DragHandleProps>;
+//# sourceMappingURL=DragHandle.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"DragHandle.d.ts","sourceRoot":"","sources":["../../../../src/range/DragHandle.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAQnE,oGAAoG;AACpG,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE7E;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,MAAM,EAAE,YAAY,CAAC;IACrB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,UAAU,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,WAAW,EAAE;QACX,aAAa,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;QAC/C,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;QACjD,cAAc,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;QACjD,KAAK,EAAE,KAAK,CAAC,aAAa,CAAC;KAC5B,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,KAAK,EAAE,WAAW,CAAC;IACnB,mDAAmD;IACnD,MAAM,EAAE,YAAY,CAAC;IACrB,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yFAAyF;IACzF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kGAAkG;IAClG,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAChE,6FAA6F;IAC7F,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAC/E,0DAA0D;IAC1D,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAC9E;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,qGAAqG;IACrG,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3C;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IACjC;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;;;;;;;;;;OAUG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,GAAG,GAAG,GAAG,CAAC;IAClC;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,KAAK,CAAC,SAAS,CAAC;IACjE,iFAAiF;IACjF,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC;IAC5B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,EAAE,KAAK,CAAC,EAAE,CAAC,eAAe,CA6GhD,CAAC"}

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

@@ -0,0 +1,86 @@
+import { RangeCoords } from '@sheetxl/utils';
+/**
+ * Props for {@link Draggable}.
+ */
+export interface DraggableProps {
+    /**
+     * The range the wrapped content occupies (controlled). The drag's "from"; the result range comes out
+     * via `onDrag*`.
+     */
+    range?: RangeCoords;
+    /**
+     * The content to make movable — any visual ({@link RangeRect}, `RangeResizer`, …), rendered at
+     * `range` and grabbable. `Draggable` draws nothing itself; the visuals are all composed children.
+     */
+    children?: React.ReactNode;
+    /**
+     * Where you can grab to move: the whole rectangle (`entire`, the default) or only its **border ring**
+     * (`edges` — interior clicks fall through, for a selection whose interior is for selecting/editing).
+     *
+     * @defaultValue 'entire'
+     */
+    grip?: 'entire' | 'edges';
+    /**
+     * Grab slack in device px. For `grip: 'edges'` it's the border-ring hit thickness (centered on the
+     * border, so half reaches outside the range). For `grip: 'entire'` the whole rectangle is grabbable
+     * and this pads the hit area OUTWARD by the same amount, so you can grab just past the edge too.
+     *
+     * @defaultValue 10
+     */
+    hitSize?: number;
+    /**
+     * The pointer entered (`true`) or left (`false`) the grip's hit area — the border ring for
+     * `grip: 'edges'`, the whole (outward-padded) rectangle for `grip: 'entire'`. Use it to render a
+     * hover affordance on the composed visual, e.g. Excel thickening the move border on hover. Fires only
+     * on a real enter/leave, not on every move.
+     */
+    onHoverChange?: (hovered: boolean) => void;
+    /**
+     * The drag began (`true`) / ended (`false`) — fires on every press/release, even a press with no
+     * movement (unlike `onDragEnd`, which only fires on an actual translation). Separate from
+     * {@link DraggableProps.onHoverChange} because pointer-capture suppresses the grip's hover events
+     * mid-drag; use this to keep a drag affordance (e.g. the thickened move border) lit for the whole drag.
+     */
+    onDragStateChange?: (dragging: boolean) => void;
+    /** Drag started; `range` is the original. */
+    onDragStart?: (range: RangeCoords, e: React.PointerEvent) => void;
+    /**
+     * The translated range during the drag. Wire it to update `range` (the content follows the pointer —
+     * "live"), or to position a composed ghost preview. `Draggable` itself stays silent.
+     */
+    onDragMove?: (range: RangeCoords, e: React.PointerEvent) => void;
+    /** Drag released: commit the translated range. */
+    onDragEnd?: (range: RangeCoords, e: React.PointerEvent) => void;
+    /**
+     * Render a **ghost** at the in-flight translated range while a drag is in progress (nothing is rendered
+     * when idle). `Draggable` owns the preview state internally, so the consumer doesn't have to stash it
+     * — return e.g. a faded {@link RangeRect} to trail the pointer while the original stays put (the
+     * cut-move pattern). For a "live" feel (content follows the pointer) wire `onDragMove → range` instead.
+     */
+    renderMove?: (range: RangeCoords) => React.ReactNode;
+    /**
+     * Keep the current focus across a move drag (`preventDefault` on pointer-down, suppressing the compat
+     * `mousedown` that would move focus to the grid's `tabIndex` Stage). Used by the reference-range picker
+     * so dragging a range doesn't blur the formula editor's textarea. @defaultValue false
+     */
+    preserveFocus?: boolean;
+}
+/**
+ * A **"make draggable" wrapper**: it makes its `children` movable (translate — same size, new location)
+ * and reports the translated range via `onDrag*`. It owns ONLY the gesture (pointer-capture +
+ * cell-delta translate + edge auto-scroll); it draws nothing. The consumer composes the visuals and
+ * decides what a drag means:
+ *
+ * - **Live** — `onDragMove` → update `range`; the wrapped child follows the pointer (e.g. a picker, or
+ *   any draggable `RangeRect`). This is the default feel.
+ * - **Ghost** — pass `renderMove`; `Draggable` tracks the in-flight range internally and hands it to
+ *   your callback to render a second, faded layer, while the original stays put and commits on
+ *   `onDragEnd` (e.g. a selection's cut-move). No preview state to manage in the consumer.
+ *
+ * @remarks
+ * The grip is the whole rectangle ({@link DraggableProps.grip} = `entire`) by default, or just its
+ * border ring (`edges`). Drawn first so child handles (resize corners) layered above stay grabbable;
+ * `stopPropagation` keeps a layer beneath from also reacting.
+ */
+export declare const Draggable: React.FC<DraggableProps>;
+//# sourceMappingURL=Draggable.d.ts.map

package/types/src/range/Draggable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Draggable.d.ts","sourceRoot":"","sources":["../../../../src/range/Draggable.tsx"],"names":[],"mappings":"AAEA,OAAO,EAA+B,KAAK,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAa/E;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B;;;;;OAKG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC;IAC1B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC3C;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC;IAChD,6CAA6C;IAC7C,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAClE;;;OAGG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IACjE,kDAAkD;IAClD,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,EAAE,KAAK,CAAC,YAAY,KAAK,IAAI,CAAC;IAChE;;;;;OAKG;IACH,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,KAAK,CAAC,SAAS,CAAC;IACrD;;;;OAIG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,EAAE,KAAK,CAAC,EAAE,CAAC,cAAc,CAmI9C,CAAC"}