@sheetxl/sdk 0.8.0-beta.15 → 0.8.0-beta.16

package/types/src/calculation/grid/ICalcGrid.d.ts

@@ -308,6 +308,23 @@ export interface ICalcGrid {
      * @param options See {@link ICalcGrid.RequestOptions}.
      */
     setFiltered(filtered: boolean, options?: ICalcGrid.RequestOptions): void;
+    /**
+     * Sets the pivot tables on the grid, as the values each shows: what `GETPIVOTDATA` reads
+     * (`IFormulaContext.getPivotAt`). Recorded and told as {@link setFiltered} is; every formula
+     * that calls `GETPIVOTDATA` recalculates.
+     *
+     * @remarks
+     * The whole set each time, its tables where they sit now: told again when one is added,
+     * moved, refreshed or deleted. Held for a start to seed from; never written by a save, the
+     * owner computes them from its tables.
+     *
+     * A table with a {@link ICalcGrid.PivotJSON.block} is placed by the engine as a spill, or
+     * `#SPILL!` at its anchor; the cells it places and removes come back as an input's do.
+     *
+     * @param pivots The tables; empty for none.
+     * @param options See {@link ICalcGrid.RequestOptions}.
+     */
+    setPivots(pivots: readonly ICalcGrid.PivotJSON[], options?: ICalcGrid.RequestOptions): Promise<ICalcGrid.Results>;
     seed(json: ICalcGrid.JSON, options?: ICalcGrid.SeedOptions): Promise<ICalcGrid.Results>;
     /**
      * Returns a JSON representation of the calcGrid.
@@ -798,12 +815,83 @@ export declare namespace ICalcGrid {
          * Whether the grid's owner is filtered ({@link ICalcGrid.setFiltered}); absent for not.
          */
         filtered?: boolean;
+        /**
+         * The pivot tables on the grid ({@link ICalcGrid.setPivots}), read by a seed; a save does not
+         * write them.
+         */
+        pivots?: readonly PivotJSON[];
         /**
          * The grid's size ({@link ICalcGrid.resize}), read by a seed; absent to keep the one it has. A
          * save does not write it: the owner keeps its own.
          */
         entireCoords?: IRange.Coords;
     }
+    /**
+     * A pivot table as the values it shows ({@link ICalcGrid.setPivots}): the data behind
+     * `IFormulaContext.PivotView`.
+     */
+    interface PivotJSON {
+        /** The cells the table covers, its page fields included. */
+        range: IRange.Coords;
+        dataFields: {
+            name: string;
+            sourceName: string;
+        }[];
+        /** The fields on rows, columns and pages, in that order. */
+        fields: PivotFieldJSON[];
+        /**
+         * Each value the table shows: per data field, then per field on rows and columns in
+         * {@link fields}' order, the item's index, or `-1` for the total over the field; then the
+         * value. Absent, the table does not show it.
+         */
+        values: [key: string, value: Scalar][];
+        /**
+         * Where the table is laid out: its cells, which are the sheet's stored values, are held over
+         * {@link range} as an extent anchored at {@link PivotBlockJSON.anchor}, which refuses a shift
+         * that would move part of it. Absent, the table is not laid out.
+         */
+        block?: PivotBlockJSON;
+        /**
+         * `false` for a table that is there but whose values are not computed (not modeled, or not
+         * laid out): {@link range} is its location, and its data fields, fields and values are empty.
+         * Absent, the values are the table's.
+         */
+        computed?: false;
+    }
+    /**
+     * Where a laid-out {@link PivotJSON | pivot table} sits.
+     */
+    interface PivotBlockJSON {
+        /** The location's top-left: where `#SPILL!` shows. Inside the range, below any page fields. */
+        anchor: {
+            row: number;
+            column: number;
+        };
+        /**
+         * The table shows `#SPILL!` at its anchor, stored there by the sheet, and covers that cell
+         * alone: it holds no extent.
+         */
+        blocked?: true;
+        /**
+         * The key in {@link PivotJSON.values} of the first cell of the data area. While the table
+         * shows `#SPILL!` it is collapsed to its anchor, where that cell sits: a query naming it reads
+         * `#SPILL!`, any other none. Absent, the table has no data area.
+         */
+        first?: string;
+    }
+    /**
+     * A field of a {@link PivotJSON}.
+     */
+    interface PivotFieldJSON {
+        name: string;
+        items: {
+            value: Scalar;
+            text: string;
+            name?: string;
+        }[];
+        /** On the page axis: the item shown, by index into `items`; `-1` for all of them. */
+        page?: number;
+    }
     /**
      * Options for {@link ICalcGrid.seed}.
      */

