@sheetxl/sdk 0.8.0-beta.11 → 0.8.0-beta.12

package/types/src/calculation/state/DeferredCalls.d.ts

@@ -0,0 +1,260 @@
+import { IFormulaContext, IRange, IRichData, Scalar } from '@sheetxl/primitives';
+import { ISpatialMap } from '../../collections';
+import { AsyncValue } from '../../primitives/AsyncValue';
+import { CalcNode } from './CalcNode';
+import { CalcScope } from './CalcScope';
+/**
+ * Where a call stands: still wanted and unanswered, answered, failed, or closed.
+ */
+export declare const CallState: {
+    readonly Open: 0;
+    readonly Settled: 1;
+    readonly Rejected: 2;
+    readonly Closed: 3;
+};
+export type CallState = typeof CallState[keyof typeof CallState];
+/**
+ * One `IFormulaContext.defer` at one site of one cell's formula (DESIGN-ASYNC §4.4): what the
+ * executor is handed, and what a later evaluation of the cell finds again by its ordinal.
+ */
+export declare class DeferredCall implements IFormulaContext.DeferredCall {
+    readonly id: number;
+    readonly executor: IFormulaContext.DeferExecutor;
+    readonly payload: unknown;
+    /** Which function made the call (its declaration), or `null` for one with none. */
+    readonly site: object | null;
+    /**
+     * The node whose evaluation made, last served, or now holds the call (DESIGN-ASYNC §4.5 settle
+     * step 1); `null` for an evaluation with no cell. A re-mint of the cell's node takes it over.
+     */
+    owner: CalcNode | null;
+    state: CallState;
+    /** The most recent result; `undefined` until one arrives. */
+    latest: unknown;
+    protected _onCancel: (() => void)[] | null;
+    /** The port (DESIGN-ASYNC §4.9): told each time the latest moves. */
+    protected _onMoved: ((call: DeferredCall) => void) | null;
+    /** Told of the call's final answer: the manager, which holds the call only until then. */
+    protected _onFinal: ((call: DeferredCall) => void) | null;
+    /** Makes a result cell-ready (see {@link DeferredCalls.Normalize}). */
+    protected _normalize: DeferredCalls.Normalize;
+    constructor(id: number, executor: IFormulaContext.DeferExecutor, payload: unknown, site: object | null, owner: CalcNode | null, onMoved?: ((call: DeferredCall) => void) | null, onFinal?: ((call: DeferredCall) => void) | null, normalize?: DeferredCalls.Normalize);
+    /** @inheritdoc IFormulaContext.DeferredCall.resolve */
+    resolve(value: unknown): void;
+    /** @inheritdoc IFormulaContext.DeferredCall.reject */
+    reject(error: unknown): void;
+    /** @inheritdoc IFormulaContext.DeferredCall.onCancel */
+    onCancel(fn: () => void): void;
+    /** @inheritdoc IFormulaContext.DeferredCall.cancelled */
+    get cancelled(): boolean;
+    /** Whether the call has not answered yet: it is running, and a recalculation leaves it be. */
+    isOpen(): boolean;
+    /** Closes the call; `onCancel` runs when it had not finished. */
+    close(): void;
+    protected _moved(): void;
+    protected _final(): void;
+}
+/** The default settle window (DESIGN-ASYNC §4.8): at most one settle pass per window. */
+export declare const DefaultSettleWindow = 100;
+/** What an evaluation that deferred leaves for the cell: its calls, and whether the root is the only one. */
+export interface DeferredEvaluation {
+    readonly calls: readonly DeferredCall[];
+    /** The formula's root is its only call: the cell's value is that call's answer. */
+    readonly direct: boolean;
+}
+/**
+ * The holder at a cell, if any: the engine grid's value there, or the entry of the spill anchored
+ * there when the cell is an anchor (the anchor cell itself holds the first element).
+ */
+export type HeldAt = (gridId: string, row: number, column: number) => AsyncValue<DeferredCall> | null;
+/**
+ * The calls a calculation backend has made, the batch the evaluation in progress is collecting,
+ * and the state each executor keeps (DESIGN-ASYNC §4.3, §4.4).
+ *
+ * @remarks
+ * One per backend. Nothing here is touched by an evaluation that does not defer: the dispatch
+ * notices a deferral through {@link CalcScope.deferCount}, and only then asks this.
+ */
+export declare class DeferredCalls {
+    protected _scope: CalcScope;
+    protected _heldAt: HeldAt;
+    protected _getRandom: () => number;
+    protected _nextId: number;
+    /** The calls that have not given their final answer, by id. A holder names any other by pointer. */
+    protected _calls: Map<number, DeferredCall>;
+    protected _onFinal: (call: DeferredCall) => void;
+    /** Whether a holder has ever been written: until then no read needs to look for one. */
+    protected _holders: boolean;
+    /** The calls of the evaluation in progress, by ordinal, and which of them it made. */
+    protected _current: DeferredCall[];
+    protected _made: DeferredCall[];
+    /** The calls made since the last {@link flush}, by executor: each executor's batch. */
+    protected _batch: Map<IFormulaContext.DeferExecutor, DeferredCall[]>;
+    /** What each executor keeps between batches (`IBatchContext.getState`). */
+    protected _states: Map<IFormulaContext.DeferExecutor, unknown>;
+    protected _batchContext: IFormulaContext.IBatchContext;
+    protected _setCurrent: (executor: IFormulaContext.DeferExecutor | null) => void;
+    /**
+     * The port (DESIGN-ASYNC §4.9): the calls whose latest moved since the last settle pass took
+     * them. A set, so a bursting feed is one entry however often it posts: the latest is on the call.
+     */
+    protected _moved: Set<DeferredCall>;
+    protected _onMoved: (call: DeferredCall) => void;
+    /** The settle pass, run on its own task at most once per window (DESIGN-ASYNC §4.8). */
+    protected _onSettle: (() => void) | null;
+    protected _settleWindow: number;
+    protected _settleTimer: ReturnType<typeof setTimeout> | null;
+    protected _settledAt: number;
+    /** The grids a settle told the model about without a write: the next pass vends their records. */
+    protected _repaintGrids: Set<string>;
+    /** The cells a settle marked for re-evaluation, scoped: the next pass's seeds, beside its own. */
+    protected _settleDirty: ISpatialMap.Entry[];
+    protected _normalize: DeferredCalls.Normalize;
+    /**
+     * Every site is served its call (a settle pass, or an evaluation waiting on its answers);
+     * otherwise only a running call is, and a stopped one is called again (DESIGN-ASYNC §4.5).
+     */
+    protected _serving: boolean;
+    /** The batch the next {@link flush} hands out fetches past the workbook's cache (`CalculateOptions.external`). */
+    protected _external: boolean;
+    /** {@link _batchContext}, with a `fetch` that goes to the source. */
+    protected _reloadContext: IFormulaContext.IBatchContext;
+    /**
+     * The last answer the site's call gave for the same question, read by `IFormulaContext.defer`
+     * right after {@link defer}: `undefined` when there was none.
+     */
+    previous: unknown;
+    /** The {@link whenChanged} waits in progress: woken by a final answer, a settle pass starting, a cancel. */
+    protected _waiters: Set<() => void>;
+    /**
+     * Told when the counts may have changed, at the moments they become visible: calls handed out,
+     * a settle pass starting, a cancel, a close. Never per answer: a million answers are one settle.
+     */
+    protected _onCountsChange: (() => void) | null;
+    constructor(scope: CalcScope, heldAt: HeldAt, getRandom: () => number, onSettle?: (() => void) | null, settleWindow?: number, normalize?: DeferredCalls.Normalize, services?: DeferredCalls.Services, onCountsChange?: (() => void) | null);
+    /** How many calls have not answered. `0` lets a pass skip every pending-input check. */
+    getOpenCount(): number;
+    /** The held calls whose owner is a cell of `gridId`. */
+    getCallsOf(gridId: string): DeferredCall[];
+    /** Whether an answer that landed has yet to be applied: its settle pass is still to run. */
+    hasSettleWork(): boolean;
+    /**
+     * Resolves at the next change a wait for answers cares about — a call's final answer, a settle
+     * pass starting, a cancel — or after `timeout` ms, whichever is first.
+     */
+    whenChanged(timeout: number): Promise<void>;
+    protected _wake(): void;
+    /**
+     * Closes every held call whose owner `cover` covers (`ICalculation.cancelAsync`): `onCancel`
+     * runs, and a later answer is dropped. A cancelled call stays in its holders: its cell is served
+     * what it shows now, and asks again only on an external calculation.
+     *
+     * @param cover `true` for every call, a grid id for one grid's, scoped coords for a range's.
+     * @returns The calls closed, for the caller to re-evaluate their owners.
+     */
+    cancel(cover: true | string | IRange.Coords): DeferredCall[];
+    /** Closes `calls`: those still owed an answer run `onCancel`, and a later answer is dropped. */
+    closeCalls(calls: Iterable<DeferredCall>): void;
+    /** Whether any grid of this backend may hold an {@link AsyncValue}: what gates every unwrap. */
+    hasHolders(): boolean;
+    /** The open call with `id`; `undefined` once it has given its final answer, or for one unknown. */
+    getCall(id: number): DeferredCall | undefined;
+    /** Drains the port: every call whose latest moved since the last drain. */
+    takeMoved(): DeferredCall[];
+    /** Records that a settle told the model about a cell of `gridId` without a write. */
+    noteRepaint(gridId: string): void;
+    /** Marks `cells` (scoped) for the next pass to collect: a settled composite owner, or a dependent of a direct one. */
+    addSettleDirty(cells: readonly ISpatialMap.Entry[]): void;
+    /** The cells settles marked since the last pass; empties them. */
+    takeSettleDirty(): ISpatialMap.Entry[];
+    /** The grids with a repaint since the last pass, for the pass to vend; empties them. */
+    takeRepaintGrids(): string[];
+    /**
+     * Asks for a settle pass: at once on the leading edge, else when the window since the last one
+     * ends. Always a fresh task, so an executor settling synchronously cannot re-enter the pass that
+     * ran it.
+     */
+    protected _requestSettle(): void;
+    /**
+     * The cell's value for an evaluation that deferred; for one that spilled, what its spill entry
+     * carries. From here on reads must look for holders.
+     */
+    newHolder(value: Scalar | IRange, evaluation: DeferredEvaluation): AsyncValue<DeferredCall>;
+    /**
+     * Takes one `defer` from the evaluation in progress: the call this site made last time when the
+     * same function made it with an equal payload and it still stands, or a new one for the batch.
+     * It stands while it runs: a recalculation leaves it be. Once it has
+     * stopped, a recalculation calls the function again; only an answer landing ({@link setServing})
+     * serves a stopped call. Same function, not same executor: an inline executor is a new closure
+     * every evaluation, and is still served.
+     *
+     * @param site Which function is deferring (its declaration); `null` compares executors instead. The site's last call is the one the
+     * holder in its cell names at this ordinal, so a version of the grid brought back by an undo,
+     * or a cell moved by a shift, is answered by the call it was given.
+     * @param volatile The function declares itself volatile: it asks again on every evaluation,
+     * payload equal or not, as `RAND()` re-rolls (DESIGN-ASYNC §4.7).
+     * @returns The call the site was served, for the dispatch around the body to answer its latest
+     * in place of the body's return; `null` for a new call.
+     */
+    defer(executor: IFormulaContext.DeferExecutor, payload: unknown, site?: object | null, volatile?: boolean): DeferredCall | null;
+    /**
+     * Ends the deferring evaluation in progress: its calls, by ordinal. Resets the scope's
+     * per-evaluation fields.
+     */
+    endEvaluation(): DeferredEvaluation;
+    /**
+     * Ends an evaluation that will not stand — a probe of whether an answer can be shared — without
+     * keeping its calls: what it made never reaches an executor.
+     */
+    abandonEvaluation(): void;
+    /**
+     * Runs every executor once with the calls the batch collected for it (DESIGN-ASYNC §4.3). Each
+     * in its own try: a throw, or a promise that rejects, fails the calls it has not settled and no
+     * other executor's.
+     */
+    flush(): void;
+    /** Closes every open call and drops every batch and state: the backend is going away. */
+    close(): void;
+    /**
+     * Whether every site is served its call until the next {@link flush}: a settle pass, whose
+     * re-evaluations are answers landing, or an evaluation waiting on its own calls.
+     */
+    setServing(serving: boolean): void;
+    /**
+     * Whether the batch the next {@link flush} hands out fetches past the workbook's cache, to the
+     * source (`CalculateOptions.external`, `cache: 'reload'`).
+     */
+    setExternal(external: boolean): void;
+    protected _coversCell(cover: true | string | IRange.Coords, gridId: string | null, row: number, column: number): boolean;
+    protected _batchFor(executor: IFormulaContext.DeferExecutor): DeferredCall[];
+    /**
+     * The call this site of the evaluation in progress made last time: what its cell's holder names,
+     * or, for a formula held in no cell (a temporary one), the holder its node keeps.
+     */
+    protected _siteCall(ordinal: number): DeferredCall | undefined;
+}
+export declare namespace DeferredCalls {
+    /**
+     * Makes a result cell-ready as it arrives, so a holder always reads as something a cell can
+     * hold: an author's array (`[[1],[2]]`, DESIGN-ASYNC §7.3) becomes a range, and a one-cell
+     * range its scalar. The backend supplies it; a scalar or a multi-cell range passes as is.
+     */
+    type Normalize = (value: unknown) => unknown;
+    /** What the backend lends an executor through its batch context; each omitted, a default. */
+    interface Services {
+        /** Makes rich values for the backend's workbook. Omitted, made outside any workbook. */
+        createRichData?: (type: string, data?: any) => IRichData;
+        /** Adds resources to the backend's workbook. Omitted, made outside any workbook. */
+        addResource?: (buffer: ArrayBuffer, options?: {
+            fetchedFrom?: string;
+        }) => object;
+        /** The workbook's fetch. Omitted, the global `fetch`. */
+        fetch?: (input: string, init?: RequestInit) => Promise<Response>;
+    }
+}
+/**
+ * Whether two payloads are the same question (DESIGN-ASYNC §4.3): `Object.is`, or for two plain
+ * objects or arrays, `Object.is` over their own enumerable values one level deep.
+ */
+export declare const samePayload: (a: unknown, b: unknown) => boolean;
+//# sourceMappingURL=DeferredCalls.d.ts.map

