@sheetxl/sdk 0.7.26 → 0.7.28-beta.1

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

@@ -0,0 +1,190 @@
+import { IRange, InteropScalarType, IRuntime, Scalar } from '@sheetxl/primitives';
+import { RunCoords, MaybePromise } from '@sheetxl/utils';
+import { ISparseGrid } from '../collections';
+import { ICalculation } from '../calculation';
+import { ICondition } from './ICondition';
+export declare class ConditionOperator<P = any> implements ICondition.IOperator<P> {
+    protected _delegate: ICondition.IOperator;
+    protected _types: readonly (InteropScalarType | null)[] | null;
+    constructor(delegate: ICondition.IOperator);
+    /** {@inheritDoc ICondition.getName} */
+    getName(): string;
+    /** {@inheritDoc ICondition.createPredicate} */
+    createPredicate(param: P, ctx: ICondition.IContext): MaybePromise<ICondition.Predicate | null>;
+    /** {@inheritDoc ICondition.getAcceptsTypes} */
+    getAcceptsTypes(): readonly (InteropScalarType | null)[] | null;
+    /** {@inheritDoc ICondition.acceptsList} */
+    acceptsList(): boolean;
+    /** {@inheritDoc ICondition.getParamType} */
+    getParamType(lhsSelector?: ICondition.ISelector): string | null;
+    /** {@inheritDoc ICondition.isCombinator} */
+    isCombinator(): boolean;
+    /** {@inheritDoc ICondition.getTitle} */
+    getTitle(): string | undefined;
+    /** {@inheritDoc ICondition.getDescription} */
+    getDescription(): string | null;
+    /** {@inheritDoc ICondition.createDefaultParam} */
+    createDefaultParam(lhsSelector?: ICondition.ISelector): P | null | undefined;
+    /** {@inheritDoc ICondition.doBatch} */
+    doBatch(keys: Set<any>, param: P, ctx: ICondition.IContext): MaybePromise<IRange<boolean> | null> | undefined;
+    /** {@inheritDoc ICondition.toString} */
+    toString(param: P, lhsSelector?: ICondition.ISelector): string | undefined;
+    get [Symbol.toStringTag](): string;
+}
+/**
+ * Encodes error scalars in a condition param for JSON, using the cell-value spelling
+ * (`{ t: 'e', v: code }` — `Sheet.toJSON`'s convention): an error operand (`cellIs` equal `#N/A`)
+ * must survive the sxl-JSON round trip the same way an error cell value does. Everything else
+ * passes through unchanged (and identity is preserved when nothing encodes).
+ *
+ * Reaches the shapes an error can actually sit in: the Scalar param itself, a between option's
+ * `from`/`to`, and (through `not`'s raw input) a nested condition's param. Combinator children
+ * that are resolved conditions serialize through their own `toJSON`.
+ */
+export declare function encodeParamJSON(param: any): any;
+/**
+ * The inverse of {@link encodeParamJSON}, applied where a param is INSTALLED ({@link resolveInput}):
+ * the marker (and a between option's marked bounds) revive to error instances. Combinator children
+ * are left encoded — they decode when their own input resolves.
+ */
+export declare function decodeParamJSON(param: any): any;
+export declare function resolveInput(condition: ICondition.Input | null): ICondition | null;
+/**
+ * A condition whose selector or operator is not in the registry.
+ *
+ * @remarks
+ * Persistence must never depend on the engine understanding a rule. Rather than take the whole rule
+ * down with it, an unresolvable condition is kept **verbatim** and evaluates to nothing — it
+ * round-trips exactly and starts working the moment the missing name is registered, which is what
+ * makes `Condition.Operators.register` usable after a workbook has already loaded.
+ *
+ * Resolution is retried on each access until it succeeds, then cached.
+ */
+export declare class UnresolvedCondition<P = any> implements ICondition<P> {
+    protected _json: ICondition.JSON<P>;
+    protected _reason: string;
+    protected _resolved: ICondition<P> | null;
+    constructor(json: ICondition.JSON<P>, reason: string);
+    /**
+     * Retries resolution against the current registry.
+     *
+     * @returns The resolved condition, or `null` while a name it needs is still unregistered.
+     */
+    resolve(): ICondition<P> | null;
+    /**
+     * Why the condition could not be resolved.
+     */
+    getUnresolvedReason(): string;
+    /** {@inheritDoc ICondition.getSelector} */
+    getSelector(): ICondition.ISelector | null;
+    /** {@inheritDoc ICondition.getOperator} */
+    getOperator(): ICondition.IOperator | null;
+    /** {@inheritDoc ICondition.getParam} */
+    getParam(): P;
+    /** {@inheritDoc ICondition.isIncludeBlanks} */
+    isIncludeBlanks(): boolean;
+    /** {@inheritDoc ICondition.toString} */
+    toString(): string;
+    /** {@inheritDoc ICondition.toJSON} */
+    toJSON(): ICondition.JSON<P>;
+    /** {@inheritDoc ICondition.isICondition} */
+    get isICondition(): true;
+}
+/**
+ * Resolves a persisted condition. Unlike {@link resolveInput} this never throws.
+ *
+ * @remarks
+ * The load-time counterpart to {@link resolveInput}. A selector or operator the registry does not
+ * know yields an {@link UnresolvedCondition} — inert to evaluate, lossless to serialize — instead
+ * of an exception that costs the caller the entire rule.
+ */
+export declare function fromJSON<P = any>(json: ICondition.JSON<P> | null | undefined): ICondition<P> | null;
+/**
+ * Iterates through all values executing a single condition (`conditions[0]`) and calling the
+ * appropriate callbacks. Used by Data Validation and Conditional Formatting.
+ *
+ * @remarks
+ * For N conditions ANDed per row (`ICellRange.filter` / `ITable.filter`), see
+ * {@link evalRangeConditions}.
+ */
+export declare function evalConditions(options: DoRunConditionsOptions): Promise<void>;
+export interface DoRunRangeConditionsOptions extends ICondition.RangeOptions {
+    runtime: IRuntime;
+    /**
+     * {@inheritDoc DoRunConditionsOptions.calculation}
+     */
+    calculation?: ICalculation | null;
+    /**
+     * Backs {@link ICondition.IContext.watchFormula} — registers a watch for `expression` if the
+     * caller owns one, and returns its delivered values (or `null` until they arrive). Supplied by a
+     * long-lived owner; absent for a one-shot evaluation, which leaves the operator to evaluate for
+     * itself.
+     */
+    watchFormula?: ((expression: string) => MaybePromise<IRange | null>) | null;
+    values: ISparseGrid<Scalar>;
+    coords: Readonly<IRange.Coords>;
+    getHiddenRuns?: (axis: IRange.Axis) => readonly RunCoords[];
+    /**
+     * Called once per contiguous run of rows/columns (per {@link ICondition.RangeOptions.axis})
+     * that remain visible once every condition has been applied, in ascending order.
+     */
+    onVisibleRun?: (run: Readonly<RunCoords>) => void;
+    /**
+     * Called once per contiguous run of rows/columns that end up hidden once every condition has
+     * been applied, in ascending order.
+     */
+    onHiddenRun?: (run: Readonly<RunCoords>) => void;
+}
+/**
+ * Evaluates `conditions[]` in array order against the row (or column) axis, ANDing each condition
+ * into a running visibility mask — Excel's own AutoFilter model (DESIGN-FILTER.md §2): a dynamic
+ * condition (Average, Top N) only ever sees the rows/columns still visible under the mask
+ * accumulated by the conditions *before* it. Each condition carries its column (or row) via
+ * `IndexedProperties.index`, defaulting to its position in `conditions[]` when omitted — mirrors
+ * `ISort.Options.index ?? level`.
+ *
+ * @remarks
+ * Backs `ICellRange.filter` / `ITable.filter` (`_SheetFilterUtils.doFilter`). Data Validation and
+ * Conditional Formatting keep using the single-condition {@link evalConditions}.
+ */
+export declare function evalRangeConditions(options: DoRunRangeConditionsOptions): Promise<void>;
+export interface DoRunConditionsOptions extends ICondition.RangeOptions {
+    runtime: IRuntime;
+    /**
+     * The calculation engine backing {@link ICondition.IContext.createFormula} /
+     * {@link ICondition.IContext.resolveFormula}.
+     *
+     * @remarks
+     * Optional — a caller with no live workbook (e.g. a headless condition eval) simply gets a
+     * context where those two methods return `null` / the value unchanged, same as before either
+     * was implemented. See `ConditionContext.createFormula`.
+     */
+    calculation?: ICalculation | null;
+    /**
+     * Backs {@link ICondition.IContext.watchFormula} — registers a watch for `expression` if the
+     * caller owns one, and returns its delivered values (or `null` until they arrive). Supplied by a
+     * long-lived owner; absent for a one-shot evaluation, which leaves the operator to evaluate for
+     * itself.
+     */
+    watchFormula?: ((expression: string) => MaybePromise<IRange | null>) | null;
+    values: ISparseGrid<Scalar>;
+    coords: Readonly<IRange.Coords>;
+    getHiddenRuns?: (axis: IRange.Axis) => readonly RunCoords[];
+    /**
+     * Called on `true` condition.
+     */
+    onTrue?: (coords: IRange.CellCoords, value: Scalar) => void;
+    /**
+     * Called on `false` condition.
+     */
+    onFalse?: (coords: IRange.CellCoords, value: Scalar) => void;
+    /**
+     * Call on blank.
+     *
+     * @remarks
+     * Only called once.
+     * Only called if there is at least one blank.
+     */
+    onBlank?: (isTrue: boolean) => void;
+}
+//# sourceMappingURL=_ConditionUtils.d.ts.map

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

