@sheetxl/sdk 0.7.28-beta.2 → 0.7.28-beta.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/sdk",
   "description": "SDK - A high-performance, embeddable spreadsheet engine.",
-  "version": "0.7.28-beta.2",
+  "version": "0.7.28-beta.4",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -43,11 +43,11 @@
     "automation"
   ],
   "dependencies": {
-    "@sheetxl/formulas": "^0.7.28-beta.2",
-    "@sheetxl/formulas-extended": "^0.7.28-beta.2",
-    "@sheetxl/primitives": "^0.7.28-beta.2",
-    "@sheetxl/scripting": "^0.7.28-beta.2",
-    "@sheetxl/utils": "^0.7.28-beta.2",
+    "@sheetxl/formulas": "^0.7.28-beta.4",
+    "@sheetxl/formulas-extended": "^0.7.28-beta.4",
+    "@sheetxl/primitives": "^0.7.28-beta.4",
+    "@sheetxl/scripting": "^0.7.28-beta.4",
+    "@sheetxl/utils": "^0.7.28-beta.4",
     "bahttext": "^2.4.0",
     "bessel": "^1.0.2",
     "chalk": "^6.0.0",

package/resources/locales/de/model.msg.json

@@ -95,6 +95,17 @@
   "error.address.textToColumnsOverwrite": "Der Zielbereich enthält Daten.",
   "error.anchor.protected": "{description} nicht möglich. Das Element ist geschützt.",
   "error.hyperlink.invalidHyperlink": "Ungültiger Link.",
+  "error.io.encryptionUnavailable": "Kennwortschutz ist nicht verfügbar, daher kann diese Arbeitsmappe nicht mit einem Kennwort gespeichert werden.",
+  "error.io.passwordIncorrect": "Das Kennwort ist falsch.",
+  "error.io.passwordRequired": "''{name}'' ist kennwortgeschützt. Zum Öffnen ist ein Kennwort erforderlich.",
+  "error.io.passwordRequiredSave": "''{name}'' ist kennwortgeschützt. Geben Sie das Kennwort an, um die Datei zu speichern, oder speichern Sie sie ohne Schutz.",
+  "error.io.passwordRequiredSaveUnnamed": "Diese Datei ist kennwortgeschützt. Geben Sie das Kennwort an, um die Datei zu speichern, oder speichern Sie sie ohne Schutz.",
+  "error.io.passwordRequiredUnnamed": "Diese Datei ist kennwortgeschützt. Zum Öffnen ist ein Kennwort erforderlich.",
+  "error.io.readFailed": "{format} kann nicht gelesen werden — {reason}",
+  "error.io.readFormatUnavailable": "''{format}'' kann nicht geöffnet werden — dieser Dateityp wird nicht unterstützt.",
+  "error.io.writeFailed": "Die Arbeitsmappe kann nicht gespeichert werden — {reason}",
+  "error.io.writeFormatUnavailable": "Speichern als ''{format}'' ist nicht möglich — dieser Dateityp wird nicht unterstützt.",
+  "error.io.writeFormatUnresolved": "Der Dateityp zum Speichern konnte nicht ermittelt werden. Wählen Sie einen Dateityp oder verwenden Sie einen Dateinamen mit bekannter Erweiterung.",
   "error.model.modelClosed": "Das Modell wurde geschlossen. Weitere Vorgänge sind nicht zulässig.",
   "error.model.nameRequired": "Name ist erforderlich",
   "error.named.containsSpaces": "Der Name darf keine Leerzeichen enthalten.",
@@ -506,5 +517,6 @@
   "table.defaultName": "Tabelle{n}",
   "table.emptyColumnName": "Spalte",
   "table.totalsRowLabel": "Ergebnis",
+  "workbook.defaultName": "Arbeitsmappe",
   "workbook.defaultSheetName": "Tabelle{n}"
 }

package/resources/locales/en/model.msg.json

