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

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/calculation/toolkit/FormulaLiteralReader.d.ts

@@ -0,0 +1,4 @@
+import { Scalar } from '@sheetxl/primitives';
+/** {@link parseFormulaLiteral}, with the toolkit loaded. */
+export declare function readFormulaLiteral(text: string): Scalar | undefined;
+//# sourceMappingURL=FormulaLiteralReader.d.ts.map

package/types/src/calculation/toolkit/FormulaTextParser.d.ts

@@ -0,0 +1,10 @@
+import { IRange } from '@sheetxl/primitives';
+import { ICalculation } from '../ICalculation';
+import { FormulaText } from '../FormulaText';
+/** {@link FormulaText.parse}, with the toolkit loaded. */
+export declare function parse(text: string, options?: FormulaText.ParseOptions): ICalculation.FormulaNode | null;
+/** {@link FormulaText.transform}, with the toolkit loaded. */
+export declare function transform(root: ICalculation.FormulaNode, transform: ICalculation.FormulaTransform): ICalculation.FormulaNode;
+/** {@link FormulaText.imager}, with the toolkit loaded. */
+export declare function imager(root: ICalculation.FormulaNode, options?: Omit<FormulaText.ImageOptions, 'at'>): (at?: IRange.CellCoords) => string;
+//# sourceMappingURL=FormulaTextParser.d.ts.map

package/types/src/calculation/toolkit/FunctionDeclarationTable.d.ts

@@ -0,0 +1,4 @@
+import { FunctionDeclarations } from '../functions/FunctionDeclarations';
+/** A built-in function's declaration, or `null` when no built-in has that name. Not case sensitive. */
+export declare function getFunctionDeclaration(name: string): FunctionDeclarations.Declared | null;
+//# sourceMappingURL=FunctionDeclarationTable.d.ts.map

package/types/src/calculation/toolkit/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The formula toolkit's code: the parser, the printer, the literal reader and the built-in
+ * declarations, behind `FormulaText`, `parseFormulaLiteral` and `FunctionDeclarations`.
+ *
+ * @remarks
+ * Loaded by `FormulaText.load()` and by a calculation's start, never carried from import
+ * (DESIGN-CALC-SERVICE §13.25). Only `_FormulaToolkit` imports it.
+ */
+export { parse, transform, imager } from './FormulaTextParser';
+export { readFormulaLiteral } from './FormulaLiteralReader';
+export { getFunctionDeclaration } from './FunctionDeclarationTable';
+//# sourceMappingURL=index.d.ts.map

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

@@ -1,17 +1,18 @@
 import { Scalar, ScalarType, InteropScalarType, InteropScalar, IRange } from '@sheetxl/primitives';
 import { Size, Rectangle, Bounds } from '@sheetxl/utils';
 import { ITypes } from '../type';
-import { ITextFrame, TextRotation, TextStacked } from '../text';
+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';
 import { ICellRanges, ICellRange } from '../cellRange';
 import { ICalculation } from '../calculation';