@@ -0,0 +1,3 @@
+export * from './ICondition';
+export * from './Condition';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,20 @@
+import { Scalar, IRange } from '@sheetxl/primitives';
+import { IProperties } from '../type';
+import { IStyle } from '../style';
+import { ISpatialMap } from '../collections/ISpatialMap';
+import { IConditionalFormat } from './IConditionalFormat';
+export declare class ConditionalEntry implements IProperties.ICellRanged<IStyle.Properties>, ISpatialMap.IUpdatableValue {
+    protected _c: IRange.Coords;
+    protected _m: IConditionalFormat;
+    constructor(coords: IRange.Coords, model: IConditionalFormat);
+    getModel(): IConditionalFormat;
+    /** {@inheritDoc IProperties.ICellRanged.getCoords} */
+    getCoords(): IRange.Coords;
+    /** {@inheritDoc IProperties.ICellRanged.getPropertiesAt} */
+    getPropertiesAt(rowIndex: number, colIndex: number, value: Scalar): Readonly<IStyle.Properties>;
+    /** {@inheritDoc IConditionalFormat.getDecorationAt} */
+    getDecorationAt(rowIndex: number, colIndex: number, value: Scalar): IConditionalFormat.Decoration | null;
+    /** {@inheritDoc ISpatialMap.IUpdatableValue.getSplit} */
+    getSplit(coords: readonly [IRange.Coords, IRange.Coords]): [this, this] | undefined;
+}
+//# sourceMappingURL=ConditionalEntry.d.ts.map

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

