@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.10

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

@@ -0,0 +1,152 @@
+import { IRange, Scalar } from '@sheetxl/primitives';
+import { ITransaction } from '../transaction';
+import { ICellRanges, ICellRange } from '../cellRange';
+import { ICalculation } from '../calculation/ICalculation';
+import { FormulaHost } from '../calculation/grid';
+/**
+ * What a condition formula needs from the rule that owns it: the engine to compile with, and the
+ * cell — and sheet — its text is authored at.
+ */
+export interface ConditionFormulaBinding {
+    getCalculation(): ICalculation | null;
+    getAnchor(): IRange.CellCoords | null;
+    /** The display name of the sheet the rule is on. */
+    getScope(): string | null;
+}
+/**
+ * `text` (as a view images it at `at`) imaged through `transform`, or the text itself when there
+ * is no transform, the text does not parse, or the transform changes nothing.
+ */
+export declare function imageTransformed(text: string, at: IRange.CellCoords, transform: ICalculation.FormulaTransform | undefined): string;
+/** Drops the qualifier from a cell reference to `sheetName`, so it reads as authored on that sheet. */
+export declare function unqualifyTransform(sheetName: string): ICalculation.FormulaTransform;
+/**
+ * Compiles storage `text` at `anchor`, or `null` when the engine cannot compile yet.
+ */
+export declare function createStoredFormula(calculation: ICalculation, text: string, anchor: Partial<IRange.CellCoords> | null): ICalculation.IFormula | null;
+/**
+ * A formula held by a condition — an `expression` param, a comparison operand, a between bound.
+ *
+ * @remarks
+ * Its text is CANONICAL, and once the owning rule watches it the engine holds the body: the text is
+ * then read back from the watch's body on every access, so what the engine did to the body — a row
+ * insert, a sheet rename, an undo — is what the condition reports and what `toJSON` persists. Before
+ * that (no engine, a standalone condition) it answers from the text it was created with, and it keeps
+ * the last text the body had when the watch goes away.
+ *
+ * The rest of {@link ICalculation.IFormula} is a detached formula compiled from that text, with the
+ * storage compiler, at the rule's anchor.
+ */
+export declare class ConditionFormula implements ICalculation.IFormula {
+    protected _text: string;
+    protected readonly _marked: boolean;
+    protected _host: FormulaHost | null;
+    protected _binding: ConditionFormulaBinding | null;
+    protected _compiled: {
+        key: string;
+        formula: ICalculation.IFormula;
+    } | null;
+    /**
+     * @param text Canonical formula text, with or without a leading `=`.
+     * @param marked Whether the slot spells the formula with a leading `=` on the wire (a comparison
+     * operand, a between bound) or bare (an `expression` param).
+     */
+    constructor(text: string, marked: boolean);
+    /** Whether the wire form carries the leading `=`. */
+    isMarked(): boolean;
+    /** @internal */
+    bind(binding: ConditionFormulaBinding | null): void;
+    /**
+     * Reads the text from `host`'s body from now on; `null` stops, keeping the body's last text.
+     * @internal
+     */
+    bindHost(host: FormulaHost | null): void;
+    protected _readHost(host: FormulaHost): string | null;
+    /** The transform the body's text is imaged through; see {@link _readHost}. */
+    protected _readTransform(scope: string | null): ICalculation.FormulaTransform | undefined;
+    /** The canonical text, without a leading `=`. */
+    getText(): string;
+    protected _formula(): ICalculation.IFormula | null;
+    /** {@inheritDoc ICalculation.IFormula.evaluate} */
+    evaluate(options?: number | ICalculation.EvaluateOptions): Promise<Scalar | IRange>;
+    /** {@inheritDoc ICalculation.IFormula.getCalculationStatus} */
+    getCalculationStatus(): ICalculation.ResultStatus;
+    /** {@inheritDoc ICalculation.IFormula.isCompiled} */
+    isCompiled(): boolean;
+    /** {@inheritDoc ICalculation.IFormula.getExpression} */
+    getExpression(options?: ICalculation.FormulaTextOptions): string;
+    /** {@inheritDoc ICalculation.IFormula.getAnchor} */
+    getAnchor(): IRange.CellCoords | null;
+    /** {@inheritDoc ICalculation.IFormula.shift} */
+    shift(target: IRange.CellCoords): ICalculation.IFormula | null;
+    /** {@inheritDoc ICalculation.IFormula.getReferences} */
+    getReferences(): ICellRanges | null;
+    /** {@inheritDoc ICalculation.IFormula.hasRefError} */
+    hasRefError(): boolean;
+    /**
+     * {@inheritDoc ICalculation.IFormula.setReferenceAt}
+     *
+     * @remarks
+     * Not supported: a condition's formula changes by setting the condition.
+     */
+    setReferenceAt(_index: number, _reference: ICellRange.Address, _options?: string | ITransaction.OperationOptions): Promise<this>;
+    /**
+     * {@inheritDoc ICalculation.IFormula.setReferenceModeAt}
+     *
+     * @remarks
+     * Not supported: a condition's formula changes by setting the condition.
+     */
+    setReferenceModeAt(_index: number, _side?: ICalculation.ReferenceSide, _mode?: number, _options?: string | ITransaction.OperationOptions): Promise<this>;
+    /** {@inheritDoc ICalculation.IFormula.isReferenceOnly} */
+    isReferenceOnly(): boolean;
+    /** {@inheritDoc ICalculation.IFormula.isVolatile} */
+    isVolatile(): Promise<boolean>;
+    /** {@inheritDoc ICalculation.IFormula.getTokens} */
+    getTokens(evalIndex?: number): readonly ICalculation.FormulaToken[];
+    /** {@inheritDoc ICalculation.IFormula.isValid} */
+    isValid(): boolean;
+    /** {@inheritDoc ICalculation.IFormula.autoCorrect} */
+    autoCorrect(): ICalculation.IFormula | null;
+    /** The wire form: canonical text, `=`-prefixed for a marked slot. */
+    toJSON(): string;
+    /** The expression, `=`-prefixed for a marked slot. */
+    toString(): string;
+    get [Symbol.toStringTag](): string;
+    /** {@inheritDoc ICalculation.IFormula.isIFormula} */
+    get isIFormula(): true;
+}
+/**
+ * The live base of a set (`inSet`'s `source`): a reference, a name, or a formula whose result is
+ * the list.
+ *
+ * @remarks
+ * What the rule WATCHES is not the source but the check Excel makes with it,
+ * `ISNUMBER(MATCH(<cell>, <source>, 0))`: `MATCH`'s exact mode is Excel's list-validation rule
+ * (wildcards, text case-insensitive, type strict), and as a per-cell formula it resolves a
+ * relative source (`INDIRECT($E11)`) against each cell's own row the way every condition formula
+ * does. The text this holds is still the source's: read back from the watched body with the root
+ * swapped for `MATCH`'s second argument, so a row insert above the source moves the source here
+ * as it does any condition formula.
+ */
+export declare class ListSourceFormula extends ConditionFormula {
+    constructor(text: string);
+    /**
+     * The per-cell check, authored at `at`: `<cell>` is `at` itself, relative, so a fill to each
+     * cell tests that cell's own value.
+     *
+     * @remarks
+     * A source that does not compile on its own fails every cell (`FALSE`) rather than being spliced
+     * in: an unclosed one (`OFFSET($A$1,0,0,3`) would take the check's own `,0))` as its arguments,
+     * and the text read back from the check would carry them.
+     */
+    getCheckExpression(at: IRange.CellCoords): string;
+    /**
+     * Not for a source that does not compile: its check does not hold it (see
+     * {@link getCheckExpression}), so its text stays as authored.
+     */
+    bindHost(host: FormulaHost | null): void;
+    /** {@inheritDoc ConditionFormula._readTransform} */
+    protected _readTransform(scope: string | null): ICalculation.FormulaTransform | undefined;
+    get [Symbol.toStringTag](): string;
+}
+//# sourceMappingURL=_ConditionFormula.d.ts.map

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