@@ -96,6 +96,17 @@
   "error.anchor.protected": "Unable to {description}. The item is protected.",
   "error.function.builtInName": "''{name}'' is a built-in function. Choose a different name.",
   "error.hyperlink.invalidHyperlink": "Invalid hyperlink",
+  "error.io.encryptionUnavailable": "Password protection is not available, so this workbook cannot be saved with a password.",
+  "error.io.passwordIncorrect": "The password is incorrect.",
+  "error.io.passwordRequired": "''{name}'' is password protected. A password is required to open it.",
+  "error.io.passwordRequiredSave": "''{name}'' is password protected. Supply the password to save it, or save it without protection.",
+  "error.io.passwordRequiredSaveUnnamed": "This file is password protected. Supply the password to save it, or save it without protection.",
+  "error.io.passwordRequiredUnnamed": "This file is password protected. A password is required to open it.",
+  "error.io.readFailed": "Unable to read {format} — {reason}",
+  "error.io.readFormatUnavailable": "Unable to open ''{format}'' — that file type is not supported.",
+  "error.io.writeFailed": "Unable to save the workbook — {reason}",
+  "error.io.writeFormatUnavailable": "Unable to save as ''{format}'' — that file type is not supported.",
+  "error.io.writeFormatUnresolved": "Unable to determine the file type to save as. Choose a file type, or use a file name with a known extension.",
   "error.model.modelClosed": "Model has been closed. No further operations are allowed.",
   "error.model.nameRequired": "Name is required",
   "error.named.containsSpaces": "Name must not contain any spaces.",
@@ -521,5 +532,6 @@
   "table.defaultName": "Table{n}",
   "table.emptyColumnName": "Column",
   "table.totalsRowLabel": "Total",
+  "workbook.defaultName": "Workbook",
   "workbook.defaultSheetName": "Sheet{n}"
 }

package/types/scripting-enums.json

@@ -183,6 +183,7 @@
       "AutoTable": "autoTable",
       "Border": "border",
       "CalcError": "calcError",
+      "Circular": "circular",
       "Comments": "comments",
       "Conditionals": "conditionals",
       "Contentful": "contentful",
@@ -841,6 +842,7 @@
       "ArrowsGray5": "5ArrowsGray",
       "Boxes5": "5Boxes",
       "Flags3": "3Flags",
+      "NoIcons": "NoIcons",
       "Quarters5": "5Quarters",
       "Rating4": "4Rating",
       "Rating5": "5Rating",

package/types/scripting.d.ts

@@ -1707,6 +1707,32 @@ declare global {
             readonly TwoCell: "twoCell";
         };
         type Type = typeof Type[keyof typeof Type];
+        /**
+         * Options shared by the collections that add anchored items — conditional formats, data
+         * validations, protected ranges.
+         */
+        interface AddOptions extends ITransaction.OperationOptions {
+            /**
+             * Position in the collection. `0` is first — for a conditional format, the highest priority.
+             *
+             * @defaultValue 0 — a new item goes first, as in Excel.
+             */
+            index?: number;
+            /**
+             * Redefine the item already at `index` instead of inserting, when it is anchored to exactly
+             * the same ranges (discontiguous ranges compare area by area, in authored order).
+             *
+             * @defaultValue false
+             *
+             * @remarks
+             * Only the item at `index` is considered, as in Excel. What counts as the same item is per
+             * collection: a data validation or protected range matches on ranges alone; a conditional
+             * format only redefines a scale rule (data bar, color scale, icon set) of the same kind —
+             * a style rule always inserts, since several may apply to one cell, whereas a second scale
+             * of one kind on the same ranges could never render.
+             */
+            replaceExisting?: boolean;
+        }
     }
 
     /**
@@ -2192,6 +2218,63 @@ declare global {
          * This is similar convenience method for `getCalculation().createFormula(expression).evaluate(options)`.
          */
         evaluate(expression: string, options?: number | ICalculation.EvaluateOptions & Partial<IRange.CellCoords>): Promise<Scalar | IRange>;
