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

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

@@ -1,17 +1,17 @@
-import { Scalar, ScalarType, InteropScalarType, InteropScalar, IRange } from '@sheetxl/primitives';
+import { Scalar, ScalarType, InteropScalarType, InteropScalar, IRange, IRichData } from '@sheetxl/primitives';
 import { Size, Rectangle, Bounds } from '@sheetxl/utils';
 import { ITypes } from '../type';
-import { ITextFrame, TextRotation } 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 { IHyperlink } from '../hyperlink';
 import { IComment } from '../comment';
-import { IStyle } from '../style';
+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.
@@ -53,16 +53,21 @@ export interface ICell {
      * Returns the formula assigned to the cell.
      *
      * @remarks
-     * Returns `null` if the cell has no formula.
+     * Returns `null` if the cell has no formula, or if its protection hides the formula (see
+     * {@link ICell.isFormulaHidden}).
      */
     getFormula(options?: ICalculation.FormulaTextOptions): ICalculation.IFormula | null;
     /**
-     * Returns the formula text assigned to the cell, WITHOUT a leading `=`.
+     * Returns the formula text assigned to the cell, with its leading `=` (`'=SUM(A1:A3)'`).
      *
      * @remarks
-     * A convenience for `getFormula()?.getExpression()` — the stored shape, so `null` and `''` stay
-     * distinguishable from a formula and the text can be re-parsed as-is. Displaying it the way
-     * Excel's API answers means prefixing `'=' +`; see {@link ICalculation.IFormula.getExpression}.
+     * The form a formula is entered in and the form Excel's API answers, so it can be written back
+     * with {@link ICellRange.setValue}. The `=` is what keeps a formula like `=+A1` apart from the
+     * text `+A1`. For the stored form without the `=`, use
+     * {@link ICalculation.IFormula.getExpression} on {@link ICell.getFormula}.
+     *
+     * Returns `null` for a cell without a formula, and when protection hides the formula, like
+     * {@link ICell.getFormula}.
      */
     getFormulaText(options?: ICalculation.FormulaTextOptions): string | null;
     /**
@@ -77,35 +82,66 @@ export interface ICell {
      *
      * @remarks
      * These represent the direct inputs required to compute the cell's value.
-     * Returns `null` if the cell has no precedents.
+     * Resolves `null` if the cell has no precedents.
+     * A question for the calculation engine: it resolves once the engine has answered, in order
+     * behind the writes made before it, and with `null` while the engine is `Off`.
      */
-    getDirectPrecedents(): ICellRanges;
+    getDirectPrecedents(): Promise<ICellRanges | null>;
     /**
      * Returns the cells that directly reference this cell in their own formulas.
      *
      * @remarks
      * These represent the immediate consumers of this cell's value.
-     * Returns `null` if the cell has no dependents.
+     * Resolves `null` if the cell has no dependents.
      */
-    getDirectDependents(): ICellRanges;
+    getDirectDependents(): Promise<ICellRanges | null>;
     /**
      * Returns all ranges that contribute to this cell's value, including
      * those referenced indirectly through the full calculation chain.
      *
      * @remarks
      * This performs a recursive search upstream to find all root data sources.
-     * Returns `null` if the cell has no precedents.
+     * Resolves `null` if the cell has no precedents.
      */
-    getPrecedents(): ICellRanges;
+    getPrecedents(): Promise<ICellRanges | null>;
     /**
      * Returns all cells that are eventually affected by this cell, including
      * those that depend on it indirectly through the full calculation chain.
      *
      * @remarks
      * This performs a recursive search downstream to find the total impact of a value change.
-     * Returns `null` if the cell has no dependents.
+     * Resolves `null` if the cell has no dependents.
+     */
+    getDependents(): Promise<ICellRanges | null>;
+    /**
+     * 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.
      */
-    getDependents(): ICellRanges;
+    getRole(): ICell.Role | null;
     /**
      * Returns the hyperlink assigned to the cell.
      *
@@ -114,11 +150,22 @@ export interface ICell {
      */
     getHyperlink(): IHyperlink | null;
     /**
-     * Retrieves a list of comments associated with the cell.
+     * The cell's text as formatted runs, or `null` when the text has one font throughout.
      *
-     * **Note**: This feature is not yet implemented.
+     * @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}.
      */
-    getComments(): Readonly<IComment.Properties>;
+    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 IWorksheet.getComments} is where one is added.
+     */
+    getComments(): IComment | null;
     /**
      * Retrieves any warnings attached to the cell.
      *
@@ -156,7 +203,7 @@ export interface ICell {
      * Otherwise, returns the rendered style, which may include effects like
      * conditional or table formatting.
      */
