@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.3

package/types/src/sheet/_SheetIntents.d.ts

@@ -0,0 +1,250 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICellRange } from '../cellRange';
+import { IRangeSelection } from '../selection';
+import { ITransaction } from '../transaction';
+import { SheetEvents } from './_SheetEvents';
+/**
+ * Directives a sheet operation records on its transaction: something to do once the operation
+ * completes, rather than a change the operation makes.
+ *
+ * @remarks
+ * All coords, ids and options - no sheet, view or range instances. An intent is recorded on the
+ * root transaction, so a batch of operations resolves one set of them, and it travels on the
+ * commit, so undo and redo read it back.
+ *
+ * @internal
+ */
+/** Key for the {@link EventsIntent}. */
+export declare const IntentEvents = "sheet.events";
+/** Key for the {@link FormulasEnteredIntent}. */
+export declare const IntentFormulasEntered = "sheet.formulasEntered";
+/** Key for the {@link SelectionIntent}`[]` the operations of a commit declared. */
+export declare const IntentSelection = "sheet.selection";
+/** Key for the {@link BatchSelectIntent}. */
+export declare const IntentBatchSelect = "sheet.batchSelect";
+/** Key for {@link AutoFitIntent}`[]`. */
+export declare const IntentAutoFit = "sheet.autoFit";
+/**
+ * Key for the sheet ids ({@link ISheet.getId}) whose commit-time protection check stands down.
+ *
+ * @remarks
+ * The catch-all at `onBeforeCommitStart` refuses any write to a locked sheet. An operation that
+ * has already ruled on its own allowance (`Sheet._protectionCheck`) records itself here so the
+ * catch-all does not veto what the allowance permitted; so does a load, which is not a user's
+ * write. Read on the way in, so it has to be on the record before the root commits.
+ */
+export declare const IntentSkipProtectionCheck = "sheet.skipProtectionCheck";
+/** Key for the {@link FreezePanesIntent}. */
+export declare const IntentFreezePanes = "sheet.freezePanes";
+/** Key for the {@link MovableSelectionIntent}. */
+export declare const IntentMovableSelection = "sheet.movableSelection";
+/**
+ * Key for the sheet ids ({@link ISheet.getId}) a load is populating in this commit.
+ *
+ * @remarks
+ * A load is not an edit: nothing it writes is announced, and the calculation it would otherwise
+ * trigger is the calc-on-load decision's to make, not the commit's. The writes inside a load go
+ * through the same mutation paths as an edit and record the same changes (an added table records
+ * `anchored`), so the announce has to be told to stand down for the commit as a whole. Implies
+ * {@link IntentSkipProtectionCheck}.
+ */
+export declare const IntentInitial = "sheet.initial";
+/**
+ * Key for the sheet ids ({@link ISheet.getId}) whose entered formulas should take the number
+ * format of the first cell they read that has one, or failing that the format their results
+ * carry, once the compile and the calculation have them.
+ *
+ * @remarks
+ * The one directive that cannot be resolved when the operation completes: the result it formats,
+ * and the engine's word on which cells the formula reads, do not exist yet. It is resolved by the
+ * calculation's amend into this commit (`Sheet._promoteCalcResults`), and only once - see
+ * {@link IntentCalcResolved}.
+ */
+export declare const IntentAutoFormat = "sheet.autoFormat";
+/**
+ * Key for the sheet ids whose entry directives the calculation has resolved for this commit.
+ *
+ * @remarks
+ * Recorded by the calculation's amend once it has formatted and fitted the results of the
+ * formulas the commit entered on that sheet. A later pass for the same commit - a dependent on
+ * another sheet, an explicit recalculation, the pass a redo triggers - finds the sheet here and
+ * leaves the promoted format and the sizes as they are, which is also why an undo and a redo see
+ * them: they are in the snapshot, not re-derived.
+ */
+export declare const IntentCalcResolved = "sheet.calcResolved";
+/**
+ * What to announce once the operation lands, by sheet ({@link ISheet.getId}) and by category.
+ *
+ * @remarks
+ * The one intent every mutation writes. A union: each write appends the ranges it wrote, so a
+ * batch describes all of its operations rather than its last, and an amend unions into the commit
+ * it folds into. Written copy-on-write ({@link Sheet._recordChange}), because an amend's
+ * accumulator is handed the TARGET commit's value as its `prev` and must not mutate it.
+ *
+ * What it holds is not "what was touched" - a registration amend writes state and deliberately
+ * records nothing - but what a consumer has to hear about. Six of the categories have an event of
+ * their own; the rest reach a consumer through the union ({@link Sheet._changedRanges}), which is
+ * also what an undo selects over and what gates the calculation.
+ */
+export type EventsIntent = Readonly<Record<string, SheetEvents>>;
+/**
+ * The ranges a formula was entered over, by sheet ({@link ISheet.getId}).
+ *
+ * @remarks
+ * A subset of the `data` category, found from what the write produced rather than named by the
+ * caller - a cleared formula is a data change and nothing more. No event fires for it: it is read
+ * by the calculation's amend (`Sheet._promoteCalcResults`) to decide what to format and what to
+ * fit, which is Excel's rule that entering a formula formats and fits it while recalculating it
+ * does not.
+ */
+export type FormulasEnteredIntent = Readonly<Record<string, readonly IRange.Coords[]>>;
+/**
+ * `list` with `ranges` appended, for an intent accumulator that unions range lists.
+ *
+ * @param list The list on the record so far, or none.
+ * @param ranges What this write adds.
+ * @param owner The id of the operation recording it ({@link ITransaction.getId}).
+ *
+ * @remarks
+ * An accumulator must not change the value it is handed: on a fold that value is the TARGET
+ * commit's, and a list the target announces would grow by what the amend recorded. A list this
+ * operation built is a different matter - nothing else holds it until the operation lands - so it
+ * is appended to, and only a list from elsewhere is copied first. Without that, a batch of one
+ * write per cell copies every range recorded so far on each write, and so does the replay of those
+ * writes when the batch folds.
+ */
+export declare const _appendOwnedRanges: (list: readonly IRange.Coords[] | undefined, ranges: readonly IRange.Coords[], owner: string) => readonly IRange.Coords[];
+/**
+ * What one operation declared about the selection: where it leaves the user, and where an undo of
+ * it lands when that is somewhere else.
+ *
+ * @remarks
+ * Every operation declares, whatever it was asked, and never applies: whether the view moves, and
+ * which declaration it moves to, is decided once the commit closes ({@link resolveSelection}). So
+ * an operation neither reads the transaction stack nor decides whether it is the one that counts,
+ * and a replay can apply a different policy to the same record.
+ *
+ * Entries are kept in the order they were declared, one per operation, so a batch holds all of
+ * its operations'.
+ */
+export interface SelectionIntent {
+    /** {@link ISheet.getId} of the sheet the selection is on. */
+    sheetId: string;
+    /**
+     * {@link ISheetView.getId} of the view the operation was made against.
+     *
+     * @remarks
+     * A sheet can be shown through more than one view - each user in a shared workbook has their
+     * own - and only the view that made the change is moved by undoing it.
+     */
+    viewId: string;
+    /** Where the operation leaves the user, and where a redo of it lands. */
+    selection: Partial<IRangeSelection.Coords>;
+    /**
+     * Where an undo of the operation lands, when it is not {@link selection}: an auto-fill undoes
+     * to the template it was dragged from, a cut-drag to the source.
+     */
+    undo?: Partial<IRangeSelection.Coords>;
+    /**
+     * The operation's `autoSelect`, resolved against its axis (see `Sheet._resolveSelectOptions`),
+     * or `false` when it was not asked to select.
+     */
+    options: boolean | ICellRange.SelectOptions;
+    /** The operation's `autoSelectRestore`, resolved like {@link options}: whether an undo or a redo selects. */
+    restoreOptions: boolean | ICellRange.SelectOptions;
+    /**
+     * The operation ran inside another one ({@link _isInsideOperation}): the writes a table makes
+     * when it expands are the expansion's, and where they would put the user is not the
+     * expansion's to say.
+     */
+    nested: boolean;
+}
+/**
+ * The `autoSelect` a batch was opened with, by sheet ({@link ISheet.getId}).
+ *
+ * @remarks
+ * A batch asks to select for the operations inside it that did not ask for themselves: a command
+ * groups a per-range loop and selects the result, and the operations in the loop were never told.
+ */
+export type BatchSelectIntent = Readonly<Record<string, boolean | ICellRange.SelectOptions>>;
+/**
+ * Whether `trans` is begun inside a transaction that names an operation
+ * ({@link ITransaction.getOperation}).
+ *
+ * @remarks
+ * An enclosing transaction that names no operation - a batch - is not one.
+ */
+export declare const _isInsideOperation: (trans: ITransaction) => boolean;
+/**
+ * Where a commit moves a view's selection, or `null` when it does not move it.
+ *
+ * @param intents The commit's intents.
+ * @param sheetId The sheet whose view is asking.
+ * @param viewId The view that is asking.
+ * @param direction Whether the operation has just run, or is being undone or redone.
+ *
+ * @remarks
+ * The local policy. Only an operation that is not part of another one counts, and only one that
+ * was asked to select - itself, or by the batch it ran in: by `autoSelect` as it runs, by
+ * `autoSelectRestore` when it is undone or redone. A script that did not ask never moves the user,
+ * and neither does anything that reacts to the user's edit. Forward and redo land where the LAST
+ * such operation left the user; an undo lands where the FIRST one says, since a batch is undone
+ * as a whole.
+ */
+export declare const resolveSelection: (intents: Readonly<Record<string, any>> | undefined, sheetId: string, viewId: string, direction: "forward" | "undo" | "redo") => {
+    selection: Partial<IRangeSelection.Coords>;
+    options: boolean | ICellRange.SelectOptions;
+} | null;
+/**
+ * Where the freeze panes sit before and after the operation, by sheet ({@link ISheet.getId}).
+ *
+ * @remarks
+ * The one view fact an insert or delete changes: a frozen row above the insertion point moves
+ * with the cells. Recorded only by an operation that moved them, and merged the way the
+ * selection pair is - `before` first-writer-wins, `after` last-writer-wins - so a batch undoes to
+ * where it started and redoes to where it ended. The forward operation moves the panes itself;
+ * this is what undo and redo read.
+ */
+export type FreezePanesIntent = Readonly<Record<string, {
+    before: IRange.CellCoords;
+    after: IRange.CellCoords;
+}>>;
+/**
+ * Which movables are selected before and after the operation, by sheet ({@link ISheet.getId}).
+ *
+ * @remarks
+ * The movable counterpart of {@link SelectionIntent}, merged the way the freeze pair is - `before`
+ * first-writer-wins, `after` last-writer-wins - so a batch undoes to the selection it began with
+ * and redoes to the one it ended on. Recorded only by an operation that changes which movables
+ * exist or which of them the user is working on; everything else leaves the selection alone.
+ *
+ * Movables are named by their id ({@link ITransaction.ITransactional.getId}). A snapshot restores
+ * the same instances, so holding them would work - but an intent is data, and an id is what
+ * survives a reload and a collaborator.
+ */
+export type MovableSelectionIntent = Readonly<Record<string, {
+    /**
+     * {@link ISheetView.getId} of the view the operation was made against.
+     *
+     * @remarks
+     * Only the view that made the change is moved by undoing it - see {@link SelectionIntent}.
+     */
+    viewId: string;
+    before?: readonly string[];
+    after?: readonly string[];
+}>>;
+/**
+ * Fit these ranges when the operation completes.
+ *
+ * @remarks
+ * A union: every operation in a batch adds the ranges it wrote, and one fit covers them all.
+ * Entries are kept per sheet and per option set - two operations that fit differently cannot
+ * be measured as one.
+ */
+export interface AutoFitIntent {
+    /** {@link ISheet.getId} of the sheet to fit on. */
+    sheetId: string;
+    ranges: IRange.Coords[];
+    options?: ICellRange.AutoFitOptions;
+}
+//# sourceMappingURL=_SheetIntents.d.ts.map

