@sheetxl/grid-react 0.7.27 → 0.7.28-beta.1

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

@@ -0,0 +1,70 @@
+import { default as React } from 'react';
+import { CellCoords } from '@sheetxl/utils';
+import { LayerProps } from '../layer';
+import { CellRendererProps } from './CellRenderer';
+import { CellModelOptions } from './_CellModel';
+/**
+ * Props for {@link CellTileDiv} — the tiled cell content WITHOUT a layer: everything the tiling
+ * engine needs, none of the z-slot concerns.
+ */
+export interface CellTileDivProps extends CellModelOptions {
+    /** Class for the tiling-origin box (devtools identification). */
+    className?: string;
+    /** Style merged UNDER the scroll-carry transform (which must win). */
+    style?: React.CSSProperties;
+    /**
+     * Render one cell. Called a lot — keep it cheap. Mirrors `GridSurface.renderCells`.
+     */
+    renderCell: (props: CellRendererProps) => React.ReactNode;
+    /**
+     * Opaque cache-bust token. The per-cell render cache survives scrolling (cells keep their
+     * absolute position), but must be dropped when cell CONTENT or geometry changes. Pass a value
+     * whose identity changes on invalidate / metrics change (and NOT on scroll); a new identity
+     * drops the cache. `renderCell` identity is always also treated as a bust.
+     */
+    cacheToken?: unknown;
+    /**
+     * Visually suppress the cell at these SHEET-absolute coordinates — WITHOUT invalidating anything.
+     *
+     * @remarks
+     * Transient per-coordinate state (a cell hidden under an open editor / a custom single-cell
+     * overlay) must not live inside the tile snapshots, or every change would rebuild tiles. This is
+     * the live channel: one scoped CSS rule targeting the cell's `data-rc` stamp (see
+     * `CellRendererProps`), so cached, rebuilt, and scrolled-back-in tiles all honor it for free.
+     * `visibility: hidden` (not `opacity`) so the suppressed cell — including any text overflowing
+     * its bounds, and a hyperlink that opted back into pointer-events — is neither visible nor
+     * hit-testable. Distinct from `hiddenCellAt`, which is a structural scan-time skip.
+     */
+    suppressCell?: CellCoords | null;
+}
+/**
+ * {@link CellLayer} is the cells' **layer**: a {@link Layer} (its z-slot; tap props forward to it)
+ * hosting one {@link CellTileDiv}. Use it directly as a grid child when the cells are the layer's
+ * ONLY content; a composite layer that hosts more than the tiles (an overlay peer of the cells)
+ * renders its own `Layer` with a `CellTileDiv` inside instead. `className` merges onto the layer's
+ * boundary div and `style` merges under the scroll transform (which must win).
+ */
+export interface CellLayerProps extends Omit<LayerProps, 'children'>, CellTileDivProps {
+}
+/**
+ * The tiled cell content — a full-view scroll-carry {@link VirtualDiv} of immutable tile
+ * snapshots, plus the live per-coordinate suppression rule. NOT a layer: it is hosted inside one
+ * (see {@link CellLayer} for the direct-use wrapper), so a composite layer can stack overlay
+ * content beside the tiles within its single z-slot.
+ *
+ * @remarks
+ * Tiles (segment containers) are positioned in ABSOLUTE content space (`tileIndex * SEGMENT_SIZE`),
+ * so a tile is a pure function of its tile coordinate — an immutable snapshot. A single outer
+ * `<div>` translates the whole content by `-origin` to carry the scroll. The tile tree is
+ * `useMemo`'d on the visible RANGE (+ content token), NOT the pixel scroll: within a range, every
+ * cell's absolute position is invariant (`origin + bounds.x` is constant as scroll shifts both
+ * terms oppositely), so a sub-tile scroll reuses the exact same tile tree and only re-renders the
+ * one outer element. Net on-screen position is identical to the classic path (`= bounds.x`).
+ */
+export declare const CellTileDiv: React.MemoExoticComponent<(props: CellTileDivProps) => React.JSX.Element>;
+/**
+ * CellLayer — the thin direct-use wrapper: one {@link Layer} (its z-slot; tap props forward)
+ * hosting one {@link CellTileDiv}. See {@link CellTileDiv} for the tiling model.
+ */
+export declare const CellLayer: React.MemoExoticComponent<(props: CellLayerProps) => React.JSX.Element>;
+//# sourceMappingURL=CellLayer.d.ts.map

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