@@ -3,6 +3,7 @@ import { RunCoords, MaybePromise } from '@sheetxl/utils';
 import { ISparseGrid } from '../collections';
 import { ICalculation } from '../calculation';
 import { ICondition } from './ICondition';
+import { ConditionFormula } from './_ConditionFormula';
 export declare class ConditionOperator<P = any> implements ICondition.IOperator<P> {
     protected _delegate: ICondition.IOperator;
     protected _types: readonly (InteropScalarType | null)[] | null;
@@ -13,8 +14,6 @@ export declare class ConditionOperator<P = any> implements ICondition.IOperator<
     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} */
@@ -24,7 +23,9 @@ export declare class ConditionOperator<P = any> implements ICondition.IOperator<
     /** {@inheritDoc ICondition.getDescription} */
     getDescription(): string | null;
     /** {@inheritDoc ICondition.createDefaultParam} */
-    createDefaultParam(lhsSelector?: ICondition.ISelector): P | null | undefined;
+    createDefaultParam(lhsSelector?: ICondition.ISelector, context?: ICondition.DefaultConditionContext): P | null | undefined;
+    /** {@inheritDoc ICondition.IOperator.validateParam} */
+    validateParam(param: P, lhsSelector?: ICondition.ISelector | null): string | null;
     /** {@inheritDoc ICondition.doBatch} */
     doBatch(keys: Set<any>, param: P, ctx: ICondition.IContext): MaybePromise<IRange<boolean> | null> | undefined;
     /** {@inheritDoc ICondition.toString} */