+        /**
+         * When the engine recalculates on its own — Excel's Calculation Options.
+         *
+         * @remarks
+         * In {@link ICalculation.CalculationMode.Automatic} every commit that dirties a formula
+         * schedules a pass. In {@link ICalculation.CalculationMode.Manual} an edit only marks its
+         * dependents out of date ({@link isCalculationRequired}) and nothing is recalculated — volatile
+         * functions (`NOW`, `RAND`) stop re-rolling too — until {@link calculate}: Excel's F9 (every
+         * sheet), Shift+F9 (`scope`) and Ctrl+Alt+F9 (`full`). {@link ready} resolves at once in manual
+         * mode; a caller that wants current values calls {@link calculate}.
+         *
+         * @defaultValue {@link ICalculation.CalculationMode.Automatic}
+         */
+        getCalculationMode(): ICalculation.CalculationMode;
+        /**
+         * Sets the calculation mode.
+         *
+         * @remarks
+         * Leaving manual mode recalculates whatever is out of date, as Excel does.
+         * {@link ICalculation.CalculationMode.AutomaticExceptTables} is accepted for parity with the
+         * file format and Office Scripts; this engine has no what-if data tables, so it recalculates
+         * exactly as `Automatic` does.
+         */
+        setCalculationMode(mode: ICalculation.CalculationMode): this;
+        /**
+         * Whether any formula is out of date — Excel's `Calculate` indicator in the status bar.
+         *
+         * @remarks
+         * Meaningful in manual mode, where edits accumulate until {@link calculate}. In automatic
+         * mode it is `true` only between an edit and the pass it schedules.
+         */
+        isCalculationRequired(): boolean;
+        /**
+         * How a reference cycle is resolved — Excel's "Enable iterative calculation" and its limits.
+         *
+         * @see {@link ICalculation.IterativeCalculation}
+         */
+        getIterativeCalculation(): ICalculation.IterativeCalculation;
+        /**
+         * Enables, disables or configures iterative calculation.
+         *
+         * @param options `true`/`false` toggles `enabled` alone; an object updates the fields given and
+         * keeps the rest.
+         *
+         * @remarks
+         * Every cell in a cycle is recalculated when this changes: turning iteration on resolves the
+         * cycles the workbook shows as unresolved, turning it off writes `0` to them again.
+         */
+        setIterativeCalculation(options: boolean | Partial<ICalculation.IterativeCalculation>): this;
+        /**
+         * The calculation settings as JSON — what an xlsx carries in `calcPr`.
+         *
+         * @remarks
+         * Sparse: a setting at its default is omitted. Settings a file carried that this engine does
+         * not act on (`calcOnSave`, `fullCalcOnLoad`, `fullPrecision`, …) are kept and written back.
+         */
+        toJSON(): ICalculation.JSON;
         /**
          * Add Listeners.
          *
@@ -2221,6 +2304,87 @@ declare global {
          * tokenizer, the AST, a formula input — is ever handed an expression of unbounded size.
          */
         const MAX_EXPRESSION_LENGTH = 8192;