package/types/src/sheet/_SheetMutations.d.ts

@@ -1,4 +1,4 @@
-import { IRange } from '@sheetxl/primitives';
+import { IRange, Scalar } from '@sheetxl/primitives';
 import { CoordUtils } from '@sheetxl/utils';
 import { ITransaction } from '../transaction';
 import { Tuple, ISpatialMap } from '../collections';
@@ -7,8 +7,11 @@ import { ICell } from '../cell';
 import { IComment } from '../comment';
 import { IHyperlink } from '../hyperlink';
 import { IStyle } from '../style';
-import { IAutoFill } from '../autoFill';
-import { InternalTupleUpdate } from './_SheetStateTypes';
+import { IProperties } from '../type';
+import { FormulaEntry } from '../calculation/grid';
+import { CellStateIteratorContext } from './_SheetUtils';
+import { SheetDirectStyle } from './style/SheetDirectStyle';
+import { RangeState, InternalTupleUpdate } from './_SheetStateTypes';
 import { SheetMutationContext } from './Sheet';
 /**
  * The shared insert/delete engine (see SHEET-SPLIT-DESIGN §6e). Shifts every state map (values,
@@ -19,11 +22,16 @@ import { SheetMutationContext } from './Sheet';
  */
 export declare function shiftCells(ctx: SheetMutationContext, ranges: readonly IRange.Coords[], options: IRange.Axis | ICellRange.InsertOptions | ICellRange.DeleteOptions | undefined, isInsert: boolean, coordValidator?: CoordUtils.CoordValidator): void;
 /**
- * Replace the comments over each range with the given comment (or clear when `comments === null`).
- * Writes a fresh `commentsSpatial` and commits with auto-select. See SHEET-SPLIT-DESIGN §5.4.
+ * Sets the comment on each range's first cell, or clears every comment within a range when its
+ * update is `null`. Commits with auto-select. See SHEET-SPLIT-DESIGN §5.4.
+ *
+ * @remarks
+ * A comment is one cell's, so a value lands on the top-left cell: the comment there is updated
+ * when the update is modifiers, replaced when it is a whole JSON (how `updateTuples` carries a
+ * moved cell's thread, id and replies included), and added when there is none.
  * @internal
  */
