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

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

@@ -2,21 +2,23 @@ import { IRange, IRuntime, Scalar } from '@sheetxl/primitives';
 import { MaybePromise } from '@sheetxl/utils';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
-import { ISparseGrid } from '../collections';
+import { Tuple, ISparseGrid } from '../collections';
 import { ICalculation } from '../calculation';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { ICondition } from '../condition';
+import { ConditionFormulaBinding } from '../condition/_ConditionFormula';
 import { IAnchored } from '../anchored';
 import { AbstractAnchored } from '../anchored/AbstractAnchored';
 import { Anchored } from '../anchored/Anchored';
+import * as _ConditionUtils from '../condition/_ConditionUtils';
 /**
  * Implementation of {@link IDataValidation}.
  */
-export declare abstract class AnchoredConditional<STATE extends AnchoredConditional.State, VIEW extends AnchoredConditional.CommitView = AnchoredConditional.CommitView, EVENTS extends ICondition.Events = ICondition.Events, JSON = any> extends AbstractAnchored<STATE, VIEW, EVENTS> implements IAnchored, ITransaction.ITransactional, IListener.ISource<IAnchored> {
+export declare abstract class AnchoredConditional<STATE extends AnchoredConditional.State, EVENTS extends ICondition.Events = ICondition.Events, JSON = any> extends AbstractAnchored<STATE, EVENTS> implements IAnchored, ITransaction.ITransactional, IListener.ISource<IAnchored> {
     protected _rangeListener: ICellRange.Listener | null;
     protected _getValueGrid: () => ISparseGrid<Scalar>;
     /**
-     * One registered watch per formula the condition asked for, keyed by expression: its remove, and
+     * One registered watch per formula the condition asked for, keyed by the formula: its remove, and
      * the values delivered so far, indexed by anchored area.
      *
      * @remarks
@@ -26,7 +28,9 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
      * the difference between a new formula-valued operator working automatically and needing this
      * class edited to know about it.
      */
-    protected _conditionWatches: Map<string, WatchEntry>;
+    protected _conditionWatches: Map<ICalculation.IFormula | string, WatchEntry>;
+    /** What this rule's condition formulas compile with — see {@link _getFormulaBinding}. */
+    protected _formulaBinding: ConditionFormulaBinding | undefined;
     /**
      * The area marked stale since the last flush: `undefined` = nothing, `null` = the whole rule,
      * a range = just that part. See {@link _markValueUpdates}.
@@ -75,10 +79,11 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
      *
      * Registered through `ICellRanges.addWatch`, which fills the expression to every area — a rule
      * over `'C19:C23 C3:C7'` reads different cells in its second area, and only the filled form knows
-     * which. The delivery re-runs the rule; the pass after it has values.
+     * which. The delivery re-runs the rule; the pass after it has values. Evaluated as a rule's
+     * formula is (`arrayFirstCell`): each cell an array-entered formula over itself.
      * @internal
      */
-    protected _watchConditionFormula(ranges: ICellRanges, expression: string, areaIndex: number, used: Set<string>): MaybePromise<IRange | null>;
+    protected _watchConditionFormula(ranges: ICellRanges, formula: ICalculation.IFormula | string, areaIndex: number, used: Set<ICalculation.IFormula | string>): MaybePromise<IRange | null>;
     /**
      * Drops watches nothing asked for during the evaluation that just finished.
      *
@@ -88,7 +93,7 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
      * the pass and pruning after is what closes that.
      * @internal
      */
-    protected _pruneConditionWatches(used: Set<string>): void;
+    protected _pruneConditionWatches(used: Set<ICalculation.IFormula | string>): void;
     /** @internal */
     protected _removeConditionWatches(): void;
     /**
@@ -100,13 +105,35 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
      * resolve. They resolve to `null` — "no values", which reads as an inert condition.
      * @internal
      */
-    protected _removeConditionWatch(entry: WatchEntry): void;
+    protected _removeConditionWatch(formula: ICalculation.IFormula | string, entry: WatchEntry): void;
     /** @internal */
     protected _processClose(): void;
+    /**
+     * An undo or redo can hand back a different condition while no value changes, so no range
+     * listener fires to re-derive the results. Heard here, not in `_processRestoreOrRevert`: that
+     * is told of every record in the store on every undo, this only of the ones the undo changed.
+     * @internal
+     */
+    protected _processAfterStateChange(state: STATE, commit: ITransaction.ICommit, isRevert?: boolean, isRestore?: boolean): void;
     /** @internal */
     protected _processAnchorCoords(): void;
+    /**
+     * Set while the container is shifting or deleting this rule, so {@link _processAnchorCoords}
+     * leaves the listener alone.
+     *
+     * @remarks
+     * Both run INSIDE the anchored map's own pass. The listener's reference lives in a map of the
+     * same kind and is moved (or dropped) by the same pass, so there is nothing to re-register - and
+     * reaching into a map that is mid-shift to do it is what used to throw.
+     * @internal
+     */
+    protected _isContainerShifting: boolean;
+    /** @internal */
+    protected _processContainerDelete(): void;
     /** @internal */
     protected _processContainerShift(options: Anchored.ShiftOptions): IRange.Coords | null | void;
+    /** @internal */
+    protected _doProcessContainerShift(options: Anchored.ShiftOptions): IRange.Coords | null | void;
     /**
      * Whether the anchor is absolute. See {@link AbstractAnchored._isAnchorAbsolute}.
      *
@@ -132,11 +159,19 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
     setIndex(index: number): this;
     /** {@inheritDoc ICondition.Stateful.getCondition} */
     getCondition(): Readonly<ICondition> | null;
+    /**
+     * The engine and anchor this rule's condition formulas compile with: the rule's calculation, at
+     * the top-left of the bounding box of its ranges.
+     * @internal
+     */
+    protected _getFormulaBinding(): ConditionFormulaBinding;
+    /** @internal */
+    protected _bindConditionFormulas(condition: ICondition | null): void;
     /** {@inheritDoc IDataValidation.setCondition} */
     setCondition(condition: ICondition.Input | ICondition.Predicate | string | null, options?: ITransaction.OperationOptions): this;
     /**
-     * Rewrites the condition's anchor-relative formulas after the anchor cell (the first
-     * range's top-left) moves — fill semantics: relative references follow the anchor,
+     * Rewrites the condition's anchor-relative formulas after the anchor cell (the top-left of
+     * the bounding box of every range) moves — fill semantics: relative references follow the anchor,
      * absolute ones stay put. Excel does the same when extending a rule's applies-to moves
      * its origin: `G5>5` on `F5:F10` becomes `G1>5` when the rule grows to `F1:F10`.
      *
@@ -214,8 +249,6 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
      * @internal
      */
     protected _shiftFormulaText(text: string, from: IRange.CellCoords, to: IRange.CellCoords): string | null;
-    /** {@inheritDoc ICondition.createDefaultCondition} */
-    createDefaultCondition(): ICondition;
     /** {@inheritDoc ICondition.Stateful.apply} */
     apply(): void;
     /**
@@ -229,12 +262,41 @@ export declare abstract class AnchoredConditional<STATE extends AnchoredConditio
      * be answered from a single cell's value.
      */
     protected _evalConditionRanges(handlers: {
-        onTrue?: (coords: IRange.CellCoords, value: Scalar) => void;
-        onFalse?: (coords: IRange.CellCoords, value: Scalar) => void;
+        /** `area` is the anchored area the cell belongs to — see {@link AreaResultCollector}. */
+        onTrue?: (coords: IRange.CellCoords, value: Scalar, area: IRange.Coords) => void;
+        onFalse?: (coords: IRange.CellCoords, value: Scalar, area: IRange.Coords) => void;
+        /**
+         * The answer for the BLANK cells of one anchored area, once per area — see
+         * `DoRunConditionsOptions.onBlank`. `area` is that area's coords, so a caller keeping the
+         * resolver can tell which cells it answers for.
+         */
+        onBlank?: (resolve: _ConditionUtils.BlankResolver, area: IRange.Coords) => void;
     }): Promise<void>;
     get [Symbol.toStringTag](): string;
     toString(): string;
 }
+/**
+ * Collects a rule's per-cell `true` results across its anchored areas into one grid.
+ *
+ * @remarks
+ * One tuple builder PER AREA. A builder takes cells in axis order, and a rule's areas are in
+ * authored order, not axis order — Excel writes `C3 C1` when it merges identical rules on save —
+ * and two areas can interleave on the major axis besides. One builder across all of them throws
+ * on the first area that runs backwards.
+ * @internal
+ */
+export declare class AreaResultCollector {
+    protected _isColumn: boolean;
+    protected _regions: Tuple.GridTuple<boolean>[];
+    protected _builder: Tuple.IBuilder<boolean> | null;
+    protected _area: IRange.Coords | null;
+    constructor(isColumn: boolean);
+    /** Adds a cell. Cells of one area arrive together, in axis order. */
+    push(coords: IRange.CellCoords, area: IRange.Coords): void;
+    /** The collected cells, or `null` when none were pushed. */
+    build(axis: IRange.Axis): ISparseGrid<boolean> | null;
+    protected _flush(): void;
+}
 /**
  * One registered formula watch: its remove, the values delivered per area, and any resolver still
  * waiting on an area's first delivery.
@@ -275,9 +337,6 @@ export declare namespace AnchoredConditional {
         condition: ICondition | null;
         removeListener: IListener.Remove | null;
     }
-    /** @internal */
-    interface CommitView extends AbstractAnchored.CommitView {
-    }
 }
 export {};
 //# sourceMappingURL=AnchoredConditional.d.ts.map