+        /**
+         * A reference cycle — the answer to "why is this cell `0`".
+         *
+         * @remarks
+         * A cell is in a cycle when calculating it opens its own value, directly or through other cells
+         * — `=A1+1` in A1, `=OFFSET(A1,0,0)` in A1, `=SUMIF(B1,C1,A1)` in A1 while B1 matches C1. With
+         * iterative calculation off (the default, and Excel's) every cell in a cycle, and every cell
+         * downstream of one, evaluates to `0`; nothing on the value says why. This does.
+         *
+         * Reached from a cell — {@link ICell.getCircularReference} answers it for members and for
+         * downstream cells alike — and carried by the `ICellRange.Feature.Circular` regions, so a
+         * range, a sheet or the workbook is asked the way any other error is asked:
+         * `getCounts(Feature.Circular)` for how many, `getRegions(Feature.Circular)` for which, with
+         * this object as each region's payload. There is no list of cycles on the calculation: nobody
+         * starts from the cycle; they start from a cell or a range and want to know more.
+         *
+         * Live, not a snapshot: it reads the engine's cycle table on every call and drops members whose
+         * formula has since been edited away, so a stale handle answers `getMemberCount() === 0`.
+         * Persists until the last member is edited away.
+         */
+        interface ICircularReference {
+            /**
+             * The cell named for the cycle, the way Excel's status bar names one
+             * (`Worksheet.CircularReference` likewise answers a single cell): the first member in
+             * row-major order. `scope` is the sheet name, or `null` when the member lives in a named
+             * formula's body rather than on a sheet.
+             */
+            getRepresentative(): IRange.CellCoords | null;
+            /**
+             * Every cell IN the cycle, in row-major order, `scope` set to the sheet name. Small — a cycle
+             * is the cells that read each other, not everything that reads them (that is
+             * {@link getDownstreamCount}).
+             */
+            getMembers(): readonly IRange.CellCoords[];
+            /** How many cells are IN the cycle, the representative included. */
+            getMemberCount(): number;
+            /** How many cells read the cycle (transitively) and evaluate to `0` because of it. */
+            getDownstreamCount(): number;
+            /**
+             * Whether `coords` is IN the cycle, as opposed to downstream of it. A cell that reads a
+             * member's `0` answers `false` here but still resolves this cycle from
+             * {@link ICell.getCircularReference} — the tooltip for it says "reads a circular reference
+             * at A1", not "is one".
+             */
+            isMember(coords: IRange.CellCoords): boolean;
+            /**
+             * The cycle as a walk of reads from `from` back to itself — each cell reads the next, and
+             * the last reads the first. A cycle has no start, so it is told from the cell that asks:
+             * with `A1 = B1+1` and `B1 = A1+1`, asked from A1 it is `[A1, B1]` (A1 → B1 → A1), asked
+             * from B1 it is `[B1, A1]`. A cycle of one is `[A1]`.
+             *
+             * @remarks
+             * Exact, not inferred from formula text: it is the order the engine found the cycle in,
+             * which is the order the reads happened — a dynamic read (`INDIRECT`, `OFFSET`) is a step
+             * like any other. Interlocking cycles share members; the walk follows the read that closed
+             * the cycle `from` was found in, so it is ONE loop through that cell, not every member
+             * ({@link getMembers} is every member).
+             *
+             * Empty when `from` is not a live member — a downstream cell asks from
+             * {@link getRepresentative}.
+             */
+            getPath(from: IRange.CellCoords): readonly IRange.CellCoords[];
+            /**
+             * Whether iterative calculation was on when the cycle was last evaluated. When `false` the
+             * cycle is unresolved and every member and downstream cell is `0`; the iteration answers
+             * below are then meaningless (`0` sweeps, no change).
+             */
+            isIterative(): boolean;
+            /**
+             * Whether iterative calculation settled it: every member moved by less than the workbook's
+             * `maxIterateChange` in the last sweep. Always `false` with iteration off.
+             */
+            isConverged(): boolean;
+            /** How many sweeps the last evaluation ran — up to the workbook's `maxIterations`. */
+            getIterationCount(): number;
+            /**
+             * The largest change any member made in the last sweep — what stopped the iteration when
+             * {@link isConverged}, what it never got under when not. `0` with iteration off.
+             */
+            getLastChange(): number;
+        }
         /**
          * Represents a formula that can be evaluated.
          */
