@sheetxl/sdk 0.7.21 → 0.7.23-beta.2

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

@@ -0,0 +1,915 @@
+import { Scalar, InteropScalar, IRange, InteropScalarType } from '@sheetxl/primitives';
+import { MaybePromise } from '@sheetxl/utils';
+import { IAnchored } from '../anchored';
+import { ICalculation } from '../calculation';
+import { IStyle } from '../style';
+import { ParsedDateTime } from '../date/_DateUtils';
+/**
+ * Interface that captures the selector, operator, and param.
+ */
+export interface ICondition<P = any> {
+    /**
+     * Returns the selector.
+     *
+     * @remarks
+     * The selector is responsible for transforming the cell value before it is passed to the operator predicate.
+     * If `null` is returned then the raw cell value is used (identity selector).
+     * This allows operators to focus on their core logic and delegate any necessary value transformation to the selector.
+     * For example, a "Text Contains" operator might use a selector that converts values to lowercase strings, enabling case-insensitive matching.
+     */
+    getSelector(): ICondition.ISelector | null;
+    /**
+     * Returns the operator.
+     *
+     * @remarks
+     * The operator is responsible for evaluating the condition param against the transformed value from the selector.
+     * Return null if there is no operator and the condition is purely based on the selector transformation (e.g. "Is Blank" could be a selector that checks for blank values without needing an operator).
+     */
+    getOperator(): ICondition.IOperator | null;
+    /**
+     * Returns the param for the condition.
+     *
+     * @remarks
+     * This is operator-specific and not all operators require a param.
+     */
+    getParam(): P;
+    /**
+     * Whether to include blank cells when applying the condition.
+     *
+     * @remarks
+     * **Evaluation Behavior:**
+     * - If `false` (default): Blank cells evaluate to FALSE (fail the condition test)
+     * - If `true`: Blank cells evaluate to TRUE (pass the condition test)
+     *
+     * **Why This Matters:**
+     *
+     * Different consumers interpret condition results differently:
+     *
+     * **DataValidation (acts on FALSE = invalid):**
+     * - `includeBlanks: false` → Blanks FAIL validation (are invalid/rejected)
+     * - `includeBlanks: true` → Blanks PASS validation (are valid/allowed)
+     * - Example: "Allow dates, ignore blanks" needs `includeBlanks: true` so blank cells are allowed
+     *
+     * **ConditionalFormat & TableFilter (act on TRUE = show/format):**
+     * - `includeBlanks: false` → Blanks are NOT formatted/shown (natural behavior)
+     * - `includeBlanks: true` → Blanks ARE formatted/shown (rarely needed)
+     * - Example: "Highlight dates" with `includeBlanks: false` correctly excludes blanks
+     *
+     * **UI Guidance:**
+     * - Show "Ignore Blanks" checkbox for DataValidation (common use case)
+     * - Hide for ConditionalFormat/TableFilter (default behavior is usually correct)
+     */
+    isIncludeBlanks(): boolean;
+    /**
+     * Returns a string representation of the selector, operator, and param.
+     */
+    toString(): string;
+    /**
+     * Returns the JSON representation of the condition.
+     */
+    toJSON(): ICondition.JSON<P>;
+    /**
+     * For runtime introspection.
+     */
+    get isICondition(): true;
+}
+/**
+ * Capabilities for applying and managing conditions.
+ *
+ * Conditions enable dynamic filtering of data based on param specified per column,
+ * allowing users to quickly focus on relevant information.
+ *
+ * Key features include:
+ * - Applying conditions to specific columns within a range.
+ * - Defining condition param using various operators (e.g., equals, greater than, contains).
+ * - Hiding rows that don't match the condition param.
+ * - Clearing or modifying conditions.
+ */
+export declare namespace ICondition {
+    /**
+     * A single condition applied to a range.
+     */
+    interface Stateful {
+        /**
+         * Return the condition, or `null` if none is set.
+         */
+        getCondition(): ICondition | null;
+        /**
+         * Applies the condition.
+         */
+        apply(): void;
+        /**
+         * Clear the condition
+         */
+        delete(): void;
+    }
+    interface Events extends IAnchored.Events {
+        /**
+         * Called when the condition changes.
+         */
+        onConditionChange?(source: ICondition.Stateful): void;
+    }
+    /**
+     * Selectors
+     */
+    const BuiltInSelectorNames: {
+        readonly List: "list";
+        readonly Logical: "logical";
+        readonly Date: "date";
+        readonly DateTime: "dateTime";
+        readonly Time: "time";
+        readonly Text: "text";
+        readonly TextLength: "textLength";
+        readonly Number: "number";
+        readonly Whole: "wholeNumber";
+    };
+    type BuiltInSelectorNames = typeof BuiltInSelectorNames[keyof typeof BuiltInSelectorNames];
+    const BuiltInOperatorNames: {
+        /**
+         * And operator that returns true if all param are met.
+         *
+         * @remarks
+         * Accepts a `readonly ICondition.Input[]`
+         */
+        readonly And: "and";
+        /**
+         * Checks for values above or below average.
+         *
+         * * Accepts `ICondition.AverageOption`.
+         */
+        readonly Average: "average";
+        /**
+         * Checks for values between two values.
+         *
+         * * Accepts `ICondition.BetweenOption`.
+         */
+        readonly Between: "between";
+        /**
+         * Checks for color.
+         *
+         * @remarks
+         * Accepts `ICondition.ColorOption`
+         */
+        readonly Color: "color";
+        /**
+         * Checks any value is equal to.
+         */
+        readonly EqualTo: "equalTo";
+        /**
+         * Checks any value is greater than.
+         */
+        readonly GreaterThan: "greaterThan";
+        /**
+         * Checks any value is greater than.
+         */
+        readonly GreaterThanEqualTo: "greaterThanEqualTo";
+        /**
+         * Checks any value is less than.
+         */
+        readonly LessThan: "lessThan";
+        /**
+         * Checks any value is less than or equal to.
+         */
+        readonly LessThanEqualTo: "lessThanEqualTo";
+        /**
+         * Checks date is after.
+         */
+        readonly After: "after";
+        /**
+         * Checks date is after or equal to.
+         */
+        readonly AfterEqualTo: "afterEqualTo";
+        /**
+         * Checks date is before
+         */
+        readonly Before: "before";
+        /**
+         * Checks date is before or equal to.
+         */
+        readonly BeforeEqualTo: "beforeEqualTo";
+        /**
+         * Checks that value is unique.
+         */
+        readonly Unique: "unique";
+        /**
+         * Checks that value is blank.
+         */
+        readonly Blank: "blank";
+        /**
+         * Checks that value is an error.
+         */
+        readonly Error: "error";
+        /**
+         * An operator that filters by specific items (values).
+         *
+         * @remarks
+         * * Accepts `ICondition.InSetOption`
+         */
+        readonly InSet: "inSet";
+        /**
+         * An operator that filters by icon sets.
+         *
+         * @remarks
+         * * Accepts `ICondition.IconOption`
+         */
+        readonly Icon: "icon";
+        /**
+         * Negates another condition.
+         *
+         * @remarks
+         * * Accepts `ICondition.Input`.
+         */
+        readonly Not: "not";
+        /**
+         * Checks any text matches an email pattern.
+         */
+        readonly TextEmail: "textEmail";
+        /**
+         * Checks any text matches a url pattern.
+         */
+        readonly TextIsUrl: "textUrl";
+        /**
+         * Checks any text value starts with.
+         */
+        readonly TextStartsWith: "textStartsWith";
+        /**
+         * Checks any text value is greater than.
+         */
+        readonly TextEndsWith: "textEndsWith";
+        /**
+         * Checks any text value is greater than or equal to.
+         */
+        readonly TextContains: "textContains";
+        /**
+         * Evaluates a formula expression.
+         *
+         * @remarks
+         * * Accepts a formula `string`.
+         *
+         * Backs conditional formatting's `expression` rule and data validation's `type="custom"`.
+         */
+        readonly Expression: "expression";
+        /**
+         * An operator that filters dates for time periods.
+         *
+         * @remarks
+         * * Accepts `ICondition.TimePeriodOption`
+         */
+        readonly TimePeriod: "timePeriod";
+        /**
+         * An operator that filters by top N or bottom N values.
+         *
+         * @remarks
+         * * Accepts `ICondition.TopNOption`
+         */
+        readonly TopN: "topN";
+        /**
+         * Or operator that returns true if any param are met.
+         *
+         * @remarks
+         * Accepts a `readonly ICondition.Input[]`
+         */
+        readonly Or: "or";
+    };
+    type BuiltInOperatorNames = typeof BuiltInOperatorNames[keyof typeof BuiltInOperatorNames];
+    const AverageType: {
+        readonly Above: "above";
+        readonly Below: "below";
+        /**
+         * Equal to or above average (>=). Maps to OOXML `equalAverage=true` + `aboveAverage=true`.
+         */
+        readonly AboveOrEqual: "aboveOrEqual";
+        /**
+         * Equal to or below average (<=). Maps to OOXML `equalAverage=true` + `aboveAverage=false`.
+         */
+        readonly BelowOrEqual: "belowOrEqual";
+    };
+    type AverageType = typeof AverageType[keyof typeof AverageType];
+    interface AverageOption {
+        /**
+         * @defaultValue `AverageType.Above`
+         */
+        type?: AverageType;
+        stdDevs?: number;
+    }
+    /**
+     * Options for specifying a value within a range.
+     *
+     * @remarks
+     * Purely convenience. This is logically equivalent to `operator: 'and', [{ operator: 'greaterThan', param: value }]` but it's common enough that it's worth having a dedicated operator+option for it.
+     */
+    interface BetweenOption {
+        /**
+         * The lower bound value — a number, or a `=`-prefixed formula whose result is compared
+         * per cell.
+         */
+        from: number | string;
+        /**
+         * The upper bound value — a number, or a `=`-prefixed formula whose result is compared
+         * per cell.
+         */
+        to: number | string;
+    }
+    interface ColorOption {
+        /**
+         * Indicated whether to filter by cell's fill color.
+         *
+         * @defaultValue true
+         */
+        cellColor?: boolean;
+        /**
+         * If filtered then the id.
+         */
+        styleId?: number;
+    }
+    /**
+     * Types of time-periods.
+     */
+    const TimePeriodType: {
+        /**
+         * The seven days ending today.
+         *
+         * @remarks
+         * Conditional formatting only — OOXML's `ST_TimePeriod` has it, `ST_DateTimeGrouping` (the
+         * AutoFilter domain) does not.
+         */
+        readonly Last7Days: "last7Days";
+        readonly LastMonth: "lastMonth";
+        readonly LastQuarter: "lastQuarter";
+        readonly LastWeek: "lastWeek";
+        readonly LastYear: "lastYear";
+        readonly M1: "M1";
+        readonly M2: "M2";
+        readonly M3: "M3";
+        readonly M4: "M4";
+        readonly M5: "M5";
+        readonly M6: "M6";
+        readonly M7: "M7";
+        readonly M8: "M8";
+        readonly M9: "M9";
+        readonly M10: "M10";
+        readonly M11: "M11";
+        readonly M12: "M12";
+        readonly NextMonth: "nextMonth";
+        readonly NextQuarter: "nextQuarter";
+        readonly NextWeek: "nextWeek";
+        readonly Null: "null";
+        readonly Q1: "Q1";
+        readonly Q2: "Q2";
+        readonly Q3: "Q3";
+        readonly Q4: "Q4";
+        readonly ThisMonth: "thisMonth";
+        readonly ThisQuarter: "thisQuarter";
+        readonly ThisWeek: "thisWeek";
+        readonly Today: "today";
+        readonly Tomorrow: "tomorrow";
+        readonly YearToDate: "yearToDate";
+        readonly Yesterday: "yesterday";
+    };
+    type TimePeriodType = typeof TimePeriodType[keyof typeof TimePeriodType];
+    interface TimePeriodOption {
+        /**
+         * The time-period to compare against (e.g. "today", "lastWeek").
+         */
+        type?: TimePeriodType;
+        /**
+         * Optional anchor date (serial) used as "today" for relative periods.
+         *
+         * @remarks
+         * If omitted, the operator uses `ICondition.IContext.getNow()`.
+         */
+        anchorDate?: number;
+        /**
+         * Optional precomputed max value for the period.
+         *
+         * This is required for:
+         * today, yesterday, tomorrow, nextWeek, thisWeek, lastWeek, nextMonth, thisMonth,
+         * lastMonth, nextQuarter, thisQuarter, lastQuarter, nextYear, thisYear,
+         * lastYear, and yearToDate.
+         *
+         * @remarks
+         * This is an optimization only.
+         */
+        maxVal?: number;
+    }
+    const DateItemGroupingType: {
+        readonly Day: "day";
+        readonly Hour: "hour";
+        readonly Minute: "minute";
+        readonly Month: "month";
+        readonly Second: "second";
+        readonly Year: "year";
+    };
+    type DateItemGroupingType = typeof DateItemGroupingType[keyof typeof DateItemGroupingType];
+    interface DateGroupItem {
+        /**
+         * Grouping level.
+         */
+        group?: DateItemGroupingType;
+        /**
+         * Day 1 - 31.
+         */
+        day?: number;
+        /**
+         * Hour 0-23.
+         */
+        hour?: number;
+        /**
+         * Minute 0-59.
+         */
+        minute?: number;
+        /**
+         * Month 1-12.
+         */
+        month?: number;
+        /**
+         * Minute 0-59.
+         */
+        second?: number;
+        /**
+         * 4 Digits.
+         */
+        year?: number;
+    }
+    interface InSetOption {
+        /**
+         * If true this filter by blank.
+         */
+        blank?: boolean;
+        /**
+         * List of item filters
+         *
+         * @remarks
+         * If this is a string that is a formula then the formula is evaluated to get the list of items.
+         */
+        items?: Scalar[] | string;
+        /**
+         * List of date group filters.
+         */
+        dateGroups?: DateGroupItem[];
+        /**
+         * Calendar type for date group items.
+         */
+        calendarType?: string;
+    }
+    interface IconOption {
+        /**
+         * 0-based index of an icon from an icon set. If missing then no icon.
+         */
+        iconId?: number;
+        /**
+         * Specifies which icon set to use.
+         */
+        iconSet?: IStyle.IconSet;
+    }
+    interface TopNOption {
+        /**
+         * Top or bottom value to use as the filter param. For example "Filter by Top 10 Percent" or "Filter by Top 5 Items".
+         *
+         * @defaultValue `Determined by Rule - Builtin 'Top10' is 10`
+         */
+        limit?: number;
+        /**
+         * Flag indicating whether or not to filter by percent value. A `false` value filters by number of items.
+         */
+        percent?: boolean;
+        /**
+         * Flag indicating whether or not to filter by top order. A `false` value filters by bottom order.
+         */
+        top?: boolean;
+        /**
+         * The actual cell value in the range which is used to perform the comparison for this filter.
+         *
+         * @remarks
+         * This is internal cache value used during filtering.
+         */
+        filterVal?: number;
+    }
+    /**
+     * The context provided to condition predicates during evaluation.
+     *
+     * @remarks
+     * Includes information about the current cell being evaluated, the range,
+     * and utility methods for value transformation and formula resolution.
+     */
+    interface IContext {
+        /**
+         * Returns the raw cell type for the current cell being evaluated.
+         */
+        getType(value: Scalar): InteropScalarType;
+        /**
+         * Return the current location in the sheet.
+         */
+        getPosition(): Readonly<IRange.CellCoords>;
+        /**
+         * Returns the range for the entire area being valuated.
+         *
+         * @remarks
+         * Convenience method for `getRange().getCoords()`.
+         */
+        getCoords(): Readonly<IRange.Coords>;
+        /**
+         * Return the range for the condition.
+         */
+        getRange(): IRange;
+        /**
+         * Convert the value to the specified scalar type.
+         */
+        toType<T extends InteropScalar>(value: Scalar, type: InteropScalarType): T;
+        /**
+         * Resolves a condition input to a fully-built ICondition instance.
+         *
+         * @param input Any valid condition input (ICondition, properties, predicate function, string)
+         * @returns A resolved ICondition ready for evaluation, or `null` if the input could not be resolved
+         *
+         * @remarks
+         * **For Combinator Authors:**
+         * - Call this to recursively resolve child conditions
+         * - Handles all input formats (objects, strings, functions)
+         * - Enables composition without type worries
+         *
+         * **Why This Exists:**
+         * - Uniform handling of condition inputs
+         * - Enables recursive composition (AND/OR/NOT)
+         * - Keeps combinator code clean
+         */
+        resolveInput<C = any>(input: ICondition.Input<C>): Promise<ICondition | null>;
+        /**
+         * Gets now as a serial number.
+         */
+        getNow(): number;
+        /**
+         * Returns an SerialDate value from a date. This is used for date calculations.
+         *
+         * @param date A date as a javascript object.
+         */
+        toSerialDate(date: Date): number;
+        /**
+         * Returns a date from an SerialDate value. This is used for date calculations.
+         *
+         * @param serialDate A serialized date as a number.
+         */
+        fromSerialDate(serialDate: number): Date;
+        /**
+         * Splits a serial date into its calendar and clock fields, without constructing a `Date`.
+         *
+         * @param serialDate The serial date to split.
+         * @param reuseParts Avoids allocating a fresh `ParsedDateTime`:
+         * - An object: the fields are written into THIS object, which is returned. The caller owns
+         *   the buffer's lifetime — do not hold onto a previous result across a reused call, each
+         *   call overwrites it in place. For an operator that calls this once per cell over a large
+         *   range (e.g. matching a date-group filter).
+         * - `true`: the fields are written into a shared scratch object and returned — for a
+         *   one-off caller that just wants to avoid the allocation without owning a buffer itself.
+         *   The result must be consumed immediately (read a field, done).
+         *
+         * @remarks
+         * Prefer this to {@link fromSerialDate} for calendar-field comparisons (year/month/day/…) —
+         * it skips the `Date` allocation entirely, not just the reuse of one.
+         */
+        getDateParts(serialDate: number, reuseParts?: ParsedDateTime | boolean): ParsedDateTime;
+        /**
+         * Defers evaluation of the current value so it can be processed in a
+         * batched call to {@link ICondition.IOperator.doBatch}.
+         *
+         * @param key A grouping key used to batch or deduplicate values.
+         * The key can be any value; typical choices are:
+         * - The raw cell value (to dedupe identical values).
+         * - A normalized form (e.g. lower-cased email, trimmed address).
+         * - A composite object if the operator needs multiple fields for batching.
+         *
+         * @remarks
+         * This method is intended for advanced operators that want to:
+         *
+         * - Call external services (e.g. email verification, address lookup).
+         * - Perform expensive computations once per unique value or per batch.
+         *
+         * When a predicate calls `ctx.deferBatch(key)`:
+         *
+         * - The engine records the current value (and its cell context) into a batch
+         *   associated with the active operator.
+         * - The **immediate boolean return value of the predicate is ignored** for
+         *   that call; the final result will come from the operator’s
+         *   {@link ICondition.IOperator.doBatch} implementation.
+         * - After the scan, the engine invokes `doBatch` once with the collected
+         *   values and uses its boolean results as the actual condition outcomes.
+         *
+         * Rules that do not use batching can ignore this API entirely.
+         *
+         * @throws Error
+         * Throws if `deferBatch` is called but the active operator does not implement
+         * {@link ICondition.IOperator.doBatch}. This protects against accidentally
+         * deferring work for a operator that has no batch handler.
+         */
+        deferBatch(key?: any): void;
+        /**
+         * Returns a formula instance if calculations are available.
+         *
+         * @remarks
+         * This can be used by operators that need to create temporary formulas
+         * for evaluating expressions or other complex logic.
+         */
+        createFormula(expression: string, coords?: IRange.CellCoords | null): ICalculation.IFormula | null;
+        /**
+         * Declares that this condition depends on `expression`, and resolves to its values across
+         * {@link getCoords}.
+         *
+         * @param expression The formula this operator needs, exactly 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
+         *          answer with. Already-delivered values come back without awaiting anything.
+         *
+         * @remarks
+         * The ONLY way an operator should reach a formula. Await it in `createPredicate` — which is
+         * itself awaited — and the predicate that comes out is a plain synchronous read of the values.
+         * No operator needs to compile, evaluate, or batch anything.
+         *
+         * What happens behind it depends on who is asking, and an operator neither knows nor cares:
+         *
+         * - A long-lived owner (a conditional format, a data validation) **watches**. The first call
+         *   registers, so that when anything the formula reads changes — including cells outside the
+         *   rule's own ranges, which its range listener cannot see — the rule re-runs and this returns
+         *   the new values. The owner holds the registration, because a watch outlives the predicate.
+         * - 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>;
+    }
+    /**
+     * Predicate function used to evaluate condition matches.
+     */
+    interface Predicate {
+        (value: Scalar, ctx: ICondition.IContext): boolean;
+    }
+    /**
+     * Used for defining condition operators.
+     */
+    interface IOperator<P = any> {
+        /**
+         * The name of the operator.
+         */
+        getName(): string;
+        /**
+         * Called once per evaluation to build the operator predicate.
+         *
+         * @remarks
+         * - May be async: callers must await the result before evaluation.
+         * - `ctx` is scoped to the condition block (same one you’ll see inside the predicate),
+         *   so you can safely use it for one-time initialization, stats, etc.
+         * - The createPredicate pattern is used to enable batching and async.
+         * - May return `null` to indicate no predicate (the condition always evaluates to true).
+         */
+        createPredicate(param: P, ctx: ICondition.IContext): MaybePromise<ICondition.Predicate | null>;
+        /**
+         * Return types of scalars this operator supports.
+         *
+         * @remarks
+         * * If not specified or `null` is returns all types will be passed.
+         * * A `null` entry indicates untyped/variant values.
+         * * Value is stable and should not change between calls for the same operator instance.
+         */
+        getAcceptsTypes?(): readonly (InteropScalarType | null)[] | null;
+        /**
+         * Returns true if operator works with list selectors.
+         * Expects param to have { values: Scalar[] }
+         */
+        acceptsList?(): boolean;
+        /**
+         * Composes other conditions (param is ICondition or ICondition[])
+         */
+        isCombinator?(): boolean;
+        /**
+         * Get selector type for param (RHS).
+         *
+         * @param lhsSelector - The current LHS selector (for context)
+         * @returns The selector type for the param.
+         *
+         * @remarks
+         * If `null` then this is a 'unary' operator (no param).
+         */
+        getParamType?(lhsSelector?: ICondition.ISelector): string | null;
+        /**
+         * Creates the default param for this operator type.
+         */
+        createDefaultParam?(lhsSelector?: ICondition.ISelector): P | null | undefined;
+        /**
+         * Returns a human-readable title of the operator.
+         */
+        getTitle?(): string | undefined;
+        /**
+         * Returns a human-readable description of the operator.
+         */
+        getDescription?(): string | null;
+        /**
+         * Optional hook that allows this operator to evaluate multiple values in a single
+         * batched operation instead of one-by-one predicate calls.
+         *
+         * @param keys A set of batch **keys** previously passed to
+         * {@link ICondition.IContext.deferBatch}. The interpretation of each
+         * key is operator-specific:
+         * - Many operators use the value itself as the key (e.g. ticker symbol, email).
+         * - Some operators may use an accumulator object (e.g. a single SparseBuilder).
+         *
+         * @param param
+         * The same param object originally passed to {@link ICondition.IOperator.createPredicate}.
+         *
+         * @param ctx
+         * A shared {@link ICondition.IContext} instance that can be used to:
+         * - Inspect range statistics via {@link ICondition.IContext.getRangeStats}.
+         * - Coerce values via {@link ICondition.IContext.toScalarType}.
+         * - Access today’s date, the condition coordinates, current workbook calculation
+         *   engine, etc.
+         *
+         * @returns An `IRange<boolean>` whose shape matches the condition range.
+         *
+         * @remarks
+         * Typical pattern:
+         *
+         * 1. `createPredicate` constructs one or more accumulator objects (e.g., a
+         *    range updater or a per-key bucket).
+         * 2. Each predicate call:
+         *    - records its input in the relevant accumulator,
+         *    - calls `ctx.deferBatch(accumulatorKey)`,
+         *    - and returns a dummy boolean (ignored for batched cases).
+         * 3. After all predicate calls complete for this condition, the engine calls
+         *    `doBatch` once with the set of accumulator keys. The operator then:
+         *    - finalizes its accumulators, and
+         *    - produces an `IRange<boolean>` giving the final in/out result per cell.
+         *
+         * Rules that do not implement `doBatch` must not call
+         * {@link ICondition.IContext.deferBatch}. The engine will throw in that case.
+         */
+        doBatch?(keys: Set<any>, param: P, ctx: ICondition.IContext): MaybePromise<IRange<boolean> | null> | undefined;
+        /**
+         * Optional function to convert the param to a string representation.
+         *
+         * @returns A string representation of the param, or `undefined` if not implemented.
+         *
+         * @remarks
+         * This can be used for displaying the operator and param in a human-readable format.
+         */
+        toString?(param?: P, lhsSelector?: ICondition.ISelector | null): string | undefined;
+    }
+    interface Transformer<T extends Scalar, I extends Scalar = T> {
+        (value: I, ctx: ICondition.IContext): T;
+    }
+    /**
+     * Used for defining condition selectors.
+     */
+    interface ISelector<T extends Scalar = Scalar, I extends Scalar = T> {
+        /**
+         * Called once per evaluation to build the selector predicate.
+         *
+         * @remarks
+         * - May be async: callers must await the result before evaluation.
+         * - `ctx` is scoped to the condition block (same one you’ll see inside the predicate),
+         *   so you can safely use it for one-time initialization, stats, etc.
+         * - An example of where we would want to batch is 'address or 'in list'.
+         * - Return `null` for identity selectors (no transformation needed — value passes through as-is).
+         */
+        createTransformer(ctx: ICondition.IContext): MaybePromise<ICondition.Transformer<T, I> | null>;
+        /**
+         * The name of the selector.
+         */
+        getName(): string;
+        /**
+         * Return type of scalar this selector returns.
+         *
+         * @remarks
+         * * If not specified or `null` is returns all types will be passed.
+         * * Value is stable and should not change between calls for the same selector instance.
+         */
+        getSelectType(): InteropScalarType | null;
+        /**
+         * Return type of scalar this selector accepts.
+         *
+         * @remarks
+         * * If not specified or `null` is returns all types will be passed.
+         * * Value is stable and should not change between calls for the same selector instance.
+         */
+        getInputType(): InteropScalarType | null;
+        /**
+         * Returns a human-readable title of the selector.
+         */
+        getTitle?(): string;
+        /**
+         * Returns a human-readable description of the selector.
+         */
+        getDescription?(): string;
+        /**
+         * Optional function to provide a hint for rendering the condition in the UI.
+         *
+         * @returns A string hint for rendering the condition.
+         *
+         * @remarks
+         * This can be used to provide additional context or guidance for users when displaying the condition in the UI.
+         * Some examples of built-in hints are:
+         *
+         * Examples:
+         * * The `Items` operator might return `"list"` to suggest a list-style editor.
+         * * The `Boolean` operator might return `"checkbox"`.
+         */
+        getRenderHints?(): readonly string[] | null;
+    }
+    /**
+     * A selector that operates on lists of values, such as "is in list" or "contains".
+     */
+    interface IListSelector<T extends Scalar = Scalar, I extends Scalar = T> extends ISelector<T, I> {
+        /**
+         * Returns true to indicate this is a list selector.
+         */
+        readonly isList: true;
+    }
+    /**
+     * This is a a simple object that has the operator and param for a filter.
+     */
+    interface Properties<P = any> {
+        /**
+         * The selector.
+         */
+        selector?: string | ICondition.ISelector | null;
+        /**
+         * The operator.
+         */
+        operator?: string | ICondition.IOperator | null;
+        /**
+         * The param for the condition.
+         *
+         * @remarks
+         * This is operator-specific and not all operators require param.
+         */
+        param?: P;
+        /**
+         * Whether to include blank cells when applying the condition.
+         *
+         * @defaultValue `false`
+         *
+         * @remarks
+         * If `includeBlanks` is `false` (default), blanks are treated as non-matches,
+         * even if the operator would otherwise match them.
+         */
+        includeBlanks?: boolean;
+    }
+    type Input<P = any> = ICondition<P> | ICondition.IndexedProperties<P> | ICondition.Predicate | string;
+    interface IndexedProperties<P = any> extends ICondition.Properties<P> {
+        /**
+         * The zero-based index within the consumer to which this condition applies.
+         */
+        index?: number;
+    }
+    /**
+   * Options for applying conditions across multiple spans (rows or columns).
+   */
+    interface RangeOptions {
+        /**
+         * The condition.
+         */
+        conditions: ICondition.Input[];
+        /**
+         * The axis to hide.
+         */
+        axis?: IRange.Axis;
+        /**
+         * If filtering should include the hidden row/columns
+         *
+         * @defaultValue false
+         */
+        includeHidden?: boolean | IRange.Axis;
+        /**
+         * Indicate if the range has a header. If `true` the first row/column (per {@link axis}) is
+         * never evaluated or hidden.
+         *
+         * @defaultValue false
+         *
+         * @remarks
+         * Mirrors `ISort.RangeOptions.hasHeader`, but unlike sort this never guesses — a filter
+         * with no explicit `hasHeader` evaluates the entire range, header row included.
+         */
+        hasHeader?: boolean;
+    }
+    /**
+     * JSON for serialization and round-tripping.
+     */
+    interface JSON<C = any> extends IndexedProperties<C> {
+    }
+}
+//# sourceMappingURL=ICondition.d.ts.map