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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/grid-react",
   "description": "Grid React - Advanced grid component for React",
-  "version": "0.8.0-beta.1",
+  "version": "0.8.0-beta.11",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -9,13 +9,12 @@
       "types": "./types/index.d.ts",
       "browser": "./browser/esm/index.mjs",
       "node": "./node/esm/index.mjs",
-      "import": "./browser/esm/index.mjs",
-      "require": "./browser/cjs/index.cjs"
+      "default": "./browser/esm/index.mjs"
     }
   },
   "types": "./types/index.d.ts",
   "module": "./browser/esm/index.mjs",
-  "main": "./browser/cjs/index.cjs",
+  "main": "./browser/esm/index.mjs",
   "sideEffects": [
     "*.css",
     "**/*.css"
@@ -41,20 +40,17 @@
     "table"
   ],
   "dependencies": {
-    "@floating-ui/react-dom": "^2.1.9",
-    "@sheetxl/utils": "^0.8.0-beta.1",
-    "@sheetxl/utils-react": "^0.8.0-beta.1",
+    "@sheetxl/utils": "^0.8.0-beta.11",
+    "@sheetxl/utils-react": "^0.8.0-beta.11",
     "clsx": "^2.1.1",
-    "react-merge-refs": "^3.0.2",
-    "react-use": "^17.6.1",
-    "tiny-invariant": "^1.3.3"
+    "react-merge-refs": "^3.0.2"
   },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3"
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0"
   }
 }

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/cell/GridlineLayer.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
-import { OrientationFlags } from '@sheetxl/utils';
+import { RangeCoords, OrientationFlags } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
 import { LayerProps } from '../layer';
 import { CellModelOptions } from './_CellModel';
 /**
@@ -28,6 +29,43 @@ export interface GridlineLayerProps extends Omit<LayerProps, 'children'>, CellMo
     /** Per-`<path>` props for the vertical (column) lines. */
     propsColumns?: React.SVGProps<SVGPathElement>;
 }
+/**
+ * Options for {@link buildGridlinePath}.
+ */
+export interface GridlinePathOptions {
+    /**
+     * Stroke width in device pixels; decides how each line center snaps.
+     *
+     * @defaultValue 1
+     */
+    width?: number;
+    /**
+     * CSS px added to each line's cross-axis position before it snaps (an even-width stroke that
+     * grows toward the trailing side).
+     *
+     * @defaultValue 0
+     */
+    shift?: number;
+    /**
+     * More gaps for one line, as view-relative `[start0, end0, start1, end1, ...]` along the line,
+     * sorted by start. `trailIndex` is the row (horizontal) or column (vertical) whose trailing edge
+     * the line is.
+     */
+    breaksAt?: (trailIndex: number) => readonly number[] | undefined;
+}
+/**
+ * Build a single SVG path `d` for one orientation's gridlines — each line broken around the merged
+ * ranges that straddle it. ONE path with many `M…L…` subpaths (vs one `<path>` per segment) keeps the
+ * DOM to a single node per axis; the segment count changes every scroll tick, so per-segment elements
+ * would thrash the DOM. Device snapping is baked into each subpath's coordinates and the stroke width
+ * is uniform, so a single path renders identically to N separate paths at any dpr.
+ *
+ * @param pane The pane to draw for.
+ * @param isHorizontal `true` for the row lines, `false` for the column lines.
+ * @param ranges Index-space ranges the lines break around (merges, overflow).
+ * @param options See {@link GridlinePathOptions}.
+ */
+export declare const buildGridlinePath: (pane: IGridPane, isHorizontal: boolean, ranges: readonly RangeCoords[], options?: GridlinePathOptions) => string;
 /**
  * A **layer** (pane-aware): paints the gridlines for its pane, broken around merged cells, inside a
  * single full-pane {@link Layer} host box. Sources the merge spans from the merges-only

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

@@ -1,4 +1,4 @@
-import { CellCoords } from '@sheetxl/utils';
+import { CellCoords, MaybePromise } from '@sheetxl/utils';
 import { ICellAnchor } from '../selection';
 import { EditCommitArgs } from './EditState';
 import { EditSession, StartEditOptions, EditModel } from './EditSession';
@@ -10,7 +10,7 @@ import { EditSession, StartEditOptions, EditModel } from './EditSession';
  * @remarks
  * An implementation detail of {@link DefaultEditable}, not part of the layer-facing contract. Collapses
  * the former `getClean` + `canEdit` + `commit` (`null` ⇒ "not editable"). A story closes over a values
- * map; the real app reads an `ISheet` (and returns `null` for a protected cell).
+ * map; the real app reads an `IWorksheet` (and returns `null` for a protected cell).
  *
  * @typeParam C - clean type. @typeParam D - dirty type. @typeParam A - commit args.
  */