package/types/src/condition/BuiltInOperators/AbstractOperator.d.ts

@@ -1,5 +1,6 @@
 import { InteropScalarType, IRange, Scalar } from '@sheetxl/primitives';
 import { MaybePromise } from '@sheetxl/utils';
+import { ICalculation } from '../../calculation';
 import { ICondition } from '../ICondition';
 /**
  * Reads a comparison operand's value at the cell being evaluated. Built once per
@@ -42,8 +43,8 @@ export declare abstract class AbstractOperator<P> implements ICondition.IOperato
     /** {@inheritDoc ICondition.doBatch} */
     doBatch(keys: Set<any>, param: P, ctx: ICondition.IContext): MaybePromise<IRange<boolean> | null>;
     /**
-     * Resolves a comparison operand that may be formula-valued — a string param with a leading `=`,
-     * the Scalar-param convention — into a per-cell {@link OperandReader}.
+     * Resolves a comparison operand that may be formula-valued — an {@link ICalculation.IFormula}, or
+     * a string param with a leading `=` — into a per-cell {@link OperandReader}.
      *
      * @returns The reader, or `null` when the operand is a formula with nothing to read (no engine,
      * an empty expression) — the caller returns a `null` predicate and the condition is inert
@@ -57,18 +58,18 @@ export declare abstract class AbstractOperator<P> implements ICondition.IOperato
      * same code path.
      *
      * A per-cell value that is an ERROR is returned as the error — comparisons must treat it as
-     * no-match, never a throw — and warns once per predicate build. A value that is a RANGE (a
-     * reference operand) takes its top-left: Excel does NOT implicitly intersect here (`$E$5:$F$6>10`
-     * tested `E5` for every cell; measured 2026-08-21).
+     * no-match, never a throw — and warns once per predicate build. A reference operand reads its
+     * top-left: Excel does NOT implicitly intersect here (`$E$5:$F$6>10` tested `E5` for every cell;
+     * measured 2026-08-21), which is the watch's `arrayFirstCell` evaluation.
      */