-export declare function setComments(ctx: SheetMutationContext, ranges: readonly ISpatialMap.Entry<IComment.Properties>[], comments?: IComment.JSON | null, // we do this because updateTuples may update each
+export declare function setComments(ctx: SheetMutationContext, ranges: readonly ISpatialMap.Entry<IComment.Update>[], comments?: IComment.Update, // `undefined` = each entry carries its own (updateTuples)
 options?: ITransaction.OperationOptions): void;
 /**
  * Set (or clear when the resolved update is `null`) the hyperlink over each range, applying the
@@ -45,7 +53,38 @@ options?: ITransaction.OperationOptions): void;
  * @internal
  */
 export declare function updateStyles(ctx: SheetMutationContext, ranges: readonly ISpatialMap.Entry<IStyle.Update>[], defaultUpdate?: IStyle.Update, // we do this because updateTuples may update each
-options?: IStyle.UpdateOptions, calcedNumberFormat?: boolean): void;
+options?: IStyle.UpdateOptions, calcedNumberFormat?: boolean, // this is a bit of a hack. This is prevent number formats from functions to override user defined formats.
+isStep?: boolean): void;
+/**
+ * A cell's direct styles as `update` leaves them, applied to each style map the way
+ * {@link updateStyles} applies it, so a held style reads without being written.
+ *
+ * @remarks
+ * A function update is given the cell's composed direct style and its result is split back by
+ * category, as `updateStyles`' function form does over its region.
+ *
+ * @param intersection The cell's range state before the update.
+ * @returns The intersection with the updated styles; `null` if the update reaches past the cell
+ * (a border, a continuous alignment) or clears every style, so it has to be written to know.
+ * @internal
+ */
+export declare function intersectionAfterStyleUpdate(ctx: SheetMutationContext, intersection: RangeState.Intersection | null, rowIndex: number, colIndex: number, update: ScanStyleUpdate): RangeState.Intersection | null;
+/**
+ * Whether a style update written to one cell changes that cell alone. A border does not: it
+ * changes the neighbor's edge. Nor does a horizontal alignment that is, or replaces, a continuous
+ * one: it is drawn across the neighbors.
+ *
+ * @param continuousFillSpatial The sheet's continuous alignments.
+ * @internal
+ */
+export declare function isLocalStyleUpdate(ctx: SheetMutationContext, continuousFillSpatial: ISpatialMap<SheetDirectStyle>, rowIndex: number, colIndex: number, update: IStyle.Update): boolean;
+/**
+ * Whether a cell's number reads as a date once `update` is applied to its style - decided as
+ * {@link updateStyles} decides its date map: by the number format the update leaves in the cell's
+ * direct style. `contentSpatial` is the content map the update would be applied over.
+ * @internal
+ */
+export declare function isDateAfterStyleUpdate(ctx: SheetMutationContext, contentSpatial: ISpatialMap<SheetDirectStyle>, rowIndex: number, colIndex: number, update: ScanStyleUpdate): boolean;
 /**
  * Merge each range into a single cell: relocates/keeps a lone value at the top-left (discarding the
  * rest, or throwing on multiple values unless `discardMultipleValues`), unifies the style over the
@@ -61,77 +100,158 @@ export declare function merge(ctx: SheetMutationContext, ranges: readonly IRange
  */
 export declare function unmerge(ctx: SheetMutationContext, ranges: readonly IRange.Coords[], options?: ITransaction.OperationOptions): void;
 /**
- * The central cell-write path: iterates the incoming `ICell.Update` tuples, resolves each cell
- * (parsing text, applying merges/spills), splits out style / hyperlink / formula side-updates, writes
- * values + contentful + calc grids, and delegates the side-updates to {@link updateStyles} /
- * {@link setHyperlinks} / {@link merge}. See SHEET-SPLIT-DESIGN §5.4.
- * @internal
+ * A formula text on its way through {@link updateTuples}: the A1 text as entered, the cell it was
+ * entered at, and its relative (R1C1) form, derived only when a neighbor asks for it.
  */