-import { ISheet } from '../sheet';
+import { IWorksheet } from '../sheet';
 import { ICellProtection } from './ICellProtection';
 /**
  * A single unit of data and meta data within an `ICellRange`, located at a specific row and column.
@@ -114,18 +115,62 @@ export interface ICell {
      */
     getDependents(): Promise<ICellRanges | null>;
     /**
-     * Returns the hyperlink assigned to the cell.
+     * Returns whether the cell ignores one of Excel's error checks.
+     *
+     * @param check The check.
+     * @see {@link ICellRange.setErrorIgnored}
+     */
+    isErrorIgnored(check: ICell.ErrorCheck): boolean;
+    /**
+     * Returns the error checks that fire at the cell, each with its evidence.
+     *
+     * @remarks
+     * The payload of the `anomalies` feature at this cell ({@link ICellRange.Feature}): a cell of a
+     * `getRegions('anomalies')` region reads its region's findings here. A check the cell ignores
+     * ({@link isErrorIgnored}) does not fire. Empty when nothing fires.
+     *
+     * Derived on first read and cached until the sheet changes; it costs nothing before that.
+     */
+    getAnomalies(): readonly ICell.Anomaly[];
+    /**
+     * Returns the cell's role: its job in the model, from what it reads and who reads it.
+     *
+     * @remarks
+     * The payload of the `role` feature at this cell ({@link ICellRange.Feature.Role}); see
+     * {@link ICell.Role} for the six roles. `null` for an empty cell, and for a formula before the
+     * calculation engine has loaded its parser.
+     *
+     * Derived on first read and cached until the sheet changes; it costs nothing before that.
+     */
+    getRole(): ICell.Role | null;
+    /**
+     * 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;
+    /**
+     * The cell's text as formatted runs, or `null` when the text has one font throughout.
+     *
+     * @remarks
+     * Each run's font is the whole font the run shows in: the cell's font with what the run sets
+     * over it. The value itself (`getValue()`) is a `RichText`, whose runs record only what they
+     * set. Set with {@link ICellRange.setRichText}.
+     */
+    getRichText(): IRichText.JSON | null;
     /**
      * Returns the comment on the cell, or `null` if there is none.
      *
      * @remarks
      * One per cell — the thread's root, with its replies, or a note. The sheet's
-     * {@link ISheet.getComments} is where one is added.
+     * {@link IWorksheet.getComments} is where one is added.
      */
     getComments(): IComment | null;
     /**
@@ -178,6 +223,11 @@ export interface ICell {
      * Returns the cell's value as a formatted string, applying any number formatting.
      */
     getText(options?: ICell.GetTextOptions): string;
+    /**
+     * @deprecated Use {@link getText}.
+     * @hidden
+     */
+    getFormattedValue(): string;
     /**
      * Returns the cell's value as a string with additional number format details.
      *
@@ -320,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.
      */
