@sheetxl/sdk 0.7.28-beta.3 → 0.8.0-beta.1

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.d.ts

@@ -15,6 +15,13 @@ export interface HostDetails {
     domain?: string | null;
     fingerprint?: NodeFingerprint;
 }
+/**
+ * A placeholder license key: the "evaluation" spellings a caller may pass to
+ * `LicenseManager.setLicenseKey` to run unlicensed on purpose (`eval`, `trial`, or the
+ * `visit …`/`email …` pointer text a starter template ships with). These select an evaluation
+ * license; they are never keys, so the persistent key store ignores them.
+ */
+export declare function isPlaceholderLicenseKey(key: string | null | undefined): boolean;
 export declare function getBuildVersion(): string;
 export declare function getBuildDate(): string;
 //# sourceMappingURL=_Utils.d.ts.map

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/primitives/PrimitiveUtils.d.ts

@@ -127,7 +127,8 @@ export declare function isMultiAreaValue(value: any): boolean;
 export declare function countArgDepth(value: any): number;
 export declare function flattenToScalarArray(context: IFormulaContext, coercedArr: FixedPackedArray | Scalar[], currentArg: any, isDirect: boolean | undefined, rangeType: string | null, // the range preference for dims higher than 2 (if not specified then will materialize to array values
 scalarType: ScalarType | null, // the scalar preference. If not specified no coercion will occur.
-errors?: 'reject' | 'accept' | null): void | FormulaError.Known;
+errors?: 'reject' | 'accept' | null, // effective error policy (TypedFunction resolves the default)
+noMemberFilter?: boolean): void | FormulaError.Known;
 /**
  * Returns a 2d shape. Either a reference.
  */
@@ -168,7 +169,8 @@ isDirect: boolean, errors?: 'reject' | 'accept' | null): IRange | any[][] | Form
  */
 export declare function addCoercedValue(context: IFormulaContext, coercedArr: FixedPackedArray | Scalar[], currentArg: any, isDirect: boolean, rangeType: 'p' | 'r' | 'm' | null, scalarType: ScalarType | null, // the scalar preference. If not specified then no coercion will occur.
 allowError: boolean, flatten: boolean, // indicates we should flatten
-errors?: 'reject' | 'accept' | null): FormulaError.Known | void;
+errors?: 'reject' | 'accept' | null, // effective error policy (TypedFunction resolves the default)
+noMemberFilter?: boolean): FormulaError.Known | void;
 /**
  * Minimal validation used from the return value of functions.
  */

package/types/src/primitives/Range.d.ts

@@ -58,7 +58,9 @@ export declare class Range<T extends Scalar = Scalar> implements IRange<T> {
     /** @inheritdoc IRange.filter */
     filter<TS extends Scalar = T>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => boolean, options?: IRange.IteratorOptions): this;
     /** @inheritdoc IRange.flatten */