-    getStyle(direct?: boolean): IStyle;
+    getStyle(direct?: boolean): ICellStyle;
     /**
      * Returns the cell's value as a JavaScript `Date` object if the cell contains a date.
      *
@@ -169,6 +216,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.
      *
@@ -215,7 +267,11 @@ export interface ICell {
      */
     getBestFit(colWidth?: number, minContent?: boolean): Readonly<Partial<Size>> | null;
     /**
-     * Returns protection information.
+     * Returns the cell's protection format, the same as `getStyle().getProtection()`.
+     *
+     * @remarks
+     * Whether the cell can be edited right now also depends on its sheet and its unlocked ranges; see
+     * {@link ICell.isEditAllowed}.
      */
     getProtection(): ICellProtection;
     /**
@@ -237,6 +293,15 @@ export interface ICell {
      * Returns the range of the cell if it is a spill cell.
      */
     getSpill(): ICellRange | null;
+    /**
+     * Returns which {@link ITypes.FormulaArrayKind | kind} of array block the cell belongs to, or
+     * `null` if it is not part of one.
+     *
+     * @remarks
+     * Answers for every cell of the block, not only the anchor — a `fixed` (array-entered) block
+     * shows `{=…}` on all of its cells, as Excel does.
+     */
+    getSpillKind(): ITypes.FormulaArrayKind | null;
     /**
      * Returns `true` if the cell is a spill and not the top left.
      */