@@ -48,6 +49,56 @@ export declare function encodeParamJSON(param: any): any;
  * are left encoded — they decode when their own input resolves.
  */
 export declare function decodeParamJSON(param: any): any;
+/**
+ * The operators whose Scalar param may be a `=`-prefixed formula operand. The text rules
+ * (`textContains` &c.) are not among them: their param is text by type.
+ */
+export declare const FormulaOperandOperators: ReadonlySet<string>;
+/**
+ * Lifts the formula slots of `param`, for `operatorName`, into {@link ConditionFormula}s: an
+ * `expression` param, a `=`-prefixed comparison operand, a between bound, an `inSet`'s live base,
+ * and the same inside a combinator's raw children. An `IFormula` is taken by its canonical text.
+ */
+export declare function liftFormulaParam(operatorName: string | null | undefined, param: any): any;
+/**
+ * An `inSet` param with each part under its own name (see {@link ICondition.InSetOption}), or
+ * `param` itself when it already is.
+ *
+ * @remarks
+ * `items` once carried all three kinds of list, told apart by the spelling of a string. Those
+ * spellings are still read, here and nowhere else: a quoted literal (`"Yes,No"`) is `additions`,
+ * any other text is a `source`, and a bare string param is `items` holding it.
+ */
+export declare function normalizeInSetParam(param: any): any;
+/**
+ * Whether `text` is a list LITERAL (`"a,b,c"`): one string token, a doubled quote inside being one
+ * quote. Anything else is a reference or a formula whose result is the list.
+ */
+export declare function isListLiteral(text: string): boolean;
+/**
+ * The items of a list literal, or `null` when `text` is not one (see {@link isListLiteral}).
+ *
+ * @remarks
+ * Excel's reading: the string's doubled quotes become one quote, then the whole is split on `,`
+ * with no quoting inside, so `"q,r",s` is the three items `"q`, `r"` and `s`. The items are returned
+ * as stored, spaces and all; matching is {@link createListLiteralMatcher}'s business.
+ */
+export declare function parseListLiteral(text: string): string[] | null;
+/**
+ * `items` spelled as a list literal (`"a,b,c"`), the inverse of {@link parseListLiteral}: items kept
+ * as given, a quote doubled. `null` when an item holds `,`, which a literal has no way to spell.
+ */
+export declare function formatListLiteral(items: readonly string[]): string | null;
+/**
+ * Whether a cell's `text` is on a literal list, the way Excel checks one: the text trimmed of
+ * spaces, against each item with its LEADING spaces dropped, case-sensitively. An item with a
+ * trailing space can therefore never match, as in Excel.
+ */
+export declare function createListLiteralMatcher(items: readonly string[]): (text: string) => boolean;
+/**
+ * Visits every {@link ConditionFormula} a condition holds, at any combinator depth.
+ */
+export declare function forEachConditionFormula(condition: ICondition | null | undefined, visit: (formula: ConditionFormula) => void): void;
 export declare function resolveInput(condition: ICondition.Input | null): ICondition | null;
 /**
  * A condition whose selector or operator is not in the registry.
@@ -83,6 +134,8 @@ export declare class UnresolvedCondition<P = any> implements ICondition<P> {
     getParam(): P;
     /** {@inheritDoc ICondition.isIncludeBlanks} */
     isIncludeBlanks(): boolean;