@@ -0,0 +1,190 @@
+import { Scalar, IRange } from '@sheetxl/primitives';
+import { ReferenceableClipboard } from '@sheetxl/utils';
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { ICellRange, ICellRanges } from '../cellRange';
+import { IStyle, IStyleCollection } from '../style';
+import { ISheet } from '../sheet';
+import { ISparseGrid, ISpatialMap } from '../collections';
+import { AnchoredConditional } from '../condition/AnchoredConditional';
+import { IConditionalFormat } from './IConditionalFormat';
+/**
+ * Implementation of {@link IConditionalFormat}.
+ */
+export declare class ConditionalFormat extends AnchoredConditional<State, CommitView, IConditionalFormat.Events> implements IConditionalFormat {
+    protected _styles: IStyleCollection;
+    protected _stylesRemoveListener: IListener.Remove | null;
+    protected _colorScale: PreparedColorScale | null;
+    protected _dataBar: PreparedDataBar | null;
+    protected _iconSet: PreparedIconSet | null;
+    protected _matches: ISparseGrid<boolean> | null;
+    /**
+     * What each `formula` stop currently resolves to, keyed by its expression — kept fresh by the
+     * watches {@link _syncStopWatches} registers, and read (never computed) while preparing a scale.
+     *
+     * @remarks
+     * A stop's formula usually points OUTSIDE the rule's own ranges (`=$Z$1`), which the rule's range
+     * listener cannot see. Resolving it during the prepare therefore answered once and then aged
+     * silently; a watch is what makes it keep answering.
+     */
+    protected _stopValues: Map<string, number | null>;
+    /** Removes for those watches, and the (anchor, expressions) pair they were registered for. */
+    protected _stopWatchRemoves: IListener.Remove[] | null;
+    protected _stopWatchKey: string | null;
+    /**
+     * Which round of prepares is current. Bumped once per {@link _processValueUpdates}; a prepare
+     * assigns its cache only if it is still the newest when it finishes.
+     *
+     * @remarks
+     * The four prepares are started fire-and-forget, so two rounds overlap whenever a change arrives
+     * while one is still resolving — and they do NOT finish in order. The realistic case is await
+     * DEPTH, not contention: the first round waits on a cold `calculation.ready()` inside a formula
+     * stop while the second finds it warm, finishes, and paints; the first then lands on top with its
+     * older read and stays there until something else changes. Watch callbacks re-enter here, so
+     * there are now two independent sources of rounds rather than one.
+     */
+    protected _prepareGeneration: number;
+    /** @internal */
+    protected _initialize(options: ConditionalFormat.ConstructorOptions): void;
+    /** @internal */
+    protected _getType(): string;
+    /** @internal */
+    protected _getActionDescription(action: 'delete' | 'initialize' | 'updateListener'): string | null;
+    /** @internal */
+    protected _getDefaultState(options: ConditionalFormat.ConstructorOptions): Readonly<State>;
+    /** @internal */
+    protected _processValueUpdates(_range?: ICellRange | null): void;
+    /**
+     * Resolves every stop to the number it stands for, in the order they were authored.
+     *
+     * @remarks
+     * A stop is a *description* of a threshold (`min`, `percentile 40`, a formula), not the threshold
+     * itself — resolving one needs the whole range's spread, which is why this is async and why the
+     * result is cached rather than recomputed per cell. A stop that cannot resolve (a formula that
+     * does not return a number, `min` over a range holding no numbers) yields `null` in its slot;
+     * callers decide whether that is fatal to their scale.
+     *
+     * Shared by all three scales, so `percentile` means one thing across them.
+     */
+    protected _resolveStopValues(ranges: ICellRanges, stops: IConditionalFormat.Stop[]): Promise<(number | null)[]>;
+    /**
+     * The cell a stop's formula is anchored at — the top-left of the rule's FIRST range, the same
+     * origin an `expression` rule's relative references shift from (and the origin the writer
+     * anchors a generated formula to).
+     */
+    protected _formulaAnchor(ranges: ICellRanges): Partial<IRange.CellCoords> | null;
+    /**
+     * Registers (or leaves alone) one watch per distinct `formula` stop.
+     *
+     * @remarks
+     * ONE value per expression for the whole rule, not one per cell: a stop is the gradient's domain,
+     * not a per-cell test, so each watch covers just the anchor cell. Relative references in a stop
+     * therefore mean what they mean AT the anchor — which is why the editor picks references for a
+     * stop as absolute.
+     *
+     * Idempotent, because `_processValueUpdates` calls it on every edit: watches are rebuilt only when
+     * the anchor moves or the set of expressions changes, never merely because a value did. A rule
+     * with no engine behind it (a standalone format, calculation `Off` and never woken) registers
+     * nothing and its formula stops resolve `null`, dropping out of the scale the way an unresolvable
+     * `min` does.
+     */
+    protected _syncStopWatches(ranges: ICellRanges, stops: IConditionalFormat.Stop[] | null): void;
+    /** @internal */
+    protected _removeStopWatches(): void;
+    /** @internal */
+    protected _processClose(): void;
+    _prepareColorScale(ranges: ICellRanges, colorScale: IConditionalFormat.ColorScaleStop[]): Promise<PreparedColorScale | null>;
+    /**
+     * Resolves a data bar's track once, so that a per-cell read is arithmetic.
+     *
+     * @remarks
+     * The two stops are the ends of the TRACK, not of the bar. Where zero falls between them is the
+     * axis, and that is what lets a negative bar grow leftward from it. `axisPosition` overrides
+     * that: `middle` pins the axis halfway however the data is spread, `none` drops the axis so
+     * every bar grows from the same edge.
+     */
+    protected _prepareDataBar(ranges: ICellRanges, dataBar: IConditionalFormat.DataBar): Promise<PreparedDataBar | null>;
+    /**
+     * Resolves an icon set's bands once, so that a per-cell read is a scan of at most five numbers.
+     *
+     * @remarks
+     * The first stop is the range's floor rather than a threshold — every value is at least in band
+     * 0 — so band selection tests stops `1..n`. `reverse` flips the answer, and a per-stop override
+     * re-points a band at a *different* set's icon, which is why the answer names the set it indexes.
+     */
+    protected _prepareIconSet(ranges: ICellRanges, iconSet: IConditionalFormat.IconSet): Promise<PreparedIconSet | null>;
+    /** {@inheritDoc IConditionalFormat.setStopIfTrue} */
+    setStopIfTrue(stopIfTrue: boolean, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IConditionalFormat.setStopIfTrue} */
+    isStopIfTrue(): boolean;
+    /** {@inheritDoc IConditionalFormat.getScale} */
+    getScale(): IConditionalFormat.Scale | null;
+    /** {@inheritDoc IConditionalFormat.getStyle} */
+    getStyle(): IStyle.Properties | null;
+    /**
+     * {@inheritDoc AnchoredConditional._rebaseAnchorFormulas}
+     *
+     * Scale rules keep their formulas in `formula`-type stops rather than the condition, so
+     * those rebase here.
+     * @internal
+     */
+    _rebaseAnchorFormulas(from: IRange.CellCoords, to: IRange.CellCoords): boolean;
+    /** {@inheritDoc IConditionalFormat.getSnapshot} */
+    getSnapshot(options?: ReferenceableClipboard.CopyOptions): IConditionalFormat.ISnapshot;
+    /** @internal */
+    protected _createSpatial(coords: IRange.Coords): ISpatialMap.IUpdatableValue;
+    /** {@inheritDoc IConditionalFormat.update} */
+    update(properties: IConditionalFormat.Modifiers, options?: ITransaction.OperationOptions): this;
+    /** {@inheritDoc IConditionalFormat.toJSON} */
+    toJSON(): IConditionalFormat.JSON | null;
+    /** @internal */
+    protected _fromJSON(json: IConditionalFormat.JSON): void;
+    /** {@inheritDoc IProperties.ICellRanged.getPropertiesAt} */
+    getPropertiesAt(rowIndex: number, colIndex: number, value: Scalar): Readonly<IStyle.Properties>;
+    /** {@inheritDoc IConditionalFormat.getDecorationAt} */
+    getDecorationAt(_rowIndex: number, _colIndex: number, value: Scalar): IConditionalFormat.Decoration | null;
+    /** {@inheritDoc IConditionalFormat.isIConditionalFormat} */
+    get isIConditionalFormat(): true;
+}
+export declare namespace ConditionalFormat {
+    interface ConstructorOptions extends AnchoredConditional.ConstructorOptions<IConditionalFormat.JSON> {
+        sheet?: ISheet;
+    }
+}
+interface State extends AnchoredConditional.State {
+    /**
+     * The differential style applied where the condition holds.
+     *
+     * @remarks
+     * Mutually exclusive with {@link State.scale} — a rule either tests cells and formats them, or
+     * renders across the range itself.
+     */
+    style: IStyle.Properties | null;
+    scale: IConditionalFormat.Scale | null;
+    stopIfTrue: boolean;
+    pivot: boolean;
+    /** Opaque third-party payload. Carried, never interpreted. */
+    ext: Record<string, unknown> | null;
+}
+interface CommitView extends AnchoredConditional.CommitView {
+}
+type RGB = readonly [number, number, number];
+interface ResolvedStop {
+    v: number;
+    rgb: RGB;
+    exclusive: boolean;
+}
+interface PreparedColorScale {
+    stops: ResolvedStop[];
+    colorFor(value: number): string;
+}
+interface PreparedDataBar {
+    /** Places a value on the resolved track. Total, because the track's ends are already known. */
+    barFor(value: number): IConditionalFormat.DataBarDecoration;
+}
+interface PreparedIconSet {
+    /** Picks the value's band. `null` where the band is an explicit "no icon" override. */
+    iconFor(value: number): IConditionalFormat.IconSetDecoration | null;
+}
+export {};
+//# sourceMappingURL=ConditionalFormat.d.ts.map

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