@@ -386,6 +444,11 @@ export interface ICell {
      * @param r1c1 If unspecified defaults to the environment's default format.
      */
     getAddress(r1c1?: boolean): string;
+    /**
+     * @deprecated Use {@link getAddress}.
+     * @hidden
+     */
+    getA1(): string;
     /**
      * Selects the current cell.
      * @returns An async boolean indicating the cell was selected.
@@ -394,7 +457,7 @@ export interface ICell {
     /**
      * Returns the Sheet.
      */
-    getSheet(): ISheet;
+    getWorksheet(): IWorksheet;
     /**
      * For runtime type checking.
      */
@@ -522,7 +585,7 @@ export declare namespace ICell {
         comments?: IComment.Update;
     }
     /**
-     * Options for {@link ICell.createCell} and {@link ISheet.createCell}.
+     * Options for {@link ICell.createCell} and {@link IWorksheet.createCell}.
      */
     interface CreateCellOptions {
         /**
@@ -669,36 +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;
-        v: number;
-    }
     /**
      * 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.
      *
@@ -759,5 +796,236 @@ export declare namespace ICell {
         readonly DataValidations: "dataValidations";
     };
     type Content = typeof Content[keyof typeof Content];
+    /**
+     * A cell's job in the model, read from two facts: what the cell reads and who reads it.
+     *
+     * @remarks
+     * A typed cell is a `label` when nothing reads it and an `input` when something does. A formula
+     * is a `link` when it is one cell of another sheet (negated or scaled at most, or a reference
+     * built with `INDIRECT`), a `reference` when it is one cell of this sheet (negated at most),
+     * else `computed` where something reads it and `output` where nothing does. "Who reads it" is
+     * the sheet's own formulas, so a cell only another sheet reads is a `label` or an `output`.
+     *
+     * A finance model's color convention (inputs blue, links green, calculations black) is a
+     * statement about this layer, which is what the `styleRole` check reads
+     * ({@link ICell.ErrorCheck}).
+     */
+    const Role: {
+        /** A typed value nothing on the sheet reads. */
+        readonly Label: "label";
+        /** A typed value a formula reads. */
+        readonly Input: "input";
+        /** One cell of another sheet. */
+        readonly Link: "link";
+        /** One cell of this sheet. */
+        readonly Reference: "reference";
+        /** An expression something reads. */
+        readonly Computed: "computed";
+        /** An expression nothing on the sheet reads. */
+        readonly Output: "output";
+    };
+    type Role = typeof Role[keyof typeof Role];
+    /**
+     * One of Excel's background error checks (**Formulas > Error Checking**), by the name the file
+     * stores it under, or one of SheetXL's own. A cell can be told to ignore a check
+     * ({@link ICellRange.setErrorIgnored}); Excel then draws no error indicator on it for that rule.
+     *
+     * @remarks
+     * The checks SheetXL runs fire through {@link ICell.getAnomalies} and the `anomalies` feature;
+     * an ignored check does not fire. Ignores follow their cells through inserts and deletes, are
+     * never copied, and leave a cell that is written or cleared, as in Excel.
+     */
+    const ErrorCheck: {
+        /** A formula that evaluates to an error value. */
+        readonly EvaluatesToError: "evalError";
+        /** A year written as two digits in text. */
+        readonly TextDate: "twoDigitTextYear";
+        /** A number stored as text. */
+        readonly NumberAsText: "numberStoredAsText";
+        /** A formula inconsistent with the formulas around it. */
+        readonly InconsistentFormula: "formula";
+        /** A formula that omits cells adjacent to the range it refers to. */
+        readonly OmittedCells: "formulaRange";
+        /** A formula in an unlocked cell. */
+        readonly UnlockedFormula: "unlockedFormula";
+        /** A formula that refers to empty cells. */
+        readonly EmptyCellReference: "emptyCellReference";
+        /** A value that fails the cell's list data validation. */
+        readonly ListDataValidation: "listDataValidation";
+        /** A formula inconsistent with its table's calculated column. */
+        readonly InconsistentListFormula: "calculatedColumn";
+        /**
+         * A typed value in a run of formulas: the cells on both sides of it, along a row or a column,
+         * are formulas. SheetXL's own; not written to an xlsx file's ignored errors.
+         */
+        readonly HardcodeInRun: "hardcodeInRun";
+        /**
+         * An authored format (font, fill, number format, alignment) that breaks the run around it:
+         * the cells on both sides carry one format, and this cell another. SheetXL's own; not
+         * written to an xlsx file's ignored errors.
+         */
+        readonly StyleBreak: "styleBreak";
+        /**
+         * A format part paired with the cell's role: a link to another sheet, a reference on this
+         * sheet or a calculation whose font color is other than most of its role on the sheet have,
+         * and is one the workbook writes some role in. SheetXL's own; not written to an xlsx file's
+         * ignored errors.
+         */
+        readonly StyleRole: "styleRole";
+        /** A cell or range counted twice in one sum. */
+        readonly RepeatedReference: "repeatedReference";
+        /** An aggregate over one cell, or over typed numbers only. */
+        readonly DegenerateCall: "degenerateCall";
+        /** A sum whose range holds a subtotal of its own cells, or a ratio. */
+        readonly SumIncludesSubtotal: "sumIncludesSubtotal";
+        /**
+         * A total, or the first line of a block, that sums its block and also adds a cell outside it:
+         * another block's line item, another block's total, or an absolute reference.
+         */
+        readonly MisalignedReference: "misalignedReference";
+        /** A lookup that matches the nearest key rather than the key. */
+        readonly ApproximateMatch: "approximateMatch";
+        /** A lookup whose result array and lookup vector do not line up. */
+        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];
+    /**
+     * One error check firing at a cell: the check, and the facts that make it fire.
+     *
+     * @remarks
+     * Evidence, never a verdict: what the cell breaks and where, so the reader can judge it. A
+     * pattern break is sometimes the right cell in a wrong run. There is no confidence.
+     *
+     * The evidence a cell's finding carries is the same for every cell of a filled run that breaks
+     * the same way, so a row of breaks is one region of the `anomalies` feature. Positions are
+     * therefore relative to the cell, in R1C1 (`R[-1]C` is the cell above).
+     *
+     * | check | evidence |
+     * | --- | --- |
+     * | `formula` | `axis` (`'row'` / `'column'`) the run lies along; `expected`, the R1C1 formula both neighbors share; `thickness`, the cells across the break (Excel flags only `1`); `flanks`, how far the run goes on each side; `corroborated` |
+     * | `formulaRange` | `reference`, the range the formula reads; `omitted`, the typed number just past its end |
+     * | `numberStoredAsText` | none — the cell's own text is the fact |
+     * | `emptyCellReference` | `reference`, the reference that reads an empty cell |
+     * | `unlockedFormula` | none |
+     * | `hardcodeInRun` | `axis`, `expected` (`'formula'`), `thickness`, `flanks`, `corroborated` |
+     * | `styleBreak` | `layer` (`'font'`, `'fill'`, `'numberFormat'`, `'alignment'`); `axis`; `expected`, the format both sides share; `actual`, this cell's; `thickness`, `flanks`, `corroborated` |
+     * | `styleRole` | `part` (`'fontColor'`); `role` (`'link'`, `'reference'`, `'computed'`, `'input'`); `expected`, the color most cells of that role on the sheet have; `actual`, this cell's; `majority`, how many cells of the role have `expected`; `of`, how many cells the role has on the sheet |
+     * | `repeatedReference` | `reference`, the reference counted again; `overlaps`, the one it falls inside when the two are not the same |
+     * | `degenerateCall` | `function`; `reference`, the one cell aggregated, or `literals`, the typed numbers |
+     * | `sumIncludesSubtotal` | `reference`, the range summed; `subtotal` or `ratio`, the cell inside it that is one |
+     * | `misalignedReference` | `term`, the reference outside the block; `block`, the rows (or columns) of the cell's own block that the formula sums; `landsAt`, the block the term lands in, when it lands in one; `targetRole`, what the term reads: `'lineItem'` (a line of another block), `'closingRow'` (another block's last line, a subtotal), `'outsideBlocks'` (no block) or `'absolute'` (a fixed reference, a rate or an assumption) |
+     * | `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
+     * other and not with it, and the run goes on at least two cells each side and at least as far as
+     * the region is thick (`flanks`), so a block as large as its surroundings is a section, not a
+     * break. A single cell between two that agree is kept too, with `flanks: 1`. A format compares
+     * as authored on the cell: none (`'normal'`), one equal to the Normal style's
+     * (`'authored-normal'`), or the authored properties as JSON.
+     *
+     * `corroborated` lists the other layers that change at both of the region's edges too: formula
+     * shape (`'formulaShape'`), formula or typed value (`'hasFormula'`), the value's kind (`'kind'`),
+     * and the format layers. A lone change, corroborated by nothing, is the stronger candidate; a
+     * row that differs on many layers (a total under its line items) is usually structure.
+     *
+     * **Blocks.** `misalignedReference` reads a formula against the block it closes or opens: the
+     * lines (rows, or columns for a row-wise total) holding content in the formula's own columns,
+     * between blank lines that span them. It fires on a sum that adds the block's own cells and
+     * also, with the same sign, a cell off the block's lines: `=SUM(K51:K53)+J46` in K54. A term on
+     * the block's lines in another column (a prior period) and a term taken away are not reported,
+     * nor is a sum of other blocks' totals that reads nothing of its own block. A running total that
+     * adds the previous block's total is reported as `closingRow`, ranked low.
+     *
+     * **Roles.** A cell's role ({@link ICell.Role}, the `role` feature) is its job, from what it
+     * reads and who reads it. `styleRole` pairs a format part with the role, for links, references, computed cells and inputs
+     * beside a label: the color most cells of a role have on the
+     * sheet is the role's, and a link, reference or computed cell in another color fires when that
+     * color is one the workbook writes some role in, on any sheet (a link left black where links
+     * are green and calculations black), never when it is decorative (white, red, a section's text
+     * color). A label never fires, and an input fires only beside a label: a typed number inside a
+     * data block reads like the data around it. Colors are the authored font color as `#RRGGBB`; a
+     * cell with none authored has the Normal style's. `majority` and `of` are evidence, not a
+     * gate: a convention held by 3 of 5 cells is reported as such.
+     *
+     * **Rank** says which finding to read first. It is not a confidence. For a run finding it is
+     * `weight × (1 / thickness) × (flanks / max(2, thickness)) × (1 − corroboration)`, where
+     * `weight` is the layer's and `corroboration` is the weight of the corroborating layers over the
+     * weight of every layer that could have corroborated. The layer weights are formula shape `1`,
+     * kind `0.6`, number format `0.5`, formula or typed value `0.4`, font `0.3`, fill `0.1`,
+     * alignment `0.05`. Every other check ranks at a fixed weight: `repeatedReference` and
+     * `lookupShape` `1`, `approximateMatch` and `externalReference` `0.9`, `formulaRange` and
+     * `degenerateCall` `0.8`, `emptyCellReference` and `sumIncludesSubtotal` `0.6`,
+     * `keyLabelMismatch` and `linkLabelMismatch` `0.4`, `unlockedFormula` and `signVsSiblings` `0.1`,
+     * `numberStoredAsText` `0.05`. A `styleRole` finding ranks at the role's weight (`link` `0.6`,
+     * `reference` `0.4`, `input` `0.3`, `computed` `0.2`) times `majority / of`. A
+     * `misalignedReference` finding ranks at `0.8` times its target's share: `lineItem` `1`,
+     * `outsideBlocks` `0.5`, `closingRow` and `absolute` `0.25`.
+     *
+     * A run or `styleRole` finding's rank is then divided by the number of times the same finding
+     * (the same check and evidence) occurs in the workbook: a finding repeated across a model is the
+     * author's style, and the one that occurs once is the exception to read first. So a finding's
+     * rank can change when another sheet changes. The weights are measured on the SpreadsheetBench
+     * 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.
+     */
+    interface Anomaly {
+        /** The check that fires. */
+        readonly check: ErrorCheck;
+        /** The facts it fires on. */
+        readonly evidence: Readonly<Record<string, string | number | readonly string[]>>;
+        /** Which finding to read first, highest first; see the remarks. */
+        readonly rank: number;
+    }
 }
 //# sourceMappingURL=ICell.d.ts.map

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

@@ -62,6 +62,11 @@ export interface ICellHeader {
      * @see `IOutline`
      */
     getOutlineLevel(): number;
+    /**
+     * Whether the column's width was last set by fitting it to its content. Setting the width any
+     * other way clears it, as in Excel. Always `false` for a row.
+     */
+    isBestFit(): boolean;
     /**
      * For runtime introspection.
      */
@@ -152,13 +157,9 @@ export declare namespace ICellHeader {
          */
         cl?: boolean;
         /**
-         * Style id
-         *
-         * @remarks
-         * * The style id is only available for export for backward compatible `ISheet.ToJSONOptions.includeHeaderStyles` is set.
-         * * This flag is ignored during loading.
+         * Best fit. The column's width was last set by fitting it to its content.
          */
-        s?: number;
+        bf?: boolean;
     }
 }
 //# sourceMappingURL=ICellHeader.d.ts.map

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

@@ -32,7 +32,7 @@ export interface ICellProtection {
      *
      * @remarks
      * * An exception, like {@link isAlwaysUnlocked}: a formula shows when the sheet
-     *   (`ISheetProtection.isShowFormulasAllowed`) or the cell allows it, so this only matters while
+     *   (`IWorksheetProtection.isShowFormulasAllowed`) or the cell allows it, so this only matters while
      *   the sheet hides them.
      * * A hidden formula reads as no formula ({@link ICell.getFormula} is `null`), but it still
      *   calculates and is still saved with the workbook. It is a view rule, not secrecy.

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