@@ -2688,6 +2852,11 @@ declare global {
              * two diverge exactly where normalization is lossy — a number (`3.0` → `3`, `1**2` → `100`) or a
              * cell (raw `b2` vs the resolved coords). `undefined` only for a token with no captured source
              * image (e.g. a reference the engine rewrote programmatically rather than one the user typed).
+             *
+             * A reference literal is ONE span: a typed sheet qualifier and a trailing spill anchor ride inside
+             * the `cell`/`named` token's `text` (`Sheet2!A1#`), so the caret rules an editor applies per token
+             * treat the whole reference as one. The anchor keeps its own `postfix` token (carrying the same
+             * {@link referenceIndex}) imaging the empty string, so the concatenation above still holds.
              */
             text?: string;
             /**
@@ -2894,8 +3063,16 @@ declare global {
             /**
              * Called when the calculation has been updated and
              * a calculation has not been started.
+             *
+             * @remarks
+             * In manual mode this is every edit that leaves a formula out of date — see
+             * {@link ICalculation.isCalculationRequired}.
              */
             onStale?(source: ICalculation): void;
+            /**
+             * Called when the calculation mode or the iterative-calculation settings change.
+             */
+            onOptionsChange?(source: ICalculation): void;
             /**
              * Called when a calculation is starting.
              */
@@ -2979,6 +3156,38 @@ declare global {
             readonly AutomaticExceptTables: "automaticExceptTables";
         };
         type CalculationMode = typeof CalculationMode[keyof typeof CalculationMode];
+        /**
+         * Iterative calculation — Excel's "Enable iterative calculation" with its two limits.
+         *
+         * @remarks
+         * With it off a reference cycle evaluates to `0` and is reported as unresolved. With it on the
+         * cells of the cycle are re-evaluated in turn, each read seeing the latest value, until no cell
+         * moved by {@link maxChange} or {@link maxIterations} sweeps ran — and the results persist into
+         * the next recalculation, which re-runs every cycle the way it re-runs `NOW()`: `=A1+1` in A1 is
+         * a counter that advances by `maxIterations` per recalc. A cycle that stops on the sweep cap is
+         * still reported ({@link ICircularReference.isConverged}); a converged one is not.
+         *
+         * Office Scripts calls the count `maxIteration`; the file format `iterateCount` / `iterateDelta`.
+         */
+        interface IterativeCalculation {
+            /**
+             * @defaultValue `false`
+             */
+            enabled: boolean;
+            /**
+             * The most sweeps one recalculation runs over a cycle.
+             *
+             * @defaultValue `100`
+             */
+            maxIterations: number;
+            /**
+             * Sweeps stop early once every cell in the cycle moved by less than this. A non-numeric
+             * change (text, error) never counts as settled.
+             *
+             * @defaultValue `0.001`
+             */
+            maxChange: number;
+        }
         /**
          * Represents the status of a calculation result
          */
@@ -3241,12 +3450,28 @@ declare global {
          *
          * @remarks
          * Warnings differ from errors in that they may alter the display of the cell's value or type.
+         * A cell in a reference cycle, or downstream of one, carries one here — the text form of
+         * {@link getCircularReference}: the walk from this cell around the cycle and back
+         * ("Circular reference: A1 → B1 → A1"), or "Reads a circular reference at A1".
          */
         getWarnings(): readonly string[];
         /**
          * Retrieves any errors attached to the cell.
          */
         getErrors(): readonly string[];
+        /**
+         * The reference cycle this cell is in, or downstream of — or `null` when it is neither.
+         *
+         * @remarks
+         * Evaluated state, beside the value: a cell in a cycle, and every cell that reads one, is `0`
+         * (Excel, iterative calculation off), and this is the only thing that says why. Ask the cycle
+         * whether this cell is a member or a reader ({@link ICalculation.ICircularReference.isMember})
+         * and, under iterative calculation, whether it converged.
+         *
+         * The range-level view is `ICellRange.Feature.Circular` — `getCounts` for how many cells,
+         * `getRegions` for which, each region carrying this same object as its payload.
+         */
+        getCircularReference(): ICalculation.ICircularReference | null;
         /**
          * Returns the style information applied to the cell.
          *
@@ -4689,11 +4914,24 @@ declare global {
          * Returns a range that includes the current range up to a content edge boundary.
          *
          * @param direction The direction.
-         * @param cell The cell to use as a starting point.
-         *               If not provide the cell closest to the edge will be used.
+         * @param cell Either the cell to walk from — as {@link ICellRange.GetExtendedOptions.cell}, and
+         *               the positional form Office Scripts' `getExtendedRange` takes — or the full
+         *               {@link ICellRange.GetExtendedOptions}. If neither is given the cell closest to
+         *               the edge is used.
          * @returns `ICellRange` extended in the given direction.
+         *
+         * @remarks
+         * The result **includes** the current range, and a boundary with nowhere to go returns the range
+         * unchanged — so comparing the two is how you tell there was nothing to extend onto.
+         *
+         * {@link ICellRange.GetExtendedOptions.basis} picks what the boundary is read from: the range's
+         * own content (Ctrl+Arrow, the default) or the lines flanking it (a double-clicked fill handle).
+         *
+         * Both bases read the content, merge and table indexes rather than walking cells, so the cost is
+         * the blocks involved and not the distance traveled — extending across a million rows costs what
+         * extending across ten does.
          */
-        getExtended(direction: IRange.Direction, cell?: ICell.Address): this;
+        getExtended(direction: IRange.Direction, cell?: ICell.Address | ICellRange.GetExtendedOptions): this;
         /**
          * Returns a range with coordinates adjusted to be fixed (absolute) or flexible (relative).
          *
@@ -5809,6 +6047,50 @@ declare global {
              */
             colEnd?: boolean;
         }
+        /**
+         * Options for {@link ICellRange.getExtended}.
+         */
+        interface GetExtendedOptions {
+            /**
+             * The cell to walk from. Only `'content'` extends from a cell — the flanking lines a
+             * `'adjacent'` extension reads are fixed by the range's own edges — so this is ignored there.
+             *
+             * @defaultValue the cell of the range closest to the edge being extended toward.
+             */
+            cell?: ICell.Address;
+            /**
+             * What the content edge is read from.
+             *
+             * - `'content'` — the range's own content, walked from {@link cell}. This is Ctrl+Arrow: it
+             *   runs to the end of the block it is in, or from a blank onto the next block.
+             * - `'adjacent'` — the two lines flanking the range on the cross axis (for a downward
+             *   extension, the column left of the left edge and the column right of the right edge). Each
+             *   contributes its contiguous run measured from the line the extension would start on, and
+             *   the **further** of the two wins; a flank that starts blank contributes nothing, which is
+             *   why a spacer column stops the extension dead. The reach is then cut short **before** the
+             *   nearest populated line inside the range's own columns, so an existing block is not run
+             *   over. This is the destination Excel picks when the fill handle is double-clicked, and it
+             *   feeds {@link ICellRange.autoFill} directly.
+             *
+             * @defaultValue 'content'
+             */
+            basis?: 'content' | 'adjacent';
+            /**
+             * Where a walk that begins on a **blank** cell comes to rest.
+             *
+             * - `'enter'` — on the first cell of the block it runs into. This is Ctrl+Arrow.
+             * - `'before'` — on the last blank, one short of that block. This is what a double-clicked
+             *   selection border does.
+             *
+             * Blanks are the *only* thing this changes: from a populated cell both run to the end of that
+             * cell's own block and stop in the same place. It is also independent of {@link basis} — that
+             * says where the boundary is read from, this says what happens on the way — though `'adjacent'`
+             * has nothing to apply it to, since a blank flank contributes no reach in the first place.
+             *
+             * @defaultValue 'enter'
+             */
+            fromBlank?: 'enter' | 'before';
+        }
         /**
          * Options for {@link ICellRange.getSurrounding}.
          */
@@ -6552,11 +6834,20 @@ declare global {
             /** Cells inside a dynamic-array spill zone. Writing into one is a real failure mode. */
             readonly Spills: "spills";
             /**
-             * Evaluated state: cells whose calculation itself failed — mostly circular references.
-             * Distinct from {@link Feature.Error}: `#DIV/0!` is a successfully calculated error VALUE
-             * (the `Error` kind); `CalcError` is the engine failing to evaluate at all.
+             * Evaluated state: cells whose calculation itself failed. Distinct from
+             * {@link Feature.Error}: `#DIV/0!` is a successfully calculated error VALUE (the `Error`
+             * kind); `CalcError` is the engine failing to evaluate at all. A reference cycle is not a
+             * failure — its cells evaluate, to `0` — and is {@link Feature.Circular}.
              */
             readonly CalcError: "calcError";
+            /**
+             * Evaluated state: cells in a reference cycle, or downstream of one. Both evaluate to `0`
+             * (Excel, iterative calculation off) with nothing else to show for it — this is the marker.
+             * Regions group by cycle and by kind (`member` | `downstream`), so a block that reads one bad
+             * cell is ONE region, and each region's payload is the cycle itself
+             * (`ICalculation.ICircularReference` — members, counts, whether iteration settled it).
+             */
+            readonly Circular: "circular";
             /** Direct fill. */
             readonly Fill: "fill";
             /** Direct borders. */
@@ -9846,8 +10137,11 @@ declare global {
          * Only the keys named are touched. An explicit `null` **clears** a key — required when switching
          * a rule between its two shapes, since `condition`+`style` and `scale` are mutually exclusive
          * (setting one side also clears the other unless the caller named both).
+         *
+         * Passing another rule takes its whole definition — every key, cleared where the other rule
+         * has none — so the shape switches with it. The anchor is not part of it.
          */
-        update(properties: IConditionalFormat.Modifiers, options?: ITransaction.OperationOptions): this;
+        update(properties: IConditionalFormat.Modifiers | IConditionalFormat, options?: ITransaction.OperationOptions): this;
         /**
          * Returns a snapshot of the conditional that can be used for copying and archiving.
          */
@@ -10277,8 +10571,12 @@ declare global {
     export namespace IConditionalFormatCollection {
         /**
          * Options for adding a {@link IConditionalFormat}.
+         *
+         * @remarks
+         * `replaceExisting` redefines the rule at `index` only when it is a scale rule of the same
+         * kind on exactly the same ranges — see {@link IAnchored.AddOptions.replaceExisting}.
          */
-        interface AddOptions extends IConditionalFormat.Properties, ITransaction.OperationOptions {
+        interface AddOptions extends IConditionalFormat.Properties, IAnchored.AddOptions {
         }
         /**
          * Options for searching for {@link IConditionalFormat}s.
@@ -10662,8 +10960,12 @@ declare global {
     export namespace IDataValidationCollection {
         /**
          * Options for adding a data validation to the collection.
+         *
+         * @remarks
+         * `replaceExisting` redefines the validation at `index` when it covers exactly the same ranges —
+         * see {@link IAnchored.AddOptions.replaceExisting}.
          */
-        interface AddOptions extends IDataValidation.Properties, ITransaction.OperationOptions {
+        interface AddOptions extends IDataValidation.Properties, IAnchored.AddOptions {
         }
         interface GetItemsOptions {
             /**
@@ -12313,12 +12615,19 @@ declare global {
          */
         getFormulaAt(row: number, column: number, sheetName?: string): string | null;
         /**
-         * Returns the spill range anchored at a cell.
+         * Returns the range the formula anchored at a cell OCCUPIES — what the spill anchor operator
+         * (`A1#`) resolves to.
          *
-         * @param row The row where the spill starts.
-         * @param column The column where the spill starts.
+         * @param row The row the formula is anchored at.
+         * @param column The column the formula is anchored at.
          * @param sheetName The name of the sheet. If not provided the current sheet is used.
-         * @returns The spilled range, or `null` if nothing spills from that cell.
+         * @returns The range, or `null` if no formula is anchored there.
+         *
+         * @remarks
+         * The range is the formula's spill when it produced an array, the whole block for a legacy
+         * array formula, and the cell ITSELF for an ordinary formula — every formula occupies at least
+         * the cell it sits in. `null` means no formula is anchored at that cell: it holds a constant, it
+         * is empty, or it merely lies INSIDE another cell's spill or array block.
          */
         getSpillAt(row: number, column: number, sheetName?: string): IReferenceRange | null;
         /**
@@ -13952,7 +14261,9 @@ declare global {
          * @remarks
          * This has no counterpart in Excel; it is ours and applies to links opened in a browser.
          *
-         * @defaultValue `_self` for a location within this workbook, otherwise `_blank`.
+         * @defaultValue `_self` for a location within this workbook or a `mailto:`/`tel:`/`sms:`
+         * address (handled by another application, so there is nothing to show in a new tab),
+         * otherwise `_blank`.
          */
         getTarget(): string;
         /**
@@ -16294,8 +16605,13 @@ declare global {
     export namespace IProtectedRangeCollection {
         /**
          * Options for adding an {@link IProtectedRange}.
+         *
+         * @remarks
+         * `replaceExisting` redefines the entry at `index` when it covers exactly the same ranges; the
+         * entry keeps its name unless a free one is supplied — see
+         * {@link IAnchored.AddOptions.replaceExisting}.
          */
-        interface AddOptions extends IProtectedRange.Properties, ITransaction.OperationOptions {
+        interface AddOptions extends IProtectedRange.Properties, IAnchored.AddOptions {
         }
         /**
          * Options for searching for {@link IProtectedRange}s.
@@ -22025,6 +22341,11 @@ declare global {
             readonly Quarters5: "5Quarters";
             readonly Rating5: "5Rating";
             readonly Boxes5: "5Boxes";
+            /**
+             * Not a set to apply — the x14 name Excel writes for a band whose custom icon is
+             * "No Cell Icon" (`iconSet="NoIcons" iconId="0"`). It holds zero icons.
+             */
+            readonly NoIcons: "NoIcons";
         };
         type IconSet = typeof IconSet[keyof typeof IconSet];
     }
@@ -27830,6 +28151,11 @@ declare global {
         getCpuCount(): number;
         getMemory(): number;
         isEval(): boolean;
+        /**
+         * `true` when the licensed product may run `feature` without the license watermark: a valid
+         * license with no exceptions, or an evaluation on localhost / in a dev build. An evaluation on
+         * any other host answers `false` so the watermark shows.
+         */
         isValidFor: (feature: string) => boolean;
         getDeveloperCount(): number;
         getType(): string;

package/types/src/anchored/IAnchored.d.ts

@@ -1,6 +1,7 @@
 import { IRange } from '@sheetxl/primitives';
 import { IListener } from '../listener';
 import { ICellRange, ICellRanges } from '../cellRange';
+import { ITransaction } from '../transaction';
 /**
  * `IAnchored` objects are anchored to one or more ranges.
  */
@@ -114,5 +115,31 @@ export declare namespace IAnchored {
         readonly TwoCell: "twoCell";
     };
     type Type = typeof Type[keyof typeof Type];
+    /**
+     * Options shared by the collections that add anchored items — conditional formats, data
+     * validations, protected ranges.
+     */
+    interface AddOptions extends ITransaction.OperationOptions {
+        /**
+         * Position in the collection. `0` is first — for a conditional format, the highest priority.
+         *
+         * @defaultValue 0 — a new item goes first, as in Excel.
+         */
+        index?: number;
+        /**
+         * Redefine the item already at `index` instead of inserting, when it is anchored to exactly
+         * the same ranges (discontiguous ranges compare area by area, in authored order).
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * Only the item at `index` is considered, as in Excel. What counts as the same item is per
+         * collection: a data validation or protected range matches on ranges alone; a conditional
+         * format only redefines a scale rule (data bar, color scale, icon set) of the same kind —
+         * a style rule always inserts, since several may apply to one cell, whereas a second scale
+         * of one kind on the same ranges could never render.
+         */
+        replaceExisting?: boolean;
+    }
 }
 //# sourceMappingURL=IAnchored.d.ts.map