+    /** {@inheritDoc ICondition.validate} */
+    validate(): string | null;
     /** {@inheritDoc ICondition.toString} */
     toString(): string;
     /** {@inheritDoc ICondition.toJSON} */
@@ -99,6 +152,78 @@ export declare class UnresolvedCondition<P = any> implements ICondition<P> {
  * 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;
+/**
+ * A combinator's reading of a value through a child's selector, as the driver reads one for the
+ * root: the transformer gates and projects a value, and a blank (`null`, which reaches a
+ * predicate only with Ignore Blank off) is read by no selector. It passes on as it is, for the
+ * operator to judge as Excel judges an empty cell (0 under a number rule, "" under a text one;
+ * P7, DESIGN-DV §5). Display in particular must not turn it into the empty text it shows.
+ */
+export declare function readThroughSelector(transformer: ICondition.Transformer<any, any> | null | undefined, value: Scalar, ctx: ICondition.IContext): Scalar | typeof ICondition.NotApplicable;
+/**
+ * The condition's answer for the BLANK cells of a range, asked per cell — lazily, by the caller,
+ * for the cells it actually reads. Blank cells are never visited by the engine.
+ */
+export type BlankResolver = (rowIndex: number, colIndex: number) => boolean;
+/**
+ * Whether a value is blank by Excel's AutoFilter rule (`LEN(TRIM(x))=0`, DESIGN-FILTER.md §3.3):
+ * nothing, an empty string, or a string of only U+0020 spaces. A tab, a non-breaking space, `0`
+ * and an error are values.
+ */
+export declare function isBlankValue(value: Scalar): boolean;
+/**
+ * The calc engine's blank: an empty cell, or the `""` a formula returns (`=A1=""` is TRUE for
+ * both). A string of spaces is a string. The filter's rule for a value-shaped level
+ * (DESIGN-FILTER §3.3); {@link isBlankValue} is the display rule.
+ */
+export declare function isBlankByValue(value: Scalar): boolean;
+/** Whether a selector, by name or instance, is {@link ICondition.BuiltInSelectorNames.Display}. */
+export declare function isDisplaySelector(selector: unknown): boolean;
+/**
+ * Whether a filter level reads displayed text somewhere in it — a leaf under the Display
+ * selector, at the top or inside a combinator — and so takes the display rule for blanks (a
+ * string of only spaces is a blank cell). Anything else takes the calc engine's.
+ */
+export declare function isDisplayShaped(condition: ICondition | ICondition.JSON | null | undefined): boolean;
+/**
+ * Options for {@link evalConditionAt}.
+ */
+export interface EvalConditionAtOptions {
+    runtime: IRuntime;
+    /**
+     * The engine the condition's formulas are evaluated by. Absent, a formula answers nothing and
+     * its condition is inert (passes).
+     */
+    calculation?: ICalculation | null;
+    /**
+     * {@inheritDoc DoRunConditionsOptions.watchFormula}
+     *
+     * Here a one-shot caller's hook: it may answer `undefined` to leave a formula to the context,
+     * which evaluates it once as a temporary formula at the cell.
+     */
+    watchFormula?: ((formula: ICalculation.IFormula | string) => MaybePromise<IRange | null> | undefined) | null;
+    /**
+     * Where the condition's formulas were authored: the first cell of the rule's area the cell is in.
+     * A formula is shifted from there to the cell, as the rule's own evaluation reads it there.
+     *
+     * @defaultValue the cell itself
+     */
+    anchor?: IRange.CellCoords;
+}
+/**
+ * Whether `value` would pass `condition` at `cell`: the check a cell editor makes before it writes,
+ * for a value that is not in any grid.
+ *
+ * @remarks
+ * The judgment {@link evalConditions} makes per cell, made once: the selector gates and projects
+ * the value, the operator's predicate answers, and a deferring operator is settled with its one
+ * key. A blank (`null`) answers as the rule answers a blank cell: `true` with Ignore Blank, else
+ * what the predicate says of `null`. An inert condition (no operator) passes.
+ *
+ * The condition's formulas are temporary ones, evaluated at the cell and discarded; nothing is
+ * registered with the engine or kept on the condition.
+ */
+export declare function evalConditionAt(condition: ICondition, value: Scalar, cell: IRange.CellCoords, options: EvalConditionAtOptions): Promise<boolean>;
 /**
  * Iterates through all values executing a single condition (`conditions[0]`) and calling the
  * appropriate callbacks. Used by Data Validation and Conditional Formatting.
@@ -120,10 +245,16 @@ export interface DoRunRangeConditionsOptions extends ICondition.RangeOptions {
      * long-lived owner; absent for a one-shot evaluation, which leaves the operator to evaluate for
      * itself.
      */
-    watchFormula?: ((expression: string) => MaybePromise<IRange | null>) | null;
+    watchFormula?: ((formula: ICalculation.IFormula | string) => MaybePromise<IRange | null>) | null;
     values: ISparseGrid<Scalar>;
     coords: Readonly<IRange.Coords>;
     getHiddenRuns?: (axis: IRange.Axis) => readonly RunCoords[];
+    /**
+     * The text a cell shows, backing {@link ICondition.IContext.getDisplayText}. Supplied by the
+     * sheet; asked only for the cells an operator matching displayed text reads. `value` is the
+     * cell's, which the driver holds already.
+     */
+    getDisplayText?: (rowIndex: number, colIndex: number, value: Scalar) => string;
     /**
      * 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.
@@ -135,6 +266,15 @@ export interface DoRunRangeConditionsOptions extends ICondition.RangeOptions {
      */
     onHiddenRun?: (run: Readonly<RunCoords>) => void;
 }