-export declare function updateTuples(ctx: SheetMutationContext, boundedTuples: Tuple.BoundedTuples<ICell.Update> | null, options?: ICellRange.UpdateCellsOptions, coordValidator?: CoordUtils.CoordValidator | null | undefined, internalOptions?: InternalTupleUpdate | null): void;
+export interface FormulaTextUpdate {
+    a1: string;
+    rowIndex: number;
+    colIndex: number;
+    /** Derived on first use by {@link relativeFormOf}. */
+    r1c1: string | null;
+    /** Derived on first use by {@link formulaEntryFor}. */
+    entry: FormulaEntry | null;
+}
 /**
- * Clear the given content category (values/formats/comments/hyperlinks, or all) over each range:
- * delegates styles/hyperlinks/comments to their ops, deletes values + spills + calc, and drops tables
- * / auto-tables inside the cleared area (unless `excludeSorts`). See SHEET-SPLIT-DESIGN §5.4.
+ * The text a conflated run's formula reads as at one of the run's cells, before the run is written.
+ *
+ * @remarks
+ * A run keeps its FIRST cell's text, and every other cell reads that text imaged at it - as it
+ * will once the run is written and until it is compiled.
  * @internal
  */
-export declare function clear(ctx: SheetMutationContext, ranges: readonly IRange.Coords[], applyTo?: ICell.Content | null, options?: ITransaction.OperationOptions, excludeSorts?: boolean, isCut?: boolean): void;
+export declare function formulaTextAt(update: FormulaTextUpdate, rowIndex: number, colIndex: number): string;
 /**
- * Resolve a raw destination to the nearest destination {@link autoFill} accepts — what
- * {@link ICellRange.AutoFillOptions.snap} runs before the fill.
+ * Style updates to one cell, in the order they were made: a cell styled more than once in one
+ * scan. Written in that order, as separate calls would write them; a callback cannot be folded
+ * into the update before it.
  * @internal
  */
