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

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

@@ -1,11 +1,3 @@
-/**
- * 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';

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;
     /**
@@ -291,6 +298,11 @@ export interface ICell {
     isTopLeft(): boolean;
     /**
      * Returns the range of the cell if it is a spill cell.
+     *
+     * @remarks
+     * For a blocked spill (a {@link getSpillKind | kind} of `error`, the anchor shows `#SPILL!`) this
+     * is the range it would take. It holds none of those cells: their values are whatever is in the
+     * way. Spills can overlap, and one that is not blocked is returned ahead of one that is.
      */
     getSpill(): ICellRange | null;
     /**
@@ -363,6 +375,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 +737,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 +894,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 +940,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
@@ -976,26 +981,26 @@ export declare namespace ICell {
      * 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.
+     * **Rank** says which finding to read first. It is not a confidence, and it is relative to 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. 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.
+     *
+     * A sign divergence ranks low: signs differ between line items by design, so it is read when
+     * asked for by check.
+     *
+     * `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`). The rarer the
+     * constant, the higher it ranks. 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

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

@@ -0,0 +1,47 @@
+import { Scalar } from '@sheetxl/primitives';
+/**
+ * What a control type does to the cells it covers: which values it draws.
+ *
+ * @remarks
+ * The SDK half of a control type. How it looks and how it responds to the pointer and keys belong
+ * to the UI, which registers its own renderer under the same `type`.
+ */
+export interface ICellControlKind {
+    /**
+     * The type this kind is registered under, such as `'checkbox'`.
+     */
+    readonly type: string;
+    /**
+     * The kind's name where a UI lists the kinds that can be inserted, such as `'Rating'`. Plain
+     * text; the built-in checkbox takes its name from the command catalog instead.
+     */
+    readonly label?: string;
+    /**
+     * Whether the control draws a cell holding `value`. Any other value draws as text.
+     */
+    accepts(value: Scalar): boolean;
+}
+/**
+ * Excel's checkbox: draws a boolean or a blank cell, in place of its text.
+ */
+export declare const CheckboxKind: ICellControlKind;
+/**
+ * The control types a cell control can have, by type.
+ *
+ * @remarks
+ * The built-in types are registered before the registry is first used; a host registers its own
+ * the same way. A type nobody has registered still loads and saves, and accepts no value, so its
+ * cells draw as text.
+ */
+export declare namespace CellControlRegistry {
+    /**
+     * Registers a kind. A kind registered again under the same type replaces the earlier one,
+     * a built-in included.
+     */
+    function register(kind: ICellControlKind): void;
+    /** The kind registered for `type`, or `null`. */
+    function get(type: string): ICellControlKind | null;
+    /** The registered types. */
+    function getTypes(): string[];
+}
+//# sourceMappingURL=CellControlRegistry.d.ts.map

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