+/**
+ * The `RangeOptions` a filter call means: a bare `ICondition.Input` is one condition at index 0
+ * (the JSDoc example on `ICellRange.filter`), a `RangeOptions` (identified by its `conditions`
+ * array) passes through unchanged, and nothing is an empty list.
+ *
+ * @remarks
+ * Shared by `ICellRange.filter` and `ITable.filter`, so a bare input means the same to both.
+ */
+export declare function normalizeFilterInput(condition: ICondition.Input | ICondition.RangeOptions | null | undefined): ICondition.RangeOptions;
 /**
  * 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
@@ -151,13 +291,12 @@ export declare function evalRangeConditions(options: DoRunRangeConditionsOptions
 export interface DoRunConditionsOptions extends ICondition.RangeOptions {
     runtime: IRuntime;
     /**
-     * The calculation engine backing {@link ICondition.IContext.createFormula} /
-     * {@link ICondition.IContext.resolveFormula}.
+     * The calculation engine backing {@link ICondition.IContext.createFormula} and the unwatched
+     * fallback of {@link ICondition.IContext.watchFormula}.
      *
      * @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`.
+     * context where both return `null`. See `ConditionContext.createFormula`.
      */
     calculation?: ICalculation | null;
     /**
@@ -166,7 +305,7 @@ export interface DoRunConditionsOptions extends ICondition.RangeOptions {
      * long-lived owner; absent for a one-shot evaluation, which leaves the operator to evaluate for
      * itself.
      */
-    watchFormula?: ((expression: string) => MaybePromise<IRange | null>) | null;
+    watchFormula?: ((formula: ICalculation.IFormula | string) => MaybePromise<IRange | null>) | null;
     values: ISparseGrid<Scalar>;
     coords: Readonly<IRange.Coords>;
     getHiddenRuns?: (axis: IRange.Axis) => readonly RunCoords[];