-    protected _resolveOperand(param: Scalar | undefined, ctx: ICondition.IContext): Promise<OperandReader | null>;
+    protected _resolveOperand(param: Scalar | ICalculation.IFormula | undefined, ctx: ICondition.IContext): Promise<OperandReader | null>;
     /**
      * The shared predicate shape of the ordered comparisons (`greaterThan` … `before`): resolve the
      * operand (formula or literal — see {@link _resolveOperand}), then compare per cell. An ERROR
      * operand never matches; a `null` return means the operand could not resolve and the condition
      * is inert.
      */
-    protected _createComparePredicate(param: Scalar | undefined, ctx: ICondition.IContext, compare: (value: number, operand: number) => boolean): Promise<ICondition.Predicate | null>;
+    protected _createComparePredicate(param: Scalar | ICalculation.IFormula | undefined, ctx: ICondition.IContext, compare: (value: number, operand: number) => boolean): Promise<ICondition.Predicate | null>;
     /** {@inheritDoc ICondition.IOperator.toString} */
     toString(param?: P, lhsSelector?: ICondition.ISelector): string | undefined;
 }

package/types/src/condition/BuiltInOperators/EqualToOperator.d.ts

@@ -1,10 +1,11 @@
 import { Scalar } from '@sheetxl/primitives';
