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

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 source of a list condition (`inSet` with formula text for its items): 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;
@@ -48,6 +49,46 @@ 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, 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;
+/**
+ * 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.
@@ -99,6 +140,15 @@ 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;
+/**
+ * Per-condition options shared by the single-condition ({@link evalConditions}) and
+ * multi-condition ({@link evalRangeConditions}) drivers.
+ */
+/**
+ * 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;
 /**
  * Iterates through all values executing a single condition (`conditions[0]`) and calling the
  * appropriate callbacks. Used by Data Validation and Conditional Formatting.
@@ -120,7 +170,7 @@ 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[];
@@ -135,6 +185,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 +210,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 +224,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 +237,17 @@ 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?: (isTrue: boolean) => void;
+    onBlank?: (resolve: BlankResolver) => void;
 }
 //# sourceMappingURL=_ConditionUtils.d.ts.map

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

@@ -1,4 +1,4 @@
-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';
@@ -6,12 +6,15 @@ import { ICellRange, ICellRanges } from '../cellRange';
 import { IStyle, 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;
     /**
@@ -173,8 +186,6 @@ interface State extends AnchoredConditional.State {
     /** 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,6 +6,7 @@ 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 { IConditionalFormatCollection } from './IConditionalFormatCollection';
@@ -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.
          *

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

@@ -27,6 +27,8 @@ export interface IConditionalFormatCollection extends ICollection<IConditionalFo
      * @param template A template to use for the temporary item.
      */
     createItem(template?: IConditionalFormat): IConditionalFormat;
+    /** For runtime type checking. */
+    readonly isIConditionalFormatCollection: true;
 }
 /**
  * {@inheritDoc IConditionalFormatCollection}

package/types/src/dataValidation/DataValidation.d.ts

@@ -1,14 +1,16 @@
+import { IRange } from '@sheetxl/primitives';
 import { ReferenceableClipboard } from '@sheetxl/utils';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 import { IGrid } from '../collections';
 import { ICellRange } from '../cellRange';
+import { BlankResolver } from '../condition/_ConditionUtils';
 import { AnchoredConditional } from '../condition/AnchoredConditional';
 import { IDataValidation } from './IDataValidation';
 /**
  * Implementation of {@link IDataValidation}.
  */