@@ -179,12 +318,27 @@ export interface DoRunConditionsOptions extends ICondition.RangeOptions {
      */
     onFalse?: (coords: IRange.CellCoords, value: Scalar) => void;
     /**
-     * Call on blank.
+     * How to answer for the BLANK cells of `coords`, delivered ONCE per evaluation and only when
+     * the range has at least one.
      *
      * @remarks
-     * Only called once.
-     * Only called if there is at least one blank.
+     * Blank cells are not stored and are never visited. What the caller gets is a reader to ask per
+     * cell, lazily, for the cells it actually reads — a render asks for the cells on screen — so the
+     * evaluation itself costs nothing for them however many there are. A reader rather than one
+     * precomputed answer because the answer can differ per blank: an `expression` shifts its
+     * references with the cell, so `Key!B3="#"` over an all-blank grid is TRUE in some cells and
+     * FALSE in others, and the formula's own block evaluation already holds each one.
+     */
+    onBlank?: (resolve: BlankResolver) => void;
+    /**
+     * Whether a stored value that is blank by Excel's AutoFilter rule ({@link isBlankValue}: a
+     * `""` result, a string of only spaces) is answered as the blank cell it shows as, never shown
+     * to the selector or the operator. Conditional Formatting sets it (`containsBlanks` is
+     * `LEN(TRIM(x))=0`); Data Validation does not, since there a blank is an empty cell and a
+     * `""` result is judged (DESIGN-DV §5). The filter driver decides per level: a display-shaped
+     * one ({@link isDisplayShaped}) takes this rule, any other the calc engine's, where only `""`
+     * is blank (DESIGN-FILTER §3.3).
      */
-    onBlank?: (isTrue: boolean) => void;
+    spacesAreBlank?: boolean;
 }
 //# sourceMappingURL=_ConditionUtils.d.ts.map

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

@@ -1,9 +1,9 @@
 import { Scalar, IRange } from '@sheetxl/primitives';
 import { IProperties } from '../type';
-import { IStyle } from '../style';
+import { ICellStyle } from '../style';
 import { ISpatialMap } from '../collections/ISpatialMap';
 import { IConditionalFormat } from './IConditionalFormat';