@@ -25,7 +25,7 @@ export type CreateEdit<C, D = string, A = EditCommitArgs> = (coords: CellCoords)
  * (`startEdit`/`commit`/`cancel`); an app-side bridge can publish {@link getSession} onto the edit-mode
  * bus on each `subscribe` notification. It does **not** vend sessions — there is only
  * ever one active edit, held here. {@link DefaultEditable} is the default implementation; the real app
- * supplies its own (or reuses it with an `ISheet`-backed {@link CreateEdit}).
+ * supplies its own (or reuses it with an `IWorksheet`-backed {@link CreateEdit}).
  *
  * @typeParam C - clean type. @typeParam D - dirty type. @typeParam A - commit args.
  */
@@ -40,10 +40,20 @@ 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. */
-    commit(args?: A): boolean;
+    /**
+     * Commit the current edit. On success clears the session; returns whether it succeeded, or a
+     * promise of that while the model's {@link EditModel.validate} answers asynchronously (the session
+     * stays open until then).
+     */
+    commit(args?: A): MaybePromise<boolean>;
     /** Cancel the current edit (revert + clear the session). */
     cancel(): void;
     /**
@@ -73,6 +83,10 @@ export interface DefaultEditableOptions {
      * — an invalid entry keeps you in the cell); the owner — who holds the writable selection the
      * anchor reads — performs the move. When omitted, the editable **cancels** the failed edit instead
      * (the typed value is discarded, but session and selection stay in sync).
+     *
+     * A click-away whose commit is still being checked ({@link EditModel.validate} answering
+     * asynchronously) is held on the edited cell the same way, and once the commit succeeds this is
+     * called again with the cell the user went to.
      */
     revertAnchor?: (coords: CellCoords) => void;
 }
@@ -99,19 +113,24 @@ export declare class DefaultEditable<C, D = string, A = EditCommitArgs> implemen
     private readonly revertAnchor?;
     private readonly unsubscribeAnchor;
     private current;
+    private leaveTarget;
     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 */
     startEdit(coords: CellCoords, options?: StartEditOptions<D>): boolean;
     /** @inheritdoc IEditable.commit */
-    commit(args?: A): boolean;
+    commit(args?: A): MaybePromise<boolean>;
+    private end;
     /** @inheritdoc IEditable.cancel */
     cancel(): void;
     /** @inheritdoc IEditable.dispose */

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