-export declare function autoFillRange(ctx: SheetMutationContext, template: IRange.Coords, destination: IRange.Coords): IRange.Coords;
+export declare class StyleUpdateSequence {
+    readonly updates: readonly IStyle.Update[];
+    constructor(updates: readonly IStyle.Update[]);
+}
+/** A {@link TupleScan}'s style update to a cell: one update, or several in order. @internal */
+export type ScanStyleUpdate = IStyle.Update | StyleUpdateSequence;
+/** The updates in a {@link ScanStyleUpdate}, in order. @internal */
+export declare function styleUpdatesOf(update: ScanStyleUpdate): readonly IStyle.Update[];
 /**
- * What an `autoFill` run with `preview` hands back instead of committing: the destination plus a
- * cell-level projection of the fill that *would* happen. `SheetRange` wraps this in a read-only
- * `ICellRange` — see {@link ICellRange.autoFill}.
+ * One scan of cell updates: what {@link updateTuples} knows while it walks its cells, and what the
+ * walk collects for {@link finishTupleScan} to write.
+ *
+ * @remarks
+ * A scan is {@link beginTupleScan}, {@link scanCell} for each cell in order, then
+ * {@link finishTupleScan}. The cells are asked in ONE order, major then minor, and both the
+ * range-state sweep and the collectors rely on it. Which axis is the major one is the scan's
+ * own ({@link TupleScan.isColumn}), not necessarily the sheet's.
+ *
+ * An open scan changes nothing and holds no transaction: the finish begins one, writes and commits
+ * it. So a scan can stay open across calls ({@link CellBuffer}), and one that is dropped needs no
+ * undoing.
  * @internal
  */