@@ -0,0 +1,20 @@
+import { ICellRanges } from '../cellRange';
+import { IConditionalFormatCollection } from './IConditionalFormatCollection';
+import { IConditionalFormat } from './IConditionalFormat';
+export declare class ConditionalFormatCollection implements IConditionalFormatCollection {
+    private _add;
+    private _get;
+    private _createItem;
+    constructor(add: (address: ICellRanges.Address | IConditionalFormat, options?: IConditionalFormatCollection.AddOptions) => IConditionalFormat, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IConditionalFormat[], createItem: (template?: IConditionalFormat | null) => IConditionalFormat);
+    /** {@inheritDoc IConditionalFormatCollection.add} */
+    add(address: ICellRanges.Address | IConditionalFormat, options?: IConditionalFormatCollection.AddOptions): IConditionalFormat;
+    /** {@inheritDoc ICollection.[Symbol.iterator]} */
+    [Symbol.iterator](): IterableIterator<IConditionalFormat>;
+    /** {@inheritDoc IConditionalFormatCollection.getItems} */
+    getItems(options?: IConditionalFormatCollection.GetItemsOptions): IConditionalFormat[];
+    /** {@inheritDoc IConditionalFormatCollection.createItem} */
+    createItem(template?: IConditionalFormat | null): IConditionalFormat;
+    /** {@inheritDoc IConditionalFormatCollection.getCount} */
+    getCount(): number;
+}
+//# sourceMappingURL=ConditionalFormatCollection.d.ts.map