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

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

@@ -1,8 +1,9 @@
 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 { ICellStyle } from '../style';
 import { ParsedDateTime } from '../date/_DateUtils';
 /**
  * Interface that captures the selector, operator, and param.
@@ -55,11 +56,33 @@ export interface ICondition<P = any> {
      * - `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)
+     * **Ignore Blank:**
+     *
+     * On, a blank is taken out of the population before anything is asked, so whatever the host
+     * does on failure never happens to it. Off, a blank is a value like any other, judged as Excel
+     * judges an empty cell: 0 under a number rule, "" under a text one (so "whole number not
+     * between 1 and 5" passes it), a member of a set by {@link InSetOption.blank}, and what
+     * {@link BuiltInOperatorNames.Blank} names. Read on the root condition only; an editor shows
+     * it as one checkbox, "Ignore Blank", under every host. Excel's `allowBlank`.
+     *
+     * **What is blank:**
+     * - Filters and ConditionalFormat: an empty cell, a `""` result, or a string of only spaces
+     *   (Excel's `LEN(TRIM(x))=0`). A tab, a non-breaking space, `0` and an error are values.
+     * - DataValidation: an empty cell only. A `""` result is a value and is judged.
      */
     isIncludeBlanks(): boolean;
+    /**
+     * Whether the condition can be authored as it is.
+     *
+     * @returns A message key naming the first problem — an operand not yet given, bounds the wrong
+     * way around, a whole-number rule holding a fraction — or `null` when there is none.
+     *
+     * @remarks
+     * Advisory, and what an editor asks before it saves: the rules are the ones Excel's dialogs
+     * refuse on. A condition read from a file is kept and evaluated whatever this answers; a
+     * comparison missing an operand evaluates as inert rather than as wrong.
+     */
+    validate(): string | null;
     /**
      * Returns a string representation of the selector, operator, and param.
      */