-export declare class ConditionalEntry implements IProperties.ICellRanged<IStyle.Properties>, ISpatialMap.IUpdatableValue {
+export declare class ConditionalEntry implements IProperties.ICellRanged<ICellStyle.Properties>, ISpatialMap.IUpdatableValue {
     protected _c: IRange.Coords;
     protected _m: IConditionalFormat;
     constructor(coords: IRange.Coords, model: IConditionalFormat);
@@ -11,7 +11,7 @@ export declare class ConditionalEntry implements IProperties.ICellRanged<IStyle.
     /** {@inheritDoc IProperties.ICellRanged.getCoords} */
     getCoords(): IRange.Coords;
     /** {@inheritDoc IProperties.ICellRanged.getPropertiesAt} */
-    getPropertiesAt(rowIndex: number, colIndex: number, value: Scalar): Readonly<IStyle.Properties>;
+    getPropertiesAt(rowIndex: number, colIndex: number, value: Scalar): Readonly<ICellStyle.Properties>;
     /** {@inheritDoc IConditionalFormat.getDecorationAt} */
     getDecorationAt(rowIndex: number, colIndex: number, value: Scalar): IConditionalFormat.Decoration | null;
     /** {@inheritDoc ISpatialMap.IUpdatableValue.getSplit} */

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

@@ -1,17 +1,20 @@
-import { Scalar, IRange } from '@sheetxl/primitives';
+import { IRange, Scalar } 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 { ICellStyle, IStyleCollection } from '../style';
 import { ISheet } from '../sheet';
 import { ISparseGrid, ISpatialMap } from '../collections';
+import { ICalculation } from '../calculation';
+import { BlankResolver } from '../condition/_ConditionUtils';
+import { ConditionFormula } from '../condition/_ConditionFormula';
 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 {
+export declare class ConditionalFormat extends AnchoredConditional<State, IConditionalFormat.Events> implements IConditionalFormat {
     protected _styles: IStyleCollection;
     protected _stylesRemoveListener: IListener.Remove | null;
     protected _colorScale: PreparedColorScale | null;
@@ -19,7 +22,16 @@ export declare class ConditionalFormat extends AnchoredConditional<State, Commit
     protected _iconSet: PreparedIconSet | null;
     protected _matches: ISparseGrid<boolean> | null;
     /**
-     * What each `formula` stop currently resolves to, keyed by its expression — kept fresh by the
+     * How to answer for the BLANK cells, one reader per anchored area, asked per cell read. Blanks
+     * are never materialized into `_matches`: a rule over a whole empty column is one entry here,
+     * not a million there.
+     */
+    protected _blankResolvers: {
+        area: IRange.Coords;
+        resolve: BlankResolver;
+    }[] | null;
+    /**
+     * What each `formula` stop currently resolves to, keyed by its formula — kept fresh by the
      * watches {@link _syncStopWatches} registers, and read (never computed) while preparing a scale.
      *
      * @remarks
@@ -27,9 +39,10 @@ export declare class ConditionalFormat extends AnchoredConditional<State, Commit
      * 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 _stopValues: Map<ICalculation.IFormula, number | null>;
+    /** Removes for those watches, the formulas they hold, and the (anchor, formulas) pair they were registered for. */
     protected _stopWatchRemoves: IListener.Remove[] | null;
+    protected _stopWatchFormulas: ConditionFormula[] | null;
     protected _stopWatchKey: string | null;
     /**
      * Which round of prepares is current. Bumped once per {@link _processValueUpdates}; a prepare
@@ -68,9 +81,9 @@ export declare class ConditionalFormat extends AnchoredConditional<State, Commit
      */
     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).
+     * The cell a stop's formula is anchored at — the top-left of the bounding box of the rule's
+     * ranges, 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;
     /**
@@ -120,7 +133,7 @@ export declare class ConditionalFormat extends AnchoredConditional<State, Commit
     /** {@inheritDoc IConditionalFormat.getScale} */
     getScale(): IConditionalFormat.Scale | null;
     /** {@inheritDoc IConditionalFormat.getStyle} */
-    getStyle(): IStyle.Properties | null;
+    getStyle(): ICellStyle.Properties | null;
     /**
      * {@inheritDoc AnchoredConditional._rebaseAnchorFormulas}
      *
@@ -147,7 +160,7 @@ export declare class ConditionalFormat extends AnchoredConditional<State, Commit
     /** @internal */
     protected _fromJSON(json: IConditionalFormat.JSON): void;
     /** {@inheritDoc IProperties.ICellRanged.getPropertiesAt} */
-    getPropertiesAt(rowIndex: number, colIndex: number, value: Scalar): Readonly<IStyle.Properties>;
+    getPropertiesAt(rowIndex: number, colIndex: number, value: Scalar): Readonly<ICellStyle.Properties>;
     /** {@inheritDoc IConditionalFormat.getDecorationAt} */
     getDecorationAt(_rowIndex: number, _colIndex: number, value: Scalar): IConditionalFormat.Decoration | null;
     /** {@inheritDoc IConditionalFormat.isIConditionalFormat} */
@@ -166,15 +179,13 @@ interface State extends AnchoredConditional.State {
      * Mutually exclusive with {@link State.scale} — a rule either tests cells and formats them, or
      * renders across the range itself.
      */
-    style: IStyle.Properties | null;
+    style: ICellStyle.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;

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

@@ -1,20 +1,31 @@
 import { ICellRanges } from '../cellRange';
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
 import { IConditionalFormatCollection } from './IConditionalFormatCollection';
 import { IConditionalFormat } from './IConditionalFormat';
-export declare class ConditionalFormatCollection implements IConditionalFormatCollection {
+/**
+ * Implementation for {@link IConditionalFormatCollection}.
+ *
+ * @remarks
+ * A front over the sheet's own conditional-format state — the sheet keeps the store and the
+ * events, this class keeps the API. `onCollectionChange` is the sheet's
+ * `onConditionalFormatsChange`, forwarded with this collection as the source.
+ */
+export declare class ConditionalFormatCollection extends AbstractCollection<IConditionalFormat, IConditionalFormatCollection.GetItemsOptions> 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);
+    private _addListeners;
+    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, addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove);
     /** {@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 AbstractCollection._getItems} */
+    protected _getItems(options?: IConditionalFormatCollection.GetItemsOptions): IConditionalFormat[];
     /** {@inheritDoc IConditionalFormatCollection.createItem} */
     createItem(template?: IConditionalFormat | null): IConditionalFormat;
-    /** {@inheritDoc IConditionalFormatCollection.getCount} */
-    getCount(): number;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IConditionalFormatCollection.isIConditionalFormatCollection} */
+    get isIConditionalFormatCollection(): true;
 }
 //# sourceMappingURL=ConditionalFormatCollection.d.ts.map

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

@@ -6,8 +6,9 @@ import { IHistory } from '../history';
 import { IAnchored } from '../anchored';
 import { ICellRanges } from '../cellRange';
 import { IListener } from '../listener';
+import { ICalculation } from '../calculation';
 import { ICondition } from '../condition';
-import { IStyle } from '../style';
+import { ICellStyle } from '../style';
 import { IConditionalFormatCollection } from './IConditionalFormatCollection';
 /**
  * Represents a conditional formatting rule for a range.
@@ -21,7 +22,7 @@ import { IConditionalFormatCollection } from './IConditionalFormatCollection';
  * * Conditional formatting help users identify patterns, trends, and exceptions
  *   in data by applying visual styles dynamically.
  */
-export interface IConditionalFormat extends IAnchored, ICondition.Stateful, IProperties.ICellRanged<IStyle.Properties> {
+export interface IConditionalFormat extends IAnchored, ICondition.Stateful, IProperties.ICellRanged<ICellStyle.Properties> {
     /**
      * Re-anchors this rule to `address`, REPLACING every range it currently covers.
      *
@@ -97,7 +98,7 @@ export interface IConditionalFormat extends IAnchored, ICondition.Stateful, IPro
      * @remarks
      * The OOXML `dxf`, inlined. A differential format: only the properties it names are overridden.
      */
-    getStyle(): IStyle.Properties | null;
+    getStyle(): ICellStyle.Properties | null;
     /**
      * Returns what this rule draws in a cell, or `null` if it draws nothing there.
      *
@@ -241,10 +242,11 @@ export declare namespace IConditionalFormat {
          *   - Num: absolute number
          *   - Percent: 0..100 of min..max span
          *   - Percentile: 0..100 quantile (requires percentile stats)
-         * * For strings:
-         * - Formula: a formula that evaluates to a string value.
+         * * For formulas:
+         * - Formula: a formula whose result is the threshold. Authored as formula text or an
+         *   {@link ICalculation.IFormula}; a rule holds it as an `IFormula`.
          */
-        value?: number | string;
+        value?: number | string | ICalculation.IFormula;
         /**
          * Upper bound exclusivity.
          *
@@ -338,13 +340,13 @@ export declare namespace IConditionalFormat {
          * from and its zero-based index within that set.
          */
         icon?: {
-            set: IStyle.IconSet;
+            set: ICellStyle.IconSet;
             id: number;
         }[];
         /**
          * The icon set to use
          */
-        iconSet?: IStyle.IconSet;
+        iconSet?: ICellStyle.IconSet;
         reverse?: boolean;
         /**
          * If true, the value will be shown in the cell.
@@ -406,7 +408,7 @@ export declare namespace IConditionalFormat {
         /** Which band the value fell in. `0` is the lowest band, matching `stops[0]`. */
         index: number;
         /** The set {@link index} indexes into — the rule's own, or a per-stop override. */
-        set: IStyle.IconSet;
+        set: ICellStyle.IconSet;
         /** How many bands {@link set} has, so a renderer can bounds-check {@link index}. */
         count: number;
         /** Draw the cell's value beside the icon. When `false` the icon is the cell's only content. */
@@ -449,7 +451,7 @@ export declare namespace IConditionalFormat {
         /**
          * The differential style applied where the condition holds.
          */
-        style?: IStyle.Properties;
+        style?: ICellStyle.Properties;
         /**
          * The value→visual mapping, for the three rules that are not predicates.
          *