@@ -0,0 +1,99 @@
+import { Scalar } from '@sheetxl/primitives';
+import { IAnchored } from '../anchored';
+import { ICellRange } from '../cellRange';
+import { IListener } from '../listener';
+/**
+ * A control drawn in the cells of a range, such as a checkbox.
+ *
+ * @remarks
+ * A cell control decorates the cell's value; it never holds one. A checkbox draws `TRUE` as
+ * checked and `FALSE` or blank as unchecked, and a click writes the boolean into the cell, where
+ * formulas read it as any other value. Excel's model is the same: the checkbox is a cell
+ * *format*, and *Clear Formats* removes it while the value stays.
+ *
+ * * A cell has at most one control. One control covers any number of cells, and its ranges
+ *   shift, split, copy and fill with them.
+ * * A control draws only the values its type accepts ({@link isAccepted}). Any other value draws
+ *   as plain text: a checkbox over `2` or `"true"` draws `2` or `true`, as in Excel.
+ * * Most code never needs this interface: {@link ICellRange.setControl} and
+ *   {@link ICellRange.getControls} stand in for Office Scripts' `Range.setControl` /
+ *   `getControl`.
+ */
+export interface ICellControl extends IAnchored {
+    /**
+     * The control's type, such as `'checkbox'`.
+     *
+     * @remarks
+     * A type nobody has registered (`CellControlRegistry`) is kept and saved as it was read; it
+     * accepts no value, so its cells draw as text.
+     */
+    getType(): string;
+    /**
+     * Returns the first range the control covers.
+     *
+     * @remarks
+     * See {@link IAnchored.getRanges} for all of them. To change where a control is, use
+     * {@link ICellRange.setControl}.
+     */
+    getRange(): ICellRange;
+    /**
+     * Whether the control draws a cell holding `value`.
+     *
+     * @remarks
+     * A checkbox accepts a boolean or a blank cell. A value it does not accept draws as the cell
+     * would without the control.
+     */
+    isAccepted(value: Scalar): boolean;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: ICellControl.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * The control as JSON: its `type` and any properties of that type.
+     */
+    toJSON(): ICellControl.JSON;
+    /**
+     * For runtime type checking.
+     */
+    readonly isICellControl: true;
+}
+/**
+ * {@inheritDoc ICellControl}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICellControl}
+ *
+ * **Additional Interfaces**
+ * * {@link ICellControlCollection}
+ */
+export declare namespace ICellControl {
+    /**
+     * A control as JSON: its `type`, and any properties that type defines.
+     *
+     * @remarks
+     * Office Scripts' `CellControl`: `{ type: 'checkbox' }`. A checkbox has no other properties.
+     * Office Scripts' `EmptyCellControl` is `null` here.
+     */
+    interface JSON {
+        /**
+         * The control's type, such as `'checkbox'`.
+         */
+        type: string;
+        /**
+         * Properties of the type.
+         */
+        [property: string]: unknown;
+    }
+    /**
+     * IListener for {@link ICellControl} events.
+     */
+    interface Events extends IAnchored.Events<ICellControl> {
+    }
+    interface IListeners extends IListener.Callbacks<ICellControl, ICellControl.Events> {
+    }
+}
+//# sourceMappingURL=ICellControl.d.ts.map

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

@@ -0,0 +1,67 @@
+import { ICellRange, ICellRanges } from '../cellRange';
+import { ICollection } from '../type';
+import { ITransaction } from '../transaction';
+import { ICellControl } from './ICellControl';
+/**
+ * Holds a sheet's {@link ICellControl}s.
+ *
+ * @remarks
+ * Most code reaches controls through the range instead: {@link ICellRange.setControl} puts a
+ * control on cells and {@link ICellRange.getControls} reads it back. The collection is for listing
+ * every control, as a task pane does.
+ */
+export interface ICellControlCollection extends ICollection<ICellControl> {
+    /**
+     * Puts a control on the cells of `address`, replacing their controls, and returns it.
+     *
+     * @param address The address of the cells. May name several discontiguous ranges.
+     * @param control The control, such as `{ type: 'checkbox' }`.
+     *
+     * @remarks
+     * The same write as {@link ICellRange.setControl}, over any address. A cell has at most one
+     * control, so the cells leave whatever control they had, and join a control of the same
+     * definition when the sheet already has one.
+     */
+    add(address: ICellRanges.Address, control: ICellControl.JSON, options?: ITransaction.OperationOptions): ICellControl;
+    /**
+     * Returns items that match the filter criteria.
+     *
+     * If no filter criteria is provided, all items will be returned.
+     *
+     * @param options {@link ICellControlCollection.GetItemsOptions}
+     */
+    getItems(options?: ICellControlCollection.GetItemsOptions): ICellControl[];
+    /** For runtime type checking. */
+    readonly isICellControlCollection: true;
+}
+/**
+ * {@inheritDoc ICellControlCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICellControlCollection}
+ */
+export declare namespace ICellControlCollection {
+    /**
+     * Options for searching for {@link ICellControl}s.
+     */
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * If provided, the search will be limited to items that intersect the range.
+         */
+        address?: ICellRange.Address;
+        /**
+         * Indicate if items that are in hidden headers or marked as hidden should be returned.
+         *
+         * @defaultValue false
+         */
+        ignoreHidden?: boolean;
+        /**
+         * Only return items that are completely contained with the search bounds.
+         *
+         * @defaultValue false
+         */
+        fullyContained?: boolean;
+    }
+}
+//# sourceMappingURL=ICellControlCollection.d.ts.map

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

@@ -0,0 +1,4 @@
+export * from './ICellControl';
+export * from './ICellControlCollection';
+export * from './CellControlRegistry';
+//# sourceMappingURL=index.d.ts.map