@@ -0,0 +1,42 @@
+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.
+     */
+    pane: IGridPane;
+    /**
+     * The range bounds relative to the current viewport and zoom.
+     */
+    bounds: Bounds;
+    /**
+     * The cell coords that is being rendered.
+     */
+    cell: CellCoords;
+    /**
+     * The RangeCoords that is being rendered.
+     *
+     * @defaultValue A range representing the coords
+     *
+     * @remarks
+     * For most cells this is the same as the coords. This will only be different for spanning cells.
+     */
+    range?: RangeCoords;
+    /**
+     * Absolute cell-coordinate stamp (`"rowIndex:colIndex"`), provided by the layer.
+     *
+     * @remarks
+     * A renderer that spreads its rest props onto its root element carries this automatically; a
+     * custom renderer must place it on its root itself. It is the hook the layer's live suppression
+     * rule targets (see `CellLayerProps.suppressCell`) — per-coordinate CSS over immutable cached
+     * tiles, so transient state (an open editor) never invalidates the tile cache. Coordinates are
+     * SHEET-absolute (never tile- or pane-relative): a cell rendered in more than one pane (a merge
+     * spanning a freeze line) matches the one selector in every instance.
+     */
+    'data-rc'?: string;
+}
+//# sourceMappingURL=CellRenderer.d.ts.map

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

@@ -0,0 +1,6 @@
+import { CellRendererProps } from './CellRenderer';
+/**
+ * Default cell component capable of rendering a value.
+ */
+export declare const DefaultCellRenderer: import('react').MemoExoticComponent<(props: CellRendererProps) => import("react").JSX.Element>;
+//# sourceMappingURL=DefaultCellRenderer.d.ts.map

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

@@ -0,0 +1,38 @@
+import { default as React } from 'react';
+import { OrientationFlags } from '@sheetxl/utils';
+import { LayerProps } from '../layer';
+import { CellModelOptions } from './_CellModel';
+/**
+ * {@link GridlineLayer} is the gridlines' **layer**: a {@link Layer} (its z-slot; tap props forward
+ * to it) hosting its two axis `<svg>`s inside one full-view, pointer-transparent {@link VirtualDiv}
+ * (a decoration host). Use it directly as a grid child. `className`/`style` apply to the host box.
+ */
+export interface GridlineLayerProps extends Omit<LayerProps, 'children'>, CellModelOptions {
+    /** Class for the host box (devtools identification). */
+    className?: string;
+    /** Style for the host box. */
+    style?: React.CSSProperties;
+    /**
+     * Show grid lines. `true` shows both; an {@link OrientationFlags} partial toggles each axis.
+     *
+     * @defaultValue true
+     */
+    showGridLines?: boolean | Partial<OrientationFlags>;
+    /**
+     * Grid line color. Overridden per-axis by {@link GridlineLayerProps.propsRows} /
+     * {@link GridlineLayerProps.propsColumns}.
+     */
+    gridLineColor?: string;
+    /** Per-`<path>` props for the horizontal (row) lines. */
+    propsRows?: React.SVGProps<SVGPathElement>;
+    /** Per-`<path>` props for the vertical (column) lines. */
+    propsColumns?: React.SVGProps<SVGPathElement>;
+}
+/**
+ * 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
+ * {@link getMergedRanges} pass — index-space, memoized on the visible RANGE (not pixel scroll), so
+ * ordinary scroll frames re-render this layer without re-scanning a single cell.
+ */
+export declare const GridlineLayer: React.MemoExoticComponent<(props: GridlineLayerProps) => React.JSX.Element | null>;
+//# sourceMappingURL=GridlineLayer.d.ts.map

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