-export interface AutoFillProjection {
-    /** The destination the projection covers. */
-    coords: IRange.Coords;
+export interface TupleScan {
+    readonly ctx: SheetMutationContext;
+    readonly options: ICellRange.UpdateCellsOptions | undefined;
+    readonly internalOptions: InternalTupleUpdate | null;
+    /** The order the cells are asked in: `true` if a column is the major axis. */
+    readonly isColumn: boolean;
+    readonly isDataChange: boolean;
+    readonly isInternalHyperlink: boolean;
+    readonly isBroadcast: boolean;
+    readonly isLocked: boolean;
+    readonly allowFormatCells: boolean;
+    readonly hasUnlockRanges: boolean;
+    readonly runtime: SheetMutationContext['runtime'];
+    /**
+     * A scan that stays open holds only cells whose write cannot fail once scanned, and whose held
+     * style changes that cell alone: a cell that carries a hyperlink or comments, or a style that
+     * {@link isLocalStyle} refuses, is REFUSED - nothing is collected for it and {@link isRefused} is
+     * set - for the caller to write on its own.
+     */
+    readonly isHeld: boolean;
+    isRefused: boolean;
+    /**
+     * Whether a style held for a cell changes that cell alone; a held scan refuses one that does not,
+     * since a read of a neighbor does not see a held write. Set by the scan's holder.
+     */
+    isLocalStyle: ((rowIndex: number, colIndex: number, update: IStyle.Update) => boolean) | null;
     /**
-     * The projected (uncommitted) cell at these coords. Cells the fill does not touch read straight from
-     * the sheet; filled cells are derived — value, style and, when the template tiles a merge across the
-     * fill, the merge itself (so `getRange`/`getSpans`/`getExtrusions` report the projected block, and a
-     * coord inside one resolves to that block's anchor, where the value lives).
+     * A merge, hyperlink, comments or a style callback that can throw was collected. Their writes can
+     * still refuse after the finish has changed the maps in place, so the finish writes them in a
+     * savepoint of its own.
      */
-    getCellAt(rowIndex: number, colIndex: number): ICell;
+    hasLateRefusals: boolean;
+    iterRanges: ReturnType<SheetMutationContext['rangeStateIterator']> | null;
+    requiresRangeCheck: boolean;
+    readonly seekCoords: IRange.CellCoords;
+    cellMajor: number;
+    cellMinor: number;
+    cellIntersection: RangeState.Intersection | null;
+    readonly optionsFromString: ICell.ModifiersFromStringOptions | null;
+    readonly contextState: CellStateIteratorContext | null;
+    readonly resolvedStringCache: Map<string, ICell.Modifiers>;
+    lastDirectStyle: IProperties.ICellRanged<IStyle.Properties> | undefined;
+    isTextNumFmt: boolean;
+    readonly defaultStyleUnlocked: boolean;
+    isStyleUnlocked: boolean;
+    usedStyleUnlock: boolean;
+    lastUnlock: RangeState.Intersection['unlock'];
+    isUnlockExempt: boolean;
+    isPasswordGated: boolean;
+    readonly deletes: ISpatialMap.IConflatingEntries<any>;
+    readonly styleUpdates: ISpatialMap.IConflatingEntries<ScanStyleUpdate>;
+    readonly hyperlinkUpdates: ISpatialMap.IConflatingEntries<IHyperlink.Update>;
+    readonly commentUpdates: ISpatialMap.IConflatingEntries<IComment.Update>;
+    readonly formulaUpdates: ISpatialMap.IConflatingEntries<FormulaTextUpdate | null>;
+    readonly mergeUpdates: IRange.Coords[];
 }
 /**
- * The single-entry series memo behind `autoFill({ preview })` — the "last autofill".
+ * Begins a scan of cell updates within `boundsRange`.
  *
- * @remarks
- * A drag previews the same template in the same direction over and over, changing only the destination;
- * the series does not depend on the destination, so scanning it once serves the whole drag. Held on the
- * sheet (one entry) and validated against `state` identity: the transaction store rebuilds the state
- * object on every real change (reference-equal *is* its "nothing changed" signal), so any mutation,
- * undo or redo drops the memo without anything having to invalidate it explicitly.
- * @internal
- */
-export interface AutoFillPreviewCache {
-    /** The sheet state the series was read from. */
-    state: unknown;
-    template: IRange.Coords;
-    isForward: boolean;
-    filler: IAutoFill.Filler;
-    /** The caller's `fillerOptions` **by reference** — a caller that rebuilds it simply misses the memo. */
-    fillerOptions: IAutoFill.Options | undefined;
-    /** Series per line of the opposite axis; `null` marks a line that produced nothing to fill. */
-    seriesByLine: Map<number, IAutoFill.FillAt | null>;
-}
+ * @param isColumn The order the cells will be asked in; the sheet's if not given.
+ * @param isHeld See {@link TupleScan.isHeld}.
+ * @internal
+ */
+export declare function beginTupleScan(ctx: SheetMutationContext, boundsRange: IRange.Coords, options: ICellRange.UpdateCellsOptions | undefined, internalOptions: InternalTupleUpdate | null, isColumn?: boolean, isHeld?: boolean): TupleScan;
+/**
+ * Scans one cell of a {@link TupleScan}: the next one, major then minor.
+ *
+ * @returns The value to store, for the caller to place; `null` if the cell is cleared and
+ * `undefined` if it is not written - either ends a run of values.
+ * @internal
+ */
+export declare function scanCell(scan: TupleScan, update: ICell.Update, major: number, minor: number): Scalar | null | undefined;
+/**
+ * Writes what a {@link TupleScan} collected, with the values the caller placed, in a transaction
+ * of its own; rolled back if the write throws.
+ *
+ * @param gridTuple The values {@link scanCell} returned, in the SHEET's orientation whatever the
+ * scan's was.
+ * @param written The cells to report as changed and the selection the write leaves, where they
+ * are not `boundsRange`.
+ * @internal
+ */
+export declare function finishTupleScan(scan: TupleScan, gridTuple: Tuple.GridTuple<Scalar>, bounds: Tuple.OrientatedCoords, boundsRange: IRange.Coords, written?: {
+    changes: readonly IRange.Coords[];
+    selection: IRange.Coords;
+}): void;
 /**
- * Fill the template's series/pattern into the destination (outward drag of the fill handle). Handles
- * merges (tiles them, never splits), date series, previewing, table extension, and copies the
- * per-feature style maps into the filled range. Delegates a negative (inward) fill to
- * {@link autoFillShrink}. See SHEET-SPLIT-DESIGN §5.4.
+ * The central cell-write path: iterates the incoming `ICell.Update` tuples, resolves each cell
+ * (parsing text, applying merges/spills), splits out style / hyperlink / formula side-updates, writes
+ * values + contentful + calc grids, and delegates the side-updates to {@link updateStyles} /
+ * {@link setHyperlinks} / {@link merge}. See SHEET-SPLIT-DESIGN §5.4.
  * @internal
  */
-export declare function autoFill(ctx: SheetMutationContext, template: IRange.Coords, destination: IRange.Coords, options?: ICellRange.AutoFillOptions): boolean | AutoFillProjection;
+export declare function updateTuples(ctx: SheetMutationContext, boundedTuples: Tuple.Region<ICell.Update> | null, options?: ICellRange.UpdateCellsOptions, coordValidator?: CoordUtils.CoordValidator | null | undefined, internalOptions?: InternalTupleUpdate | null): void;
 /**
- * An inward fill — Excel's drag of the fill handle back over the source range. The strip of the
- * template beyond the destination edge is vacated: its cells are cleared, not filled.
+ * Clear the given content category over each range (`null` = all): delegates styles / hyperlinks /
+ * comments / notes to their ops, deletes values + spills + calc, and drops tables / auto-tables
+ * inside the cleared area (unless `excludeSorts`). See SHEET-SPLIT-DESIGN §5.4.
+ *
+ * `cutFrom` is the source of a cut this clear is part of: a table inside it is the cut's to move
+ * or remove, so the clear leaves it standing.
  * @internal
  */
-export declare function autoFillShrink(ctx: SheetMutationContext, template: IRange.Coords, destination: IRange.Coords, direction: IRange.Direction, options?: ICellRange.AutoFillOptions): boolean;
+export declare function clear(ctx: SheetMutationContext, ranges: readonly IRange.Coords[], applyTo?: ICell.Content | null, options?: ITransaction.OperationOptions, excludeSorts?: boolean, cutFrom?: IRange.Coords | null): void;
 //# sourceMappingURL=_SheetMutations.d.ts.map

package/types/src/sheet/_SheetStateReader.d.ts

@@ -5,7 +5,10 @@ import { ICell } from '../cell';
 import { IStyle } from '../style';
 import { ICellRange, ICellHeaderRange } from '../cellRange';
 import { ISheetHeader } from '../sheetHeader';
+import { ScalarListFactory } from './_ScalarListFactory';
 import { IStringCollection } from '../string';
+import { ITransaction } from '../transaction';
+import { ICalcGrid } from '../calculation/grid';
 import { RangeState, CellState, State } from './_SheetStateTypes';
 import { SheetCellOptions } from './SheetCell';
 /** @internal */
@@ -34,19 +37,21 @@ export interface OverFlowsAndStops {
  */
 export interface SheetReadContext {
     readonly state: Readonly<State>;
+    /**
+     * The sheet's grid, as an object. NOT part of `state`: one grid serves every version of the
+     * sheet, so a scoped read that overrides `state` with a snapshot still gets the live grid here.
+     * What it HOLDS versions in its own record; a read that must not make the writes a cell buffer
+     * holds asks its reads for that buffer's transaction, beside the `state` it took the same way.
+     */
+    readonly calcGrid: ICalcGrid;
     readonly rowHeaders: ISheetHeader;
     readonly columnHeaders: ISheetHeader;
     readonly cellOptions: SheetCellOptions;
     readonly strings: IStringCollection;
+    /** Makes the lists cell values are stored as. */
+    readonly lists: ScalarListFactory;
     getEntireCoords(): IRange.Coords;
     getUsedCoords(options?: ICellRange.GetRangeOptions): IRange.Coords | null;
-    /**
-     * The RECONCILED error-VALUE spatial (`RangeState.Type.Error`) — current values are the truth,
-     * not `state.errorSpatial` (write-path only; stale for formula cells after a recalc). Calling
-     * this may lazily build the view (a value scan, cached per state version) — which is why
-     * `Type.Error` is opt-in only and never part of the all-types sweep.
-     */
-    getErrorSpatial(): ISpatialMap<boolean>;
 }
 /**
  * The read engine for a {@link Sheet}'s versioned state.
@@ -132,13 +137,14 @@ export declare function getVisible(ctx: SheetReadContext, coords: readonly IRang
  * `state` defaults to `ctx.state` but can be overridden for a scoped query against a snapshot.
  * @internal
  */
-export declare function collectRanges(ctx: SheetReadContext, queryCoords: IRange.Coords, rangesByType?: ISpatialMap.Entry<RangeState.Intersection>[], searchTypes?: boolean | RangeState.SearchTypes | null, injectReferences?: IRange.JSONReference<any>[][], state?: Readonly<State>, containedBounds?: IRange.Coords): void;
+export declare function collectRanges(ctx: SheetReadContext, queryCoords: IRange.Coords, rangesByType?: ISpatialMap.Entry<RangeState.Intersection>[], searchTypes?: boolean | RangeState.SearchTypes | null, injectReferences?: IRange.JSONReference<any>[][], state?: Readonly<State>, containedBounds?: IRange.Coords, transaction?: ITransaction | null): void;
 /**
  * Iterate the non-overlapping range-state intersections over the bounded region.
  *
  * @remarks
- * Walks the (optionally visible-only) header spans, collects range types per span via
- * {@link collectRanges}, then flattens overlaps into a non-overlapping sequence.
+ * Each searched map is queried once over the bounds; `RangeStateSweep` then flattens the entries
+ * into a non-overlapping sequence (major-axis bands, minor-axis intervals of constant overlap set),
+ * clipped to the visible headers when hidden ones are excluded.
  * @internal
  */
 export declare function rangeStateIterator(ctx: SheetReadContext, options: RangeState.IteratorOptions): RangeState.Iterator;