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

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

@@ -5,7 +5,9 @@ export declare class OrOperator extends AbstractOperator<readonly ICondition.Inp
     /** {@inheritDoc ICondition.IOperator.isCombinator} */
     isCombinator(): boolean;
     /** {@inheritDoc ICondition.IOperator.createPredicate} */
-    createPredicate(param: readonly ICondition.Input[], ctx: ICondition.IContext): Promise<ICondition.Predicate>;
+    createPredicate(param: readonly ICondition.Input[], ctx: ICondition.IContext): Promise<ICondition.Predicate | null>;
+    /** {@inheritDoc ICondition.IOperator.validateParam} */
+    validateParam(param: readonly ICondition.Input[], lhsSelector?: ICondition.ISelector | null): string | null;
     /** {@inheritDoc ICondition.IOperator.toString} */
     toString(param?: readonly ICondition.Input[], lhsSelector?: ICondition.ISelector): string | undefined;
 }

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

@@ -4,5 +4,7 @@ export declare class StartsWithOperator extends AbstractOperator<string> impleme
     constructor();
     /** {@inheritDoc ICondition.IOperator.createPredicate} */
     createPredicate(param: string, ctx: ICondition.IContext): ICondition.Predicate;
+    /** {@inheritDoc ICondition.IOperator.validateParam} */
+    validateParam(param: string, lhsSelector?: ICondition.ISelector | null): string | null;
 }
 //# sourceMappingURL=StartsWithOperator.d.ts.map

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