@@ -270,10 +335,13 @@ export interface ICell {
      */
     getColumn(): ITable.IColumn | null;
     /**
-     * Returns the data validation assigned to the cell if there is one.
+     * Returns the cell's primary data validation: the highest-priority one that covers it, or `null`
+     * when none does.
      *
      * @remarks
-     * Will return null if there is no data validation assigned.
+     * Validations may overlap, and every one that covers the cell applies; see
+     * {@link ICellRange.getDataValidations} for all of them. The primary one is also the one Excel
+     * honors when it opens a file whose validations overlap.
      */
     getDataValidation(): IDataValidation | null;
     /**
@@ -322,7 +390,13 @@ export interface ICell {
      */
     isEditAllowed(): boolean;
     /**
-     * Returns `true` if the formula is hidden.
+     * Returns `true` if protection hides this cell's formula.
+     *
+     * @remarks
+     * The sheet is protected (not paused), and neither the sheet's `showFormulas` nor the cell style's
+     * allows it.
+     * A hidden formula reads as no formula: {@link ICell.getFormula} and {@link ICell.getFormulaText}
+     * return `null`. It still calculates, and is still saved with the workbook.
      */
     isFormulaHidden(): boolean;
     /**
@@ -338,10 +412,13 @@ export interface ICell {
     /**
      * Creates a temporary copy of the cell with the specified updates applied.
      *
+     * @param modifiers The update.
+     * @param options How the update is read. See {@link ICell.CreateCellOptions}.
+     *
      * @remarks
      * The original cell remains unchanged, making this useful for temporary modifications.
      */
-    createCell(modifiers: ICell.Update): ICell;
+    createCell(modifiers: ICell.Update, options?: ICell.CreateCellOptions): ICell;
     /**
      * Returns the `CellCoords`.
      */
@@ -352,6 +429,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.
@@ -360,7 +442,7 @@ export interface ICell {
     /**
      * Returns the Sheet.
      */
-    getSheet(): ISheet;
+    getWorksheet(): IWorksheet;
     /**
      * For runtime type checking.
      */
@@ -448,10 +530,17 @@ export declare namespace ICell {
         /**
          * Present when the cell's text is rotated (angle not a multiple of 180°): per-line rotated
          * strip geometry — each laid-out line is an independent strip drawn at
-         * {@link TextRotation.Layout.angle}, wrapped against the content height and marching
+         * {@link TextRotation.RotatedLayout.angle}, wrapped against the content height and marching
          * horizontally. See {@link TextRotation.layoutLines} for the model.
          */
-        rotation?: TextRotation.Layout;
+        rotation?: TextRotation.RotatedLayout;
+        /**
+         * Present when the cell's text is stacked ("vertical text"): per-column slot geometry — every
+         * glyph upright in its own slot of the line pitch, columns from line breaks (and from wrapping
+         * against the content height), each column aligned on its own. See
+         * {@link TextStacked.layoutColumns} for the model. {@link bounds} is then the column group.
+         */
+        stacked?: TextStacked.StackedLayout;
     }
     /**
      * Expansive way to set cell updates options.
@@ -470,11 +559,32 @@ export declare namespace ICell {
         /**
          * Update the style.
          */
-        style?: IStyle.Update;
+        style?: ICellStyle.Update;
         /**
          * Allow to to set a hyperlink to this value.
          */
         hyperlink?: IHyperlink.Update;
+        /**
+         * Update the comment: modifiers, a plain string as the content, or `null` to remove.
+         */
+        comments?: IComment.Update;
+    }
+    /**
+     * Options for {@link ICell.createCell} and {@link IWorksheet.createCell}.
+     */
+    interface CreateCellOptions {
+        /**
+         * Whether a text value is read as a typed entry is — `9/23/95` a date, `12.3%` a number —
+         * rather than taken as the text it is. `true` reads it with the defaults; an
+         * {@link ICell.ModifiersFromStringOptions} customizes the reading.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * The same reading {@link ICellRange.setValues} gives text, where it is the default. Here it
+         * is opt-in: a cell created from a value keeps that value.
+         */
+        textParser?: boolean | ICell.ModifiersFromStringOptions;
     }
     /**
      * Configuration options for customizing the parsing of a string into an `ICell.Update` object.
@@ -616,7 +726,11 @@ export declare namespace ICell {
      */
     interface JSONTypedValue {
         t: JSONScalarType;
-        v: number;
+        /**
+         * 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.
@@ -675,14 +789,224 @@ export declare namespace ICell {
         /**
          * Represents notes associated with the cells.
          * @remarks
-         * **NOT IMPLEMENTED**
+         * A note is a comment carrying `asNote` — the two share one store — so this selects the
+         * notes out of a range rather than naming a store of its own. Displaying a note as Excel's
+         * simple yellow box, rather than as a comment, is **NOT IMPLEMENTED**.
          */
         readonly Notes: "notes";
         /**
-         * Represents comments attached to the cells.
+         * Represents comments attached to the cells, notes included.
+         * @remarks
+         * Excel offers a single `Clear Comments and Notes`, and this is it. {@link Content.Notes}
+         * is the narrower one, for the notes alone.
          */
         readonly Comments: "comments";
+        /**
+         * Represents the data validations covering the cells.
+         * @remarks
+         * A clear cuts the cells out of every validation covering them; a validation left covering
+         * nothing is deleted, and one that also covers other cells keeps them. Office Scripts'
+         * `range.getDataValidation().clear()`.
+         */
+        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 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";
+    };
+    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'` |
+     * | `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 |
+     *
+     * **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.
+     *
+     * 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

@@ -56,6 +56,17 @@ export interface ICellHeader {
      * {@link https://support.microsoft.com/en-us/office/change-the-column-width-and-row-height-72f5e3cc-994d-43e8-ae58-9774a0905f46}
      */
     getSizeRelative(): number;
+    /**
+     * The outline level, `0` to `7`. `0` is not grouped; `1` is the outermost group.
+     *
+     * @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.
      */
@@ -104,6 +115,22 @@ export declare namespace ICellHeader {
          * {@link ICellHeader.getSizeRelative()}
          */
         relativeSize?: boolean;
+        /**
+         * The outline level, `0` to `7`, or a function of the current one.
+         *
+         * @remarks
+         * To group or ungroup, prefer `ICellRange.group` and `ICellRange.ungroup`.
+         *
+         * @see
+         * {@link ICellHeader.getOutlineLevel()}
+         */
+        outlineLevel?: number | ((level: number) => number);
+        /**
+         * Whether the group this header is the summary of is collapsed.
+         *
+         * @internal
+         */
+        collapsed?: boolean;
     }
     /**
      * Stores information about header runs.
@@ -122,21 +149,17 @@ export declare namespace ICellHeader {
          */
         h?: boolean;
         /**
-         * Header level
+         * Outline level, `1` to `7`. Absent when not grouped.
          */
         l?: number;
         /**
-         * Collapsed level
+         * Collapsed. Set on the summary header of a collapsed group.
          */
         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