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

package/types/src/calculation/state/CalculationContext.d.ts

@@ -1,4 +1,4 @@
-import { IRange, ScalarType, FormulaError, Scalar, IReferenceRange, IFunction, IFormulaContext, IRuntime } from '@sheetxl/primitives';
+import { IRange, ScalarType, FormulaError, Scalar, IReferenceRange, IFunction, IFormulaContext, IFunctionArguments, IRuntime } from '@sheetxl/primitives';
 import { FunctionProvider } from '@sheetxl/scripting';
 import { ITransaction } from '../../transaction';
 import { IFunctionCollection } from '../../scripting';
@@ -158,6 +158,8 @@ export declare class CalculationContext implements IFormulaContext {
     toText(value: Scalar | undefined): string;
     /** @inheritdoc IFormulaContext.getRuntime */
     getRuntime(): IRuntime;
+    /** @inheritdoc IFormulaContext.getArgs */
+    getArgs(): IFunctionArguments;
     get [Symbol.toStringTag](): string;
     toString(): string;
 }

package/types/src/calculation/state/IContextContainer.d.ts

@@ -156,6 +156,37 @@ export interface IContextContainer {
      * still carry, and the "already visited this cycle" guards would skip their re-evaluation.
      */
     getCycleId(): number;
+    /**
+     * The graph-version counters the executor's plan caches key on (CALC-PERFORMANCE-PLAN.md §1.1).
+     *
+     * `staticEpoch` advances whenever the static edges may have changed — formula block
+     * register/unregister/edit, structural shift, sheet add/remove, undo/redo state swap — and
+     * governs order-stamp validity. `precedentEpoch` advances whenever `staticEpoch` does, plus on
+     * dynamic-precedent commits (spill/INDIRECT watchers), and governs `CalcNode.dependents`
+     * validity. The split is load-bearing: a dynamic commit changes who is affected, never the
+     * static topological constraints, so a sheet with a spill keeps a valid order cache.
+     *
+     * READING is what synchronizes: the implementation compares the identities of the spatial maps
+     * it last saw and advances the counters when a clone-then-swap happened (edits, shifts, undo/
+     * redo, pass-end dynamic commits all publish fresh maps). Sites that mutate the CURRENT maps in
+     * place — `CalcGrid.fromJSON` loads, an un-cloned `shift` — must call {@link bumpCalcEpochs}
+     * explicitly, because no identity changes there.
+     *
+     * Both counters are monotonic and deliberately NOT transactional, for the same reason as
+     * {@link getCycleId}: they are compared against stamps on plain mutable graph objects that
+     * undo/redo never rewinds, so rewinding a counter would re-validate stale stamps.
+     */
+    getCalcEpochs(): {
+        staticEpoch: number;
+        precedentEpoch: number;
+    };
+    /**
+     * Advances the epoch counters for an IN-PLACE mutation of the current spatial maps — the paths
+     * identity comparison in {@link getCalcEpochs} cannot see. `includeStatic: true` advances both
+     * counters (a formula/structure change); `false` advances only `precedentEpoch` (a
+     * dynamic-precedent-only change).
+     */
+    bumpCalcEpochs(includeStatic: boolean): void;
     /**
      * Returns the committed or in-progress scalar values for the given grid.
      *

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

@@ -1,5 +1,5 @@
 import { FormulaError, IRange, Scalar, InteropScalar, IRangeStats } from '@sheetxl/primitives';
-import { Bounds, ReferenceableClipboard } from '@sheetxl/utils';
+import { Bounds, Size, ReferenceableClipboard } from '@sheetxl/utils';
 import { ITypes } from '../type';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
@@ -1102,6 +1102,22 @@ export interface ICellRange {
      * Returns the absolute bounds for the range.
      */
     getBounds(): Bounds;
+    /**
+     * The size this range's content needs — what {@link getBounds} would report if the range had
+     * been {@link autoFit}. A pure query: nothing is measured onto the model and nothing is committed.
+     *
+     * @param options Measurement options. Default `{ axes: IRange.AxisSelection.Both }`.
+     *
+     * @remarks
+     * - The width is the sum of the per-column best fits and the height the sum of the per-row best
+     *   fits, so a single-column range answers "how wide must this list be" directly.
+     * - An axis left out of {@link BestFitOptions.axes} reports its current size.
+     * - Only the range's own content is measured, so the answer never depends on cells outside it.
+     *   (`autoFit` also scans outside the range, to prove a shrink is safe.)
+     * - Sheet protection is not consulted: reading a size cannot violate it, and a protected sheet
+     *   answers the same as an unprotected one.
+     */
+    getBestFit(options?: ICellRange.BestFitOptions): Size;
     /**
      * Indicates if the range is readonly only.
      *
@@ -1613,9 +1629,9 @@ export declare namespace ICellRange {
         includeMergeOverflow?: boolean;
     }
     /**
-     * Options for {@link ICellRange.autoFit}.
+     * Options for {@link ICellRange.getBestFit} — measurement only.
      */
-    interface AutoFitOptions extends ITransaction.OperationOptions {
+    interface BestFitOptions {
         /**
          * Best fit using the minimum amount of space required.
          *
@@ -1626,21 +1642,6 @@ export declare namespace ICellRange {
          * For example allowing numbers to round or use scientific notation.
          */
         minContent?: boolean;
-        /**
-         * Restricts autoFit to only grow, never shrink.
-         *
-         * @defaultValue false - adjust in both directions.
-         *
-         * @remarks
-         * This is useful when adjusting fonts and wan the columns to resize but not the rows.
-         */
-        expandOnly?: boolean | IRange.Axis;
-        /**
-         * If this is set to `true` then any headers that have custom sizes will be ignored.
-         *
-         * @defaultValue false
-         */
-        skipCustomSize?: boolean;
         /**
          * The axes to autoFit.
          *
@@ -1662,6 +1663,26 @@ export declare namespace ICellRange {
          */
         formulaView?: boolean;
     }
+    /**
+     * Options for {@link ICellRange.autoFit}.
+     */
+    interface AutoFitOptions extends BestFitOptions, ITransaction.OperationOptions {
+        /**
+         * Restricts autoFit to only grow, never shrink.
+         *
+         * @defaultValue false - adjust in both directions.
+         *
+         * @remarks
+         * This is useful when adjusting fonts and wan the columns to resize but not the rows.
+         */
+        expandOnly?: boolean | IRange.Axis;
+        /**
+         * If this is set to `true` then any headers that have custom sizes will be ignored.
+         *
+         * @defaultValue false
+         */
+        skipCustomSize?: boolean;
+    }
     /**
      * Options for {@link ICellRanges.getFlattened}.
      */

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

@@ -224,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;
@@ -386,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;
@@ -608,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;
     /**

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/browser/cjs/BF14ZEAnaqxXroSj.cjs

@@ -1 +0,0 @@
-exports.loadEnumManifest=async function(){let e=`@0.7.28-beta.4`;e!==`@local`&&e!==`@0.0.0`||(e=``);let t=`https://cdn.jsdelivr.net/npm/@sheetxl/sdk${e}/types/scripting-enums.json`,n=await fetch(t);if(!n.ok)throw Error(`Unable to load script enum runtime (${n.status}) from ${t}.`);return n.json()};