@@ -0,0 +1,12 @@
+import { CellCoords, RangeCoords, Bounds } from '@sheetxl/utils';
+/**
+ * A single cell resolved for rendering: its anchor coords, the range it occupies (a 1x1 range for
+ * a normal cell, larger for a merge), the pane-relative bounds, and an optional pre-resolved value.
+ */
+export interface VisibleCell {
+    cell: CellCoords;
+    range?: RangeCoords;
+    bounds?: Bounds;
+    value?: any;
+}
+//# sourceMappingURL=Types.d.ts.map

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

@@ -0,0 +1,82 @@
+import { CellCoords, RangeCoords } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+import { VisibleCell } from './Types';
+/**
+ * The "what is visible right now" pass for a single pane.
+ *
+ * @remarks
+ * {@link CellLayer} renders `cells`. {@link GridlineLayer} needs only the spans — it consumes the
+ * dedicated merges-only {@link getMergedRanges} pass (same source semantics, no cell allocation)
+ * rather than this full model.
+ */
+export interface CellModel {
+    /** Visible cells (merge-deduped: only the anchor of a merge appears). */
+    cells: VisibleCell[];
+    /** Merged ranges spanning more than one ROW — horizontal gridlines break around these. */
+    rangesH: RangeCoords[];
+    /** Merged ranges spanning more than one COLUMN — vertical gridlines break around these. */
+    rangesV: RangeCoords[];
+}
+export interface CellModelOptions {
+    /**
+     * Optimization hook: return exactly the cells worth rendering for this pane. When omitted, every
+     * visible cell is iterated and {@link CellModelOptions.hiddenCellAt} is consulted.
+     *
+     * @param range Overrides the visible range (the buffered/tiled CellLayer passes a window that
+     * extends past the visible edge). When omitted, the implementation uses the pane's visible range.
+     */
+    getVisibleCells?: (pane: IGridPane, range?: RangeCoords) => (VisibleCell | CellCoords)[];
+    /**
+     * Skip a cell that has nothing to render. Ignored for merged cells (a merge is always considered)
+     * and ignored entirely when {@link CellModelOptions.getVisibleCells} is provided.
+     */
+    hiddenCellAt?: (coords: CellCoords) => boolean;
+    /**
+     * Render cells for this range instead of just the visible range — an overscan buffer so scrolling
+     * within it needs no recompute. Cells outside the visible range get their geometry from
+     * `getBoundsFromRange` (they are not in the visible offset maps). Used by the tiled CellLayer.
+     */
+    bufferRange?: RangeCoords;
+    /**
+     * Content-version token (cache-key only; ignored by {@link computeCellModel}). A new identity busts
+     * the {@link getCellModel} memo so a content edit recomputes the model immediately — without it the
+     * model cache (keyed on scroll + callback identity) would return the pre-edit cells for a frame,
+     * since an in-place value edit changes neither the scroll key nor the callback identities. Pass the
+     * same token CellLayer uses to drop its tile cache so both invalidate in lockstep.
+     */
+    cacheToken?: unknown;
+}
+/**
+ * Compute the visible cells + merge spans for a pane. Pure; no React. This is the ENUMERATION half
+ * of cell rendering — the tile bucketing / element rendering half lives in {@link CellLayer}.
+ */
+export declare const computeCellModel: (pane: IGridPane, options?: CellModelOptions) => CellModel;
+export declare const getCellModel: (pane: IGridPane, options?: CellModelOptions) => CellModel;
+/**
+ * The merge/extrusion spans of the visible window — the subset of {@link CellModel} that
+ * {@link GridlineLayer} consumes. Index-space only ({@link RangeCoords}), so unlike the full model it
+ * is invariant under sub-cell PIXEL scroll.
+ */
+export interface MergedRanges {
+    /** Spans covering more than one ROW — horizontal gridlines break around these. */
+    rangesH: RangeCoords[];
+    /** Spans covering more than one COLUMN — vertical gridlines break around these. */
+    rangesV: RangeCoords[];
+}
+/**
+ * Merges-only sibling of {@link computeCellModel}: collect just the spanned ranges (merges +
+ * extrusions) intersecting the pane's visible window. No cell array, no bounds resolution, no
+ * per-cell allocation — the full model allocates ~a-thousand `VisibleCell`s just to throw them away
+ * when the caller (gridlines) only breaks lines around spans.
+ *
+ * @remarks
+ * `hiddenCellAt` is deliberately not consulted: it is documented as ignored for merged cells, and a
+ * single (non-spanned) cell contributes nothing here — so it cannot affect this output.
+ */
+export declare const computeMergedRanges: (pane: IGridPane, options?: CellModelOptions) => MergedRanges;
+export declare const getMergedRanges: (pane: IGridPane, options?: CellModelOptions) => MergedRanges;
+/**
+ * Create a stringified cell identifier.
+ */
+export declare const cellIdentifier: (rowIndex: number, colIndex: number) => string;
+//# sourceMappingURL=_CellModel.d.ts.map

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

