@sheetxl/sdk 0.7.28-beta.4 → 0.8.0-beta.10

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';
@@ -6,9 +6,12 @@ import { ICellRange } from '../cellRange';
 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 { ICellStyle } from '../style';
+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
@@ -38,14 +46,45 @@ options?: ITransaction.OperationOptions): void;
 export declare function setHyperlinks(ctx: SheetMutationContext, ranges: readonly ISpatialMap.Entry<IHyperlink.Update>[], defaultUpdate?: IHyperlink.Update, // we do this because updateTuples may update each
 options?: ITransaction.OperationOptions): void;
 /**
- * The single style write choke point. Partitions each `IStyle.Update` by category (border / fill /
+ * The single style write choke point. Partitions each `ICellStyle.Update` by category (border / fill /
  * content) and writes each per-feature map directly (DISCRETE — no merged blob); the function-form
  * branch is the one surviving write-side compose. Re-derives the content-derived side maps
  * (continuousFill + dateFormat) over the touched region. See SHEET-STYLE-SPLIT step 4/5.
  * @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;
+export declare function updateStyles(ctx: SheetMutationContext, ranges: readonly ISpatialMap.Entry<ICellStyle.Update>[], defaultUpdate?: ICellStyle.Update, // we do this because updateTuples may update each
+options?: ICellStyle.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: ICellStyle.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 ICellStyle.Update[];
+    constructor(updates: readonly ICellStyle.Update[]);
+}
+/** A {@link TupleScan}'s style update to a cell: one update, or several in order. @internal */
+export type ScanStyleUpdate = ICellStyle.Update | StyleUpdateSequence;
+/** The updates in a {@link ScanStyleUpdate}, in order. @internal */
+export declare function styleUpdatesOf(update: ScanStyleUpdate): readonly ICellStyle.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: ICellStyle.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<ICellStyle.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

@@ -2,23 +2,26 @@ import { IRange, Scalar } from '@sheetxl/primitives';
 import { ISpatialQuery, ISpatialMap } from '../collections';
 import { IProperties } from '../type';
 import { ICell } from '../cell';
-import { IStyle } from '../style';
+import { ICellStyle } 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 */
 export interface ViewEdgeEntry {
     rowIndex: number;
     colIndex: number;
-    continuous: IProperties.ICellRanged<IStyle.Properties> | null | undefined;
+    continuous: IProperties.ICellRanged<ICellStyle.Properties> | null | undefined;
     leftIndex: number;
     rightIndex: number;
     overflow: ICell.HorizontalOverflow | null;
     intersection: RangeState.Intersection;
     scalar: Scalar | null;
-    style: IStyle | null;
+    style: ICellStyle | null;
 }
 /** @internal */
 export interface OverFlowsAndStops {
@@ -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;