package/types/src/calculation/grid/_CalcRequest.d.ts

@@ -40,6 +40,15 @@ export type CalcRequest =
     type: 'filtered';
     filtered: boolean;
     options?: ICalcGrid.RequestOptions;
+}
+/**
+ * The pivot tables on the grid changed: the whole set as it is now. What `GETPIVOTDATA` reads;
+ * the formulas that call it are recalculated.
+ */
+ | {
+    type: 'pivots';
+    pivots: readonly ICalcGrid.PivotJSON[];
+    options?: ICalcGrid.RequestOptions;
 } | {
     type: 'seed';
     json: ICalcGrid.JSON;

package/types/src/calculation/spatial/FormulaSpatialValue.d.ts

@@ -395,6 +395,8 @@ export declare class FormulaSpatialValue implements IFormulaBlock, ISpatialMap.I
     getReferencedSymbolIds(): string[];
     /** {@inheritDoc IFormulaBlock.hasTotals} */
     hasTotals(): boolean;
+    /** {@inheritDoc IFormulaBlock.hasPivotData} */
+    hasPivotData(): boolean;
     /** {@inheritDoc IFormulaBlock.hasDataTable} */
     hasDataTable(): boolean;
     /** {@inheritDoc IFormulaBlock.hasVolatile} */

package/types/src/calculation/spatial/SpillEntry.d.ts

@@ -11,16 +11,30 @@ import { AsyncValue } from '../../primitives/AsyncValue';
  *   from a collision detected during a calculation cycle.
  * * `fixed` - an array-entered (Ctrl+Shift+Enter) block, whose extent is authoritative rather than
  *   derived. Degenerate 1x1 fixed entries are legal and meaningful.
+ *
+ * The anchor - the cell that owns the extent, and where a blocked spill shows `#SPILL!` - is the
+ * extent's top-left unless an offset says otherwise. It is kept as an offset from the top-left, so
+ * it moves with the extent.
  */
 export declare class SpillEntry {
     private _c;
     private _k;
     private _cycleId;
+    /** The anchor's rows and columns below and right of the top-left; `null` for the top-left. */
+    private _a;
     private _h;
     private _b;
-    constructor(coords: IRange.Coords, cycleId: number, kind?: ITypes.FormulaArrayKind, holder?: AsyncValue | null, blocked?: IRange.Coords | null);
+    constructor(coords: IRange.Coords, cycleId: number, kind?: ITypes.FormulaArrayKind, anchorOffset?: SpillEntry.AnchorOffset | null, holder?: AsyncValue | null, blocked?: IRange.Coords | null);
     /** The anchor's holder, for a spill laid out by an evaluation that deferred; `null` otherwise. */
     getHolder(): AsyncValue | null;
+    /** The cell that owns the extent: its top-left unless the entry was made with an offset. */
+    getAnchor(): SpillEntry.Anchor;
+    /** The anchor's offset from the extent's top-left; `null` when the anchor is the top-left. */
+    getAnchorOffset(): SpillEntry.AnchorOffset | null;
+    /** {@inheritDoc SpillEntry.gapOf} */
+    getGap(): IRange.Coords | null;
+    /** Whether the cell at `row`, `column` is the anchor. */
+    isAnchor(row: number, column: number): boolean;
     getCycleId(): number;
     /** {@inheritDoc ITypes.FormulaArrayKind} */
     getKind(): ITypes.FormulaArrayKind;
@@ -39,9 +53,10 @@ export declare class SpillEntry {
      */
     setError(error: boolean, cycleId: number, keepExtent?: boolean): ISpatialMap.Entry<this>;
     /**
-     * Refuses a shift that would change part of a fixed block - Excel's "You can't change part of
-     * an array." A block the shift lands entirely before or after translates whole; a delete that
-     * swallows the whole block deletes it; anything that would split, trim, or grow it throws.
+     * Refuses a shift that would change part of a fixed block or a pivot table - Excel's "You can't
+     * change part of an array." and its pivot table refusal. A block the shift lands entirely before
+     * or after translates whole; a delete that swallows the whole block deletes it; anything that
+     * would split, trim, or grow it throws.
      *
      * @param intersect The inserted or deleted range, in pre-shift coordinates.
      * @param isColumn `true` for a column shift (left/right), `false` for a row shift (up/down).
@@ -51,6 +66,9 @@ export declare class SpillEntry {
      * Called from {@link getShifted}, and hoisted ahead of the maps' shift by the callers that lift
      * intersecting spills before shifting (`markFixedSpills`), which would otherwise never hand a
      * partially covered block to this node.
+     *
+     * A pivot table's extent holds its page fields and the blank row under them, so a shift through
+     * those is refused too (`pivot-probes/probe-pivot-extent.ps1`). A blocked one is its anchor alone.
      */
     checkShift(intersect: IRange.Coords, isColumn: boolean, isInsert: boolean): void;
     /**
@@ -64,6 +82,39 @@ export declare class SpillEntry {
     /** {@inheritDoc ISpatialMap.IUpdatableValue.getSplit} */
     getSplit(coords: [IRange.Coords, IRange.Coords], _axis: IRange.Axis): [this, this] | undefined;
 }
+/**
+ * The spills over `range` a cell answers for: a pivot table's extent is the table's, not an
+ * array's, so a cell inside it reports no spill (`ICell.getSpill`), as Excel's `HasSpill` is
+ * `False` there. Range-state reads take their spills from here; the engine, the shift and write
+ * checks and saving read the spill map.
+ */
+export declare const searchCellSpills: (spills: ISpatialMap<SpillEntry>, range: IRange.Coords) => ISpatialMap.Entry<SpillEntry>[];
+export declare namespace SpillEntry {
+    /** A cell, absolute. */
+    interface Anchor {
+        row: number;
+        column: number;
+    }
+    /** How far the anchor sits below and right of the extent's top-left. */
+    interface AnchorOffset {
+        rows: number;
+        columns: number;
+    }
+    /**
+     * The row of an extent that is not the spill's: a pivot table's blank row between its page
+     * fields and its location, the row above the anchor. `null` for every other spill.
+     *
+     * @remarks
+     * Excel keeps a value written there, through a refresh, and the table is not in its way
+     * (`pivot-probes/probe-pivot-edit.ps1`); a structural edit through it is still refused, so the
+     * extent keeps it and only the spill's cells leave it out ({@link cellsOf}).
+     */
+    const gapOf: (coords: IRange.Coords, kind: ITypes.FormulaArrayKind, anchorOffset: AnchorOffset | null) => IRange.Coords | null;
+    /** The cells of an extent without its `gap` ({@link gapOf}): the extent, or the rows above and below the gap. */
+    const cellsOf: (coords: IRange.Coords, gap: IRange.Coords | null) => IRange.Coords[];
+    /** Whether `range` lies wholly in `gap`. */
+    const isInGap: (range: IRange.Coords, gap: IRange.Coords | null) => boolean;
+}
 /**
  * The holder of the spill anchored at (`row`, `col`), or `null` when no spill is anchored there
  * or its evaluation did not defer. A blocked spill's entry is anchored too.

package/types/src/calculation/state/CalcNode.d.ts

@@ -33,10 +33,13 @@ export interface CalcNodeExt {
      */
     spillDependents: ISpatialMap.Entry<PrecedentSpatialValue>[];
     /**
-     * The bottom-right of the spill extent {@link spillDependents} was searched over; the top-left
-     * is the node's own position. `-1` whenever that list is empty — a node that does not spill, and
-     * equally one whose body nothing reads.
+     * The spill extent {@link spillDependents} was searched over. Its top-left is the node's own
+     * position unless the formula spills from above or left of its cell
+     * (`IFormulaBlock.getSpillOrigin`). `-1` whenever that list is empty — a node that does not
+     * spill, and equally one whose body nothing reads.
      */
+    spillRowStart: number;
+    spillColStart: number;
     spillRowEnd: number;
     spillColEnd: number;
     /**

package/types/src/calculation/state/CalculationContext.d.ts

@@ -184,8 +184,10 @@ export declare class CalculationContext implements IFormulaContext {
     parseAsNumber(textOrNumber: Scalar | undefined, options?: IFormulaContext.ParseNumberOptions): number | undefined;
     /** @inheritdoc IFormulaContext.createCriteria */
     createCriteria(criteria: Scalar, options?: IFormulaContext.CriteriaOptions): IFormulaContext.CriteriaEvaluator;
-    /** @inheritdoc IFormulaContext.createGrouping */
-    createGrouping(keys: IRange, options?: IFormulaContext.GroupingOptions): IFormulaContext.Grouping;
+    /** @inheritdoc IFormulaContext.createPivot */
+    createPivot(rows: IRange | null, columns: IRange | null, options?: IFormulaContext.PivotOptions): IFormulaContext.Pivot;
+    /** @inheritdoc IFormulaContext.getPivotAt */
+    getPivotAt(reference: IReferenceRange): IFormulaContext.PivotView | null;
     /**
      * A one-column array of `size` rows holding `values[i]` at `rows[i]` and blank elsewhere —
      * written directly, so a mostly-blank column costs its values, not its size.

package/types/src/calculation/state/_PivotView.d.ts

@@ -0,0 +1,22 @@
+import { IFormulaContext } from '@sheetxl/primitives';
+import { ICalcGrid } from '../grid/ICalcGrid';
+/**
+ * The key of a value in {@link ICalcGrid.PivotJSON.values}: the data field, then per field on rows
+ * and columns the item's index, `-1` for the total over the field.
+ */
+export declare const pivotValueKey: (dataField: number, items: readonly number[]) => string;
+/**
+ * How a reference meets a pivot table:
+ * - `placed`: on the laid-out table;
+ * - `blocked`: on the anchor of a table showing `#SPILL!` there;
+ * - `wanted`: on a cell a blocked table wants and does not hold, which is no table's.
+ */
+export type PivotViewMode = 'placed' | 'blocked' | 'wanted';
+/**
+ * The view of a pivot's data, made once per data and mode.
+ *
+ * @param mode How the reference meets the table: a blocked table answers `#SPILL!` for its first
+ * data cell at its anchor and `#REF!` elsewhere (`pivot-probes/probe-pivot-getpivotdata-spill.ps1`).
+ */
+export declare const pivotViewOf: (json: ICalcGrid.PivotJSON, mode?: PivotViewMode) => IFormulaContext.PivotView;
+//# sourceMappingURL=_PivotView.d.ts.map

package/types/src/cell/ICell.d.ts

@@ -3,9 +3,7 @@ import { Size, Rectangle, Bounds } from '@sheetxl/utils';
 import { ITypes } from '../type';
 import { ITextFrame, TextRotation, TextStacked, IRichText } from '../text';
 import { NumberFormat } from '../numFmt';
-import { ITable } from '../table';
-import { IDataValidation } from '../dataValidation';
-import { IConditionalFormat } from '../conditionalFormat';
+import { IConditionalFormat } from '../conditionalFormat/IConditionalFormat';
 import { ICellControl } from '../cellControl';
 import { IHyperlink } from '../hyperlink';
 import { IComment } from '../comment';
@@ -342,20 +340,6 @@ export interface ICell {
      *   values, as 'general' is resolved to left or right based on the cell's content type.
      */
     getRenderHorizontalAlignment(): ITextFrame.HorizontalAlignment;
-    /**
-     * Return an {@link ITable.IColumn} if the cell is the the first row of an ITable range.
-     */
-    getColumn(): ITable.IColumn | null;
-    /**
-     * Returns the cell's primary data validation: the highest-priority one that covers it, or `null`
-     * when none does.
-     *
-     * @remarks
-     * Validations may overlap, and every one that covers the cell applies; see
-     * {@link ICellRange.getDataValidations} for all of them. The primary one is also the one Excel
-     * honors when it opens a file whose validations overlap.
-     */
-    getDataValidation(): IDataValidation | null;
     /**
      * Returns what the cell's conditional formatting DRAWS in it — an in-cell bar, an icon, or
      * neither.
@@ -383,10 +367,6 @@ export interface ICell {
      * checkbox cell holding `2` has a control and draws `2`.
      */
     getControl(): ICellControl | null;
-    /**
-     * If the cell is in a table this will return it.
-     */
-    getTable(): ITable | null;
     /**
      * Returns `true` if the cell contains a value.
      *

package/types/src/cellRange/ICellRange.d.ts

@@ -15,6 +15,7 @@ import { IWorksheet } from '../sheet';
 import { ICell } from '../cell';
 import { IComment, ICommentCollection } from '../comment';
 import { ITable, ITableCollection } from '../table';
+import { IPivotTable } from '../pivot';
 import { IMovable, IMovableCollection } from '../movable';
 import { IDataValidation, IDataValidationCollection } from '../dataValidation';
 import { IConditionalFormat, IConditionalFormatCollection } from '../conditionalFormat';
@@ -131,14 +132,16 @@ export interface ICellRange {
      */
     setControl(control: ICellControl.JSON | null, options?: ITransaction.OperationOptions): this;
     /**
-     * Returns the {@link IDataValidation}s that overlap the range.
+     * Returns the {@link IDataValidation}s that overlap the range, in priority order.
      *
      * @param options The filters of {@link IDataValidationCollection.getItems} without `address` —
      * this range is the address.
      *
      * @remarks
      * **Plural, unlike Excel.** A cell carries at most one validation there, so Excel's range accessor
-     * is singular; here a range may overlap any number of independently anchored validations.
+     * is singular; here a range may overlap any number of independently anchored validations. Every
+     * one that covers a cell applies to it. For a single cell the first is its primary validation,
+     * the one Excel honors when it opens a file whose validations overlap.
      *
      * See {@link getConditionalFormats} for the overlap and one-entry-per-item rules, which are the
      * same for every ranged item lookup.
@@ -166,6 +169,14 @@ export interface ICellRange {
      * `fullyContained` to ask only for tables the range wholly encloses.
      */
     getTables(options?: ICellRange.GetItemsOptions<ITableCollection.GetItemsOptions>): ITable[];
+    /**
+     * Returns the {@link IPivotTable}s with a cell in the range, in the order the sheet lists them.
+     *
+     * @remarks
+     * A table's cells are its location and its page fields, not the blank row between them, as
+     * Excel's `Range.PivotTable` answers. A table showing `#SPILL!` holds its anchor alone.
+     */
+    getPivotTables(): IPivotTable[];
     /**
      * Returns the {@link IMovable}s anchored over the range.
      *
@@ -2819,6 +2830,11 @@ export declare namespace ICellRange {
         readonly Table: "table";
         /** Auto-table membership. */
         readonly AutoTable: "autoTable";
+        /**
+         * Cells a pivot table is laid out over, the page fields above it included. A blocked table
+         * covers none; {@link ICellRange.getPivotTables} names the tables over a range.
+         */
+        readonly Pivot: "pivot";
         /** Has a hyperlink. Regions group by what the link says, so the same link set twice is one region. */
         readonly Hyperlink: "hyperlink";
         /**

package/types/src/collections/MixedTypedArrayList.d.ts

@@ -3,8 +3,9 @@ import { IList, IListLike } from './IList';
  * An immutable run of mixed scalar values in ONE `ArrayBuffer` or `SharedArrayBuffer`.
  *
  * Numbers, booleans and blanks are stored natively; strings, errors and rich values as `int32`
- * ids that a {@link MixedTypedArrayList.Codec} resolves. The buffer is the whole list: another thread that
- * receives its {@link MixedTypedArrayList.Handle} (and has the same codec) reads it without a copy.
+ * ids that a {@link MixedTypedArrayList.Codec} resolves. The buffer, or one region of it, is the
+ * whole list: another thread that receives its {@link MixedTypedArrayList.Handle} (and has the
+ * same codec) reads it without a copy.
  *
  * @remarks
  * Layout, for `length` values at `width` 4 or 8 bytes:
@@ -29,6 +30,8 @@ export declare class MixedTypedArrayList<T = any> implements IList<T> {
     private readonly _dt;
     private readonly _m;
     private readonly _buf;
+    /** Where the list starts in `_buf`. */
+    private readonly _o;
     private readonly _vi;
     private readonly _vf;
     private readonly _t;
@@ -73,6 +76,11 @@ export declare class MixedTypedArrayList<T = any> implements IList<T> {
     fromArray(arr: T[]): IListLike<T>;
     /** The bytes a value occupies: `4` or `8`. */
     get width(): number;
+    /**
+     * What resolves the list's string ids and error codes; `null` when it has none. Two lists with
+     * the same codec mean the same thing by the same id.
+     */
+    get codec(): MixedTypedArrayList.Codec<T> | null;
     /** Whether the buffer is a `SharedArrayBuffer`. */
     get isShared(): boolean;
     /**
@@ -162,6 +170,12 @@ export declare namespace MixedTypedArrayList {
      */
     interface Handle {
         buffer: ArrayBufferLike;
+        /**
+         * Where the list starts in `buffer`: a list allocated inside a larger memory (a WebAssembly
+         * memory, say) is a region of it. A multiple of 8 when the width is 8.
+         * @defaultValue 0
+         */
+        byteOffset?: number;
         length: number;
         width: 4 | 8;
         /** The one type, when `hasTypes` is `false`. */

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

@@ -44,6 +44,16 @@ export declare abstract class AbstractOperator<P> implements ICondition.IOperato
     protected _isMissingOperand(param: Scalar | ICalculation.IFormula | undefined): boolean;
     protected _validateOperand(param: Scalar | ICalculation.IFormula | undefined, lhsSelector: ICondition.ISelector | null | undefined, allowEmptyText?: boolean): string | null;
     protected _createComparePredicate(param: Scalar | ICalculation.IFormula | undefined, ctx: ICondition.IContext, compare: (value: number, operand: number) => boolean): Promise<ICondition.Predicate | null>;
+    /**
+     * A comparison of the text a cell shows (the Display selector) with a text operand, as Excel's
+     * filters compare a caption: the calc engine's text order (`ScalarCollation`, as `="a"<"b"`), and
+     * a `*`, `?` or `~` in the operand a wildcard, so a text it matches compares equal
+     * (`pivot-probes/probe-filter-text-compare.ps1`: `> "?"` keeps no one-character caption). A
+     * formula operand is compared as the plain comparison compares it.
+     *
+     * @param test Whether the text passes, from its order against the operand: negative, zero or positive.
+     */
+    protected _createDisplayComparePredicate(param: Scalar | ICalculation.IFormula | undefined, ctx: ICondition.IContext, test: (order: number) => boolean, compare: (value: number, operand: number) => boolean): MaybePromise<ICondition.Predicate | null>;
     /**
      * An operand as a rule's text reads it: a date or time serial as the date or time it is,
      * under a selector that reads one (`34995` is `10/23/1995` under Date); anything else as it is.

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

@@ -1,9 +1,12 @@
+import { MaybePromise } from '@sheetxl/utils';
 import { ICondition } from '../ICondition';
 import { AbstractOperator } from './AbstractOperator';
 export declare class GreaterThanEqualToOperator extends AbstractOperator<number | string> implements ICondition.IOperator<number | string> {
     constructor();
     /** {@inheritDoc ICondition.IOperator.createPredicate} */
     createPredicate(param: number | string, ctx: ICondition.IContext): Promise<ICondition.Predicate | null>;
+    /** Read through the Display selector: the shown text, in text order (`_createDisplayComparePredicate`). */
+    createDisplayPredicate(param: number | string, ctx: ICondition.IContext): MaybePromise<ICondition.Predicate | null>;
     /** {@inheritDoc ICondition.IOperator.validateParam} */
     validateParam(param: number | string, lhsSelector?: ICondition.ISelector | null): string | null;
 }

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

@@ -1,9 +1,12 @@
+import { MaybePromise } from '@sheetxl/utils';
 import { ICondition } from '../ICondition';
 import { AbstractOperator } from './AbstractOperator';
 export declare class GreaterThanOperator extends AbstractOperator<number | string> implements ICondition.IOperator<number | string> {
     constructor();
     /** {@inheritDoc ICondition.IOperator.createPredicate} */
     createPredicate(param: number | string, ctx: ICondition.IContext): Promise<ICondition.Predicate | null>;
+    /** Read through the Display selector: the shown text, in text order (`_createDisplayComparePredicate`). */
+    createDisplayPredicate(param: number | string, ctx: ICondition.IContext): MaybePromise<ICondition.Predicate | null>;
     /** {@inheritDoc ICondition.IOperator.validateParam} */
     validateParam(param: number | string, lhsSelector?: ICondition.ISelector | null): string | null;
 }

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

@@ -1,9 +1,12 @@
+import { MaybePromise } from '@sheetxl/utils';
 import { ICondition } from '../ICondition';
 import { AbstractOperator } from './AbstractOperator';
 export declare class LessThanEqualToOperator extends AbstractOperator<number | string> implements ICondition.IOperator<number | string> {
     constructor();
     /** {@inheritDoc ICondition.IOperator.createPredicate} */
     createPredicate(param: number | string, ctx: ICondition.IContext): Promise<ICondition.Predicate | null>;
+    /** Read through the Display selector: the shown text, in text order (`_createDisplayComparePredicate`). */
+    createDisplayPredicate(param: number | string, ctx: ICondition.IContext): MaybePromise<ICondition.Predicate | null>;
     /** {@inheritDoc ICondition.IOperator.validateParam} */
     validateParam(param: number | string, lhsSelector?: ICondition.ISelector | null): string | null;
 }

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

@@ -1,9 +1,12 @@
+import { MaybePromise } from '@sheetxl/utils';
 import { ICondition } from '../ICondition';
 import { AbstractOperator } from './AbstractOperator';
 export declare class LessThanOperator extends AbstractOperator<number | string> implements ICondition.IOperator<number | string> {
     constructor();
     /** {@inheritDoc ICondition.IOperator.createPredicate} */
     createPredicate(param: number | string, ctx: ICondition.IContext): Promise<ICondition.Predicate | null>;
+    /** Read through the Display selector: the shown text, in text order (`_createDisplayComparePredicate`). */
+    createDisplayPredicate(param: number | string, ctx: ICondition.IContext): MaybePromise<ICondition.Predicate | null>;
     /** {@inheritDoc ICondition.IOperator.validateParam} */
     validateParam(param: number | string, lhsSelector?: ICondition.ISelector | null): string | null;
 }

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

@@ -0,0 +1,10 @@
+import { ICondition } from '../ICondition';
+import { AbstractOperator } from './AbstractOperator';
+export declare class MatchesOperator extends AbstractOperator<string> implements ICondition.IOperator<string> {
+    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=MatchesOperator.d.ts.map

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

@@ -10,6 +10,8 @@ export declare class TimePeriodOperator extends AbstractOperator<ICondition.Time
     /** {@inheritDoc ICondition.IOperator.toString} */
     toString(param?: ICondition.TimePeriodOption, lhsSelector?: ICondition.ISelector): string | undefined;
     private _computeRange;
+    /** The months (0-11) a period that names a quarter (Q1-Q4) or a month (M1-M12) covers, in any year; else `null`. */
+    private _monthsOf;
     private _quarterRange;
 }
 //# sourceMappingURL=TimePeriodOperator.d.ts.map

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

@@ -21,6 +21,7 @@ import { ValidUrlOperator } from './ValidUrlOperator';
 import { StartsWithOperator } from './StartsWithOperator';
 import { EndsWithOperator } from './EndsWithOperator';
 import { ContainsOperator } from './ContainsOperator';
+import { MatchesOperator } from './MatchesOperator';
 import { TimePeriodOperator } from './TimePeriodOperator';
 import { TopNOperator } from './TopNOperator';
 import { AndOperator } from './AndOperator';
@@ -48,6 +49,7 @@ export declare const BuiltInOperators: {
     TextStartsWith: StartsWithOperator;
     TextEndsWith: EndsWithOperator;
     TextContains: ContainsOperator;
+    TextMatches: MatchesOperator;
     TextEmail: ValidEmailOperator;
     TextIsUrl: ValidUrlOperator;
     TimePeriod: TimePeriodOperator;

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

@@ -73,6 +73,7 @@ export declare namespace Condition {
         TextStartsWith: import("./BuiltInOperators/StartsWithOperator").StartsWithOperator;
         TextEndsWith: import("./BuiltInOperators/EndsWithOperator").EndsWithOperator;
         TextContains: import("./BuiltInOperators/ContainsOperator").ContainsOperator;
+        TextMatches: import("./BuiltInOperators/MatchesOperator").MatchesOperator;
         TextEmail: import("./BuiltInOperators/ValidEmailOperator").ValidEmailOperator;
         TextIsUrl: import("./BuiltInOperators/ValidUrlOperator").ValidUrlOperator;
         TimePeriod: import("./BuiltInOperators/TimePeriodOperator").TimePeriodOperator;

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

@@ -298,6 +298,12 @@ export declare namespace ICondition {
          * Checks any text value is greater than or equal to.
          */
         readonly TextContains: "textContains";
+        /**
+         * Checks any text value matches a pattern, the whole text and ignoring case: `*` is any run of
+         * characters, `?` any one, and `~` makes the next `*`, `?` or `~` itself. Excel's filter
+         * `equal` with a wildcard (`a?ple`, `N*th`).
+         */
+        readonly TextMatches: "textMatches";
         /**
          * Evaluates a formula expression.
          *
@@ -608,8 +614,17 @@ export declare namespace ICondition {
         limit?: number;
         /**
          * Flag indicating whether or not to filter by percent value. A `false` value filters by number of items.
+         *
+         * @remarks
+         * With {@link sum}, the percent of the values' total rather than of their count.
          */
         percent?: boolean;
+        /**
+         * Whether {@link limit} bounds the values' sum rather than their count: values are taken from
+         * the top (or the bottom) until their running sum reaches the limit, the one that reaches it
+         * included. A pivot table's Top 10 by Sum, and by Percent with {@link percent}.
+         */
+        sum?: boolean;
         /**
          * Flag indicating whether or not to filter by top order. A `false` value filters by bottom order.
          */

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

@@ -152,6 +152,11 @@ export declare class UnresolvedCondition<P = any> implements ICondition<P> {
  * of an exception that costs the caller the entire rule.
  */
 export declare function fromJSON<P = any>(json: ICondition.JSON<P> | null | undefined): ICondition<P> | null;
+/**
+ * The predicate of `condition`'s operator: under the Display selector, an ordering comparison's
+ * text one ({@link DisplayComparable}), else the operator's own. `null` for an inert condition.
+ */
+export declare function createConditionPredicate(condition: ICondition, ctx: ICondition.IContext): MaybePromise<ICondition.Predicate | null>;
 export declare function readThroughSelector(transformer: ICondition.Transformer<any, any> | null | undefined, value: Scalar, ctx: ICondition.IContext): Scalar | typeof ICondition.NotApplicable;
 /**
  * The condition's answer for the BLANK cells of a range, asked per cell — lazily, by the caller,
@@ -207,6 +212,15 @@ export interface EvalConditionAtOptions {
  * registered with the engine or kept on the condition.
  */
 export declare function evalConditionAt(condition: ICondition, value: Scalar, cell: IRange.CellCoords, options: EvalConditionAtOptions): Promise<boolean>;
+/** The runtime's today, as a whole serial: what a relative period is evaluated on when it has no anchor. */
+export declare function todaySerialOf(runtime: IRuntime): number;
+/**
+ * `condition` with its `anchorDate` set to `today` when it is a relative period, as an apply
+ * evaluates it again: Excel holds the window a filter's period was last evaluated over, and writes
+ * it, until the filter is applied again (`probe-filter-dynamic-later-day.ps1`). A period named in
+ * every year (`Q1`, `M10`) has no anchor. `condition` itself when nothing changes.
+ */
+export declare function anchorTimePeriod<T extends ICondition.Input>(condition: T, today: number): T;
 /**
  * Iterates through all values executing a single condition (`conditions[0]`) and calling the
  * appropriate callbacks. Used by Data Validation and Conditional Formatting.

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

@@ -188,7 +188,8 @@ interface State extends AnchoredConditional.State {
     style: ICellStyle.Properties | null;
     scale: IConditionalFormat.Scale | null;
     stopIfTrue: boolean;
-    pivot: boolean;
+    /** See {@link IConditionalFormat.JSON.pivotKey}. */
+    pivotKey: number | null;
     /** Opaque third-party payload. Carried, never interpreted. */
     ext: Record<string, unknown> | null;
 }

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

@@ -498,11 +498,12 @@ export declare namespace IConditionalFormat {
      */
     interface JSON extends Properties {
         /**
-         * If associated with a pivot.
+         * Present when the rule belongs to a pivot table: the number the table names it by, which is
+         * the priority the rule had in the file it was read from.
          *
-         * @defaultValue false
+         * @internal
          */
-        pivot?: boolean;
+        pivotKey?: number;
         /**
          * Payload from a rule this build does not understand.
          *