@@ -86,8 +109,28 @@ export interface ICondition<P = any> {
  * - Clearing or modifying conditions.
  */
 export declare namespace ICondition {
+    /**
+     * A gate failure: the value is not of the kind the selector reads.
+     *
+     * @remarks
+     * A selector is a partial function. Outside its domain it answers this rather than a value,
+     * and the condition's answer is then neither `true` nor `false` (see {@link Answer}): "whole
+     * number between 1 and 5" asked about `2.5` is not "outside 1..5", it is "not a whole number".
+     * `not` leaves it as it is, `and` / `or` read it as `false` among their children, and every
+     * host reads it as a fail at the edge.
+     */
+    const NotApplicable: unique symbol;
+    /**
+     * What a condition answers for a value: in the set, not in the set, or not of the kind asked
+     * about ({@link NotApplicable}). A blank passes before any of these when `includeBlanks` is on.
+     */
+    type Answer = boolean | typeof NotApplicable;
     /**
      * 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 {
         /**
@@ -111,15 +154,28 @@ export declare namespace ICondition {
     }
     /**
      * Selectors
+     *
+     * @remarks
+     * A selector is how a condition reads a value: it gates (a value of another kind is not this
+     * kind) and projects (`date` is the day, `textLength` the count). No selector is "any value".
+     *
+     * Membership is not among them. A list is the {@link BuiltInOperatorNames.InSet} operator, which
+     * every selector offers; the name `'list'` is still read, as no selector with `inSet`.
      */
     const BuiltInSelectorNames: {
-        readonly List: "list";
         readonly Logical: "logical";
         readonly Date: "date";
         readonly DateTime: "dateTime";
         readonly Time: "time";
         readonly Text: "text";
         readonly TextLength: "textLength";
+        /**
+         * The text a cell SHOWS: under a filter the displayed text, so `$1` is a cell holding 1 under
+         * `$0`; under a format or a validation, where nothing is shown at evaluation, the value's own
+         * text. Type text. Excel's filter `equal` and its values list compare this way
+         * (DESIGN-FILTER §3.2, MODEL-CONDITIONS §4); `equalTo` under no selector is value equality.
+         */
+        readonly Display: "display";
         readonly Number: "number";
         readonly Whole: "wholeNumber";
     };
@@ -152,7 +208,9 @@ export declare namespace ICondition {
          */
         readonly Color: "color";
         /**
-         * Checks any value is equal to.
+         * Checks any value is equal to: value equality, `1` is every cell holding 1 and never the
+         * text `'1'`. Under the {@link BuiltInSelectorNames.Display} selector it is the text a cell
+         * shows ("displays as"), which is what Excel's filter `equal` compares.
          */
         readonly EqualTo: "equalTo";
         /**
@@ -200,7 +258,7 @@ export declare namespace ICondition {
          */
         readonly Error: "error";
         /**
-         * An operator that filters by specific items (values).
+         * Checks that a value is one of a set: membership. Offered under every selector.
          *
          * @remarks
          * * Accepts `ICondition.InSetOption`
@@ -244,7 +302,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 +359,27 @@ 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`.
+         *
+         * `null` while not yet given. The comparison matches nothing, and excludes nothing, until both
+         * bounds are.
          */
-        from: number | string;
+        from: number | string | ICalculation.IFormula | null;
         /**
-         * 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`.
+         *
+         * `null` while not yet given. The comparison matches nothing, and excludes nothing, until both
+         * bounds are.
          */
-        to: number | string;
+        to: number | string | ICalculation.IFormula | null;
     }
     interface ColorOption {
         /**
@@ -353,6 +424,7 @@ export declare namespace ICondition {
         readonly NextMonth: "nextMonth";
         readonly NextQuarter: "nextQuarter";
         readonly NextWeek: "nextWeek";
+        readonly NextYear: "nextYear";
         readonly Null: "null";
         readonly Q1: "Q1";
         readonly Q2: "Q2";
@@ -361,6 +433,7 @@ export declare namespace ICondition {
         readonly ThisMonth: "thisMonth";
         readonly ThisQuarter: "thisQuarter";
         readonly ThisWeek: "thisWeek";
+        readonly ThisYear: "thisYear";
         readonly Today: "today";
         readonly Tomorrow: "tomorrow";
         readonly YearToDate: "yearToDate";
@@ -431,26 +504,89 @@ export declare namespace ICondition {
          */
         year?: number;
     }
+    /**
+     * The set an {@link BuiltInOperatorNames.InSet} condition tests membership of.
+     *
+     * @remarks
+     * A set is `base ∪ additions − subtractions`. The base is an existing population, sampled one
+     * of two ways: a **snapshot** ({@link items}, {@link dateGroups}), resolved when the condition
+     * is authored and stored as its members, or **live** ({@link source}), a formula resolved when
+     * the condition is evaluated. {@link additions} are values the author typed, and
+     * {@link subtractions} are members taken back out.
+     *
+     * A filter's values list is a snapshot of its column. A validation's typed list is additions
+     * with no base, and a validation's range is a live base. Every part is optional and they
+     * combine: a range plus a typed `Other` is `source` and `additions`.
+     *
+     * Each part matches by its own rule, the one Excel applies to that kind of list:
+     *
+     * | part | a value matches when | text case | a number and its text |
+     * | --- | --- | --- | --- |
+     * | `items` | it is the same distinct value as an item (what `UNIQUE` tells apart) | ignored | different |
+     * | `source` | `MATCH(value, source, 0)` finds it; `*`, `?` and `~` in the value are wildcards | ignored | different |
+     * | `additions` | its text, trimmed, is an addition without its leading spaces | significant | the same |
+     * | `subtractions` | it is the same distinct value as a subtraction; it then fails whatever else it matched | ignored | different |
+     *
+     * A blank (an empty cell, a `""` result) is a member by {@link blank}, or by a `source` that
+     * holds one, less a `subtractions` entry of `null`. The condition's `includeBlanks` passes it
+     * before the set is asked.
+     *
+     * The members are matched against the selector's reading of the cell: under none, the value;
+     * under {@link BuiltInSelectorNames.Display}, the text the cell shows, so `items: ['1.50']`
+     * keeps a cell holding 1.5 under `0.00`, which is what a spreadsheet's filter list holds.
+     */
     interface InSetOption {
         /**
-         * If true this filter by blank.
+         * A snapshot's members: the values that match, as they were when the condition was authored.
+         *
+         * @remarks
+         * Matched by value: `[1]` is every cell holding 1 however it is formatted, and `['1']` the
+         * cells holding the text `1`. A value that appears later is not a member, which is why a row
+         * added under a filter is hidden when the filter is applied again.
          */
-        blank?: boolean;
+        items?: readonly Scalar[];
         /**
-         * List of item filters
+         * A live base: a formula whose result is the list, as formula text without a leading `=`
+         * (`$A$1:$A$5`, `Sheet2!$A$1:$A$9`, `MyList`, `OFFSET(...)`, `INDIRECT($E1)`).
          *
          * @remarks
-         * If this is a string that is a formula then the formula is evaluated to get the list of items.
+         * Evaluated for each cell, so a relative reference gives each cell its own list, and it
+         * follows inserts and deletes as any formula does. A resolved condition holds it as an
+         * {@link ICalculation.IFormula}.
          */
-        items?: Scalar[] | string;
+        source?: string | ICalculation.IFormula;
         /**
-         * List of date group filters.
+         * Values the author typed, as text, one entry per item. Excel's typed list (`Yes,No`).
+         *
+         * @remarks
+         * An entry is kept as typed. A trailing space is part of it and can never match, as in Excel.
+         */
+        additions?: readonly string[];
+        /**
+         * Members taken out of the set. A value that matches one fails, whatever part it came from.
+         *
+         * @remarks
+         * What narrows a live base, where a member cannot be removed from the formula. A snapshot
+         * needs none: its unchecked members are simply not in {@link items}.
          */
-        dateGroups?: DateGroupItem[];
+        subtractions?: readonly Scalar[];
+        /**
+         * A snapshot's date groups: a year, a month of a year, a day, down to the second. A date
+         * inside any group matches.
+         */
+        dateGroups?: readonly DateGroupItem[];
         /**
          * Calendar type for date group items.
          */
         calendarType?: string;
+        /**
+         * Whether a blank is a member: the `(Blank)` row of a list, OOXML's `filters/@blank`.
+         *
+         * @remarks
+         * Membership, not policy: the condition's `includeBlanks` (Ignore Blank) passes a blank
+         * before the set is asked, and is the only part of a condition a blank bypasses.
+         */
+        blank?: boolean;
     }
     interface IconOption {
         /**
@@ -460,7 +596,7 @@ export declare namespace ICondition {
         /**
          * Specifies which icon set to use.
          */
-        iconSet?: IStyle.IconSet;
+        iconSet?: ICellStyle.IconSet;
     }
     interface TopNOption {
         /**
@@ -516,6 +652,27 @@ export declare namespace ICondition {
          * Convert the value to the specified scalar type.
          */
         toType<T extends InteropScalar>(value: Scalar, type: InteropScalarType): T;
+        /**
+         * The stored value of the cell being judged, before the selector read it.
+         *
+         * @remarks
+         * For the part of a predicate that is defined on the cell rather than on the reading: an
+         * `inSet` date group is an interval of serials under any selector, since a file's values
+         * list holds its date tree beside its displayed texts. Everything else compares the value
+         * the predicate is given.
+         */
+        getValue(): Scalar;
+        /**
+         * The text the current cell shows, under a filter; `null` elsewhere.
+         *
+         * @remarks
+         * What the {@link BuiltInSelectorNames.Display} selector reads: a cell holding `1.5` and
+         * showing `1.50` reads as `1.50`. A conditional format or a data validation has no displayed
+         * text, so this answers `null` there and Display reads the value's own text.
+         *
+         * Formatted on demand, so a condition that never asks pays nothing.
+         */
+        getDisplayText(): string | null;
         /**
          * Resolves a condition input to a fully-built ICondition instance.
          *
@@ -611,10 +768,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,31 +792,19 @@ 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.
+     *
+     * @remarks
+     * A leaf operator's predicate answers `true` or `false`: it sees a blank only as `null`, and
+     * only with Ignore Blank off; never a value its selector did not read. A combinator's
+     * predicate answers an {@link Answer}, since
+     * a child's selector may have answered {@link NotApplicable}. A caller tests `=== true`.
      */
     interface Predicate {
-        (value: Scalar, ctx: ICondition.IContext): boolean;
+        (value: Scalar, ctx: ICondition.IContext): ICondition.Answer;
     }
     /**
      * Used for defining condition operators.
@@ -688,11 +834,6 @@ export declare namespace ICondition {
          * * 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[])
          */
@@ -709,8 +850,43 @@ export declare namespace ICondition {
         getParamType?(lhsSelector?: ICondition.ISelector): string | null;
         /**
          * Creates the default param for this operator type.
+         *
+         * @param lhsSelector The condition's selector, when it has one.
+         * @param context What the condition will apply to, when known. An operator may fit its
+         * default to it, as `inSet` starts from the distinct values already in the cells.
+         *
+         * @remarks
+         * Read `context.ranges` through `getStats()`, never by visiting its cells: a whole column may
+         * be selected.
+         */
+        createDefaultParam?(lhsSelector?: ICondition.ISelector, context?: ICondition.DefaultConditionContext): P | null | undefined;
+        /**
+         * Whether `param` is one this operator can be authored with under `lhsSelector`.
+         *
+         * @returns A message key naming the first problem, or `null` when there is none. Omitted, any
+         * param is taken. See {@link ICondition.validate}.
          */
-        createDefaultParam?(lhsSelector?: ICondition.ISelector): P | null | undefined;
+        validateParam?(param: P, lhsSelector?: ICondition.ISelector | null): string | null;
+        /**
+         * The candidates the param carries, as the author gave them: what a widget shows (a
+         * validation's in-cell dropdown).
+         *
+         * @param param The operator's param.
+         * @param ctx The evaluation context, when there is one. A candidate that needs evaluating (a
+         * set's live `source`) is listed only with one; without, the candidates that need none.
+         *
+         * @returns The candidates, or `null` when the param carries none. An empty array is a param
+         * that carries candidates and has none here.
+         *
+         * @remarks
+         * A sequence, not the set the predicate tests: the set is defined by every operator and
+         * rendered by none, while candidates exist only when the author supplied them (`inSet`: the
+         * typed list in its order, the source's rows). A comparison's set may be finite and still
+         * has no candidates, since nothing authored an order or a text for its members. A host asks
+         * this and keeps its own choice of whether to show a picker (a validation's `hideDropdown`);
+         * what a candidate looks like (a date wants a calendar) is the selector's type.
+         */
+        getCandidates?(param: P, ctx?: ICondition.IContext | null): MaybePromise<readonly Scalar[] | null>;
         /**
          * Returns a human-readable title of the operator.
          */
@@ -769,15 +945,30 @@ export declare namespace ICondition {
          */
         toString?(param?: P, lhsSelector?: ICondition.ISelector | null): string | undefined;
     }
+    /**
+     * A selector's reading of one value: the value as the selector's type, or
+     * {@link NotApplicable} when the value is not of the kind it reads. Never called with a blank.
+     */
     interface Transformer<T extends Scalar, I extends Scalar = T> {
-        (value: I, ctx: ICondition.IContext): T;
+        (value: I, ctx: ICondition.IContext): T | typeof NotApplicable;
     }
     /**
      * Used for defining condition selectors.
+     *
+     * @remarks
+     * A selector is how a condition reads a value: a partial function from cell values to its
+     * type ({@link getSelectType}). It **gates**, answering {@link NotApplicable} for a value that
+     * is not this kind (text under Whole, a fraction under Whole, a boolean under any number
+     * selector), and it **projects**, reading a value it accepts as something else (Text length
+     * reads `abc` as 3). Most built-in selectors only gate: Whole, Number, Date and Time read a
+     * number as itself, and differ in which operands they take.
+     *
+     * The operator never sees a value the selector did not read, and a host reads a gate failure
+     * as a fail. No selector is "any value": a condition with none reads every value as itself.
      */
     interface ISelector<T extends Scalar = Scalar, I extends Scalar = T> {
         /**
-         * Called once per evaluation to build the selector predicate.
+         * Called once per evaluation to build the selector's reading of a value.
          *
          * @remarks
          * - May be async: callers must await the result before evaluation.
@@ -785,6 +976,7 @@ export declare namespace ICondition {
          *   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).
+         * - The transformer answers {@link NotApplicable} for a value outside the selector's domain.
          */
         createTransformer(ctx: ICondition.IContext): MaybePromise<ICondition.Transformer<T, I> | null>;
         /**
@@ -800,10 +992,13 @@ export declare namespace ICondition {
          */
         getSelectType(): InteropScalarType | null;
         /**
-         * Return type of scalar this selector accepts.
+         * The type of raw value this selector reads, when it is one type.
          *
          * @remarks
-         * * If not specified or `null` is returns all types will be passed.
+         * * A fast path for the gate: a value of another type is {@link NotApplicable} without the
+         *   transformer being asked. `null` when the selector reads more than one type (Text length
+         *   reads numbers and booleans as their text), in which case the transformer gates alone.
+         * * A stored date is a number, so `Date` here admits a number.
          * * Value is stable and should not change between calls for the same selector instance.
          */
         getInputType(): InteropScalarType | null;
@@ -816,28 +1011,46 @@ export declare namespace ICondition {
          */
         getDescription?(): string;
         /**
-         * Optional function to provide a hint for rendering the condition in the UI.
+         * The condition a user starts from on choosing this selector.
          *
-         * @returns A string hint for rendering the condition.
+         * @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
-         * 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:
+         * 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.
          *
-         * Examples:
-         * * The `Items` operator might return `"list"` to suggest a list-style editor.
-         * * The `Boolean` operator might return `"checkbox"`.
+         * 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} and {@link IOperator.createDefaultParam} may fit
+     * their default to.
+     */
+    interface DefaultConditionContext {
+        /**
+         * The cells the condition will cover.
          */
-        getRenderHints?(): readonly string[] | null;
+        ranges?: ICellRanges | null;
     }
     /**
-     * A selector that operates on lists of values, such as "is in list" or "contains".
+     * The operator and param a selector's condition starts with. See
+     * {@link ISelector.getDefaultCondition}.
      */
-    interface IListSelector<T extends Scalar = Scalar, I extends Scalar = T> extends ISelector<T, I> {
+    interface DefaultCondition<P = any> {
         /**
-         * Returns true to indicate this is a list selector.
+         * The operator's name.
          */
-        readonly isList: true;
+        operator: string;
+        /**
+         * The operator's param. Omitted to take the operator's own default.
+         */
+        param?: P;
     }
     /**
      * This is a a simple object that has the operator and param for a filter.
@@ -859,13 +1072,13 @@ export declare namespace ICondition {
          */
         param?: P;
         /**
-         * Whether to include blank cells when applying the condition.
+         * Ignore Blank: a blank passes before anything is asked. See {@link ICondition.isIncludeBlanks}.
          *
-         * @defaultValue `false`
+         * @defaultValue `false`, and a blank is then a value the condition judges.
          *
          * @remarks
-         * If `includeBlanks` is `false` (default), blanks are treated as non-matches,
-         * even if the operator would otherwise match them.
+         * The root condition's alone. A combinator's child carries none: one given is not read, and
+         * is not written back.
          */
         includeBlanks?: boolean;
     }
@@ -881,7 +1094,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 +1103,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;
         /**