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

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/_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