@sheetxl/grid-react 0.7.21 → 0.7.23-beta.1

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

@@ -0,0 +1,61 @@
+import { CellCoords } from '@sheetxl/utils';
+/**
+ * The editor's two modes (renamed from `EditMode` to avoid colliding with the global edit-mode bus
+ * `EditMode` in `@sheetxl/utils`):
+ *
+ * - `enter` — started by typing (or Backspace). Typing replaces; arrow keys commit + let the
+ *   selection navigate.
+ * - `edit` — started by F2 / double-click / clicking in. Arrow keys move the caret.
+ */
+export type EditorMode = 'enter' | 'edit';
+/**
+ * Intent flags passed through a commit (the editor's commit "signal") — from the keymap, up through
+ * {@link EditorInputProps.onCommit}, to {@link IEditable.commit} and on to the model's write, where
+ * the app interprets them. Kept grid-generic: a "broadcast" commit means *apply to the whole
+ * selection, not just the active cell* — an interaction concept, not a spreadsheet one.
+ */
+export interface EditCommitArgs {
+    /**
+     * Broadcast the value to **every cell in the current selection** rather than only the active cell —
+     * Excel's `Ctrl+Enter`. The active cell does not move (the leave-key does not navigate/traverse).
+     */
+    broadcast?: boolean;
+}
+/**
+ * A text selection range within the editor input. Mirrors the `HTMLTextAreaElement` selection API.
+ */
+export interface EditorTextSelection {
+    start: number;
+    end: number;
+    direction?: 'forward' | 'backward' | 'none';
+}
+/**
+ * The immutable snapshot inside an {@link EditSession} — the value React renders from. Its existence
+ * (a non-`null` session state) means an edit is active.
+ *
+ * @typeParam C - The clean value type. @typeParam D - The dirty (working) value type.
+ */
+export interface EditState<C, D = string> {
+    /** The current {@link EditorMode}. */
+    mode: EditorMode;
+    /** The cell being edited. */
+    coords: CellCoords;
+    /**
+     * The clean value, captured from the model when the edit began. The input projects it to the
+     * displayed text when {@link dirty} is unset, and a cell-aware input reads styling/rendering info
+     * from it that the dirty text does not carry.
+     */
+    clean: C;
+    /**
+     * The working (dirty) value. `undefined` ⇒ show the {@link clean} value. The first keystroke is
+     * seeded here **by value** — why no keystroke is lost (no synthetic replay).
+     */
+    dirty: D | undefined;
+    /** Selection to apply the next time the input focuses (consumed once per {@link token}). */
+    initialSelection?: EditorTextSelection | null;
+    /** Whether the input should grab focus when the edit begins. */
+    autoFocus: boolean;
+    /** Bumped on each (re)start; editors watch it to re-focus on a fresh open. */
+    token: number;
+}
+//# sourceMappingURL=EditState.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EditState.d.ts","sourceRoot":"","sources":["../../../../src/editor/EditState.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEjD;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,MAAM,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,MAAM,CAAC;CAC7C;AAED;;;;;GAKG;AACH,MAAM,WAAW,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM;IACtC,sCAAsC;IACtC,IAAI,EAAE,UAAU,CAAC;IACjB,6BAA6B;IAC7B,MAAM,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,KAAK,EAAE,CAAC,CAAC;IACT;;;OAGG;IACH,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;IACrB,4FAA4F;IAC5F,gBAAgB,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC9C,gEAAgE;IAChE,SAAS,EAAE,OAAO,CAAC;IACnB,8EAA8E;IAC9E,KAAK,EAAE,MAAM,CAAC;CACf"}

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