+import { ICalculation } from '../../calculation';
 import { ICondition } from '../ICondition';
 import { AbstractOperator } from './AbstractOperator';
 export declare class EqualToOperator extends AbstractOperator<Scalar> implements ICondition.IOperator<Scalar> {
     constructor();
     /** {@inheritDoc ICondition.IOperator.createPredicate} */
-    createPredicate(param: Scalar, ctx: ICondition.IContext): Promise<ICondition.Predicate | null>;
+    createPredicate(param: Scalar | ICalculation.IFormula, ctx: ICondition.IContext): Promise<ICondition.Predicate | null>;
     /** {@inheritDoc ICondition.IOperator.createDefaultParam} */
     createDefaultParam(lhsSelector?: ICondition.ISelector): Scalar | undefined;
 }

package/types/src/condition/BuiltInOperators/ExpressionOperator.d.ts

@@ -1,17 +1,14 @@
+import { ICalculation } from '../../calculation';
 import { ICondition } from '../ICondition';
 import { AbstractOperator } from './AbstractOperator';
 /**
  * Evaluates a formula expression against the value of the cell.
  */
-export declare class ExpressionOperator extends AbstractOperator<string> implements ICondition.IOperator<string> {
+export declare class ExpressionOperator extends AbstractOperator<ICalculation.IFormula | string> implements ICondition.IOperator<ICalculation.IFormula | string> {
     constructor();
     /** {@inheritDoc ICondition.IOperator.createDefaultParam} */
     createDefaultParam(lhsSelector?: ICondition.ISelector): string;
     /** {@inheritDoc ICondition.IOperator.createPredicate} */
-    createPredicate(param: string, ctx: ICondition.IContext): Promise<ICondition.Predicate | null>;
+    createPredicate(param: ICalculation.IFormula | string, ctx: ICondition.IContext): Promise<ICondition.Predicate | null>;
 }
-/**
- * Creates a temporary range. This is for illustrations only.
- */
-export declare const ExpressionRuleAccumulate: ICondition.IOperator<string>;
 //# sourceMappingURL=ExpressionOperator.d.ts.map

package/types/src/condition/BuiltInOperators/InSetOperator.d.ts

@@ -5,7 +5,7 @@ export declare class InSetOperator extends AbstractOperator<ICondition.InSetOpti
     /** {@inheritDoc ICondition.IOperator.acceptsList} */
     acceptsList(): boolean;
     /** {@inheritDoc ICondition.IOperator.createPredicate} */
-    createPredicate(param: ICondition.InSetOption, ctx: ICondition.IContext): ICondition.Predicate;
+    createPredicate(param: ICondition.InSetOption, ctx: ICondition.IContext): ICondition.Predicate | Promise<ICondition.Predicate | null>;
     /** {@inheritDoc ICondition.IOperator.createDefaultParam} */
     createDefaultParam(lhsSelector?: ICondition.ISelector): ICondition.InSetOption;
     /** {@inheritDoc ICondition.IOperator.toString} */

package/types/src/condition/BuiltinSelectors/BaseSelector.d.ts

@@ -8,6 +8,7 @@ export declare class BaseSelector<T extends Scalar = Scalar, I extends Scalar =
     protected _title: string | undefined;
     protected _description: string | undefined;
     protected _renderingHints: readonly string[] | null;
+    protected _defaultCondition: ICondition.DefaultCondition | null;
     constructor(options: ConstructorOptions);
     /** {@inheritDoc ICondition.ISelector.createTransformer} */
     createTransformer(ctx: ICondition.IContext): MaybePromise<ICondition.Transformer<T, I> | null>;
@@ -31,6 +32,8 @@ export declare class BaseSelector<T extends Scalar = Scalar, I extends Scalar =
     getDescription(): string;
     /** {@inheritDoc ICondition.ISelector.getRenderHints} */
     getRenderHints(): readonly string[] | null;
+    /** {@inheritDoc ICondition.ISelector.getDefaultCondition} */
+    getDefaultCondition(_context?: ICondition.DefaultConditionContext): ICondition.DefaultCondition | null;
 }
 export interface ConstructorOptions {
     name: string;
@@ -39,5 +42,9 @@ export interface ConstructorOptions {
     title?: string;
     description?: string;
     renderingHints?: string | string[];
+    /**
+     * What {@link ICondition.ISelector.getDefaultCondition} returns.
+     */
+    defaultCondition?: ICondition.DefaultCondition | null;
 }
 //# sourceMappingURL=BaseSelector.d.ts.map

package/types/src/condition/BuiltinSelectors/ListSelector.d.ts

@@ -8,5 +8,14 @@ export declare class ListSelector<T extends Scalar = Scalar, I extends Scalar =
     constructor(options: ConstructorOptions);
     /** {@inheritDoc ICondition.IListSelector.isList} */
     get isList(): true;
+    /**
+     * {@inheritDoc ICondition.ISelector.getDefaultCondition}
+     *
+     * @remarks
+     * `inSet` over the distinct values already in the selection, sorted as a filter lists them,
+     * when there are a few, spelled as a list literal; otherwise `inSet` with no items (also when a
+     * value holds `,`, which a literal cannot). Read through the range's stats.
+     */
+    getDefaultCondition(context?: ICondition.DefaultConditionContext): ICondition.DefaultCondition | null;
 }
 //# sourceMappingURL=ListSelector.d.ts.map

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