-    flatten<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
+    flatten(options?: IRange.IteratorOptions): this;
+    /** @inheritdoc IRange.getValuesFlat */
+    getValuesFlat<TS extends Scalar = T>(options?: IRange.IteratorOptions): TS[];
     /** @inheritdoc IRange.forEach */
     forEach<TS extends Scalar = T, B = any>(callbackFn: (value: TS, coords: IRange.CellCoords, range: IRange<T>) => {
         break: B;

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/FunctionArguments.d.ts

@@ -0,0 +1,22 @@
+import { IFunction, IFunctionArguments } from '@sheetxl/primitives';
+/**
+ * A bound view, as the marshaller holds it.
+ *
+ * @internal The public half is {@link IFunctionArguments}; this adds the two things only `_exec`
+ * may do — point the view at the argument array its broadcast loop rewrites per output cell, and
+ * take it off the engine's shared dispatch buffer when the body is about to re-enter dispatch.
+ */
+export interface IArgumentsFrame extends IFunctionArguments {
+    /** @see FunctionArguments._setLiftValues */
+    _setLiftValues(values: any[] | null): void;
+    /** @see FunctionArguments._setPrivateArgs */
+    _setPrivateArgs(args: any[]): void;
+}
+/**
+ * Binds the view for a call about to dispatch, and returns it so the lift can point it at its
+ * per-cell arguments. Pairs with {@link popArguments} in a `finally`.
+ */
+export declare const pushArguments: (params: IFunction.ParameterTypeJSON[] | null | undefined, variadic: number, suffix: number, args: any[], argsLength: number) => IArgumentsFrame;
+/** Ends the call {@link pushArguments} began. */
+export declare const popArguments: () => void;
+//# sourceMappingURL=FunctionArguments.d.ts.map

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

@@ -33,6 +33,14 @@ interface RepeatPlan {
     short: boolean;
     /** Period 1 hands the body `T[]`; period 2+ hands it tuples. */
     tuples: boolean;
+    /**
+     * Declared parameters SUPPLIED after the group, solved for alongside `n` rather than fixed — a
+     * trailing suffix may be optional (SWITCH's `default`).
+     *
+     * Only `getArgs()` reads it: the suffix parameters are pinned to the TAIL of the argument list,
+     * so this is what lets a body ask for its `default` without counting how many pairs preceded it.
+     */
+    suffix: number;
 }
 export declare class TypedFunction implements IFunction {
     protected _n: string;
@@ -52,6 +60,24 @@ export declare class TypedFunction implements IFunction {
     };
     protected _lc: boolean;
     protected _rlc: boolean;
+    /**
+     * `@compat noReferenceLift` — a multi-cell REFERENCE at a non-repeating scalar parameter is
+     * `#VALUE!` rather than a broadcast (DESIGN-FUNCTION-ARGUMENTS §2.3, §6).
+     *
+     * A declaration bit and not a body concern, because the body never runs: without it the lift
+     * runs instead and answers one result per cell, so there is nothing for a body-facing API to
+     * express.
+     */
+    protected _nrl: boolean;
+    /**
+     * `@compat noMemberFilter` — members of a REPEATING scalar parameter are coerced rather than
+     * filtered: numeric text parses, a blank inside a multi-cell range reads 0, and a boolean or
+     * non-numeric text member is `#VALUE!` for the whole call (DESIGN-FUNCTION-ARGUMENTS §2.8, §6).
+     *
+     * The other half of the ATP heritage `_nrl` carries; `@compat atp` turns on both. It is applied
+     * where the native filter lives — the rest branch of the coercion loop — and nowhere else.
+     */
+    protected _nmf: boolean;
     /**
      * The declared return scalar type, normalized (`'*'`/null → null).
      *
@@ -64,6 +90,16 @@ export declare class TypedFunction implements IFunction {
     protected _pj: IFunction.ParameterTypeJSON[] | null | undefined;
     /** Index of the repeating-group parameter, or `-1`. */
     protected _gi: number;
+    /**
+     * Index of the one parameter that consumes a VARIABLE number of arguments — a repeating group or
+     * a trailing rest — or `-1`.
+     *
+     * `getArgs()` indexes by PARAMETER (DESIGN-FUNCTION-ARGUMENTS §3.3) and this is the single place
+     * parameter numbering and argument numbering part company, so it is resolved once here rather
+     * than re-derived per call. `_gi` cannot serve: it covers `Repeating<T>` only, and a plain rest
+     * parameter is the same thing to a body asking which parameter its argument landed in.
+     */
+    protected _va: number;
     /** Resolved {@link RepeatPlan} per argument count (`null` = an arity the declaration refuses). */
     protected _gc: Map<number, RepeatPlan | null> | null;
     constructor(json: IFunction.DeclarationJSON, fn: (...args: any) => any, getContext: () => IFormulaContext | null | undefined, desc?: IFunction.DescriptorJSON | ((locale?: string) => Promise<IFunction.DescriptorJSON>) | null, builtIn?: boolean);
@@ -106,6 +142,30 @@ export declare class TypedFunction implements IFunction {
      * writes anything into it.
      */
     protected _exec<R = any>(argsEval: any[], argsLength: number): R;
+    /**
+     * `@compat noReferenceLift`: is a multi-cell REFERENCE sitting at a non-repeating scalar
+     * parameter? (DESIGN-FUNCTION-ARGUMENTS §2.3, §2.7 rule 3.)
+     *
+     * Three qualifications, each measured rather than assumed
+     * (`fn-battery/adhoc-container-at-slot{,2}`, Excel 16.0 build 20326):
+     *
+     * - **A REFERENCE, not an array.** `MROUND({3,4,5},5)` spills where `MROUND(A1:A3,5)` is
+     *   `#VALUE!`, so an array at the same slot still lifts. That is the whole reason this reads the
+     *   argument's shape rather than trusting the parameter: the engine hands a reference over as
+     *   COORDS and an array as an `IRange`.
+     * - **MULTI-CELL.** A 1×1 reference collapses to its member and is an ordinary argument
+     *   (`EFFECT(J1,4)` over a text cell is `0.0824…`).
+     * - **NON-REPEATING.** A repeating scalar slot ABSORBS a container as members whatever the
+     *   function's heritage — `GCD(C1:C3)` is 4, `MULTINOMIAL(A1:A3)` is 27720 — and those were the
+     *   rows that could have broken the rule and did not. Period-1 groups marshal through the rest
+     *   branch and are already excluded by `rest`; period 2+ expand to per-argument entries, so the
+     *   group's span is skipped explicitly.
+     *
+     * A multi-AREA union `(A1:A3,C1:C5)` arrives as an ARRAY of areas and is not treated as a
+     * reference here — unmeasured at these slots, and inventing a verdict for it would be the kind
+     * of unification §2.0 warns about.
+     */
+    protected _refusesReferenceLift(params: IFunction.ParameterTypeJSON[] | null | undefined, paramLength: number, argsEval: any[], argsLength: number, plan: RepeatPlan | null): boolean;
     /**
      * The consumer half of the lift (CALC-ISSUES item 22 change 2). Each `refLifts` entry is a
      * reference-only (r:'p') argument holding a producer lift's preserved per-element results.

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';
@@ -223,6 +224,7 @@ export declare class Sheet implements ISheet {
         calculate: (ranges: ICellRanges.Coords, options?: ICalculation.CalculateOptions) => void;
         autoSelect: (options?: boolean | ICellRange.SelectOptions, selectionOverride?: Partial<IRangeSelection.Coords> | null, axis?: IRange.Axis) => Promise<IRange.Coords[]>;
         autoFit: (ranges: readonly IRange.Coords[], options?: ICellRange.AutoFitOptions) => void;
+        getBestFit: (range: IRange.Coords, options?: ICellRange.BestFitOptions) => Size;
         addRangesListeners: (ranges: readonly IRange.Coords[], listener: ICellRange.Listener, options?: ICellRange.ListenerOptions) => IListener.Remove;
         addRangesListeners2: (ranges: readonly IRange.Coords[], listener: ICellRange.Listener, options: ICellRange.ListenerOptions | undefined, isRanges: boolean) => IListener.Remove;
         surroundingRegion: (range: IRange.Coords, options?: ICellRange.GetSurroundingOptions) => IRange.Coords;
@@ -385,6 +387,7 @@ export declare class Sheet implements ISheet {
             calculate: (ranges: ICellRanges.Coords, options?: ICalculation.CalculateOptions) => void;
             autoSelect: (options?: boolean | ICellRange.SelectOptions, selectionOverride?: Partial<IRangeSelection.Coords> | null, axis?: IRange.Axis) => Promise<IRange.Coords[]>;
             autoFit: (ranges: readonly IRange.Coords[], options?: ICellRange.AutoFitOptions) => void;
+            getBestFit: (range: IRange.Coords, options?: ICellRange.BestFitOptions) => Size;
             addRangesListeners: (ranges: readonly IRange.Coords[], listener: ICellRange.Listener, options?: ICellRange.ListenerOptions) => IListener.Remove;
             addRangesListeners2: (ranges: readonly IRange.Coords[], listener: ICellRange.Listener, options: ICellRange.ListenerOptions | undefined, isRanges: boolean) => IListener.Remove;
             surroundingRegion: (range: IRange.Coords, options?: ICellRange.GetSurroundingOptions) => IRange.Coords;
@@ -607,6 +610,12 @@ export declare class Sheet implements ISheet {
      * Implementation lives in `_SheetAutoFitUtils` (same pattern as `_SheetSortUtils.doSort`).
      */
     protected _autoFit(ranges: readonly IRange.Coords[], options?: ICellRange.AutoFitOptions): void;
+    /**
+     * The size a range's content needs, without writing it. See {@link ICellRange.getBestFit}.
+     *
+     * @internal
+     */
+    protected _getBestFit(range: IRange.Coords, options?: ICellRange.BestFitOptions): Size;
     /** @internal */
     protected _createRangeEvent(coords: (readonly IRange.FixableCoords[]) | IRange.FixableCoords, options: NotifierOptions, coordsFrom?: (readonly IRange.FixableCoords[]) | IRange.FixableCoords): ICellRange.Event;
     /**
@@ -841,13 +850,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

@@ -1,4 +1,5 @@
 import { IRange, Scalar, IRangeStats, InteropScalar } from '@sheetxl/primitives';
+import { Size } from '@sheetxl/utils';
 import { ITransaction } from '../transaction';
 import { IListener } from '../listener';
 import { ICell } from '../cell';
@@ -246,6 +247,8 @@ export declare class SheetRange implements ICellRange {
     get size(): number;
     /** {@inheritDoc ICellRange.getBounds} */
     getBounds(): import('@sheetxl/utils').Bounds;
+    /** {@inheritDoc ICellRange.getBestFit} */
+    getBestFit(options?: ICellRange.BestFitOptions): Size;
     /** {@inheritDoc ICellRange.isInvalid} */
     isInvalid(): boolean;
     /** {@inheritDoc ICellRange.getDefaultShiftAxis} */

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

@@ -1,4 +1,5 @@
 import { IRange } from '@sheetxl/primitives';
+import { Size } from '@sheetxl/utils';
 import { ICellRange } from '../cellRange';
 import { Sheet } from './Sheet';
 /**
@@ -15,4 +16,31 @@ import { Sheet } from './Sheet';
  * @internal
  */
 export declare function doAutoFit(sheet: Sheet, ranges: readonly IRange.Coords[], options?: ICellRange.AutoFitOptions): void;
+/**
+ * The size `range`'s content needs — what {@link doAutoFit} would commit, reduced to a `Size`
+ * instead of written.
+ *
+ * @remarks
+ * The same phases as `doAutoFit` ({@link measureRange}, then {@link reduceColumnWidths} /
+ * {@link reduceRowHeights}) minus the commit. Everything that differs follows from not writing:
+ *
+ * - The clamps are IDENTITY. `expandOnly` reconciles a measurement with the size a header already
+ *   has; a query has no such size to reconcile against.
+ * - `axes: Both` still lays the rows out against the widths the column pass produced — a wrapped
+ *   cell's height is a function of its column width — but those widths reach
+ *   {@link refreshSegmentWidths} as a lookup rather than being read back from headers that were
+ *   never written.
+ * - The scan is not widened to the used range. Widening proves a shrink is safe, and a query does
+ *   not shrink; so only the range's own content is measured.
+ * - No protection check and no protected-axis skip: nothing is written, so nothing can be violated.
+ *
+ * An axis not being fitted reports its current size, so the result is comparable with
+ * `getBounds()` whichever axes were asked for.
+ *
+ * @param sheet The sheet to measure.
+ * @param range The range to measure.
+ * @param options Measurement options (axes, minContent, formulaView).
+ * @internal
+ */
+export declare function doBestFit(sheet: Sheet, range: IRange.Coords, options?: ICellRange.BestFitOptions): Size;
 //# sourceMappingURL=_SheetAutoFitUtils.d.ts.map

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