@@ -3,6 +3,8 @@ import { AbstractOperator } from './AbstractOperator';
 export declare class TimePeriodOperator extends AbstractOperator<ICondition.TimePeriodOption> {
     constructor();
     createPredicate(param: ICondition.TimePeriodOption, ctx: ICondition.IContext): Promise<ICondition.Predicate>;
+    /** {@inheritDoc ICondition.IOperator.validateParam} */
+    validateParam(param: ICondition.TimePeriodOption, lhsSelector?: ICondition.ISelector | null): string | null;
     /** {@inheritDoc ICondition.IOperator.createDefaultParam} */
     createDefaultParam(lhsSelector?: ICondition.ISelector): ICondition.TimePeriodOption;
     /** {@inheritDoc ICondition.IOperator.toString} */

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

@@ -4,6 +4,12 @@ export declare class TopNOperator extends AbstractOperator<ICondition.TopNOption
     constructor();
     /** {@inheritDoc ICondition.IOperator.createPredicate} */
     createPredicate(param: ICondition.TopNOption, ctx: ICondition.IContext): ICondition.Predicate;
+    /**
+     * {@inheritDoc ICondition.IOperator.validateParam}
+     *
+     * Excel's Top 10 dialog takes 1 to 1000 items, or 1 to 100 percent.
+     */
+    validateParam(param: ICondition.TopNOption, lhsSelector?: ICondition.ISelector | null): string | null;
     /** {@inheritDoc ICondition.IOperator.createDefaultParam} */
     createDefaultParam(lhsSelector?: ICondition.ISelector): ICondition.TopNOption;
     /** {@inheritDoc ICondition.IOperator.toString} */

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

@@ -1,14 +1,19 @@
 import { InteropScalarType, Scalar } from '@sheetxl/primitives';
 import { MaybePromise } from '@sheetxl/utils';
 import { ICondition } from '../ICondition';
+/**
+ * A selector that gates and does not project: a value it accepts is read as itself, any other
+ * is {@link ICondition.NotApplicable}.
+ */
 export declare class BaseSelector<T extends Scalar = Scalar, I extends Scalar = T> implements ICondition.ISelector<T, I> {
     protected _name: string;
     protected _type: InteropScalarType | null;
     protected _inputType: InteropScalarType | null;
     protected _title: string | undefined;
     protected _description: string | undefined;
-    protected _renderingHints: readonly string[] | null;
-    constructor(options: ConstructorOptions);
+    protected _gate: ((value: I) => boolean) | null;
+    protected _defaultCondition: ICondition.DefaultCondition | null;
+    constructor(options: ConstructorOptions<I>);
     /** {@inheritDoc ICondition.ISelector.createTransformer} */
     createTransformer(ctx: ICondition.IContext): MaybePromise<ICondition.Transformer<T, I> | null>;
     /** {@inheritDoc ICondition.ISelector.getName} */
@@ -29,15 +34,25 @@ export declare class BaseSelector<T extends Scalar = Scalar, I extends Scalar =
     getTitle(): string;
     /** {@inheritDoc ICondition.ISelector.getDescription} — resolved at display; see {@link getTitle}. */
     getDescription(): string;
-    /** {@inheritDoc ICondition.ISelector.getRenderHints} */
-    getRenderHints(): readonly string[] | null;
+    /** {@inheritDoc ICondition.ISelector.getDefaultCondition} */
+    getDefaultCondition(_context?: ICondition.DefaultConditionContext): ICondition.DefaultCondition | null;
 }
-export interface ConstructorOptions {
+export interface ConstructorOptions<I extends Scalar = Scalar> {
     name: string;
     type: InteropScalarType | null;
     inputType?: InteropScalarType | null;
     title?: string;
     description?: string;
-    renderingHints?: string | string[];
+    /**
+     * The selector's domain: whether a (non-blank) value is of the kind it reads. Omitted, every
+     * value is.
+     */
+    gate?: (value: I) => boolean;
+    /**
+     * What {@link ICondition.ISelector.getDefaultCondition} returns.
+     */
+    defaultCondition?: ICondition.DefaultCondition | null;
 }
+/** A number: what Whole, Number, Date and Time read. A boolean is not one (DIFFERENCES-CONDITIONS §1). */
+export declare const isNumberValue: (value: Scalar) => boolean;
 //# sourceMappingURL=BaseSelector.d.ts.map

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

@@ -1,14 +1,13 @@
-import { MaybePromise } from '@sheetxl/utils';
-import { ICondition } from '../ICondition';
 import { BaseSelector } from './BaseSelector';
 /**
  * DateSelector:
  *
- * Returns the date portion of a date time.
+ * A number read as itself, compared as a date. A date is an encoding of a serial, not a
+ * projection of one: Excel's validation compares the raw serial, so `9/23/95 12:00` passes
+ * "greater than 9/23/95" and fails "equal to 9/23/95" (P11). A day, a month or a year is an
+ * interval the operator tests (`timePeriod`, a filter's date groups), never a floor here.
  */
 export declare class DateSelector extends BaseSelector<number, number> {
     constructor();
-    /** {@inheritDoc ICondition.ISelector.createTransformer} */
-    createTransformer(ctx: ICondition.IContext): MaybePromise<ICondition.Transformer<number, number> | null>;
 }
 //# sourceMappingURL=DateSelector.d.ts.map

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

@@ -0,0 +1,20 @@
+import { Scalar } from '@sheetxl/primitives';
+import { MaybePromise } from '@sheetxl/utils';
+import { ICondition } from '../ICondition';
+import { BaseSelector } from './BaseSelector';
+/**
+ * DisplaySelector:
+ *
+ * The text a cell shows. Every cell is in its domain; the reading is the displayed text under a
+ * filter (`$1` for a cell holding 1 under `$0`), and the value's own text under a format or a
+ * validation, where nothing is shown at evaluation. Excel's filter `equal` and its values list
+ * compare this way (DESIGN-FILTER §3.2, P10), which is where the xlsx reader sets it. The text
+ * family (contains, starts with) stays under no selector: Excel's reads the raw text of a text
+ * cell and never a number's display.
+ */
+export declare class DisplaySelector extends BaseSelector<string, Scalar> {
+    constructor();
+    /** {@inheritDoc ICondition.ISelector.createTransformer} */
+    createTransformer(ctx: ICondition.IContext): MaybePromise<ICondition.Transformer<string, Scalar> | null>;
+}
+//# sourceMappingURL=DisplaySelector.d.ts.map

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

@@ -1,16 +1,18 @@
+import { Scalar } from '@sheetxl/primitives';
 import { MaybePromise } from '@sheetxl/utils';
 import { ICondition } from '../ICondition';
 import { BaseSelector } from './BaseSelector';
 /**
  * TextLengthSelector:
  *
- * Selector: Transforms string -> number (length)
- * Operator: Standard comparison (>, <, =, etc.) from Scalar
- * Result: Predicate that checks if text.length meets condition
+ * `LEN` of the value's own text: a string's length, a number's `General` text (`1.5` is 3, a
+ * serial under a date format is 5, not the date's 8), a boolean's word (`TRUE` is 4). Measured
+ * against Excel's text-length validation (P11). An error has no text and is not applicable.
+ * The displayed text is the Display selector's reading, not this one's.
  */
-export declare class TextLengthSelector extends BaseSelector<number, string> {
+export declare class TextLengthSelector extends BaseSelector<number, Scalar> {
     constructor();
     /** {@inheritDoc ICondition.ISelector.createTransformer} */
-    createTransformer(ctx: ICondition.IContext): MaybePromise<ICondition.Transformer<number, string> | null>;
+    createTransformer(ctx: ICondition.IContext): MaybePromise<ICondition.Transformer<number, Scalar> | null>;
 }
 //# sourceMappingURL=TextLengthSelector.d.ts.map

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

@@ -1,14 +1,12 @@
-import { MaybePromise } from '@sheetxl/utils';
-import { ICondition } from '../ICondition';
 import { BaseSelector } from './BaseSelector';
 /**
  * TimeSelector:
  *
- * Returns the time portion of a date time.
+ * A number read as itself, compared as a time of day. The fraction is not taken: Excel's
+ * validation compares the raw serial, so `1/1/2020 09:30` fails "between 9:00 and 17:00" and
+ * passes "not between" (P11). What differs from Date is how an operand is parsed and shown.
  */
 export declare class TimeSelector extends BaseSelector<number, number> {
     constructor();
-    /** {@inheritDoc ICondition.ISelector.createTransformer} */
-    createTransformer(ctx: ICondition.IContext): MaybePromise<ICondition.Transformer<number, number> | null>;
 }
 //# sourceMappingURL=TimeSelector.d.ts.map

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

@@ -1,14 +1,12 @@
-import { MaybePromise } from '@sheetxl/utils';
-import { ICondition } from '../ICondition';
 import { BaseSelector } from './BaseSelector';
 /**
  * WholeSelector:
  *
- * Returns the whole portion of a number.
+ * A number with no fraction, read as itself. A fraction is not a whole number: `2.5` under
+ * "whole number between 1 and 5" is not applicable rather than outside 1..5, so it fails under
+ * "not between" too (Excel, P11). Text and booleans are not numbers.
  */
 export declare class WholeSelector extends BaseSelector<number, number> {
     constructor();
-    /** {@inheritDoc ICondition.ISelector.createTransformer} */
-    createTransformer(ctx: ICondition.IContext): MaybePromise<ICondition.Transformer<number, number> | null>;
 }
 //# sourceMappingURL=WholeSelector.d.ts.map

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

@@ -1,18 +1,24 @@
+import { Scalar } from '@sheetxl/primitives';
 import { BaseSelector } from './BaseSelector';
-import { ListSelector } from './ListSelector';
 import { DateSelector } from './DateSelector';
+import { DisplaySelector } from './DisplaySelector';
 import { TimeSelector } from './TimeSelector';
 import { WholeSelector } from './WholeSelector';
 import { TextLengthSelector } from './TextLengthSelector';
+/**
+ * The built-in selectors. Each gates on one kind of value and reads it as itself, except
+ * Text length and Display, which project. A boolean is not a number under any of the number selectors
+ * (DIFFERENCES-CONDITIONS §1), and an error is nothing's.
+ */
 export declare const BuiltinSelectors: {
-    readonly List: ListSelector<import('@sheetxl/primitives').Scalar, import('@sheetxl/primitives').Scalar>;
-    readonly Logical: BaseSelector<import('@sheetxl/primitives').Scalar, import('@sheetxl/primitives').Scalar>;
-    readonly DateTime: BaseSelector<import('@sheetxl/primitives').Scalar, import('@sheetxl/primitives').Scalar>;
+    readonly Logical: BaseSelector<Scalar, Scalar>;
+    readonly DateTime: BaseSelector<Scalar, Scalar>;
     readonly Date: DateSelector;
     readonly Time: TimeSelector;
-    readonly Text: BaseSelector<import('@sheetxl/primitives').Scalar, import('@sheetxl/primitives').Scalar>;
+    readonly Text: BaseSelector<Scalar, Scalar>;
     readonly TextLength: TextLengthSelector;
-    readonly Number: BaseSelector<import('@sheetxl/primitives').Scalar, import('@sheetxl/primitives').Scalar>;
+    readonly Display: DisplaySelector;
+    readonly Number: BaseSelector<Scalar, Scalar>;
     readonly Whole: WholeSelector;
 };
 //# sourceMappingURL=index.d.ts.map

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

@@ -15,6 +15,8 @@ export declare class Condition<P = any> implements ICondition<P> {
     getParam(): P;
     /** {@inheritDoc ICondition.isIncludeBlanks} */
     isIncludeBlanks(): boolean;
+    /** {@inheritDoc ICondition.validate} */
+    validate(): string | null;
     /** {@inheritDoc ICondition.toString} */
     toString(): string;
     /** {@inheritDoc ICondition.toJSON} */
@@ -34,13 +36,13 @@ export declare namespace Condition {
      * For runtime lookup by string name, use `Condition.Selectors.get(name)`.
      */
     const BuiltInSelectors: {
-        readonly List: import("./BuiltinSelectors/ListSelector").ListSelector<import("@sheetxl/primitives").Scalar, import("@sheetxl/primitives").Scalar>;
         readonly Logical: import("./BuiltinSelectors/BaseSelector").BaseSelector<import("@sheetxl/primitives").Scalar, import("@sheetxl/primitives").Scalar>;
         readonly DateTime: import("./BuiltinSelectors/BaseSelector").BaseSelector<import("@sheetxl/primitives").Scalar, import("@sheetxl/primitives").Scalar>;
         readonly Date: import("./BuiltinSelectors/DateSelector").DateSelector;
         readonly Time: import("./BuiltinSelectors/TimeSelector").TimeSelector;
         readonly Text: import("./BuiltinSelectors/BaseSelector").BaseSelector<import("@sheetxl/primitives").Scalar, import("@sheetxl/primitives").Scalar>;
         readonly TextLength: import("./BuiltinSelectors/TextLengthSelector").TextLengthSelector;
+        readonly Display: import("./BuiltinSelectors/DisplaySelector").DisplaySelector;
         readonly Number: import("./BuiltinSelectors/BaseSelector").BaseSelector<import("@sheetxl/primitives").Scalar, import("@sheetxl/primitives").Scalar>;
         readonly Whole: import("./BuiltinSelectors/WholeSelector").WholeSelector;
     };
@@ -79,6 +81,22 @@ export declare namespace Condition {
         Or: import("./BuiltInOperators/OrOperator").OrOperator;
         Not: import("./BuiltInOperators/NotOperator").NotOperator;
     };
+    /**
+     * The items of a list literal, a file's spelling of a typed list (`'"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. They are what {@link ICondition.InSetOption.additions} holds.
+     */
+    const parseListLiteral: (text: string) => string[] | null;
+    /**
+     * Spells {@link ICondition.InSetOption.additions} as a list literal, as a file stores a typed
+     * list: `['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).
      *