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

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

@@ -6,8 +6,9 @@ import { IHistory } from '../history';
 import { IAnchored } from '../anchored';
 import { ICellRanges } from '../cellRange';
 import { IListener } from '../listener';
+import { ICalculation } from '../calculation';
 import { ICondition } from '../condition';
-import { IStyle } from '../style';
+import { ICellStyle } from '../style';
 import { IConditionalFormatCollection } from './IConditionalFormatCollection';
 /**
  * Represents a conditional formatting rule for a range.
@@ -21,11 +22,11 @@ import { IConditionalFormatCollection } from './IConditionalFormatCollection';
  * * Conditional formatting help users identify patterns, trends, and exceptions
  *   in data by applying visual styles dynamically.
  */
-export interface IConditionalFormat extends IAnchored, ICondition.Stateful, IProperties.ICellRanged<IStyle.Properties> {
+export interface IConditionalFormat extends IAnchored, ICondition.Stateful, IProperties.ICellRanged<ICellStyle.Properties> {
     /**
      * Re-anchors this rule to `address`, REPLACING every range it currently covers.
      *
-     * @param address The range or ranges to cover — anything `ISheet.getRanges` accepts
+     * @param address The range or ranges to cover — anything `IWorksheet.getRanges` accepts
      *   (`'A1:C20'`, `'A1:A5, C1:C5'`, coords). Resolved against this rule's own sheet.
      * @param options Transaction options; `description` names the entry in undo history.
      *
@@ -97,7 +98,7 @@ export interface IConditionalFormat extends IAnchored, ICondition.Stateful, IPro
      * @remarks
      * The OOXML `dxf`, inlined. A differential format: only the properties it names are overridden.
      */
-    getStyle(): IStyle.Properties | null;
+    getStyle(): ICellStyle.Properties | null;
     /**
      * Returns what this rule draws in a cell, or `null` if it draws nothing there.
      *
@@ -241,10 +242,11 @@ export declare namespace IConditionalFormat {
          *   - Num: absolute number
          *   - Percent: 0..100 of min..max span
          *   - Percentile: 0..100 quantile (requires percentile stats)
-         * * For strings:
-         * - Formula: a formula that evaluates to a string value.
+         * * For formulas:
+         * - Formula: a formula whose result is the threshold. Authored as formula text or an
+         *   {@link ICalculation.IFormula}; a rule holds it as an `IFormula`.
          */
-        value?: number | string;
+        value?: number | string | ICalculation.IFormula;
         /**
          * Upper bound exclusivity.
          *
@@ -279,7 +281,7 @@ export declare namespace IConditionalFormat {
     interface DataBar {
         type: typeof IConditionalFormat.ScaleType.DataBar;
         /**
-         * The lower and upper bound of the bar. Always two.
+         * The lower and upper bound of the bar. Always two; a missing bound is `min` / `max`.
          */
         stops: IConditionalFormat.Stop[];
         /**
@@ -330,7 +332,8 @@ export declare namespace IConditionalFormat {
     interface IconSet {
         type: typeof IConditionalFormat.ScaleType.IconSet;
         /**
-         * Where each icon's band starts. One per icon in the set.
+         * Where each icon's band starts. One per icon in the set. With fewer than two, the bands are
+         * even percents of the range (`0/33/67` for three icons).
          */
         stops: IConditionalFormat.Stop[];
         /**
@@ -338,13 +341,13 @@ export declare namespace IConditionalFormat {
          * from and its zero-based index within that set.
          */
         icon?: {
-            set: IStyle.IconSet;
+            set: ICellStyle.IconSet;
             id: number;
         }[];
         /**
          * The icon set to use
          */
-        iconSet?: IStyle.IconSet;
+        iconSet?: ICellStyle.IconSet;
         reverse?: boolean;
         /**
          * If true, the value will be shown in the cell.
@@ -406,7 +409,7 @@ export declare namespace IConditionalFormat {
         /** Which band the value fell in. `0` is the lowest band, matching `stops[0]`. */
         index: number;
         /** The set {@link index} indexes into — the rule's own, or a per-stop override. */
-        set: IStyle.IconSet;
+        set: ICellStyle.IconSet;
         /** How many bands {@link set} has, so a renderer can bounds-check {@link index}. */
         count: number;
         /** Draw the cell's value beside the icon. When `false` the icon is the cell's only content. */
@@ -449,7 +452,7 @@ export declare namespace IConditionalFormat {
         /**
          * The differential style applied where the condition holds.
          */
-        style?: IStyle.Properties;
+        style?: ICellStyle.Properties;
         /**
          * The value→visual mapping, for the three rules that are not predicates.
          *

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

@@ -27,6 +27,8 @@ export interface IConditionalFormatCollection extends ICollection<IConditionalFo
      * @param template A template to use for the temporary item.
      */
     createItem(template?: IConditionalFormat): IConditionalFormat;
+    /** For runtime type checking. */
+    readonly isIConditionalFormatCollection: true;
 }
 /**
  * {@inheritDoc IConditionalFormatCollection}

package/types/src/dataTable/DataTable.d.ts

@@ -0,0 +1,67 @@
+import { IRange } from '@sheetxl/primitives';
+import { Anchored } from '../anchored/Anchored';
+import { AbstractAnchored } from '../anchored/AbstractAnchored';
+import { AbstractMovableContent } from '../movable/AbstractMovableContent';
+import { IDataTable } from './IDataTable';
+interface State extends AbstractAnchored.State {
+    anchorCoords: IRange.Coords;
+}
+/**
+ * Implementation for {@link IDataTable}: anchored on its result cells, its input cells held in the
+ * engine as references.
+ *
+ * @remarks
+ * Excel's rules, from `openpy-parity/probe-data-table.ps1` (2026-10-18): the results move whole or
+ * go whole ({@link _processContainerShift}), and the input cells follow their cells, a deleted
+ * one keeping its last address.
+ */
+export declare class DataTable extends AbstractAnchored<State, IDataTable.Events> implements IDataTable {
+    private _rowInput;
+    private _columnInput;
+    private _calculateAlways;
+    private _removeWatches;
+    constructor(options: DataTable.ConstructorOptions);
+    protected _initialize(options: DataTable.ConstructorOptions): void;
+    /** {@inheritDoc IDataTable.getRowInput} */
+    getRowInput(): string | null;
+    /** {@inheritDoc IDataTable.getColumnInput} */
+    getColumnInput(): string | null;
+    /** {@inheritDoc IDataTable.isRowInputDeleted} */
+    isRowInputDeleted(): boolean;
+    /** {@inheritDoc IDataTable.isColumnInputDeleted} */
+    isColumnInputDeleted(): boolean;
+    /** {@inheritDoc IDataTable.toJSON} */
+    toJSON(): IDataTable.JSON | null;
+    /**
+     * Excel's "Can't change part of a data table": an insert or delete through the results, or one
+     * that moves part of them, is refused before anything of the edit commits. An edit before them
+     * moves them whole; one taking all of them deletes the table.
+     * @internal
+     */
+    protected _processContainerShift(options: Anchored.ShiftOptions): IRange.Coords | null | void;
+    /**
+     * The results may no longer be what the table calculates: has Excel recalculate it on open.
+     * TODO - goes when the engine evaluates `TABLE`; see `Sheet._markDataTablesStale`.
+     * @internal
+     */
+    _markStale(): void;
+    /**
+     * Lets go of the input cells' references.
+     * @internal
+     */
+    _releaseWatches(): void;
+    /** @internal */
+    protected _getActionDescription(action: 'delete' | 'initialize' | 'updateListener'): string | null;
+    /** {@inheritDoc IDataTable.isIDataTable} */
+    get isIDataTable(): true;
+}
+export declare namespace DataTable {
+    interface ConstructorOptions extends Anchored.ConstructorOptions<IDataTable.JSON> {
+        /**
+         * Holds an input cell's reference in the engine. Without it the inputs are kept as read.
+         */
+        addWatch?: AbstractMovableContent.AddWatch;
+    }
+}
+export {};
+//# sourceMappingURL=DataTable.d.ts.map

package/types/src/dataTable/DataTableCollection.d.ts

@@ -0,0 +1,19 @@
+import { AbstractCollection } from '../type';
+import { IDataTable } from './IDataTable';
+import { IDataTableCollection } from './IDataTableCollection';
+/**
+ * Implementation for {@link IDataTableCollection}: a front over the sheet's anchored map. Nothing
+ * edits a data table yet, so there is nothing to announce.
+ */
+export declare class DataTableCollection extends AbstractCollection<IDataTable> implements IDataTableCollection {
+    private _getItemsDelegate;
+    /**
+     * @param getItems Returns the tables, as an array the caller may keep.
+     */
+    constructor(getItems: () => IDataTable[]);
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(): IDataTable[];
+    /** {@inheritDoc IDataTableCollection.isIDataTableCollection} */
+    get isIDataTableCollection(): true;
+}
+//# sourceMappingURL=DataTableCollection.d.ts.map

package/types/src/dataTable/IDataTable.d.ts

@@ -0,0 +1,99 @@
+import { ICellRange } from '../cellRange';
+import { IAnchored } from '../anchored';
+/**
+ * A what-if data table (Excel's **What-If Analysis > Data Table**): a block of result cells, each
+ * the table's formula evaluated with its row and column values put in the input cells.
+ *
+ * @remarks
+ * The table is carried, not calculated: its results are the values the file held, and nothing
+ * recalculates them. Excel recalculates it when it opens the file (when the calculation mode and
+ * {@link IDataTable.JSON.calculateAlways} allow).
+ *
+ * The anchor is the result cells; the formula, the row values above them and the column values to
+ * their left are ordinary cells. As in Excel, an edit to part of the results is refused, and one
+ * that clears or deletes all of them deletes the table.
+ */
+export interface IDataTable extends IAnchored {
+    toJSON(): IDataTable.JSON | null;
+    /**
+     * Returns the result cells.
+     *
+     * @remarks
+     * An insert or delete before them moves them, one taking all of them deletes the table
+     * ({@link IAnchored.isDeleted}), and one that would move part of them is refused.
+     */
+    getRange(options?: ICellRange.GetRangeOptions): ICellRange;
+    /**
+     * Returns the input cell the row values are put in, as an A1 address on this sheet, or `null`
+     * when the table has none (a one-input table down a column).
+     *
+     * @remarks
+     * Follows the cell through inserts, deletes and moves. Once the cell is deleted this is the last
+     * address it had, and {@link isRowInputDeleted} is `true`.
+     */
+    getRowInput(): string | null;
+    /**
+     * Returns the input cell the column values are put in, as an A1 address on this sheet, or `null`
+     * when the table has none (a one-input table along a row).
+     *
+     * @remarks
+     * Follows the cell as {@link getRowInput} does.
+     */
+    getColumnInput(): string | null;
+    /**
+     * Returns whether the row input cell was deleted. The table's results are then `#REF!` in Excel.
+     */
+    isRowInputDeleted(): boolean;
+    /**
+     * Returns whether the column input cell was deleted.
+     */
+    isColumnInputDeleted(): boolean;
+    /** For runtime type checking. */
+    readonly isIDataTable: true;
+}
+export declare namespace IDataTable {
+    /**
+     * JSON representation of a data table.
+     *
+     * @remarks
+     * A table has a row input, a column input, or both (a two-input table).
+     */
+    interface JSON {
+        /**
+         * The result cells, as an A1 range.
+         */
+        ref: string;
+        /**
+         * The input cell the row values are put in, as an A1 address on the same sheet.
+         */
+        rowInput?: string;
+        /**
+         * The input cell the column values are put in, as an A1 address on the same sheet.
+         */
+        columnInput?: string;
+        /**
+         * Whether the row input cell was deleted; {@link rowInput} is then its last address.
+         */
+        rowInputDeleted?: boolean;
+        /**
+         * Whether the column input cell was deleted; {@link columnInput} is then its last address.
+         */
+        columnInputDeleted?: boolean;
+        /**
+         * Whether Excel recalculates the table when it opens the file. Without it, Excel shows the
+         * results as saved until something recalculates the table.
+         *
+         * @remarks
+         * Kept as read until the workbook's cell data is edited, on any sheet. Then it is set on every
+         * table, because nothing here recalculates the results and they may no longer be right. It stays
+         * set when the edit is undone.
+         */
+        calculateAlways?: boolean;
+    }
+    /**
+     * `Events` for {@link IDataTable}.
+     */
+    interface Events extends IAnchored.Events<IDataTable> {
+    }
+}
+//# sourceMappingURL=IDataTable.d.ts.map

package/types/src/dataTable/IDataTableCollection.d.ts

@@ -0,0 +1,18 @@
+import { ICollection } from '../type';
+import { IDataTable } from './IDataTable';
+/**
+ * Holds a sheet's {@link IDataTable | data tables}.
+ *
+ * @remarks
+ * Read-only for now: a table is carried as it was read and written back. Creating one and
+ * calculating it wait on the engine evaluating `TABLE`.
+ */
+export interface IDataTableCollection extends ICollection<IDataTable> {
+    /**
+     * Returns the data tables, in the order they were read.
+     */
+    getItems(options?: ICollection.GetItemsOptions): IDataTable[];
+    /** For runtime type checking. */
+    readonly isIDataTableCollection: true;
+}
+//# sourceMappingURL=IDataTableCollection.d.ts.map

package/types/src/dataTable/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @hidden
+ */
+export * from './IDataTable';
+export * from './IDataTableCollection';
+//# sourceMappingURL=index.d.ts.map

package/types/src/dataValidation/DataValidation.d.ts

@@ -1,14 +1,18 @@
+import { IRange, IRuntime, Scalar } from '@sheetxl/primitives';
 import { ReferenceableClipboard } from '@sheetxl/utils';
 import { IListener } from '../listener';
 import { ITransaction } from '../transaction';
 import { IGrid } from '../collections';
 import { ICellRange } from '../cellRange';
+import { ICondition } from '../condition';
+import { ListSourceFormula } from '../condition/_ConditionFormula';
+import { BlankResolver } from '../condition/_ConditionUtils';
 import { AnchoredConditional } from '../condition/AnchoredConditional';
 import { IDataValidation } from './IDataValidation';
 /**
  * Implementation of {@link IDataValidation}.
  */
-export declare class DataValidation extends AnchoredConditional<State, CommitView, IDataValidation.Events> implements IDataValidation {
+export declare class DataValidation extends AnchoredConditional<State, IDataValidation.Events> implements IDataValidation {
     /**
      * Cache of failing cells for quick reads in {@link getAlertAt} — a plain field, NOT transactional
      * state, mirroring ConditionalFormat's `_matches`.
@@ -20,6 +24,21 @@ export declare class DataValidation extends AnchoredConditional<State, CommitVie
      * commit onto the undo stack for a change no user made.
      */
     protected _results: IGrid<boolean> | null;
+    /**
+     * How the EMPTY cells answer, one reader per anchored area, or `null` when every blank passes
+     * (Ignore blank on, or no condition). Swapped with {@link _results}, never materialized into it:
+     * a whole-column rule is one entry here, not a million there.
+     */
+    protected _blankAreas: BlankArea[] | null;
+    /**
+     * Whether the rule's answer for a blank can differ by position (it reads a formula). When it
+     * cannot, one question per area answers every blank in it.
+     */
+    protected _blankPerCell: boolean;
+    /** {@link _blankAreas} split into disjoint pieces, built on the first count or entries read. */
+    protected _blankPieces: BlankPiece[] | null;
+    /** {@link getAlertCount}'s answer for the current results, or `null` until asked. */
+    protected _alertCount: number | null;
     /**
      * Which evaluation round is current. Bumped once per {@link _processValueUpdates}; a round
      * writes its results only if it is still the newest when it finishes. Same shape and reason as
@@ -33,13 +52,51 @@ export declare class DataValidation extends AnchoredConditional<State, CommitVie
     /** @internal */
     protected _getDefaultState(options: DataValidation.ConstructorOptions): Readonly<State>;
     /** @internal */
-    protected _processValueUpdates(_range?: ICellRange | null): void;
+    protected _processValueUpdates(_range?: ICellRange | null): void | Promise<void>;
+    /** Swaps in one evaluation's answers; everything derived from the previous ones goes with them. */
+    protected _setResults(results: IGrid<boolean> | null, blankAreas: BlankArea[] | null, blankPerCell?: boolean): void;
+    /** Whether an EMPTY cell of `areas` fails. Every area covering the cell has a say, as for values. */
+    protected _isBlankFailing(areas: readonly BlankArea[], rowIndex: number, columnIndex: number): boolean;
+    /** One area's answer for a blank. A rule reading no formula answers once for the whole area. */
+    protected _isBlankPassing(blankArea: BlankArea, rowIndex: number, columnIndex: number): boolean;
+    /**
+     * The blank areas as disjoint pieces, each knowing every area that covers it — so an overlap is
+     * counted once and still answered by all of its rules. Disjoint areas are their own pieces.
+     */
+    protected _getBlankPieces(): BlankPiece[];
+    /** How many cells of `coords` hold a value — off the value grid's runs, never its cells. */
+    protected _countValues(coords: IRange.Coords): number;
     /** {@inheritDoc IDataValidation.getAlertAt} */
     getAlertAt(rowIndex: number, columnIndex: number): boolean;
     /** {@inheritDoc IDataValidation.getAlertEntries} */
     getAlertEntries(options?: ICellRange.IteratorOptions): IGrid.EntryIterator<boolean>;
+    /**
+     * Each piece in axis order: its stored results and its blanks, merged as the caller reads. A
+     * piece whose blanks pass is read off the results grid alone; one whose blanks fail walks its
+     * values, yielding the gaps between them without asking; one read per cell asks per gap cell.
+     */
+    protected _pieceEntries(pieces: readonly BlankPiece[], results: IGrid<boolean> | null, axis: IRange.Axis, reverse: boolean): Generator<IGrid.Entry<boolean>, undefined, undefined>;
     /** {@inheritDoc IDataValidation.getAlertCount} */
     getAlertCount(): number;
+    /** {@inheritDoc IDataValidation.getListItemsAt} */
+    getListItemsAt(rowIndex: number, columnIndex: number): Promise<readonly IDataValidation.ListItem[]>;
+    /**
+     * Appends what a live base lists at a cell to `listed`: its values, duplicates kept. Returns
+     * whether the base holds a blank (an empty cell or a `""` result), which is listed by the caller.
+     */
+    protected _listSourceItemsAt(condition: ICondition, source: ListSourceFormula, rowIndex: number, columnIndex: number, listed: IDataValidation.ListItem[]): Promise<boolean>;
+    /** {@inheritDoc IDataValidation.validateInputAt} */
+    validateInputAt(input: string | Scalar, rowIndex: number, columnIndex: number): Promise<boolean>;
+    /**
+     * The value an entry would leave in a cell: text read as typed text is, a formula evaluated at
+     * the cell. `null` for a blank entry.
+     */
+    protected _resolveEntryAt(input: string | Scalar, cell: IRange.CellCoords): Promise<Scalar>;
+    /**
+     * A list source's check for one entry: `MATCH` against the source as filled to the cell, the
+     * same check the rule watches per cell (P6), answered as a one-cell range at `cell`.
+     */
+    protected _checkListEntryAt(source: ListSourceFormula, value: Scalar, cell: IRange.CellCoords, runtime: IRuntime): Promise<IRange | null>;
     /** {@inheritDoc IDataValidation.setHideDropdown} */
     setHideDropdown(hide: boolean, options?: ITransaction.OperationOptions): this;
     /** {@inheritDoc IDataValidation.isHideDropdown} */
@@ -114,8 +171,17 @@ interface State extends AnchoredConditional.State {
     /** Opaque third-party payload. Carried, never interpreted. */
     ext: Record<string, unknown> | null;
 }
-/** @internal */
-interface CommitView extends AnchoredConditional.CommitView {
+/** One anchored area's reader for its empty cells. */
+interface BlankArea {
+    area: IRange.Coords;
+    resolve: BlankResolver;
+    /** The area's one answer when it cannot vary by position; `null` until asked. */
+    passes: boolean | null;
+}
+/** A disjoint piece of the blank areas, with every area that covers all of it. */
+interface BlankPiece {
+    coords: IRange.Coords;
+    areas: readonly BlankArea[];
 }
 export {};
 //# sourceMappingURL=DataValidation.d.ts.map

package/types/src/dataValidation/DataValidationCollection.d.ts

@@ -1,20 +1,34 @@
 import { ICellRanges } from '../cellRange';
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
 import { IDataValidationCollection } from './IDataValidationCollection';
 import { IDataValidation } from './IDataValidation';
-export declare class DataValidationCollection implements IDataValidationCollection {
+/**
+ * Implementation for {@link IDataValidationCollection}.
+ *
+ * @remarks
+ * A front over the sheet's own data-validation state — the sheet keeps the store and the
+ * events, this class keeps the API. `onCollectionChange` is the sheet's
+ * `onDataValidationsChange`, forwarded with this collection as the source.
+ */
+export declare class DataValidationCollection extends AbstractCollection<IDataValidation, IDataValidationCollection.GetItemsOptions> implements IDataValidationCollection {
     private _add;
     private _get;
     private _createItem;
-    constructor(add: (address: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions) => IDataValidation, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IDataValidation[], createItem: (template?: IDataValidation | null) => IDataValidation);
+    private _addListeners;
+    private _getSettings;
+    constructor(add: (address: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions) => IDataValidation, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => IDataValidation[], createItem: (template?: IDataValidation | null) => IDataValidation, addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove, getSettings: () => Readonly<IDataValidationCollection.Settings>);
     /** {@inheritDoc IDataValidationCollection.add} */
     add(address: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions): IDataValidation;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<IDataValidation>;
-    /** {@inheritDoc IDataValidationCollection.getItems} */
-    getItems(options?: IDataValidationCollection.GetItemsOptions): IDataValidation[];
-    /** {@inheritDoc IDataValidationCollection.getCount} */
-    getCount(): number;
-    /** {@inheritDoc IDataValidationCollection.getCount} */
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IDataValidationCollection.GetItemsOptions): IDataValidation[];
+    /** {@inheritDoc IDataValidationCollection.createItem} */
     createItem(template?: IDataValidation | null): IDataValidation;
+    /** {@inheritDoc IDataValidationCollection.getSettings} */
+    getSettings(): Readonly<IDataValidationCollection.Settings>;
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc IDataValidationCollection.isIDataValidationCollection} */
+    get isIDataValidationCollection(): true;
 }
 //# sourceMappingURL=DataValidationCollection.d.ts.map