@@ -79,6 +79,22 @@ export declare namespace Condition {
         Or: import("./BuiltInOperators/OrOperator").OrOperator;
         Not: import("./BuiltInOperators/NotOperator").NotOperator;
     };
+    /**
+     * The items of a list literal, the `inSet` source `'"Yes,No"'`, or `null` when the text is a
+     * reference or formula rather than a literal.
+     *
+     * @remarks
+     * Items are returned as stored, spaces included, and split on `,` with no quoting: `'"q,r",s'`
+     * is three items. See {@link ICondition.InSetOption.items} for how they match.
+     */
+    const parseListLiteral: (text: string) => string[] | null;
+    /**
+     * Spells `items` as a list literal for {@link ICondition.InSetOption.items}: `['Yes', 'No']` is
+     * `'"Yes,No"'`.
+     *
+     * @returns The literal, or `null` when an item contains `,`, which a list literal cannot hold.
+     */
+    const formatListLiteral: (items: readonly string[]) => string | null;
     /**
      * Registry for selectors (built-in + custom).
      *

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

@@ -1,6 +1,7 @@
 import { Scalar, InteropScalar, IRange, InteropScalarType } from '@sheetxl/primitives';
 import { MaybePromise } from '@sheetxl/utils';
 import { IAnchored } from '../anchored';
+import { ICellRanges } from '../cellRange';
 import { ICalculation } from '../calculation';
 import { IStyle } from '../style';
 import { ParsedDateTime } from '../date/_DateUtils';
@@ -88,6 +89,10 @@ export interface ICondition<P = any> {
 export declare namespace ICondition {
     /**
      * A single condition applied to a range.
+     *
+     * @remarks
+     * A holder that must evaluate before it writes (a filter, which hides rows) returns a Promise
+     * from its writes; see {@link IFilter}.
      */
     interface Stateful {
         /**
@@ -244,7 +249,8 @@ export declare namespace ICondition {
          * Evaluates a formula expression.
          *
          * @remarks
-         * * Accepts a formula `string`.
+         * * Accepts formula text or an {@link ICalculation.IFormula}; a resolved condition holds an
+         *   `IFormula`.
          *
          * Backs conditional formatting's `expression` rule and data validation's `type="custom"`.
          */
@@ -300,15 +306,21 @@ export declare namespace ICondition {
      */
     interface BetweenOption {
         /**
-         * The lower bound value — a number, or a `=`-prefixed formula whose result is compared
-         * per cell.
+         * The lower bound value — a number, or a formula whose result is compared per cell.
+         *
+         * @remarks
+         * A formula is authored as a `=`-prefixed string or an {@link ICalculation.IFormula}; a resolved
+         * condition holds it as an `IFormula`.
          */
-        from: number | string;
+        from: number | string | ICalculation.IFormula;
         /**
-         * The upper bound value — a number, or a `=`-prefixed formula whose result is compared
-         * per cell.
+         * The upper bound value — a number, or a formula whose result is compared per cell.
+         *
+         * @remarks
+         * A formula is authored as a `=`-prefixed string or an {@link ICalculation.IFormula}; a resolved
+         * condition holds it as an `IFormula`.
          */
-        to: number | string;
+        to: number | string | ICalculation.IFormula;
     }
     interface ColorOption {
         /**
@@ -437,10 +449,21 @@ export declare namespace ICondition {
          */
         blank?: boolean;
         /**
-         * List of item filters
+         * The values that match: an array, or a list validation's source as formula text.
          *
          * @remarks
-         * If this is a string that is a formula then the formula is evaluated to get the list of items.
+         * A string is formula text in the typed-slot convention: bare, without a leading `=`.
+         *
+         * - A quoted literal, `"Yes,No"`, lists its items. They match as Excel matches a literal list:
+         *   the value's text, trimmed, against each item without its leading spaces, case-sensitively.
+         * - Anything else, `$A$1:$A$5`, `Sheet2!$A$1:$A$9`, `MyList`, `OFFSET(...)`, `INDIRECT($E1)`,
+         *   is a source whose result is the list. A value matches when `MATCH(value, source, 0)` finds
+         *   it, which is Excel's rule for a list validation: text case-insensitively and with `*`, `?`
+         *   and `~` as wildcards, numbers by value, text never equal to a number. The source is
+         *   evaluated for each cell, so a relative reference gives each cell its own list, and the
+         *   source follows inserts and deletes as any formula does.
+         *
+         * An array matches as a filter's list of values does.
          */
         items?: Scalar[] | string;
         /**
@@ -611,10 +634,11 @@ export declare namespace ICondition {
          */
         createFormula(expression: string, coords?: IRange.CellCoords | null): ICalculation.IFormula | null;
         /**
-         * Declares that this condition depends on `expression`, and resolves to its values across
+         * Declares that this condition depends on `formula`, and resolves to its values across
          * {@link getCoords}.
          *
-         * @param expression The formula this operator needs, exactly as authored.
+         * @param formula The formula this operator needs — the param's {@link ICalculation.IFormula},
+         * or formula text as authored.
          *
          * @returns One value per cell of {@link getCoords}, read with LOCAL coordinates
          *          (`getValueAt(0, 0)` is the coords' top-left), or `null` when there is no engine to
@@ -634,25 +658,7 @@ export declare namespace ICondition {
          * - A one-shot caller (`Range.filter()`) has no lifetime to keep fresh, so it simply evaluates
          *   once and resolves. Correct there, and identical from here.
          */
-        watchFormula(expression: string): MaybePromise<IRange | null>;
-        /**
-         * Resolves a formula string or scalar value to its evaluated result.
-         *
-         * @param formula A formula string (e.g., "=A1+B1") or a scalar value
-         * @returns The evaluated scalar value
-         *
-         * @remarks
-         * - Call this during `createPredicate` to resolve formula-based param
-         * - Returns immediately if value is already a scalar
-         * - Handles formula parsing, evaluation, and dependency tracking
-         * - Example: `const threshold = await ctx.resolveFormula(param);`
-         *
-         * **Why This Exists:**
-         * - Keeps operators simple - they work with values, not formulas
-         * - Centralizes formula evaluation infrastructure
-         * - Enables formula references in validation rules (e.g., "greater than A1")
-         */
-        resolveFormula(formula: Scalar | string): Promise<Scalar>;
+        watchFormula(formula: ICalculation.IFormula | string): MaybePromise<IRange | null>;
     }
     /**
      * Predicate function used to evaluate condition matches.
@@ -829,6 +835,46 @@ export declare namespace ICondition {
          * * The `Boolean` operator might return `"checkbox"`.
          */
         getRenderHints?(): readonly string[] | null;
+        /**
+         * The condition a user starts from on choosing this selector.
+         *
+         * @param context What the condition will apply to, when known.
+         * @returns The operator and, only where one value is plainly the right one, its param. `null`
+         * for a selector with no natural operator.
+         *
+         * @remarks
+         * An authoring UI asks for this when a user picks the selector, so the choice shows an operator
+         * at once rather than an empty condition. An omitted `param` is filled by the operator's own
+         * {@link ICondition.IOperator.createDefaultParam}; supply one only when it is the value the user
+         * would have chosen, since an invented value that is saved unnoticed is a rule nobody wrote.
+         *
+         * Read `context.ranges` through `getStats()`, never by visiting its cells: a whole column may be
+         * selected.
+         */
+        getDefaultCondition?(context?: ICondition.DefaultConditionContext): ICondition.DefaultCondition | null;
+    }
+    /**
+     * What {@link ISelector.getDefaultCondition} may fit its default to.
+     */
+    interface DefaultConditionContext {
+        /**
+         * The cells the condition will cover.
+         */
+        ranges?: ICellRanges | null;
+    }
+    /**
+     * The operator and param a selector's condition starts with. See
+     * {@link ISelector.getDefaultCondition}.
+     */
+    interface DefaultCondition<P = any> {
+        /**
+         * The operator's name.
+         */
+        operator: string;
+        /**
+         * The operator's param. Omitted to take the operator's own default.
+         */
+        param?: P;
     }
     /**
      * A selector that operates on lists of values, such as "is in list" or "contains".
@@ -881,7 +927,8 @@ export declare namespace ICondition {
    */
     interface RangeOptions {
         /**
-         * The condition.
+         * The conditions, each carrying the column (or row, per {@link axis}) it tests through
+         * {@link IndexedProperties.index}; one that omits it tests its position in the array.
          */
         conditions: ICondition.Input[];
         /**
@@ -889,9 +936,15 @@ export declare namespace ICondition {
          */
         axis?: IRange.Axis;
         /**
-         * If filtering should include the hidden row/columns
+         * Whether rows/columns already hidden take part.
          *
-         * @defaultValue false
+         * @remarks
+         * For a filter (`ICellRange.filter`, `ITable.filter`) the default is `true`: an apply is a full
+         * recompute, so a row hidden by an earlier apply, or by hand, comes back when it matches.
+         * `false` pins the rows already hidden as excluded. Conditional formats and data validations
+         * default to `false` and skip hidden cells.
+         *
+         * @defaultValue `true` for a filter, `false` otherwise
          */
         includeHidden?: boolean | IRange.Axis;
         /**