@@ -0,0 +1,65 @@
+import { default as React, CSSProperties } from 'react';
+import { EditCommitArgs } from './EditState';
+import { IEditable } from './DefaultEditable';
+import { EditorInputProps } from './EditorInput';
+/**
+ * Props for {@link EditorDiv}.
+ *
+ * @typeParam C - clean value type. @typeParam D - dirty value type. @typeParam A - commit args.
+ */
+export interface EditorDivProps<C, D = string, A = EditCommitArgs> {
+    /** The shared editable (the same instance the grid's {@link EditorLayer} uses). */
+    editable: IEditable<C, D, A>;
+    /**
+     * Swap in a custom input. Defaults to {@link DefaultEditorInput} (`C` = `D` = `string`). The
+     * cell-aware input is passed here for the formula bar, the same way it is for `EditorLayer`.
+     */
+    renderEditor?: (props: EditorInputProps<C, D>) => React.ReactNode;
+    /**
+     * The `clean` to show when there is **no active session** — i.e. the field displaying the active
+     * cell while idle (the formula bar's job). When a session is active, the session's own `clean` is
+     * used instead. The host is value-agnostic, so the caller supplies this (for the sheet, a live cell
+     * getter).
+     */
+    idleClean?: C | null;
+    /**
+     * Optional transform applied to the resolved `clean` (session **or** idle) before the input sees it.
+     * The formula bar uses this to restyle the cell — `c => () => c().createCell({ style })` —
+     * so the **same** input renders in the bar's default font instead of the cell's, with no per-input
+     * "rich styling" flag. Runs in the host, so the input stays a pure renderer.
+     */
+    mapClean?: (clean: C | null) => C | null;
+    /**
+     * This host's LOGICAL editor id, parked on the session when focus lands here (see
+     * {@link EditSession.setActiveEditorId}) so another host — e.g. the grid's in-cell editor returning from a
+     * sheet switch — can tell the user's active editor was THIS one and leave its focus alone. Identity is a
+     * host concern; the input it renders stays identity-free.
+     */
+    editorId?: string;
+    /**
+     * Display-only mode: the field shows {@link idleClean} (or a live session's value) but focusing it does
+     * **not** start an edit, and the rendered input is `readOnly`. The formula bar sets this when the anchor
+     * cell is protected (or the workbook is write-protected), so the value stays visible/copyable but can't
+     * be typed into — and, crucially, focus never reaches `startEdit` (which throws on a read-only workbook).
+     */
+    readOnly?: boolean;
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * A **non-grid** editor host: the `<div>` counterpart of {@link EditorLayer}. It binds to the same
+ * {@link IEditable} and renders the same swappable input — but in a plain box, with no pane / placement
+ * / overflow growth. Built for the **formula bar** (and any non-grid embedding): focusing it starts an
+ * edit on the active cell, and because it shares the editable, typing here drives the very same
+ * {@link EditSession} the in-grid editor shows (live two-way sync, no bus).
+ *
+ * @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.
+ */
+export declare function EditorDiv<C, D = string, A = EditCommitArgs>(props: EditorDivProps<C, D, A>): React.ReactElement;
+export declare namespace EditorDiv {
+    var displayName: string;
+}
+//# sourceMappingURL=EditorDiv.d.ts.map

package/types/src/editor/EditorDiv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EditorDiv.d.ts","sourceRoot":"","sources":["../../../../src/editor/EditorDiv.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAMlD,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE1E;;;;GAIG;AACH,MAAM,WAAW,cAAc,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,cAAc;IAC/D,mFAAmF;IACnF,QAAQ,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC;IAClE;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC;IACzC;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,cAAc,EAAE,KAAK,EAAE,cAAc,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,YAAY,CAqD/G;yBArDe,SAAS"}

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

@@ -0,0 +1,88 @@
+import { CellCoords, 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
+ * surrounding `EditorLayer` owns the session lifecycle and placement; the input only renders
+ * the value and translates keystrokes into the callbacks below.
+ *
+ * @typeParam C - The **clean** value type (see {@link IEditable}). The input projects it to the
+ * displayed text. @typeParam D - The **dirty** (working) value type — `string` for the basic input.
+ *
+ * @remarks
+ * Replace the default input by passing `EditorLayerProps.renderEditor`. The richer, cell-aware
+ * editor (`@sheetxl/react`) is just a different input — `C` = a cell handle — swapped in here.
+ * This module is host-agnostic: both the grid layer (`EditorLayer`) and the plain-div host
+ * (`EditorDiv`, the formula bar) import it, and it pulls in no grid layer code.
+ */
+export interface EditorInputProps<C, D = string> {
+    /** Whether a session is active. The input stays mounted either way; it just hides when closed. */
+    open: boolean;
+    /** The current {@link EditorMode} (drives arrow-key behavior). */
+    mode: EditorMode;
+    /**
+     * The cell being edited (or `null` when closed). The basic input ignores it; a cell-aware input
+     * (the extended `SheetCellEditor`) uses it to read the cell's style / number-format from the model.
+     */
+    coords: CellCoords | null;
+    /** The clean value (or `null` when closed) — projected to display text when {@link dirty} is unset. */
+    clean: C | null;
+    /** The working (dirty) value, or `undefined` when unmodified (show {@link clean}). */
+    dirty: D | undefined;
+    /** Bumped on each session open; watch it to (re)focus and (re)apply the initial selection. */
+    token: number;
+    /**
+     * Whether to grab focus on open. The **host** decides this — it is the one seam through which a host
+     * expresses "you should (not) take focus", so an input never needs to know about editor identity or
+     * visibility (see `EditSession.getActiveEditorId`). Under frozen panes the grid host gates it on the
+     * pane's visibility, so exactly ONE mounted input (the on-screen pane's) focuses; it may flip `true`
+     * after `open` (the edited cell scrolled into view), so watch it alongside {@link token}.
+     */
+    autoFocus: boolean;
+    /**
+     * When `true`, the input is a **display-only** view: the textarea is `readOnly` — still focusable and
+     * selectable (so the value can be read / copied) but not typeable. The formula bar sets this for a
+     * **protected** anchor cell (or a write-protected workbook); a read-only host also does not start an
+     * edit on focus (see `EditorDiv`). The basic input honors it too, though the in-grid editor never
+     * opens for a non-editable cell.
+     */
+    readOnly?: boolean;
+    /** Selection to apply on focus (consumed once per {@link token}). */
+    initialSelection?: EditorTextSelection | null;
+    /** Current pane zoom. */
+    zoom: number;
+    /**
+     * The edited cell's **own** box in **logical** (un-zoomed) px — a single cell, before any overflow
+     * growth. The basic input ignores it; a cell-aware input uses its width as the wrap width (so the
+     * mirror wraps exactly as the textarea will) and may use it as the vertical-align reference.
+     */
+    cellSize?: Size | null;
+    /** Push a change to the working (dirty) value. */
+    onDirtyChange(dirty: D): void;
+    /** Request a mode change (e.g. the user clicked into the text ⇒ `'edit'`). */
+    onModeChange(mode: EditorMode): void;
+    /**
+     * Commit the current edit and return whether it succeeded. Does NOT navigate — the editor never
+     * moves the selection. On a "leave" key (Enter/Tab/enter-mode arrow) the input commits and, **only
+     * if it succeeded**, lets the key propagate to the selection layer to perform the move; on failure
+     * (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.
+     */
+    onCommit(args?: EditCommitArgs): boolean;
+    /** Cancel/revert the edit. */
+    onCancel(): void;
+    /**
+     * Report the natural (content) text size in **logical** (un-zoomed) px so the layer can grow the
+     * box past the cell. Optional — an input that does not measure simply will not overflow.
+     */
+    onNaturalSize?(size: Size): void;
+}
+/**
+ * The default, dependency-free editor input (`C` = `D` = `string`): a single `<textarea>` as a
+ * linear text buffer with the standard spreadsheet keyMap (Enter/Tab to commit, Alt/Meta+Enter for a
+ * newline, F2 to toggle mode, Escape to cancel, arrows that navigate in `enter` mode and move the
+ * caret in `edit` mode).
+ */
+export declare const DefaultEditorInput: React.FC<EditorInputProps<string, string>>;
+//# sourceMappingURL=EditorInput.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EditorInput.d.ts","sourceRoot":"","sources":["../../../../src/editor/EditorInput.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,mBAAmB,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAS7F;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM;IAC7C,kGAAkG;IAClG,IAAI,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,IAAI,EAAE,UAAU,CAAC;IACjB;;;OAGG;IACH,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;IAC1B,uGAAuG;IACvG,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAChB,sFAAsF;IACtF,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC;IACrB,8FAA8F;IAC9F,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,qEAAqE;IACrE,gBAAgB,CAAC,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC9C,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,QAAQ,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,kDAAkD;IAClD,aAAa,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IAC9B,8EAA8E;IAC9E,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACrC;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC;IACzC,8BAA8B;IAC9B,QAAQ,IAAI,IAAI,CAAC;IACjB;;;OAGG;IACH,aAAa,CAAC,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;CAClC;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,KAAK,CAAC,EAAE,CAAC,gBAAgB,CAAC,MAAM,EAAE,MAAM,CAAC,CAmGzE,CAAC"}

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

@@ -0,0 +1,69 @@
+import { CellCoords } from '@sheetxl/utils';
+import { VirtualDivProps } from '../layer';
+import { EditCommitArgs } from './EditState';
+import { IEditable } from './DefaultEditable';
+import { EditorInputProps } from './EditorInput';
+import { EditorAlignment } from './EditorPlacement';
+/**
+ * Props for {@link EditorLayer}.
+ *
+ * @typeParam C - The clean value type. @typeParam D - The dirty value type. @typeParam A - Commit args.
+ *
+ * @remarks
+ * The editor depends only on the {@link IEditable} — anchor + the single current edit. The same
+ * `editable` instance is shared with peers (e.g. the formula bar); its anchor is the same instance the
+ * selection layer writes. The editor reads the anchor but cannot move it — navigation stays the
+ * selection's job. There is no data-source prop; how an edit is created lives inside the editable.
+ */
+export interface EditorLayerProps<C, D = string, A = EditCommitArgs> extends VirtualDivProps {
+    /**
+     * Stacking override, read by the grid's sorter **off this element** when the editor is a grid
+     * child (law 1: z belongs to Layers; the editor's Layer takes its slot from the sorted order).
+     */
+    zIndex?: number;
+    /** The editable. Construct the default with `new DefaultEditable(anchor, createEdit)`. */
+    editable: IEditable<C, D, A>;
+    /**
+     * Swap in a custom editor input. Defaults to {@link DefaultEditorInput} (which requires `C` = `D` =
+     * `string`).
+     */
+    renderEditor?: (props: EditorInputProps<C, D>) => React.ReactNode;
+    /**
+     * Horizontal anchor used when the editor grows past its cell (Excel-style overflow).
+     *
+     * @defaultValue `'left'`
+     */
+    alignment?: EditorAlignment;
+    /**
+     * Background fill for the editor box (behind the input). A string, or a **resolver** called with the
+     * cell being placed — the cell-aware editor passes a resolver that returns the grid cell→normal→body
+     * fill (so the box covers the cell while editing). The basic editor defaults to white.
+     *
+     * @defaultValue `'#ffffff'`
+     */
+    background?: string | ((coords: CellCoords) => string | undefined);
+    /**
+     * Active-border color.
+     *
+     * @defaultValue Excel-like green.
+     */
+    borderColor?: string;
+    /**
+     * Active-border width, in **device** px (matches the selection rectangle's stroke so the two line
+     * up). Snapped to the device grid; the border centerline sits on the cell boundary.
+     *
+     * @defaultValue `2`
+     */
+    borderWidth?: number;
+}
+/**
+ * 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.
+ */
+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/EditorLayer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EditorLayer.d.ts","sourceRoot":"","sources":["../../../../src/editor/EditorLayer.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,UAAU,EAA0B,MAAM,gBAAgB,CAAC;AAMzE,OAAO,EAAqB,KAAK,eAAe,EAAE,MAAM,UAAU,CAAC;AAEnE,OAAO,EAAmB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEnE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAsB,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,EAAsB,KAAK,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE7E;;;;;;;;;;GAUG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,cAAc,CAAE,SAAQ,eAAe;IAC1F;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,0FAA0F;IAC1F,QAAQ,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,KAAK,CAAC,SAAS,CAAC;IAClE;;;;OAIG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,UAAU,KAAK,MAAM,GAAG,SAAS,CAAC,CAAC;IACnE;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,cAAc,EAAE,KAAK,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,GAAG,KAAK,CAAC,YAAY,CAmLnH"}

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

@@ -0,0 +1,38 @@
+import { CellCoords, Bounds, Size } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+/**
+ * Horizontal anchor used when the editor grows past its cell. `left` grows rightward, `right` grows
+ * leftward, `center` grows both ways. (Vertical growth is always downward.)
+ */
+export type EditorAlignment = 'left' | 'right' | 'center';
+/**
+ * The result of {@link expandEditorBounds}: the placed box plus whether it is currently on-screen.
+ */
+export interface EditorPlacement {
+    /** View-pixel bounds for the editor box. */
+    bounds: Bounds;
+    /** `false` when the cell is scrolled out of the visible pane (caller should hide, keep focus). */
+    inView: boolean;
+}
+/**
+ * Compute the editor box bounds for a cell, expanding past the cell when the natural text size is
+ * larger — Excel-style overflow. (no React, no model).
+ *
+ * @param pane    The pane the cell lives in.
+ * @param coords  The cell being edited.
+ * @param natural The measured natural text size in **logical** (un-zoomed) px, or `null` for none.
+ * @param alignment Horizontal growth anchor.
+ * @param edgeInset View px of clearance to leave between the box's right edge and the surface edge.
+ *        Defaults to `0` (flush, the original behavior). A host that draws a border ON the box edge passes
+ *        its stroke width so the trailing border stays inside the viewport instead of being clipped by it —
+ *        without that the box runs flush and a wrapped editor gives no visual sign it stopped at the edge.
+ *
+ * @returns The placement, or `null` when no bounds can be resolved.
+ *
+ * @remarks
+ * Width grows across whole neighbor columns (bounded by the pane range and the surface); height
+ * grows freely (bounded by the surface). The pane metrics already include zoom, so `natural` is
+ * scaled by zoom here to compare against view-pixel cell bounds.
+ */
+export declare const expandEditorBounds: (pane: IGridPane, coords: CellCoords, natural: Size | null | undefined, alignment?: EditorAlignment, edgeInset?: number) => EditorPlacement | null;
+//# sourceMappingURL=EditorPlacement.d.ts.map

package/types/src/editor/EditorPlacement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EditorPlacement.d.ts","sourceRoot":"","sources":["../../../../src/editor/EditorPlacement.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,kGAAkG;IAClG,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,GAC7B,MAAM,SAAS,EACf,QAAQ,UAAU,EAClB,SAAS,IAAI,GAAG,IAAI,GAAG,SAAS,EAChC,YAAW,eAAwB,EACnC,YAAW,MAAU,KACpB,eAAe,GAAG,IA4DpB,CAAC"}

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

@@ -0,0 +1,10 @@
+export type { EditorMode, EditorTextSelection, EditState, EditCommitArgs } from './EditState';
+export type { StartEditOptions } from './EditSession';
+export * from './EditSession';
+export * from './useEditorKeymap';
+export * from './DefaultEditable';
+export * from './EditorPlacement';
+export * from './EditorInput';
+export * from './EditorLayer';
+export * from './EditorDiv';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/editor/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,mBAAmB,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC9F,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC"}

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

@@ -0,0 +1,74 @@
+import { RefObject } from 'react';
+import { Direction, RangeAxis } from '@sheetxl/utils';
+import { EditorMode, EditCommitArgs } from './EditState';
+import { StartEditOptions } from './EditSession';
+/**
+ * Map a keystroke (while no session is active) to an open request, or `null` if it should not start
+ * an edit. F2 ⇒ edit mode; Backspace ⇒ clear; a printable character ⇒ seed it (by value). The seed
+ * is a string (a keystroke); the built-in start path therefore assumes a string dirty. Used by
+ * `EditorLayer`'s start-key handler.
+ */
+export declare const startEventFromKey: (e: KeyboardEvent) => StartEditOptions<string> | null;
+/**
+ * Deterministic caret placement across a controlled-value re-render: call the returned setter with the
+ * desired caret offset *before* pushing the new value (`onDirtyChange`), and a layout effect applies it
+ * synchronously after the new value commits to the DOM — no `requestAnimationFrame` race (a repeated
+ * keystroke can land between the render and a deferred frame, acting on a caret still parked at the end).
+ *
+ * The input owns its textarea ref and value; the keymap consumes the setter via
+ * {@link EditorKeymapProps.setCaret}.
+ */
+export declare const usePendingCaret: (inputRef: RefObject<HTMLTextAreaElement | null>, value: string) => ((caret: number) => void);
+/**
+ * Inputs to {@link useEditorKeymap}. The editor input passes its current {@link EditorMode}, the
+ * current text (needed for newline insertion), and the lifecycle callbacks.
+ */
+export interface EditorKeymapProps {
+    mode: EditorMode;
+    /** The current text, so Alt/Meta+Enter can splice a newline at the caret. */
+    value: string;
+    onDirtyChange(dirty: string): void;
+    onModeChange(mode: EditorMode): void;
+    onCommit(args?: EditCommitArgs): boolean;
+    onCancel(): void;
+    /**
+     * Optional. When provided, a successful **enter-mode arrow** commit **navigates here, in the input**,
+     * and the key is consumed (not propagated). Used by inputs with no selection layer beneath them — the
+     * cell-aware sheet editor and the formula bar. When omitted, the arrow propagates instead so a
+     * selection layer can navigate (the default/grid behavior).
+     */
+    onNavigate?(direction: Direction): void;
+    /**
+     * Optional. When provided, a successful **Tab/Enter** commit **traverses here, in the input**, and
+     * the key is consumed (not propagated). Traversal differs from navigation: it cycles the active cell
+     * *within* the current selection rather than moving it — the Excel Tab/Enter contract. `Tab` ⇒ `Row`
+     * axis, `Enter` ⇒ `Column` axis; Shift reverses. Used by the same input hosts as {@link onNavigate};
+     * when omitted, the key propagates so a selection layer can traverse (the default/grid behavior).
+     */
+    onTraverse?(axis: RangeAxis, reverse: boolean): void;
+    /**
+     * Optional. Deterministic caret placement across a value re-render (see {@link usePendingCaret}) —
+     * used by the Alt/Meta+Enter newline splice to restore the caret after the new value renders. When
+     * omitted, falls back to a `requestAnimationFrame` restore (racy under key repeat; our inputs all
+     * supply it).
+     */
+    setCaret?(caret: number): void;
+}
+/**
+ * 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:
+ *
+ * - **Escape** cancels (consumed).
+ * - **F2** toggles `enter` ↔ `edit` (consumed).
+ * - **Alt/Meta+Enter** splices a hard newline at the caret (consumed).
+ * - **edit-mode arrows** move the caret (consumed).
+ * - **Enter / Tab / enter-mode arrow** commit, then let the key **propagate** so the selection layer
+ *   moves — but only if the commit succeeded; on a rejected value the key is stopped so the selection
+ *   stays put. Tab/Enter *traverse* (cycle within the selection); arrows *navigate* (move the cell).
+ * - **IME composition** is left entirely to the textarea (kept off the grid).
+ *
+ * Movement is intentionally NOT handled here by default — the editor only commits; the selection layer
+ * moves. Inputs with no layer beneath them opt in via {@link onNavigate}/{@link onTraverse}.
+ */
+export declare const useEditorKeymap: (props: EditorKeymapProps) => ((e: React.KeyboardEvent<HTMLTextAreaElement>) => void);
+//# sourceMappingURL=useEditorKeymap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"useEditorKeymap.d.ts","sourceRoot":"","sources":["../../../../src/editor/useEditorKeymap.ts"],"names":[],"mappings":"AAAA,OAAO,EAA2B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEhE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAItD,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,GAAI,GAAG,aAAa,KAAG,gBAAgB,CAAC,MAAM,CAAC,GAAG,IAuB/E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAC1B,UAAU,SAAS,CAAC,mBAAmB,GAAG,IAAI,CAAC,EAC/C,OAAO,MAAM,KACZ,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAS1B,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,CAAC;IACjB,6EAA6E;IAC7E,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC;IACzC,QAAQ,IAAI,IAAI,CAAC;IACjB;;;;;OAKG;IACH,UAAU,CAAC,CAAC,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IACxC;;;;;;OAMG;IACH,UAAU,CAAC,CAAC,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACrD;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAcD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,iBAAiB,KACvB,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,aAAa,CAAC,mBAAmB,CAAC,KAAK,IAAI,CA+GxD,CAAC"}

package/types/src/grid/Grid.d.ts

@@ -0,0 +1,16 @@
+import { default as React } from 'react';
+import { GridProps, IGrid } from './IGrid';
+/**
+ * A virtualized grid: a thin wrapper around {@link GridSurface} that re-adds the cell + gridline
+ * rendering the surface itself is agnostic to. It composes a `CellLayer` (cells), a `GridlineLayer`
+ * (gridlines) and an optional `renderBorders` slot as ordinary layers — in the conventional z-order
+ * (gridlines → borders → below-layers → cells → above-layers) — and owns the content cache token the
+ * cells bust on. Everything else is forwarded to the surface.
+ *
+ * @remarks
+ * This is the batteries-included entry point (what most callers want and what the stories use). A
+ * consumer that wants to own the cells itself (e.g. a sheet that drives its own partial invalidation)
+ * can skip `Grid` and compose a `CellLayer` straight onto {@link GridSurface}'s layer slots.
+ */
+export declare const Grid: React.NamedExoticComponent<Omit<GridProps, "ref"> & React.RefAttributes<IGrid>>;
+//# sourceMappingURL=Grid.d.ts.map

package/types/src/grid/Grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Grid.d.ts","sourceRoot":"","sources":["../../../../src/grid/Grid.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAa/B,OAAO,EAAE,KAAK,SAAS,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AAQrD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,IAAI,iFAgGd,CAAC"}

package/types/src/grid/IGrid.d.ts

@@ -0,0 +1,93 @@
+import { CellCoords, RangeCoords, OrientationFlags } from '@sheetxl/utils';
+import { ItemSizer } from '../metrics';
+import { CellRendererProps, VisibleCell } from '../cell';
+import { LayerNode } from '../layer';
+import { GridSurfaceProps, IGridSurface } from '../surface/IGridSurface';
+import { IGridPane } from '../surface/IGridPane';
+/**
+ * Props for {@link Grid}.
+ *
+ * @remarks
+ * `Grid` is the batteries-included grid: it renders cells ({@link GridProps.renderCells}) and
+ * gridlines ({@link GridProps.showGridLines}) and adds the size conveniences
+ * ({@link GridProps.getRowHeight} / {@link GridProps.getColumnWidth}) most apps want out of the box.
+ *
+ * It builds those features as ordinary layers — a `CellLayer`, a `GridlineLayer`, and the optional
+ * border/below slots — on top of {@link GridSurface}, the pure layer/pane engine, and owns the
+ * content cache they bust on (see {@link IGrid.invalidate}). The extra props here are all additive;
+ * reach for `GridSurface` directly only when you want to compose everything as layers yourself.
+ */
+export interface GridProps extends GridSurfaceProps {
+    /**
+     * Row height — a number (uniform) or a `(index) => number`. The size-convenience over the surface's
+     * raw `metrics`: `Grid` builds the metrics from this. Ignored when `metrics` is provided.
+     */
+    getRowHeight?: ItemSizer | number;
+    /**
+     * Column width — a number (uniform) or a `(index) => number`. Ignored when `metrics` is provided.
+     */
+    getColumnWidth?: ItemSizer | number;
+    /**
+     * Returns the element to render for a cell. There can be many cells, so keep this cheap. By default
+     * the cell's `pointerEvents` are `none`; override to enable interaction.
+     */
+    renderCells?: (props: CellRendererProps) => React.ReactNode;
+    /**
+     * Layer(s) rendered BELOW the cells/borders (but above the gridlines) — the place for fills and
+     * highlights. The `children` are the layers ABOVE the cells/borders.
+     */
+    renderBelow?: LayerNode;
+    /**
+     * Optional border layer(s), rendered just below the cells (above {@link GridProps.renderBelow} /
+     * gridlines). A render slot for a custom border treatment — distinct from the light
+     * {@link GridProps.showGridLines} gridlines.
+     */
+    renderBorders?: LayerNode;
+    /**
+     * Show grid lines. Useful for spreadsheets.
+     */
+    showGridLines?: boolean | Partial<OrientationFlags>;
+    /**
+     * Customize grid line color.
+     *
+     * @remarks
+     * Overridden per-axis by {@link GridProps.propsGridLineRows} / {@link GridProps.propsGridLineColumns}.
+     */
+    gridLineColor?: string;
+    /**
+     * Gridline props for rows.
+     */
+    propsGridLineRows?: React.SVGProps<SVGPathElement>;
+    /**
+     * Gridline props for columns.
+     */
+    propsGridLineColumns?: React.SVGProps<SVGPathElement>;
+    /**
+     * Optimization hook: return exactly the cells worth rendering for a pane. When omitted every
+     * visible cell is iterated and {@link GridProps.hiddenCellAt} is consulted. The value is passed to
+     * the cell renderer.
+     */
+    getVisibleCells?: (pane: IGridPane) => (VisibleCell | CellCoords)[];
+    /**
+     * Skip rendering a cell that has nothing to render. Ignored when {@link GridProps.getVisibleCells}
+     * is provided.
+     */
+    hiddenCellAt?: (coords: CellCoords) => boolean;
+}
+/**
+ * Imperative handle for {@link Grid}, obtained from its `ref`. Exposes the full grid API — scrolling,
+ * coordinate conversion, pane access (see {@link IGridSurfaceAttributes}) — plus a cell-aware
+ * {@link IGrid.invalidate}.
+ */
+export interface IGrid extends IGridSurface {
+    /**
+     * Invalidate the cells (content) and re-render them. Geometry and panes are left intact, so this
+     * is the cheap path for "the data changed." Change props for layout or geometry changes.
+     *
+     * @param coords Reserved for partial invalidation — currently **ignored**: every call drops the
+     * whole grid's cached cell output. (Per-range tile dirtying is a planned follow-up; see the
+     * invalidation-model item in GRID-CLEAN §Architecture.)
+     */
+    invalidate: (coords?: CellCoords | RangeCoords) => void;
+}
+//# sourceMappingURL=IGrid.d.ts.map

package/types/src/grid/IGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IGrid.d.ts","sourceRoot":"","sources":["../../../../src/grid/IGrid.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAE1F,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAC5C,OAAO,EAAE,KAAK,iBAAiB,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAE1C,OAAO,EAAE,KAAK,gBAAgB,EAAE,KAAK,YAAY,EAAE,MAAM,yBAAyB,CAAC;AACnF,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAU,SAAQ,gBAAgB;IACjD;;;OAGG;IACH,YAAY,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IAClC;;OAEG;IACH,cAAc,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC;IACpC;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,KAAK,CAAC,SAAS,CAAC;IAC5D;;;OAGG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;;;OAIG;IACH,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B;;OAEG;IACH,aAAa,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACpD;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;OAEG;IACH,iBAAiB,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IACnD;;OAEG;IACH,oBAAoB,CAAC,EAAE,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IACtD;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,KAAK,CAAC,WAAW,GAAG,UAAU,CAAC,EAAE,CAAC;IACpE;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,UAAU,KAAK,OAAO,CAAC;CAChD;AAED;;;;GAIG;AACH,MAAM,WAAW,KAAM,SAAQ,YAAY;IACzC;;;;;;;OAOG;IACH,UAAU,EAAE,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,WAAW,KAAK,IAAI,CAAC;CACzD"}

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

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

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

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