-export declare class DataValidation extends AnchoredConditional<State, CommitView, IDataValidation.Events> implements IDataValidation {
+export declare class DataValidation extends AnchoredConditional<State, IDataValidation.Events> implements IDataValidation {
     /**
      * Cache of failing cells for quick reads in {@link getAlertAt} — a plain field, NOT transactional
      * state, mirroring ConditionalFormat's `_matches`.
@@ -20,6 +22,21 @@ export declare class DataValidation extends AnchoredConditional<State, CommitVie
      * commit onto the undo stack for a change no user made.
      */
     protected _results: IGrid<boolean> | null;
+    /**
+     * How the EMPTY cells answer, one reader per anchored area, or `null` when every blank passes
+     * (Ignore blank on, or no condition). Swapped with {@link _results}, never materialized into it:
+     * a whole-column rule is one entry here, not a million there.
+     */
+    protected _blankAreas: BlankArea[] | null;
+    /**
+     * Whether the rule's answer for a blank can differ by position (it reads a formula). When it
+     * cannot, one question per area answers every blank in it.
+     */
+    protected _blankPerCell: boolean;
+    /** {@link _blankAreas} split into disjoint pieces, built on the first count or entries read. */
+    protected _blankPieces: BlankPiece[] | null;
+    /** {@link getAlertCount}'s answer for the current results, or `null` until asked. */
+    protected _alertCount: number | null;
     /**
      * Which evaluation round is current. Bumped once per {@link _processValueUpdates}; a round
      * writes its results only if it is still the newest when it finishes. Same shape and reason as
@@ -34,12 +51,33 @@ export declare class DataValidation extends AnchoredConditional<State, CommitVie
     protected _getDefaultState(options: DataValidation.ConstructorOptions): Readonly<State>;
     /** @internal */
     protected _processValueUpdates(_range?: ICellRange | null): void;
+    /** Swaps in one evaluation's answers; everything derived from the previous ones goes with them. */
+    protected _setResults(results: IGrid<boolean> | null, blankAreas: BlankArea[] | null, blankPerCell?: boolean): void;
+    /** Whether an EMPTY cell of `areas` fails. Every area covering the cell has a say, as for values. */
+    protected _isBlankFailing(areas: readonly BlankArea[], rowIndex: number, columnIndex: number): boolean;
+    /** One area's answer for a blank. A rule reading no formula answers once for the whole area. */
+    protected _isBlankPassing(blankArea: BlankArea, rowIndex: number, columnIndex: number): boolean;
+    /**
+     * The blank areas as disjoint pieces, each knowing every area that covers it — so an overlap is
+     * counted once and still answered by all of its rules. Disjoint areas are their own pieces.
+     */
+    protected _getBlankPieces(): BlankPiece[];
+    /** How many cells of `coords` hold a value — off the value grid's runs, never its cells. */
+    protected _countValues(coords: IRange.Coords): number;
     /** {@inheritDoc IDataValidation.getAlertAt} */
     getAlertAt(rowIndex: number, columnIndex: number): boolean;
     /** {@inheritDoc IDataValidation.getAlertEntries} */
     getAlertEntries(options?: ICellRange.IteratorOptions): IGrid.EntryIterator<boolean>;
+    /**
+     * Each piece in axis order: its stored results and its blanks, merged as the caller reads. A
+     * piece whose blanks pass is read off the results grid alone; one whose blanks fail walks its
+     * values, yielding the gaps between them without asking; one read per cell asks per gap cell.
+     */
+    protected _pieceEntries(pieces: readonly BlankPiece[], results: IGrid<boolean> | null, axis: IRange.Axis, reverse: boolean): Generator<IGrid.Entry<boolean>, undefined, undefined>;
     /** {@inheritDoc IDataValidation.getAlertCount} */
     getAlertCount(): number;
+    /** {@inheritDoc IDataValidation.getListItemsAt} */
+    getListItemsAt(rowIndex: number, columnIndex: number): Promise<readonly IDataValidation.ListItem[]>;
     /** {@inheritDoc IDataValidation.setHideDropdown} */
     setHideDropdown(hide: boolean, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc IDataValidation.isHideDropdown} */
@@ -114,8 +152,17 @@ interface State extends AnchoredConditional.State {
     /** Opaque third-party payload. Carried, never interpreted. */
     ext: Record<string, unknown> | null;
 }
-/** @internal */
-interface CommitView extends AnchoredConditional.CommitView {
+/** One anchored area's reader for its empty cells. */
+interface BlankArea {
+    area: IRange.Coords;
+    resolve: BlankResolver;
+    /** The area's one answer when it cannot vary by position; `null` until asked. */
+    passes: boolean | null;
+}
+/** A disjoint piece of the blank areas, with every area that covers all of it. */
+interface BlankPiece {
+    coords: IRange.Coords;
+    areas: readonly BlankArea[];
 }
 export {};
 //# sourceMappingURL=DataValidation.d.ts.map

package/types/src/dataValidation/DataValidationCollection.d.ts

@@ -1,20 +1,31 @@
 import { ICellRanges } from '../cellRange';
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
 import { IDataValidationCollection } from './IDataValidationCollection';
 import { IDataValidation } from './IDataValidation';
-export declare class DataValidationCollection implements IDataValidationCollection {
+/**
+ * Implementation for {@link IDataValidationCollection}.
+ *
+ * @remarks
+ * A front over the sheet's own data-validation state — the sheet keeps the store and the
+ * events, this class keeps the API. `onCollectionChange` is the sheet's
+ * `onDataValidationsChange`, forwarded with this collection as the source.
+ */
+export declare class DataValidationCollection extends AbstractCollection<IDataValidation, IDataValidationCollection.GetItemsOptions> implements IDataValidationCollection {
     private _add;
     private _get;
     private _createItem;
-    constructor(add: (address: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions) => IDataValidation, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IDataValidation[], createItem: (template?: IDataValidation | null) => IDataValidation);
+    private _addListeners;
+    constructor(add: (address: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions) => IDataValidation, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IDataValidation[], createItem: (template?: IDataValidation | null) => IDataValidation, addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove);
     /** {@inheritDoc IDataValidationCollection.add} */
     add(address: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions): IDataValidation;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<IDataValidation>;
-    /** {@inheritDoc IDataValidationCollection.getItems} */
-    getItems(options?: IDataValidationCollection.GetItemsOptions): IDataValidation[];
-    /** {@inheritDoc IDataValidationCollection.getCount} */
-    getCount(): number;
-    /** {@inheritDoc IDataValidationCollection.getCount} */
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IDataValidationCollection.GetItemsOptions): IDataValidation[];
+    /** {@inheritDoc IDataValidationCollection.createItem} */
     createItem(template?: IDataValidation | null): IDataValidation;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IDataValidationCollection.isIDataValidationCollection} */
+    get isIDataValidationCollection(): true;
 }
 //# sourceMappingURL=DataValidationCollection.d.ts.map