package/types/src/calculation/state/IContextContainer.d.ts

@@ -1,5 +1,6 @@
 import { Scalar, IRange, IRuntime, IFormulaContext } from '@sheetxl/primitives';
 import { ISparseGrid, ISpatialMap, ISpatialMap3D, ISpatialQuery } from '../../collections';
+import { IRichDataKind } from '../../richData';
 import { ISymbolRegistry } from '../symbol';
 import { IFormulaBlock, FormulaImager } from '../formula';
 import { PrecedentSpatialValue, PrecedentKind, FormulaSpatialValue } from '../spatial';
@@ -9,6 +10,8 @@ import { ICalculation } from '../ICalculation';
 import { NamedNodeInfo } from '../Types';
 import { CalcNode } from './CalcNode';
 import { CalcScope } from './CalcScope';
+import { DeferredCalls } from './DeferredCalls';
+import { WhatIfTable } from '../executor/_WhatIf';
 /**
  * Interface to allow grids to interact with calculation container.
  */
@@ -62,7 +65,18 @@ export interface IContextContainer {
      */
     isGridless?: (sheetId: string) => boolean;
     getScope(): CalcScope;
+    /**
+     * The calls the container's evaluations deferred (`IFormulaContext.defer`), with each
+     * executor's batch. Absent, or `null`, where nothing can answer later: a deferring function's
+     * return value is then its answer.
+     */
+    getDeferred?(): DeferredCalls | null;
     getRuntime(): IRuntime;
+    /**
+     * What rich values a formula makes are made for: the workbook's resources and strings.
+     * Absent, they are made outside any workbook.
+     */
+    getRichDataContext?(): IRichDataKind.Context;
     /**
      * Returns the current datetime in milliseconds.
      */
@@ -334,6 +348,12 @@ export interface IContextContainer {
      * recover which is which from the coords.
      */
     addDynamicPrecedent(calcNode: CalcNode, range: IRange.Coords | undefined, kind: PrecedentKind): void;
+    /**
+     * The results of a what-if data table, for the `TABLE` node being evaluated (the scope's node):
+     * its affected cells re-evaluated under each substitution, nothing written
+     * (DESIGN-DATA-TABLES §4.3). Only during a pass.
+     */
+    evaluateWhatIf(table: WhatIfTable): Scalar[][];
     /**
      * Queues an action to run at the engine's next safe point, and schedules that point.
      *

package/types/src/calculation/state/_PendingOverlayGrid.d.ts

@@ -160,4 +160,10 @@ export declare class PendingOverlayGrid implements ISparseGrid<Scalar>, Referenc
     protected _commitAll(): void;
     get [Symbol.toStringTag](): string;
 }
+/**
+ * Whether `grid` reads an error inside the rectangle, by walking it. Shared with `WhatIfLayer`.
+ *
+ * @internal
+ */
+export declare function _scanHasError(grid: ISparseGrid<Scalar>, coords: IRange.Coords): boolean;
 //# sourceMappingURL=_PendingOverlayGrid.d.ts.map

package/types/src/calculation/state/_WhatIfLayer.d.ts

@@ -0,0 +1,91 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { Direction, RangeAxis, CellCoords, RangeCoords } from '@sheetxl/utils';
+import { Tuple, IGrid, ISparseGrid, IListLike } from '../../collections';
+import { ReferenceErrorIndex } from '../../primitives/ReferenceRange';
+/**
+ * A grid's values with a what-if substitution laid over them (DESIGN-DATA-TABLES §4.3): the input
+ * cells a `TABLE` puts axis values into, and the results of the cells it re-evaluates under them.
+ * A point read and an iteration answer from the map first and the grid underneath otherwise (the
+ * pass's pending overlay during a pass), as `PendingOverlayGrid` does; nothing here is ever written
+ * through, so the committed values, the formula blocks and the model are untouched and there is
+ * nothing to restore. Dropped when the table is done.
+ *
+ * @remarks
+ * Also the error index of the references built over it ({@link ReferenceErrorIndex}): the
+ * underlying index plus a scan of the map, taken only while the map holds an error.
+ *
+ * Every write of the grid interface is refused: a what-if evaluation reads.
+ */
+export declare class WhatIfLayer implements ISparseGrid<Scalar>, ReferenceErrorIndex {
+    protected readonly _inner: ISparseGrid<Scalar>;
+    protected readonly _committed: ReferenceErrorIndex;
+    protected readonly _isColumn: boolean;
+    protected _map: Map<number, Scalar>;
+    /** Substituted values that are errors — the scan in {@link hasErrorIn} runs only while > 0. */
+    protected _errors: number;
+    protected _rowStart: number;
+    protected _rowEnd: number;
+    protected _colStart: number;
+    protected _colEnd: number;
+    constructor(inner: ISparseGrid<Scalar>, committed: ReferenceErrorIndex);
+    get isWhatIfLayer(): true;
+    /** The committed grid. */
+    getInner(): ISparseGrid<Scalar>;
+    /** Substituted cells. */
+    get size(): number;
+    /** Substitutes `value` at the cell. A blank is kept as a blank (`null`), as an axis cell's is. */
+    set(row: number, col: number, value: Scalar): void;
+    /** Drops every substitution: the committed grid answers everything again. */
+    clear(): void;
+    /** Does a rectangle overlap the bounding box of the substituted cells? */
+    intersects(rowStart: number, colStart: number, rowEnd: number, colEnd: number): boolean;
+    /** {@inheritDoc ReferenceErrorIndex.hasErrorIn} */
+    hasErrorIn(coords: IRange.Coords): boolean;
+    /** Is the cell inside the substituted box? */
+    protected _inBounds(row: number, col: number): boolean;
+    /** The run with substituted values swapped in, or the run itself when none fall inside it. */
+    protected _substituteRun(major: number, minorFrom: number, run: IListLike<Scalar>): IListLike<Scalar>;
+    /** {@inheritDoc IGrid.getValueAt} */
+    getValueAt(row: number, column: number): Scalar;
+    /**
+     * {@inheritDoc ISparseGrid.getRuns}
+     *
+     * @remarks
+     * A substituted cell the committed grid does not hold at all (an input that was never written)
+     * is not shown by a run iteration: substitution only describes cells with a run under them, as
+     * the pending overlay's does. A point read answers it.
+     */
+    getRuns(options?: ISparseGrid.RunIteratorOptions): ISparseGrid.RunIterableIterator<Scalar>;
+    /** {@inheritDoc IGrid.entries} */
+    entries(options?: IGrid.IteratorOptions): IGrid.EntryIterator<Scalar>;
+    /** {@inheritDoc IGrid.values} */
+    values(options?: IGrid.IteratorOptions): IGrid.ValueIterator;
+    /** {@inheritDoc IGrid.keys} */
+    keys(options?: IGrid.IteratorOptions): IGrid.KeyIterator;
+    /** {@inheritDoc IGrid.getValues} */
+    getValues(coords?: RangeCoords): Tuple.Region<Scalar> | null;
+    /** {@inheritDoc IGrid.copyTo} */
+    copyTo(destination: IGrid, topLeft: CellCoords, from: RangeCoords): void;
+    /** {@inheritDoc IGrid.getAxis} */
+    getAxis(): RangeAxis;
+    /** {@inheritDoc IGrid.getCount} */
+    getCount(): number;
+    /** {@inheritDoc IGrid.getCoords} */
+    getCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.getMaxCoords} */
+    getMaxCoords(): RangeCoords | null;
+    /** {@inheritDoc IGrid.clone} */
+    clone(_cloneKey?: any): this;
+    /** {@inheritDoc IGrid.cloneEmpty} */
+    cloneEmpty(cloneKey?: any): this;
+    /** {@inheritDoc IGrid.setValues} */
+    setValues(_values: Tuple.GridTuple<Scalar>): this;
+    /** {@inheritDoc IGrid.setValueAt} */
+    setValueAt(_row: number, _column: number, _value: Scalar): void;
+    /** {@inheritDoc IGrid.delete} */
+    delete(_coords: RangeCoords | null): boolean;
+    /** {@inheritDoc IGrid.shift} */
+    shift(_coords: RangeCoords, _direction: Direction): boolean;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=_WhatIfLayer.d.ts.map

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

@@ -1,11 +1,12 @@
-import { Scalar, ScalarType, InteropScalarType, InteropScalar, IRange, IRichData } from '@sheetxl/primitives';
+import { Scalar, ScalarType, InteropScalarType, InteropScalar, IRange } from '@sheetxl/primitives';
 import { Size, Rectangle, Bounds } from '@sheetxl/utils';
 import { ITypes } from '../type';
 import { ITextFrame, TextRotation, TextStacked, IRichText } from '../text';
 import { NumberFormat } from '../numFmt';
 import { ITable } from '../table';
 import { IDataValidation } from '../dataValidation';
-import { IConditionalFormat } from '../conditionalFormat/IConditionalFormat';
+import { IConditionalFormat } from '../conditionalFormat';
+import { ICellControl } from '../cellControl';
 import { IHyperlink } from '../hyperlink';
 import { IComment } from '../comment';
 import { ICellStyle } from '../style';
@@ -143,10 +144,16 @@ export interface ICell {
      */
     getRole(): ICell.Role | null;
     /**
-     * Returns the hyperlink assigned to the cell.
+     * Returns the cell's link: the hyperlink set on the cell, else the link its value is.
      *
      * @remarks
-     * Returns `null` if no hyperlink is set.
+     * Returns `null` when the cell has neither.
+     *
+     * A `HYPERLINK()` result (a {@link Hyperlink} value with an address) is returned as a link with
+     * {@link IHyperlink.isReadOnly} `true`; it is not removed or edited as a link, it changes with
+     * its formula. A hyperlink set on the cell wins when the cell has both. Excel's
+     * `Range.Hyperlinks` and Office Scripts' `Range.getHyperlink()` return nothing for a
+     * `HYPERLINK()` cell.
      */
     getHyperlink(): IHyperlink | null;
     /**
@@ -363,6 +370,14 @@ export interface ICell {
      * only lays out text does not need to read this at all.
      */
     getConditionalDecorations(): Readonly<IConditionalFormat.Decorations>;
+    /**
+     * Returns the cell's control, such as a checkbox, or `null` when it has none.
+     *
+     * @remarks
+     * A control draws only a value it accepts: ask `getControl()?.isAccepted(getValue())`. A
+     * checkbox cell holding `2` has a control and draws `2`.
+     */
+    getControl(): ICellControl | null;
     /**
      * If the cell is in a table this will return it.
      */
@@ -717,40 +732,10 @@ export declare namespace ICell {
          */
         anchorBounds: Bounds;
     }
-    /**
-     * Encodings of ScalarType for persistence
-     */
-    type JSONScalarType = 'n' | 's' | 'b' | 'e' | 'r' | 'z';
-    /**
-     * A value encoded as a number with an associated type.
-     */
-    interface JSONTypedValue {
-        t: JSONScalarType;
-        /**
-         * The number, string id, error code or boolean flag; for `'r'`, the rich data's own JSON
-         * (`IRichData.JSON`), which its registered kind reads back.
-         */
-        v: number | IRichData.JSON;
-    }
     /**
      * Reexports the `IRange.CellCoords` type for use in cell coordinates.
      */
     type Coords = IRange.CellCoords;
-    /**
-     * JSON values types that have their type embedded in the
-     * 'format'.
-     *
-     * @remarks
-     * A string value is the string id in the `IStringsCollection`.
-     */
-    type JSONUnTypedValue = number | boolean | string;
-    /**
-     * For persisting a single Cell value and type.
-     *
-     * @remarks
-     * Styling and other advanced properties are stored as ranges.
-     */
-    type JSON = JSONUnTypedValue | JSONTypedValue;
     /**
      * Represents the types of content that can be associated with a cell or range.
      *
@@ -904,12 +889,22 @@ export declare namespace ICell {
         readonly LookupShape: "lookupShape";
         /** A reference to another workbook, a deleted reference, or a function a converter could not name. */
         readonly ExternalReference: "externalReference";
+        /** A formula that is only an error value, such as `=#DIV/0!`: what a converter leaves when it drops a formula. */
+        readonly ErrorConstant: "errorConstant";
         /** A link to another sheet whose target row is labeled other than its own row. */
         readonly LinkLabelMismatch: "linkLabelMismatch";
         /** A lookup keyed by a typed string that labels neither the formula's row nor its column. */
         readonly KeyLabelMismatch: "keyLabelMismatch";
         /** A link read with the other sign from the sheet's other links into the same row. */
         readonly SignVsSiblings: "signVsSiblings";
+        /** A number typed into a formula that equals a typed number on the sheet no formula reads. */
+        readonly LiteralMatchesInput: "literalMatchesInput";
+        /** A formula that differs from its twins on the sheet, the formulas of the same shape, in a typed number. */
+        readonly TwinBlockDivergence: "twinBlockDivergence";
+        /** A typed number an order of magnitude or more off the numbers typed in its format on the sheet. */
+        readonly ScaleOutlier: "scaleOutlier";
+        /** A constant typed into a formula — a number, a string or a boolean — and how often the workbook types it. */
+        readonly ConstantFrequency: "constantFrequency";
     };
     type ErrorCheck = typeof ErrorCheck[keyof typeof ErrorCheck];
     /**
@@ -940,9 +935,14 @@ export declare namespace ICell {
      * | `approximateMatch` | `function`; `matchType`, `'1'`, `'-1'`, `'TRUE'` or `'omitted'` |
      * | `lookupShape` | `array`, the range the result is read from; `vector`, the range the key is found in |
      * | `externalReference` | `kind` (`'workbook'`, `'deleted'`, `'udf'`); `reference`, or `function` for a `'udf'` |
+     * | `errorConstant` | `error`, the error the formula is; `dataTable`, the anchor of a data table that spills less than the block it heads, and `extent`, the rectangle the two cover |
      * | `linkLabelMismatch` | `label` / `labelAt`, the cell's row label; `target` / `targetAt`, the label of the row it links to |
      * | `keyLabelMismatch` | `function`; `key`; `rowLabel` / `rowLabelAt` and `columnLabel` / `columnLabelAt`, where found |
      * | `signVsSiblings` | `reference`; `sign` (`'negative'` / `'positive'`); `siblings`, how many links into that row read the other sign; `siblingAt`, one of them |
+     * | `literalMatchesInput` | `literal`, the number as the formula types it; `inputAt`, the nearest typed number of that value no formula reads; `label` / `labelAt`, that input's label, when it has one; `matches`, the places the value is typed unread |
+     * | `twinBlockDivergence` | `part` (`'literal'` / `'sign'`); for a literal, `literal` and `expected`, this formula's number and its twins'; for a sign, `term` of `terms`, the term that differs, `references`, how many the shape holds, and `sign`, how this formula adds it; `twins`, how many formulas carry the other side; `twinAt`, one of them |
+     * | `scaleOutlier` | `format` (`'percent'`); `times`, the power of ten the value is off by; `typical`, the median of the sheet's typed numbers in that format; `of`, how many there are |
+     * | `constantFrequency` | `kind` (`'number'`, `'string'`, `'boolean'`); `value`, a number without its sign; `uses`, the places in the workbook that type it; `of`, the workbook's constant uses |
      *
      * **Runs.** `formula`, `hardcodeInRun` and `styleBreak` are one rule over different layers of
      * the sheet: a region thin against the run it sits in. The cells on both sides agree with each
@@ -997,6 +997,25 @@ export declare namespace ICell {
      * v2 Debugging goldens and move as other measurements arrive. Regions of the `anomalies` feature
      * list highest rank first, and so do a cell's findings, in check order within an equal rank.
      *
+     * **Literals and twins.** `literalMatchesInput` reads the numbers typed into a formula against
+     * the typed numbers no formula reads: a reference replaced by its value is what left the input
+     * unread. Small counts, calendar periods and powers of ten never fire. `twinBlockDivergence`
+     * reads formulas of the same shape once references, literals and signs are set aside: twins that
+     * divide by `12` and by `365`, or one that adds a term the others take away. Literals compare only
+     * when both are a calendar period, a power of ten or a small count. Every side of a divergence is
+     * listed, since two wrong rows can outvote the right one.
+     *
+     * `literalMatchesInput` ranks at `0.8 / matches`. A `twinBlockDivergence` finding ranks at `0.8`
+     * times the share of the twins on the other side, `twins / (twins + this side's count)`, halved
+     * for a sign: signs differ between line items by design, so a sign divergence is read when asked
+     * for by check. `scaleOutlier` ranks at `0.8`.
+     *
+     * `constantFrequency` reports every constant a formula types, the common ones too, with how many
+     * places in the workbook type it (`uses`) and of how many constant uses (`of`). It ranks at
+     * `0.1 / uses × of / (of + 10)`: the rarer the constant, the higher, and a constant on a workbook
+     * that types few has little to be rare against. A finding's `uses` and `of` change when another
+     * sheet changes.
+     *
      * A label's position is absolute (`R12C3`), since it stays put whichever cell of a region reads
      * it; its text is the one read at the region's first cell.
      */

package/types/src/cellControl/CellControl.d.ts

@@ -0,0 +1,67 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { IListener } from '../listener';
+import { Anchored } from '../anchored/Anchored';
+import { AbstractAnchored } from '../anchored/AbstractAnchored';
+import { ICellControl } from './ICellControl';
+/**
+ * Implementation of {@link ICellControl}.
+ *
+ * @remarks
+ * Extends {@link AbstractAnchored} directly: a control has no condition and no formula, so it
+ * never subscribes to range events. Its definition is fixed at creation; a different control is a
+ * different entry.
+ */
+export declare class CellControl extends AbstractAnchored<State, ICellControl.Events> implements ICellControl {
+    /** @internal */
+    protected _initialize(options: CellControl.ConstructorOptions): void;
+    /** @internal */
+    protected _getActionDescription(action: 'delete' | 'initialize' | 'updateListener'): string | null;
+    /**
+     * Always: a control pins to where it was authored, as a conditional format does.
+     * @internal
+     */
+    protected _isAnchorAbsolute(): boolean;
+    /** @internal */
+    protected _processContainerShift(options: Anchored.ShiftOptions): IRange.Coords | null | void;
+    /** {@inheritDoc ICellControl.getType} */
+    getType(): string;
+    /** {@inheritDoc ICellControl.isAccepted} */
+    isAccepted(value: Scalar): boolean;
+    /**
+     * Covers `ranges` too, coalesced with what the control already covers. Autofill uses it to grow
+     * the template's control rather than mint a twin.
+     * @internal
+     */
+    _extendRanges(ranges: readonly IRange.Coords[]): void;
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: ICellControl.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc ICellControl.toJSON} */
+    toJSON(): ICellControl.JSON;
+    get [Symbol.toStringTag](): string;
+    toString(): string;
+    /** {@inheritDoc ICellControl.isICellControl} */
+    get isICellControl(): true;
+}
+/**
+ * Interfaces for creating a {@link CellControl}.
+ */
+export declare namespace CellControl {
+    interface ConstructorOptions extends Anchored.ConstructorOptions<ICellControl.JSON> {
+    }
+    /**
+     * A frozen copy of `json` with a non-empty `type`.
+     *
+     * @throws when `json` names no type.
+     */
+    function normalizeJSON(json: ICellControl.JSON | null | undefined): Readonly<ICellControl.JSON>;
+    /**
+     * Whether two controls are the same definition: the same type and the same properties.
+     */
+    function isSameJSON(a: Readonly<ICellControl.JSON>, b: Readonly<ICellControl.JSON>): boolean;
+}
+/** @internal */
+interface State extends AbstractAnchored.State {
+    json: Readonly<ICellControl.JSON>;
+}
+export {};
+//# sourceMappingURL=CellControl.d.ts.map

package/types/src/cellControl/CellControlCollection.d.ts

@@ -0,0 +1,29 @@
+import { ICellRanges } from '../cellRange';
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { ICellControlCollection } from './ICellControlCollection';
+import { ICellControl } from './ICellControl';
+/**
+ * Implementation for {@link ICellControlCollection}.
+ *
+ * @remarks
+ * A front over the sheet's own cell-control state — the sheet keeps the store and the events,
+ * this class keeps the API. `onCollectionChange` is the sheet's `onCellControlsChange`, forwarded
+ * with this collection as the source.
+ */
+export declare class CellControlCollection extends AbstractCollection<ICellControl, ICellControlCollection.GetItemsOptions> implements ICellControlCollection {
+    private _add;
+    private _get;
+    private _addListeners;
+    constructor(add: (address: ICellRanges.Address, control: ICellControl.JSON, options?: ITransaction.OperationOptions) => ICellControl, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => ICellControl[], addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove);
+    /** {@inheritDoc ICellControlCollection.add} */
+    add(address: ICellRanges.Address, control: ICellControl.JSON, options?: ITransaction.OperationOptions): ICellControl;
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: ICellControlCollection.GetItemsOptions): ICellControl[];
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc ICellControlCollection.isICellControlCollection} */
+    get isICellControlCollection(): true;
+}
+//# sourceMappingURL=CellControlCollection.d.ts.map