@@ -1,4 +1,4 @@
-import { CellCoords } from '@sheetxl/utils';
+import { CellCoords, MaybePromise } from '@sheetxl/utils';
 import { ICellAnchor } from '../selection';
 import { EditState, EditorMode, EditorTextSelection, EditCommitArgs } from './EditState';
 /**
@@ -36,10 +36,25 @@ export interface IInputHandle {
  * @typeParam C - clean type. @typeParam D - dirty type. @typeParam A - commit args.
  */
 export interface EditModel<C, D = string, A = EditCommitArgs> {
+    /**
+     * The cell as the model homes it, when that is more than the cell it was asked to edit (a sheet
+     * model adds the sheet's scope). The session reports these; omitted, it reports the cell asked for.
+     */
+    coords?: CellCoords;
     /** The clean value, captured now (edit start). */
     clean: C;
     /** Write the dirty value to the model. Return `false`, or throw, to reject (keeps the edit open). */
     commit(dirty: D, args?: A): boolean | void;
+    /**
+     * Check the dirty value before it is written. Return `false` to refuse: the edit stays open and
+     * the leave-key does not navigate.
+     *
+     * @remarks
+     * May answer with a promise, and the commit then waits for it with the edit still open. If the
+     * edit is cancelled, or its value changes, before the answer arrives, nothing is written. Whoever
+     * refuses says why: the edit only stays open.
+     */
+    validate?(dirty: D, args?: A): MaybePromise<boolean>;
 }
 /**
  * What the {@link EditSession} constructor takes: the {@link EditModel} bits plus the cell. The owning
@@ -49,6 +64,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 +116,10 @@ export interface CommitContext<D = string, A = EditCommitArgs> {
  */
 export declare class EditSession<C, D = string, A = EditCommitArgs> implements ICellAnchor {
     private readonly commitFn;
+    private readonly validateFn?;
+    private pending;
+    private cancelled;
+    private readonly onCommitError?;
     private state;
     private readonly listeners;
     private readonly commitListeners;
@@ -165,11 +189,16 @@ export declare class EditSession<C, D = string, A = EditCommitArgs> implements I
     /**
      * @internal Driven by {@link DefaultEditable.commit}. Runs **every** beforeCommit consumer (a
      * `veto()` or throw rejects — a throw is also logged, never silently swallowed), then the model's
-     * write. Returns whether it succeeded. A no-op (nothing typed) skips only the model write — the
-     * listeners still run (and may veto), so a consumer observing "commit happened" is never skipped.
-     * Does NOT clear the owning editable's session — `editable.commit` does that on success.
+     * {@link EditModel.validate}, then its write. Returns whether it succeeded, or a promise of that
+     * while `validate` answers asynchronously. A no-op (nothing typed) skips the check and the write —
+     * the listeners still run (and may veto), so a consumer observing "commit happened" is never
+     * skipped. Does NOT clear the owning editable's session — `editable.commit` does that on success.
      */
-    commit(args?: A): boolean;
+    commit(args?: A): MaybePromise<boolean>;
+    private write;
+    private reportCommitError;
+    /** Whether a commit is waiting on an asynchronous {@link EditModel.validate}. */
+    isCommitPending(): boolean;
     /** @internal Driven by {@link DefaultEditable.cancel}. Notifies cancel observers; the editable clears the session. */
     cancel(): void;
     /** Register a beforeCommit consumer (validation, peers, …). Many may register; any may veto. */

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/EditorDiv.d.ts

@@ -55,8 +55,9 @@ export interface EditorDivProps<C, D = string, A = EditCommitArgs> {
  *
  * @remarks
  * Unlike the layer, this is **always visible** — while idle it shows {@link EditorDivProps.idleClean}
- * (the active cell). It never auto-grabs focus (`autoFocus: false`): the field is focused by the
- * user's click, so the in-grid editor and the formula bar don't fight over focus when an edit begins.
+ * (the active cell). It does not grab focus for an ordinary edit: the field is focused by the user's
+ * click, so the in-grid editor and the formula bar don't fight over focus when an edit begins. An edit
+ * whose session names this host as its active editor from the start is the exception: it opens here.
  */
 export declare function EditorDiv<C, D = string, A = EditCommitArgs>(props: EditorDivProps<C, D, A>): React.ReactElement;
 export declare namespace EditorDiv {

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

@@ -1,4 +1,4 @@
-import { CellCoords, Size } from '@sheetxl/utils';
+import { CellCoords, MaybePromise, Size } from '@sheetxl/utils';
 import { EditorMode, EditorTextSelection, EditCommitArgs } from './EditState';
 /**
  * Props passed to the (swappable) editor input — the visual + keyboard surface of the editor. The
@@ -67,9 +67,13 @@ 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.
+     *
+     * A promise means the commit is still being checked (the model's `validate`); the input stops
+     * the key and the session stays open until it lands.
      */
-    onCommit(args?: EditCommitArgs): boolean;
+    onCommit(args?: EditCommitArgs): MaybePromise<boolean>;
     /** Cancel/revert the edit. */
     onCancel(): void;
     /**

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

@@ -60,10 +60,15 @@ export interface EditorLayerProps<C, D = string, A = EditCommitArgs> extends Vir
  * Always-mounted inline cell editor, as a grid layer.
  *
  * @remarks
- * The input is mounted for the life of the grid (hidden when idle);
- * starting an edit just seeds the first character **by value** into the {@link IEditable} and
- * focuses the input. Render it inside `renderLayers`; with frozen panes each pane instantiates one,
- * and only the pane containing the active cell shows it.
+ * The input is mounted for the life of the grid (hidden when idle); starting an edit seeds the first
+ * character **by value** into the {@link IEditable} and focuses the input. Mount it as the grid's LAST
+ * child so the box paints over everything; with frozen panes each pane instantiates one, and only the
+ * pane containing the active cell shows it.
+ *
+ * This layer carries no event handlers. The ready-mode starters (typed key / F2 / double-click) are
+ * the {@link EditorStartLayer}, mounted as the grid's FIRST child: a Layer's handlers are its slot's
+ * tap, heard on every layer's turn top first, so start handlers on the top layer would intercept keys
+ * and double-clicks aimed at any widget below it before that widget's own handlers ran.
  */
 export declare function EditorLayer<C, D = string, A = EditCommitArgs>(props: EditorLayerProps<C, D, A>): React.ReactElement;
 //# sourceMappingURL=EditorLayer.d.ts.map

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

@@ -0,0 +1,33 @@
+import { EditCommitArgs } from './EditState';
+import { IEditable } from './DefaultEditable';
+/**
+ * Props for {@link EditorStartLayer}.
+ *
+ * @typeParam C - The clean value type. @typeParam D - The dirty value type. @typeParam A - Commit args.
+ */
+export interface EditorStartLayerProps<C, D = string, A = EditCommitArgs> {
+    /** The editable to start edits on — the same instance the {@link EditorLayer} renders. */
+    editable: IEditable<C, D, A>;
+}
+/**
+ * The grid's **ready-mode** edit starters, as a content-less grid layer: a typed character / `F2` /
+ * `Backspace` opens an edit on the anchor, a double-click opens one on the cell under the pointer.
+ *
+ * @remarks
+ * This is deliberately a separate layer from the {@link EditorLayer} that paints the box. The box must
+ * sit at the **top** of the stack to paint over everything, but a Layer's handlers are its slot's tap
+ * — grid-wide ears that fire on every layer's turn, top first — so handlers on the top layer would
+ * intercept keys and double-clicks aimed at any widget below it (a chart, a note) before that widget's
+ * own handlers ran. Starting an edit is the grid *floor's* behavior: it belongs at the **bottom** of
+ * the stack, where it only hears what no widget above consumed. Mount it as the grid's first child.
+ *
+ * Keys are positionless, so the floor position alone is not enough for them: a focused widget that
+ * does not consume a printable key (it has no use for it, and must let keys through so its own
+ * commands can resolve) would otherwise still reach this tap. The key start therefore acts only when
+ * the key is aimed at the grid surface itself — the surface (or the pane's focus target, which
+ * stands in for it) is the focused element — which is what "the grid is in
+ * ready mode" means. A double-click needs no such guard: it has a position, and a widget that owns
+ * that position consumes it.
+ */
+export declare function EditorStartLayer<C, D = string, A = EditCommitArgs>(props: EditorStartLayerProps<C, D, A>): React.ReactElement;
+//# sourceMappingURL=EditorStartLayer.d.ts.map

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

@@ -6,5 +6,6 @@ export * from './DefaultEditable';
 export * from './EditorPlacement';
 export * from './EditorInput';
 export * from './EditorLayer';
+export * from './EditorStartLayer';
 export * from './EditorDiv';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1,5 +1,5 @@
 import { RefObject } from 'react';
-import { Direction, RangeAxis } from '@sheetxl/utils';
+import { Direction, RangeAxis, MaybePromise } from '@sheetxl/utils';
 import { EditorMode, EditCommitArgs } from './EditState';
 import { StartEditOptions } from './EditSession';
 /**
@@ -29,7 +29,12 @@ export interface EditorKeymapProps {
     value: string;
     onDirtyChange(dirty: string): void;
     onModeChange(mode: EditorMode): void;
-    onCommit(args?: EditCommitArgs): boolean;
+    /**
+     * Commit the edit. A promise means the commit is still being checked: the key is consumed, and the
+     * move it asks for is made through {@link onNavigate} / {@link onTraverse} once the commit lands
+     * (with neither supplied, the active cell stays put).
+     */
+    onCommit(args?: EditCommitArgs): MaybePromise<boolean>;
     onCancel(): void;
     /**
      * Optional. When provided, a successful **enter-mode arrow** commit **navigates here, in the input**,
@@ -54,6 +59,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/GridFreezeAnchor.d.ts

@@ -0,0 +1,29 @@
+import { RangeAxis } from '@sheetxl/utils';
+import { FreezeDragPosition } from './_freezeSnap';
+export interface GridFreezeAnchorProps {
+    /** The axis the freeze moves along: `Column` drags the vertical freeze line. */
+    axis: RangeAxis;
+    /** Disable the grip (the pointer falls through to the cells). */
+    disabled?: boolean;
+    /** The pointer has moved past the threshold and the drag has begun. */
+    onFreezeDragStart?: (position: FreezeDragPosition) => void;
+    /** Called on every move while dragging. */
+    onFreezeDrag?: (position: FreezeDragPosition) => void;
+    /** The pointer was released after a drag. */
+    onFreezeDragEnd?: (position: FreezeDragPosition) => void;
+    /** The drag was abandoned (Escape); nothing should be committed. */
+    onFreezeDragCancel?: () => void;
+    /** The grip became active (hovered or dragging) or stopped being so — e.g. to highlight the freeze line. */
+    onActiveChange?: (active: boolean) => void;
+}
+/**
+ * The freeze grip over the cells: a hit strip along the main grid's freeze line, dragged like
+ * {@link HeaderFreezeAnchor}. It draws nothing — the grid draws the line, and can highlight it from
+ * `onActiveChange`.
+ *
+ * @remarks
+ * Render it in the main grid's layers. It exists only while the axis is frozen, in the frozen panes whose
+ * trailing edge is the line (for columns, the left and top-left panes).
+ */
+export declare const GridFreezeAnchor: import('react').MemoExoticComponent<(props: GridFreezeAnchorProps) => string | number | bigint | boolean | Iterable<import('react').ReactNode> | Promise<string | number | bigint | boolean | import('react').ReactPortal | import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>> | Iterable<import('react').ReactNode> | null | undefined> | import("react").JSX.Element | null | undefined>;
+//# sourceMappingURL=GridFreezeAnchor.d.ts.map

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

@@ -56,15 +56,32 @@ export interface IHeaderDividerAttributes {
 export interface IHeaderDividerElement extends HTMLDivElement, IHeaderDividerAttributes {
 }
 export interface HeaderDividerRendererProps extends HeaderDividerProps {
+    /**
+     * The divider's line in pane coordinates — zero-width for a column divider, zero-height for a row —
+     * snapped to the device pixel the gridline paints. The renderer positions its element (hit area and
+     * visible line) around it.
+     */
     bounds: Bounds;
     /**
      * Handle mouse down and all dragging
      */
     onPointerDown: React.PointerEventHandler<HTMLDivElement>;
     onAutoFit: () => void;
+    /**
+     * Reveal the hidden headers this divider sits on. Present only when the divider has hidden headers
+     * to reveal and the consumer handles it.
+     */
+    onUnhide?: () => void;
+    /** The divider is pressed or being dragged. */
+    isActive?: boolean;
 }
 export interface HeaderDividerAnchorProps extends HeaderDividerProps {
     renderDivider?: (props: HeaderDividerRendererProps, pane: IGridPane) => React.ReactNode;
+    /**
+     * The clipped bounds of the pane's visible headers, from {@link getHeaderDividerBounds}. Computed when
+     * omitted; pass it when rendering a pane's worth of dividers so it is computed once.
+     */
+    visibleBounds?: Bounds | null;
     /**
      * The number of pixels to mouse before resizing starts.
      * If this number is less than 1 then it will be 1.
@@ -110,6 +127,13 @@ export interface HeaderDividerAnchorProps extends HeaderDividerProps {
      * @param index
      */
     onDividerAutoFit?: (index: number) => void;
+    /**
+     * Called when the unhide button on a divider over hidden headers is clicked. Without it the divider
+     * shows no unhide button.
+     *
+     * @param index the index of the divider.
+     */
+    onDividerUnhide?: (index: number) => void;
 }
 export declare const DefaultHeaderDivider: import('react').NamedExoticComponent<Omit<HeaderDividerRendererProps, "ref"> & import('react').RefAttributes<IHeaderDividerElement>>;
 /**
@@ -117,4 +141,9 @@ export declare const DefaultHeaderDivider: import('react').NamedExoticComponent<
  * Resize, hide/unhide, etc.
  */
 export declare const HeaderDividerAnchor: import('react').NamedExoticComponent<Omit<HeaderDividerAnchorProps, "ref"> & import('react').RefAttributes<IHeaderDividerElement>>;
+/**
+ * The clipped bounds of a pane's visible headers on an axis — the span every divider in the pane shares —
+ * or `null` when none are visible.
+ */
+export declare const getHeaderDividerBounds: (pane: IGridPane, axis: RangeAxis) => Bounds | null;
 //# sourceMappingURL=HeaderDividerAnchor.d.ts.map

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

@@ -0,0 +1,37 @@
+import { RangeAxis } from '@sheetxl/utils';
+import { FreezeDragPosition } from './_freezeSnap';
+export type { FreezeDragPosition } from './_freezeSnap';
+export interface HeaderFreezeAnchorProps {
+    /** The axis the freeze moves along: `Column` drags the vertical freeze line along the column header. */
+    axis: RangeAxis;
+    /** Disable the grip entirely (no hit area, no hover). */
+    disabled?: boolean;
+    /**
+     * Draw the bar in its active color although this grip is not hovered — e.g. while the freeze line's grip
+     * in the body is.
+     */
+    highlight?: boolean;
+    /** The pointer has moved past the threshold and the drag has begun. */
+    onFreezeDragStart?: (position: FreezeDragPosition) => void;
+    /** Called on every move while dragging. */
+    onFreezeDrag?: (position: FreezeDragPosition) => void;
+    /** The pointer was released after a drag. */
+    onFreezeDragEnd?: (position: FreezeDragPosition) => void;
+    /** The drag was abandoned (Escape); nothing should be committed. */
+    onFreezeDragCancel?: () => void;
+    /** The grip became active (hovered or dragging) or stopped being so — e.g. to highlight the freeze line. */
+    onActiveChange?: (active: boolean) => void;
+}
+/**
+ * The freeze grip: a bar in a header on the freeze line (or at the header's start when nothing is frozen
+ * on this axis). Dragging it snaps the freeze to the nearest header boundary on screen.
+ *
+ * @remarks
+ * Render it in the header's layers, above the resize dividers. It draws in one pane only: the frozen pane,
+ * centered on its trailing edge (frozen panes sit over the scrolling one, so the grip covers the last
+ * frozen header's divider), or the scrolling pane's leading edge when nothing is frozen. The drag reports
+ * positions only — committing the freeze is the caller's. {@link GridFreezeAnchor} is the same grip on the
+ * freeze line over the cells.
+ */
+export declare const HeaderFreezeAnchor: import('react').MemoExoticComponent<(props: HeaderFreezeAnchorProps) => import("react").JSX.Element | null>;
+//# sourceMappingURL=HeaderFreezeAnchor.d.ts.map

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

@@ -0,0 +1,28 @@
+import { IGridPane } from '../surface';
+/**
+ * Where a freeze drag would land: the snapped boundary and the raw pointer, both as CLIENT coordinates
+ * on the drag axis so any pane (header or body) maps them with `getPanePointFromPointer`.
+ */
+export interface FreezeDragPosition {
+    /**
+     * The freeze count the drop commits: the index of the first track in the scrolling area. `0` ⇒
+     * unfreeze this axis.
+     */
+    index: number;
+    /** Client coordinate (x for columns, y for rows) of the snapped boundary — the solid line. */
+    snapClient: number;
+    /**
+     * Client coordinate of the pointer — the dashed line. Absent once the pointer is past the start of the
+     * header (where the drop unfreezes), so no line is drawn outside the grid.
+     */
+    pointerClient?: number;
+}
+/**
+ * Snap a client coordinate to the nearest track boundary on screen across the header's panes.
+ *
+ * Candidates are the leading edges of the visible tracks in the frozen pane and the scrolling pane, plus
+ * the surface's own leading edge (which unfreezes). Only boundaries actually on screen are candidates, so
+ * a drag can never freeze past what is visible.
+ */
+export declare const snapToBoundary: (pane: IGridPane, isColumn: boolean, pointerClient: number, crossClient: number) => FreezeDragPosition;
+//# sourceMappingURL=_freezeSnap.d.ts.map

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

@@ -0,0 +1,28 @@
+import { RangeAxis } from '@sheetxl/utils';
+import { FreezeDragPosition } from './_freezeSnap';
+export interface FreezeGripOptions {
+    axis: RangeAxis;
+    disabled: boolean;
+    /** Whether this pane draws the grip. A pane that stops drawing it never hears the pointer leave. */
+    isOwner: boolean;
+    onFreezeDragStart?: (position: FreezeDragPosition) => void;
+    onFreezeDrag?: (position: FreezeDragPosition) => void;
+    onFreezeDragEnd?: (position: FreezeDragPosition) => void;
+    onFreezeDragCancel?: () => void;
+    onActiveChange?: (active: boolean) => void;
+}
+export interface FreezeGrip {
+    /** Hovered or dragging, in the owning pane, while enabled. */
+    isActive: boolean;
+    cursor: string;
+    /** Spread onto the hit area. */
+    hitProps: React.HTMLAttributes<HTMLDivElement>;
+    /** The drag backdrop (forces the cursor, shields other components); render it alongside the hit area. */
+    backdrop: React.ReactNode;
+}
+/**
+ * The gesture behind a freeze grip, wherever its hit area sits: press, threshold, snapped drag positions,
+ * Escape to abandon, and the active (hovered or dragging) state.
+ */
+export declare const useFreezeGrip: (options: FreezeGripOptions) => FreezeGrip;
+//# sourceMappingURL=_useFreezeGrip.d.ts.map

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

@@ -1,3 +1,5 @@
 export * from './HeaderDividerAnchor';
+export * from './HeaderFreezeAnchor';
+export * from './GridFreezeAnchor';
 export * from './useHeaderSelectionPointer';
 //# sourceMappingURL=index.d.ts.map