@@ -0,0 +1,6 @@
+export * from './Types';
+export * from './CellRenderer';
+export * from './DefaultCellRenderer';
+export * from './CellLayer';
+export * from './GridlineLayer';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,121 @@
+import { CellCoords } from '@sheetxl/utils';
+import { ICellAnchor } from '../selection';
+import { EditCommitArgs } from './EditState';
+import { EditSession, StartEditOptions, EditModel } from './EditSession';
+/**
+ * How to edit a cell — supplied by whoever builds the editable. Returns the {@link EditModel} bits
+ * (`clean` + `commit`) for the cell, or `null` if the cell is not editable. The editable wraps these
+ * in an {@link EditSession}; the author never constructs one.
+ *
+ * @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).
+ *
+ * @typeParam C - clean type. @typeParam D - dirty type. @typeParam A - commit args.
+ */
+export type CreateEdit<C, D = string, A = EditCommitArgs> = (coords: CellCoords) => EditModel<C, D, A> | null;
+/**
+ * The thing a grid edits **through** — owns the active-cell anchor and the **single** current edit,
+ * and is the one place an edit is started/committed/cancelled. The parallel of {@link ICellAnchor}:
+ * where the selection owns the current coords, the editable owns the current {@link EditSession}.
+ *
+ * @remarks
+ * The layer-facing contract. {@link EditorLayer} and the formula bar share one instance and drive it
+ * (`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}).
+ *
+ * @typeParam C - clean type. @typeParam D - dirty type. @typeParam A - commit args.
+ */
+export interface IEditable<C, D = string, A = EditCommitArgs> {
+    /**
+     * The active-cell anchor, as {@link ICellAnchor}. The editor reads it (`getCoords`/`subscribe`) to
+     * follow the active cell and detect click-away; it cannot move it (navigation is the selection's
+     * job — the anchor read view is intentionally setter-less).
+     */
+    getAnchor(): ICellAnchor;
+    /** The current edit session, or `null` when idle. */
+    getSession(): EditSession<C, D, A> | null;
+    /** Subscribe to session changes (start/stop only). Returns an unsubscribe. */
+    subscribe(listener: () => 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;
+    /** Cancel the current edit (revert + clear the session). */
+    cancel(): void;
+    /**
+     * Tear the editable down: unsubscribe from the anchor (the click-away watch) and cancel any live
+     * session. Call when the owning view/sheet goes away so a per-view/per-sheet editable doesn't keep
+     * observing (and mutating through) a dead anchor.
+     */
+    dispose(): void;
+}
+/**
+ * The edit-mode bus payload published (as `EditMode.args`) while a cell edit is active: the live
+ * {@link IEditable} handle. Lives here, next to {@link IEditable}, so the publisher and every bus
+ * reader share one type instead of casting `args` loosely. The bus key for this mode is `'edit'`;
+ * the fine-grained enter/edit state is read from `editable.getSession()`, not the key.
+ */
+export interface EditModeEditArgs<C = any, D = any, A = any> {
+    editable: IEditable<C, D, A>;
+}
+/**
+ * Options for {@link DefaultEditable}.
+ */
+export interface DefaultEditableOptions {
+    /**
+     * The click-away **pre-commit gate** fallback: when the anchor moves off the edited cell and the
+     * commit FAILS (vetoed / rejected value), the session must not stay open on cell A while the
+     * selection sits on cell B. Supply this to pull the anchor **back to the edited cell** (Excel-style
+     * — 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).
+     */
+    revertAnchor?: (coords: CellCoords) => void;
+}
+/**
+ * The default {@link IEditable}: holds the {@link ICellAnchor} anchor and the single current edit, and
+ * mints that edit (when started) via a {@link CreateEdit} callback.
+ *
+ * @remarks
+ * One per workbook, passed by reference to every `EditorLayer` and the formula bar. Its `subscribe`
+ * fires **only** on a current-edit change (start/stop) — anchor changes are observed directly on the
+ * anchor; the edit's per-keystroke *value* updates live on the {@link EditSession}'s own `subscribe`.
+ *
+ * It owns the **click-away** rule: it watches the anchor and commits the current edit when the active
+ * cell moves off the edited cell — so the layer never has to. (When Point mode lands, this is where an
+ * anchor move would instead route a reference into the edit rather than commit.)
+ *
+ * Methods are plain (unbound) — consumers read it via `useBoundSyncExternalStore` (or its optional
+ * variant), which calls `subscribe`/the snapshot selector on the instance, so no per-method binding
+ * is needed.
+ */
+export declare class DefaultEditable<C, D = string, A = EditCommitArgs> implements IEditable<C, D, A> {
+    private readonly anchor;
+    private readonly createEdit;
+    private readonly revertAnchor?;
+    private readonly unsubscribeAnchor;
+    private current;
+    private readonly listeners;
+    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.getSession */
+    getSession(): EditSession<C, D, A> | null;
+    /** @inheritdoc IEditable.startEdit */
+    startEdit(coords: CellCoords, options?: StartEditOptions<D>): boolean;
+    /** @inheritdoc IEditable.commit */
+    commit(args?: A): boolean;
+    /** @inheritdoc IEditable.cancel */
+    cancel(): void;
+    /** @inheritdoc IEditable.dispose */
+    dispose(): void;
+    private notify;
+}
+//# sourceMappingURL=DefaultEditable.d.ts.map

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

@@ -0,0 +1,182 @@
+import { CellCoords } from '@sheetxl/utils';
+import { ICellAnchor } from '../selection';
+import { EditState, EditorMode, EditorTextSelection, EditCommitArgs } from './EditState';
+/**
+ * The imperative handle a caret-owning **input** exposes for **caret-dependent** operations — the input
+ * analog of the selection's `SelectionNavigation`. These act on *this input's* caret/selection, so they
+ * live on the view, not on any shared value: two inputs on the same cell (the inline editor + the formula
+ * bar) share the value but each has its own caret.
+ *
+ * @remarks
+ * Deliberately broader than "cell editor": not every range input is one (the formula bar is not). A
+ * cell editor registers on the {@link EditSession} it participates in
+ * ({@link EditSession.registerEditor}), reached via {@link EditSession.getActiveEditor}.
+ *
+ * Kept **spreadsheet-agnostic** — grid-react knows text inputs, not references. Reference-specific caret
+ * ops (F4 `$`-cycling, insert a picked reference) live on a `@sheetxl/react` subtype that extends this.
+ */
+export interface IInputHandle {
+    /** Insert `text` at the caret (replacing any selection); the caret ends up after it. */
+    insertText(text: string): void;
+    /** Select all of the input's text. */
+    selectAll(): void;
+    /**
+     * Place this input's caret / selection. The host-facing counterpart of the read-side caret ops: caret
+     * position is a **view** concern (each input owns its own), so a host that needs one parked somewhere —
+     * e.g. after the reference just picked — asks the input rather than the edit carrying a caret of its own.
+     */
+    setSelection(selection: EditorTextSelection): void;
+    /** Focus this input (used by `toggleEditorFocus` to move the edit between inputs). */
+    focus(): void;
+}
+/**
+ * The model-specific bits {@link CreateEdit} supplies for a cell: the captured clean value and how to
+ * write the dirty value back. Everything else (coords/dirty/mode/lifecycle) is the library's machinery.
+ *
+ * @typeParam C - clean type. @typeParam D - dirty type. @typeParam A - commit args.
+ */
+export interface EditModel<C, D = string, A = EditCommitArgs> {
+    /** 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;
+}
+/**
+ * What the {@link EditSession} constructor takes: the {@link EditModel} bits plus the cell. The owning
+ * {@link DefaultEditable} assembles this (model bits from `createEdit` + the coords it was asked to
+ * edit) — a `createEdit` author supplies only the {@link EditModel}.
+ */
+export interface EditSessionInit<C, D = string, A = EditCommitArgs> extends EditModel<C, D, A> {
+    /** The cell being edited. */
+    coords: CellCoords;
+}
+/**
+ * Options applied when an edit begins (`DefaultEditable.startEdit` → the `EditSession` constructor).
+ *
+ * @typeParam D - The dirty (working) value type.
+ */
+export interface StartEditOptions<D = string> {
+    /** @defaultValue `'enter'` */
+    mode?: EditorMode;
+    /** Seed dirty value (the "first keystroke, by value"). `undefined` keeps the clean value. */
+    dirty?: D;
+    /** Initial selection to apply on focus. */
+    initialSelection?: EditorTextSelection | null;
+    /** @defaultValue `true` */
+    autoFocus?: boolean;
+}
+/**
+ * Passed to each beforeCommit consumer ({@link EditSession.addCommitListener}). Call {@link veto} to
+ * reject the commit (the edit stays open and the leave-key does not navigate).
+ */
+export interface CommitContext<D = string, A = EditCommitArgs> {
+    readonly coords: CellCoords;
+    /**
+     * The working value being committed, or `undefined` for a **no-op** commit (nothing typed — the
+     * model is not written, but listeners still run and may veto, e.g. to hold the session open).
+     */
+    readonly dirty: D | undefined;
+    readonly args?: A;
+    veto(): void;
+}
+/**
+ * A single edit — created per edit by a model's `getEdit`, discarded on commit/cancel. It carries the
+ * captured clean + the model's write, and owns the working state + commit lifecycle.
+ *
+ * @remarks
+ * Consumers read it via {@link getState} / {@link subscribe} and drive its value via {@link setDirty} /
+ * {@link setMode} / {@link addCommitListener}. The owning {@link DefaultEditable} constructs it and
+ * drives its `@internal` {@link commit} / {@link cancel} (you call `editable.commit/cancel`, not these).
+ * Methods are plain (unbound) — consumers read it via `useOptionalBoundSyncExternalStore`, which calls
+ * `subscribe`/the snapshot selector on the instance, so no per-method binding is needed.
+ *
+ * Implements {@link ICellAnchor} as a **fixed-cell** anchor: `getCoords` returns the edited cell
+ * (which never moves for the life of the session) and `subscribe` observes its edit state. Lets a
+ * session be read uniformly as "a thing located at a cell".
+ */
+export declare class EditSession<C, D = string, A = EditCommitArgs> implements ICellAnchor {
+    private readonly commitFn;
+    private state;
+    private readonly listeners;
+    private readonly commitListeners;
+    private readonly cancelListeners;
+    private readonly editors;
+    private activeEditor;
+    private activeEditorId;
+    private auxState;
+    /**
+     * Built by {@link DefaultEditable.startEdit}: the model bits + coords ({@link EditSessionInit}) plus
+     * the open-time {@link StartEditOptions} (mode, seeded keystroke, focus). A fresh focus token is
+     * stamped per session — each edit is a new session, so the input re-focuses.
+     */
+    constructor(init: EditSessionInit<C, D, A>, options?: StartEditOptions<D>);
+    getState(): EditState<C, D>;
+    /** @inheritdoc ICellAnchor.getCoords */
+    getCoords(): CellCoords;
+    subscribe(listener: () => void): (() => void);
+    /**
+     * Register an editor participating in this edit (inline editor, formula bar…). Returns an unregister
+     * (call on unmount). Both editors of the same cell reach the SAME session via the shared editable, so
+     * both register here — which is how `toggleEditorFocus` enumerates them and a caret command finds the
+     * focused one.
+     */
+    registerEditor(handle: IInputHandle): () => void;
+    /** Mark the focused editor (the caret owner) on focus, or `null` on blur. */
+    setActiveEditor(handle: IInputHandle | null): void;
+    /** The focused editor's handle (the caret owner), or `null`. Caret commands target this. */
+    getActiveEditor(): IInputHandle | null;
+    /**
+     * Park the LOGICAL id of the editor taking focus. Called by the **host** (the editor layer / formula bar),
+     * which is what owns editor identity — an input is a physical mount and stays identity-free.
+     *
+     * @remarks
+     * Deliberately *not* derived from {@link IInputHandle}: a handle dies with its mount, and the whole point
+     * of this id is to outlive a host that hides or unmounts (switching sheets mid-edit) so the same host can
+     * recognize itself on the way back. Never cleared on unmount — a host parks an id on FOCUS only. `null`
+     * explicitly UN-parks (focus landed on a host with no id — no host may later reclaim focus as "the
+     * active editor"); the session itself is discarded on commit/cancel, so it can't go stale across edits.
+     */
+    setActiveEditorId(id: string | null): void;
+    /**
+     * The parked id ({@link setActiveEditorId}) of the editor that last held focus — durable across a host
+     * unmount/remount, unlike {@link getActiveEditor}. A host reads it to decide whether it *was* the active
+     * editor and may reclaim focus (so it never steals from the formula bar / a 3rd-party editor). `null`
+     * until some host has parked one.
+     */
+    getActiveEditorId(): string | null;
+    /** All editors participating in this edit — for `toggleEditorFocus` to cycle focus. */
+    getEditors(): IInputHandle[];
+    /**
+     * An opaque, **app-defined** value the active editor publishes and peer views observe (through the
+     * session's normal `subscribe`). grid-react does not interpret it — the SDK-aware `@sheetxl/react`
+     * layer defines the shape (e.g. a formula's reference ranges for the pane picker). Cast on read.
+     * Held OFF {@link EditState} so publishing it doesn't re-render the value/mode subscribers (their
+     * `getState()` snapshot is unchanged); only `getAuxState` readers re-render.
+     */
+    getAuxState<T = unknown>(): T | null;
+    /**
+     * Publish the {@link getAuxState} value (the active editor calls this on value/caret change; `null`
+     * when it has nothing to show). Referential guard only — the caller owns value-equality and should
+     * pass a stable reference for unchanged content, so a caret move that changes nothing doesn't churn.
+     */
+    setAuxState(next: unknown): void;
+    setDirty(dirty: D): void;
+    setMode(mode: EditorMode): void;
+    /**
+     * @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.
+     */
+    commit(args?: A): 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. */
+    addCommitListener(fn: (ctx: CommitContext<D, A>) => void): (() => void);
+    /** Observe a cancel. */
+    addCancelListener(fn: () => void): (() => void);
+    private emit;
+    private notify;
+}
+//# sourceMappingURL=EditSession.d.ts.map

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