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

package/types/src/cellRange/ICellRange.d.ts

@@ -246,11 +246,24 @@ export interface ICellRange {
      * 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).
      *
@@ -1391,6 +1404,50 @@ export declare namespace ICellRange {
          */
         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}.
      */
@@ -2134,11 +2191,20 @@ export declare namespace ICellRange {
         /** 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. */

package/types/src/condition/AnchoredConditional.d.ts

@@ -163,21 +163,41 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
     protected _rebaseConditionFormulas(json: any, from: IRange.CellCoords, to: IRange.CellCoords): boolean | null;
     /**
      * The extend half of a paste: fold the pasted `ranges` into THIS live rule — coalescing
-     * into clean rectangles where the union is exact — rather than minting a duplicate.
+     * into one clean rectangle — rather than minting a duplicate.
      *
      * @param ranges The pasted images of the rule's marked areas (already tiled/clipped).
      * @param jsonAtMark `JSON.stringify` of the rule's `toJSON()` at mark time.
-     * @returns `false` when this rule can no longer absorb the paste — deleted, or its
-     * definition changed since the mark — and the caller must clone instead.
+     * @returns `false` when this rule cannot absorb the paste — deleted, its definition changed
+     * since the mark, or the union would move the anchor — and the caller must clone instead.
      *
      * @remarks
      * Merging is provenance-keyed: only THE rule the areas were copied from extends, which is
-     * what keeps manually authored duplicates separate. When coalescing would move the anchor
-     * cell (first range's top-left), formulas rebase ({@link _rebaseAnchorFormulas}); if the
-     * rebase refuses, the new cells append as separate areas so the anchor stays put.
+     * what keeps manually authored duplicates separate.
+     *
+     * On top of provenance, a paste merges only when the union is a single rectangle whose
+     * top-left is still the rule's anchor. That is Excel's rule (desktop and online alike): a
+     * paste flush below or to the right of the applies-to merges into it, while one above, to
+     * the left, or with a gap mints a separate rule at top priority. The shape of it is that
+     * PASTE NEVER MOVES THE ANCHOR — growing down or right leaves the stored formula's frame
+     * alone, whereas growing up or left forces a rebase, which Excel is only willing to do for
+     * autofill. Hence fill merges in all four directions and paste in two.
      * @internal
      */
     _extendPastedRanges(ranges: readonly IRange.Coords[], jsonAtMark: string): boolean;
+    /**
+     * Re-anchors a freshly pasted CLONE, whose formulas still carry the SOURCE rule's frame, to
+     * its own anchor — the shift Excel applies when a copied rule lands as a new rule (copying
+     * `F5:F10`/`G5>5` to `F20` stores `G20>5`).
+     *
+     * The shift is source-anchor to clone-anchor; the hop through the copied cell cancels, since
+     * relative offsets are preserved by both halves of it.
+     *
+     * A rebase that cannot survive the move leaves the formulas as authored — the wrong frame,
+     * but live, which beats a rule of `#REF!`. Excel never hits this: it wraps modulo the sheet
+     * instead, the same divergence the io layer converts across.
+     * @internal
+     */
+    _rebaseClonedAnchor(anchorFrom: IRange.Coords): void;
     /**
      * The geometry half of {@link _extendPastedRanges}, shared with autofill (which needs no
      * liveness or definition guards — the rule was read live inside the fill's transaction):

package/types/src/conditionalFormat/ConditionalFormat.d.ts

@@ -134,7 +134,14 @@ export declare class ConditionalFormat extends AnchoredConditional<State, Commit
     /** @internal */
     protected _createSpatial(coords: IRange.Coords): ISpatialMap.IUpdatableValue;
     /** {@inheritDoc IConditionalFormat.update} */
-    update(properties: IConditionalFormat.Modifiers, options?: ITransaction.OperationOptions): this;
+    update(properties: IConditionalFormat.Modifiers | IConditionalFormat, options?: ITransaction.OperationOptions): this;
+    /**
+     * The modifiers that make one rule's definition another's: every mutually-exclusive key is
+     * named, so the target's old shape (`scale` vs `condition`+`style`) is cleared rather than
+     * merged with.
+     * @internal
+     */
+    static replaceModifiers(json: IConditionalFormat.JSON | null): IConditionalFormat.Modifiers;
     /** {@inheritDoc IConditionalFormat.toJSON} */
     toJSON(): IConditionalFormat.JSON | null;
     /** @internal */

package/types/src/conditionalFormat/IConditionalFormat.d.ts

@@ -123,8 +123,11 @@ export interface IConditionalFormat extends IAnchored, ICondition.Stateful, IPro
      * 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.
      */

package/types/src/conditionalFormat/IConditionalFormatCollection.d.ts

@@ -1,7 +1,7 @@
 import { ICellRange, ICellRanges } from '../cellRange';
 import { ICollection } from '../type';
+import { IAnchored } from '../anchored';
 import { IConditionalFormat } from './IConditionalFormat';
-import { ITransaction } from '../transaction';
 /**
  * Holds a collection of {@link IConditionalFormat}s.
  */
@@ -38,8 +38,12 @@ export interface IConditionalFormatCollection extends ICollection<IConditionalFo
 export declare 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.

package/types/src/dataValidation/IDataValidationCollection.d.ts

@@ -1,6 +1,6 @@
-import { ITransaction } from '../transaction';
 import { ICollection } from '../type';
 import { ICellRange, ICellRanges } from '../cellRange';
+import { IAnchored } from '../anchored';
 import { IDataValidation } from './IDataValidation';
 /**
  * Holds a collection of {@link IDataValidation}s.
@@ -38,8 +38,12 @@ export interface IDataValidationCollection extends ICollection<IDataValidation>
 export declare 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 {
         /**

package/types/src/hyperlink/IHyperlink.d.ts

@@ -49,7 +49,9 @@ export interface IHyperlink {
      * @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;
     /**

package/types/src/hyperlink/_Hyperlink.d.ts

@@ -1,5 +1,11 @@
 import { ITypes } from '../type';
 import { IHyperlink } from './IHyperlink';
+/**
+ * `true` for an address the browser hands to another application (`mailto:`, `tel:`, `sms:`)
+ * rather than rendering.
+ * @internal
+ */
+export declare const isHandlerScheme: (address: string) => boolean;
 export declare class Hyperlink implements IHyperlink {
     protected _t: () => string;
     protected _p: IHyperlink.Properties;

package/types/src/lib/utils/utils.browser.d.ts

@@ -1,6 +1,11 @@
 import { HostDetails } from './_Utils';
 import { LicenseDetails } from '../../license';
 export declare function getHostDetails(): Promise<HostDetails>;
+/**
+ * Only the loopback host is a dev environment. A dev *build* served on any other host (a LAN IP,
+ * a tunnel) is checked exactly like production: license domains apply and an evaluation shows
+ * the watermark.
+ */
 export declare function isDevEnv(): Promise<boolean>;
 /**
  * The runtime location - the current page url in the browser.

package/types/src/license/LicenseDetails.d.ts

@@ -8,6 +8,11 @@ export interface LicenseDetails {
     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/primitives/CalcSignal.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Base of the control-flow signals the calculation engine throws THROUGH a formula's evaluation.
+ *
+ * @remarks
+ * A demand evaluation (a cell the topological sort could not order) reads its precedents lazily;
+ * a read that lands on a cell not yet calculated suspends the formula so that cell can go first,
+ * and a read that lands on a cell already suspended is a reference cycle. Both are raised from
+ * inside the read and unwind the whole evaluation to the executor, which is the only catcher
+ * that knows what to do with them.
+ *
+ * Every catch site on the evaluation path that turns an arbitrary throw into a `#VALUE!` — a
+ * function call, a lambda body, a lift over range members, the commit-site dereference — must
+ * let a signal pass: {@link isCalcSignal}. A signal is not an error and never becomes a value.
+ */
+export declare class CalcSignal {
+    readonly isCalcSignal: true;
+}
+/** `true` for a {@link CalcSignal} — a throw that must be rethrown, never turned into a value. */
+export declare const isCalcSignal: (e: unknown) => e is CalcSignal;
+//# sourceMappingURL=CalcSignal.d.ts.map

package/types/src/protectedRange/IProtectedRangeCollection.d.ts

@@ -1,6 +1,6 @@
 import { ICellRange, ICellRanges } from '../cellRange';
 import { ICollection } from '../type';
-import { ITransaction } from '../transaction';
+import { IAnchored } from '../anchored';
 import { IProtectedRange } from './IProtectedRange';
 /**
  * Holds a collection of {@link IProtectedRange}s.
@@ -41,8 +41,13 @@ export interface IProtectedRangeCollection extends ICollection<IProtectedRange>
 export declare 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.

package/types/src/scripting/_ScriptUtils.d.ts

@@ -13,6 +13,19 @@ export declare const _ReuseGlobalContext: {
     FormulaError: typeof FormulaError;
     Observable: typeof Observable;
 };
+/**
+ * Publishes the shared context on `globalThis` for bundled scripts.
+ *
+ * @remarks
+ * A compiled script binds `globalThis.__SHEETXL.FormulaContext` (and `IRange`, `FormulaError`, …)
+ * ONCE, at module load — the `Bundler`'s virtual `@sheetxl/primitives` module reads them into
+ * top-level `export const`s. Every later call goes through that captured singleton, whose
+ * per-evaluation state is {@link setGlobalScope}. So the global only has to exist while a module
+ * loads. Idempotent, and never removed: nothing observes its absence, and installing it per
+ * function invocation (with a stash and a `delete` on the way out) cost ~290,000 property writes
+ * and deletes for one load of a 28K-formula workbook.
+ */
+export declare function installGlobalContext(): void;
 export declare function setGlobalScope(scope: Partial<IFormulaContext> | null | undefined): void;
 export declare function clearGlobalScope(): void;
 //# sourceMappingURL=_ScriptUtils.d.ts.map

package/types/src/sheet/Sheet.d.ts

@@ -11,6 +11,7 @@ import { IComment } from '../comment';
 import { IColor } from '../color';
 import { IHyperlink } from '../hyperlink';
 import { ISort } from '../sort';
+import { IAnchored } from '../anchored';
 import { Anchored } from '../anchored/Anchored';
 import { IAnchoredMap } from '../anchored/IAnchoredMap';
 import { ITable, ITableCollection } from '../table';
@@ -841,13 +842,43 @@ export declare class Sheet implements ISheet {
      * @internal
      */
     protected _addTable(address: ICellRange.Address, options: ITableCollection.AddOptions | boolean): ITable;
+    /**
+     * The add shared by the anchored collections — conditional formats, data validations, protected
+     * ranges. Resolves an item-or-address input, keeps the option keys out of the persisted JSON, and
+     * either redefines the item at `index` (when `replaceExisting` and the collection agrees it is the
+     * same item) or inserts there — first by default, as in Excel.
+     * @internal
+     */
+    protected _addAnchored<T extends IAnchored & {
+        getRanges(): ICellRanges;
+        toJSON(): J | null;
+    }, J extends object>(add: ICellRanges.Address | T | null | undefined, options: (IAnchored.AddOptions & J) | undefined, spec: {
+        /** The sheet-state slot the collection lives in. */
+        key: 'conditionalFormats' | 'dataValidations' | 'protectedRanges';
+        isItem: (add: unknown) => add is T;
+        description: string;
+        /** Loads one ref into the map, handing the created model to `capture`. */
+        load: (map: IAnchoredMap<T, J>, ref: IRange.JSONReference<J>, capture: (model: T) => void) => IAnchoredMap<T, J>;
+        /**
+         * Whether the item at `index` — already known to cover exactly the same ranges — is the one
+         * `json` redefines: the per-collection half of `replaceExisting`. Omit to match on ranges alone.
+         */
+        isSameItem?: (existing: T, json: J) => boolean;
+        /** Redefines `existing` from `json`, inside the add's commit. */
+        replace: (existing: T, json: J, options: ITransaction.OperationOptions) => void;
+        /** A last look at the JSON before it is inserted (a protected range mints its name here). */
+        prepareInsert?: (json: J) => J;
+        notify: () => void;
+        /** Widen the item's columns after an insert — a validation or format may show a dropdown. */
+        autoFit?: boolean;
+    }): T;
     /**
      * @internal
      */
     protected _addDataValidation(add: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions): IDataValidation;
     /**
-   * @internal
-   */
+     * @internal
+     */
     protected _addConditionalFormat(add: ICellRanges.Address | IConditionalFormat, options?: IConditionalFormatCollection.AddOptions): IConditionalFormat;
     /**
      * The first unused `Range<n>` name, matching Excel's default for a new Allow-Edit-Range.

package/types/src/sheet/SheetCell.d.ts

@@ -292,6 +292,8 @@ export declare class SheetCell implements ICell {
     getHyperlink(): IHyperlink | null;
     /** {@inheritDoc ICell.getErrors} */
     getErrors(): readonly string[];
+    /** {@inheritDoc ICell.getCircularReference} */
+    getCircularReference(): ICalculation.ICircularReference | null;
     /** {@inheritDoc ICell.getWarnings} */
     getWarnings(): readonly string[];
     /** {@inheritDoc ICell.getSpans} */

package/types/src/sheet/SheetRange.d.ts

@@ -162,7 +162,18 @@ export declare class SheetRange implements ICellRange {
     /** {@inheritDoc ICellRange.getSurrounding} */
     getSurrounding(options?: ICellRange.GetSurroundingOptions): this;
     /** {@inheritDoc ICellRange.getExtended} */
-    getExtended(direction: IRange.Direction, cell?: ICell.Address): this;
+    getExtended(direction: IRange.Direction, cell?: ICell.Address | ICellRange.GetExtendedOptions): this;
+    /**
+     * `fromBlank: 'before'` — a walk that set off from a blank comes to rest on the last blank rather
+     * than on the first cell of the block it ran into. See
+     * {@link ICellRange.GetExtendedOptions.fromBlank}.
+     */
+    private _restBeforeBlock;
+    /**
+     * `basis: 'adjacent'` — the boundary comes from the lines flanking the range rather than from its
+     * own content. See {@link ICellRange.GetExtendedOptions.basis} for the rule.
+     */
+    private _extendedAdjacent;
     /** {@inheritDoc ICellRange.getEntireRows} */
     getEntireRows(shift?: boolean, options?: ICellRange.GetRangeOptions): this;
     /** {@inheritDoc ICellRange.getEntireColumns} */

package/types/src/sheet/_SheetStateTypes.d.ts

@@ -7,7 +7,7 @@ import { IStyle } from '../style';
 import { ICellRange } from '../cellRange';
 import { OverlappingRange, ISparseGrid, ISpatialMap } from '../collections';
 import { MergeEntry } from './spatial';
-import { SpillEntry, ContentfulSpatialValue } from '../calculation/spatial';
+import { SpillEntry, ContentfulSpatialValue, CircularEntry } from '../calculation/spatial';
 import { IConditionalFormat } from '../conditionalFormat';
 import { IDataValidation } from '../dataValidation';
 import { IProtectedRange } from '../protectedRange';
@@ -220,6 +220,10 @@ export declare namespace RangeState {
          * Errors during calculation.
          */
         calcError?: string;
+        /**
+         * In a reference cycle, or downstream of one.
+         */
+        circular?: CircularEntry;
         /**
          * An error VALUE lives here (the `Error` scalar kind — from the reconciled error spatial).
          */
@@ -263,6 +267,10 @@ export declare namespace RangeState {
         readonly Spills: "spills";
         readonly Pending: "pending";
         readonly CalcError: "calcError";
+        /**
+         * In a reference cycle, or downstream of one — evaluates to `0` (DESIGN-CIRCULAR-CALC.md §7).
+         */
+        readonly Circular: "circular";
         /**
          * Error VALUES (the `Error` scalar kind). Backed by the RECONCILED view
          * (`SheetReadContext.getErrorSpatial`), not `state.errorSpatial` directly — resolving it may
@@ -383,6 +391,11 @@ export interface State {
     spillSpatial: ISpatialMap<SpillEntry>;
     pendingSpatial: ISpatialMap<boolean>;
     calcErrorsSpatial: ISpatialMap<string>;
+    /**
+     * Cells in a reference cycle or downstream of one, by cycle (DESIGN-CIRCULAR-CALC.md §7.2).
+     * Maintained by calc realize from the executor's deltas, like {@link pendingSpatial}.
+     */
+    circularSpatial: ISpatialMap<CircularEntry>;
     /**
      * Error VALUES (`#DIV/0!`, `#N/A`, …) — the `Error` scalar kind, NOT engine failures
      * (those are {@link calcErrorsSpatial} / `CalcError`). Deliberately not per-type: `true`

package/types/src/style/IStyle.d.ts

@@ -479,6 +479,11 @@ export declare namespace IStyle {
         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];
 }

package/types/src/table/AnchoredTable.d.ts

@@ -217,11 +217,27 @@ export declare class AnchoredTable extends AbstractAnchored<State, CommitView, I
      * 2. create or reused new Ids
      *
      * @remarks
-     * Mutates columnPropsNews to ensure index is correct.
+     * Each entry is cloned before its `index`/`id` are settled. Callers routinely build
+     * `columnPropsNews` out of the committed `orderedColumnsProps` (a slice, a spread, a splice),
+     * which shares the prop objects with the state undo restores - writing through them would
+     * rewrite history in place.
      *
      * @internal
      */
     protected _updateColumnsState(columnPropsNews: Partial<ColumnPropertiesState>[], options?: string | ITransaction.OperationOptions): ITable.IColumn[];
+    /**
+     * Re-derives the active filter and sort levels from the column props.
+     *
+     * @remarks
+     * A level is bound to a column id, but the column props are where a filter or sort actually
+     * lives. Rebuilding the columns (a delete, a sheet sync) can therefore take a column out from
+     * under its level, and a level that outlives its column reads back as unfiltered while its rows
+     * stay hidden. Deriving the levels from the props instead of carrying them alongside keeps the
+     * two from drifting, and closes the gap in `level` left by whatever was dropped.
+     *
+     * @internal
+     */
+    private _rebuildActiveLevels;
     /** {@inheritDoc ITable.getVisibleRefRangeCoords} */
     getVisibleRefRangeCoords(): IRange.Coords;
     /** {@inheritDoc ITable.getVisibleCellCoords} */

package/types/src/text/TextUtils.d.ts

@@ -157,6 +157,24 @@ export declare function isValidHttpUrl(value: string): boolean;
  * @returns `true` if the string is a valid email, `false` otherwise.
  */
 export declare function isValidEmail(text: string): boolean;
+/**
+ * The hyperlink address for text that Excel's AutoCorrect would turn into a link, or `null`
+ * when the text is not link-shaped.
+ *
+ * @param text The text to check.
+ * @returns The address, with the scheme Excel supplies when the text omits one, or `null`.
+ *
+ * @remarks
+ * Mirrors Excel's "Internet and network paths with hyperlinks" rule, which links:
+ *
+ * * `http(s)://…` - as is.
+ * * `www.…` - as `http://www.…`.
+ * * `mailto:…` - as is.
+ * * an email address - as `mailto:…`.
+ *
+ * A bare domain (`sheetxl.com`) is left alone, as Excel leaves it.
+ */
+export declare function toHyperlinkAddress(text: string): string | null;
 /**
  * Converts a number to alphabet.
  * @param i The number to stringify