@sheetxl/sdk 0.8.0-beta.4 → 0.8.0-beta.6

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

@@ -61,6 +61,18 @@ export interface ICondition<P = any> {
      * - Hide for ConditionalFormat/TableFilter (default behavior is usually correct)
      */
     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.
      */
@@ -311,16 +323,22 @@ export declare namespace ICondition {
          * @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 | ICalculation.IFormula;
+        from: number | string | ICalculation.IFormula | null;
         /**
          * 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 | ICalculation.IFormula;
+        to: number | string | ICalculation.IFormula | null;
     }
     interface ColorOption {
         /**
@@ -539,6 +557,18 @@ export declare namespace ICondition {
          * Convert the value to the specified scalar type.
          */
         toType<T extends InteropScalar>(value: Scalar, type: InteropScalarType): T;
+        /**
+         * The text the current cell shows, when the evaluation matches by text; `null` otherwise.
+         *
+         * @remarks
+         * A filter matches by shown text unless asked not to ({@link ICondition.RangeOptions.match}):
+         * a cell holding `1.5` and showing `1.50` is the item `1.50`. Conditional formats and data
+         * validations match by value, so this answers `null` for them. An operator that compares
+         * text reads `ctx.getText() ?? value`.
+         *
+         * Formatted on demand, so an operator that never asks pays nothing.
+         */
+        getText(): string | null;
         /**
          * Resolves a condition input to a fully-built ICondition instance.
          *
@@ -717,6 +747,13 @@ export declare namespace ICondition {
          * Creates the default param for this operator type.
          */
         createDefaultParam?(lhsSelector?: ICondition.ISelector): 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}.
+         */
+        validateParam?(param: P, lhsSelector?: ICondition.ISelector | null): string | null;
         /**
          * Returns a human-readable title of the operator.
          */
@@ -958,6 +995,26 @@ export declare namespace ICondition {
          * with no explicit `hasHeader` evaluates the entire range, header row included.
          */
         hasHeader?: boolean;
+        /**
+         * What a filter's list items and `equalTo` text are compared with: the text a cell shows, or
+         * the value it holds.
+         *
+         * @defaultValue `'text'`
+         *
+         * @remarks
+         * `'text'` is a spreadsheet's AutoFilter: the item `1.50` keeps a cell holding `1.5` under the
+         * format `0.00`, and the item `1.5` does not. A number passed as an item or operand still
+         * matches the cells holding that number, however they are formatted.
+         *
+         * `'value'` compares typed values only, so the text `"1"` never matches the number `1`.
+         *
+         * Comparisons (`>`, `between`), Top N, averages, date periods and date groups read the value
+         * either way, and the text operators (contains, starts with, ends with) only ever match a
+         * cell that holds text.
+         *
+         * Read by filters. Conditional formats and data validations match by value.
+         */
+        match?: 'text' | 'value';
     }
     /**
      * JSON for serialization and round-tripping.

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

@@ -26,6 +26,8 @@ export declare class ConditionOperator<P = any> implements ICondition.IOperator<
     getDescription(): string | null;
     /** {@inheritDoc ICondition.createDefaultParam} */
     createDefaultParam(lhsSelector?: ICondition.ISelector): P | null | undefined;
+    /** {@inheritDoc ICondition.IOperator.validateParam} */
+    validateParam(param: P, lhsSelector?: ICondition.ISelector | null): string | null;
     /** {@inheritDoc ICondition.doBatch} */
     doBatch(keys: Set<any>, param: P, ctx: ICondition.IContext): MaybePromise<IRange<boolean> | null> | undefined;
     /** {@inheritDoc ICondition.toString} */
@@ -124,6 +126,8 @@ export declare class UnresolvedCondition<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} */
@@ -174,6 +178,12 @@ export interface DoRunRangeConditionsOptions extends ICondition.RangeOptions {
     values: ISparseGrid<Scalar>;
     coords: Readonly<IRange.Coords>;
     getHiddenRuns?: (axis: IRange.Axis) => readonly RunCoords[];
+    /**
+     * The text a cell shows, backing {@link ICondition.IContext.getText}. Supplied by the sheet;
+     * asked only when {@link ICondition.RangeOptions.match} is not `'value'`, and only for the
+     * cells a text-comparing operator reads. `value` is the cell's, which the driver holds already.
+     */
+    getText?: (rowIndex: number, colIndex: number, value: Scalar) => string;
     /**
      * Called once per contiguous run of rows/columns (per {@link ICondition.RangeOptions.axis})
      * that remain visible once every condition has been applied, in ascending order.

package/types/src/filter/IFilter.d.ts

@@ -1,4 +1,4 @@
-import { IRange } from '@sheetxl/primitives';
+import { IRange, Scalar } from '@sheetxl/primitives';
 import { ITransaction } from '../transaction';
 import { ICondition } from '../condition';
 import { ICellRange } from '../cellRange';
@@ -46,6 +46,36 @@ export interface IFilter extends ICondition.Stateful, IFilter.IFilterable {
      * This is relative to the table.
      */
     getIndex(): number;
+    /**
+     * The column's distinct values, as a filter menu lists them.
+     *
+     * @param options See {@link IFilter.GetItemsOptions}.
+     *
+     * @remarks
+     * Which rows are read depends on the column:
+     * - With no condition on it, the rows that are showing. A row hidden by another column's filter,
+     *   or by hand, is not listed.
+     * - With a condition on it, the rows every *other* column's filter passes, so a value this
+     *   column's own condition hides is listed too, unchecked.
+     *
+     * An item is `checked` when at least one row holding it passes the filters, so a column filtered
+     * by any condition (`> 5`, say) lists the passing values checked. A row hidden by hand does not
+     * uncheck its value.
+     *
+     * Reads the stored values in one pass; the cost follows the column's content, not its extent.
+     *
+     * @example
+     * ```ts
+     * const filter = table.getColumnAt(1).getFilter();
+     * const { items } = await filter.getItems();
+     * // keep the first two values
+     * await filter.setCondition({
+     *   operator: ICondition.BuiltInOperatorNames.InSet,
+     *   param: { items: items.slice(0, 2).map((item) => item.text) }
+     * });
+     * ```
+     */
+    getItems(options?: IFilter.GetItemsOptions): Promise<IFilter.Items>;
     /** For runtime type checking. */
     readonly isIFilter: true;
 }
@@ -61,6 +91,51 @@ export declare namespace IFilter {
         conditions?: ICondition.JSON[];
         axis?: IRange.Axis;
     }
+    /**
+     * Options for {@link IFilter.getItems}.
+     */
+    interface GetItemsOptions {
+        /**
+         * The distinct values to stop at.
+         *
+         * @defaultValue `10000`
+         */
+        limit?: number;
+    }
+    /**
+     * One distinct value of a filtered column.
+     */
+    interface Item {
+        /**
+         * The text the cells show. This is the item an `InSet` condition holds: a filter matches by
+         * shown text ({@link ICondition.RangeOptions.match}).
+         */
+        text: string;
+        /** The value of the first cell showing `text`; the item's place in the order. */
+        value: Scalar;
+        /** The rows holding the value. */
+        count: number;
+        /** Whether at least one row holding the value passes the filters. */
+        checked: boolean;
+    }
+    /**
+     * What {@link IFilter.getItems} answers.
+     */
+    interface Items {
+        /**
+         * The distinct texts, ascending by the workbook's comparison of their values. Values that
+         * show alike are one item. Blanks are not an item.
+         */
+        items: readonly Item[];
+        /** Whether a listed row is blank. */
+        hasBlanks: boolean;
+        /** Whether at least one blank row passes the filters. */
+        blanksChecked: boolean;
+        /** Whether the column has more distinct values than `limit`; the rest are not listed. */
+        truncated: boolean;
+        /** The rows read. */
+        total: number;
+    }
     /**
      * Interface indicating the ability to filter data.
      */

package/types/src/license/license-key.d.ts

@@ -31,7 +31,7 @@ export interface LicenseAndKey {
 }
 export interface LicenseKeyDetails {
     licensee: string;
-    type?: string;
+    type?: string | null;
     expiration?: string | null;
     developerCount?: number;
     /**
@@ -40,7 +40,7 @@ export interface LicenseKeyDetails {
      */
     runtimes?: LicenseRuntime[] | null;
     /** Licensed origins, `<protocol>://<host>` each (see `Origin`); a string is comma-separated. */
-    domains?: string | string[];
+    domains?: string | string[] | null;
     fingerprint?: string | null;
     cpuCount?: number | null;
     memory?: number | null;

package/types/src/movable/AbstractMovableContent.d.ts

@@ -0,0 +1,54 @@
+import { AbstractModel, IModel } from '../model';
+import { IMovable } from './IMovable';
+/**
+ * What every content shares: its name, its description and the movable that places it.
+ */
+export declare abstract class AbstractMovableContent<STATE extends AbstractMovableContent.State = AbstractMovableContent.State, JSON extends any = any, EVENTS extends IModel.Events = IModel.Events> extends AbstractModel<STATE, JSON, EVENTS> implements IMovable.IContent {
+    /** Numbers the default names: `Chart 3`. */
+    static instanceCounter: number;
+    private _getMovable;
+    constructor(options: AbstractMovableContent.ConstructorOptions<JSON>);
+    /** {@inheritDoc IMovable.IContent.getTypeDescription} */
+    abstract getTypeDescription(): string;
+    /** {@inheritDoc IMovable.IContent.getName} */
+    getName(): string | null;
+    /** {@inheritDoc IMovable.IContent.setName} */
+    setName(name: string): this;
+    /** {@inheritDoc IMovable.IContent.getDescription} */
+    getDescription(): string | null;
+    /** {@inheritDoc IMovable.IContent.setDescription} */
+    setDescription(description: string | null): this;
+    /** {@inheritDoc IMovable.IContent.getMovable} */
+    getMovable(): IMovable | null;
+    /** @internal */
+    protected _protectionCheck(description: string): void;
+}
+/**
+ * Interfaces for creating movable content.
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link AbstractMovableContent}
+ */
+export declare namespace AbstractMovableContent {
+    interface State extends AbstractModel.State {
+        name?: string | null;
+        description?: string | null;
+    }
+    interface ConstructorOptions<J> extends IModel.ConstructorOptions<J> {
+        /**
+         * The name. Content that a movable places is given one when this is empty.
+         */
+        name?: string | null;
+        /**
+         * The alternative text.
+         */
+        description?: string | null;
+        /**
+         * Returns the movable that places the content. Not provided for content that has none.
+         */
+        getMovable?: () => IMovable | null;
+    }
+}
+//# sourceMappingURL=AbstractMovableContent.d.ts.map

package/types/src/movable/Control.d.ts

@@ -1,14 +1,14 @@
 import { IResource, IResourceCollection } from '../resource';
-import { IModel, AbstractModel } from '../model';
 import { IEmbeddedPart } from '../io';
 import { IControl } from './IControl';
-interface State extends AbstractModel.State {
+import { AbstractMovableContent } from './AbstractMovableContent';
+interface State extends AbstractMovableContent.State {
     data?: IControl.JSON;
 }
 /**
  * Implementation for {@link IControl}.
  */
-export declare class Control extends AbstractModel<State, IControl.JSON> implements IControl {
+export declare class Control extends AbstractMovableContent<State, IControl.JSON> implements IControl {
     /**
      * The part describing the control. Held beside {@link State.data} rather than in it because the
      * resources it may carry are model references, not JSON, and have to be re-persisted per save.
@@ -21,11 +21,9 @@ export declare class Control extends AbstractModel<State, IControl.JSON> impleme
     getShapeId(): number | null;
     /** {@inheritDoc IControl.getXML} */
     getXML(): string | null;
-    /** {@inheritDoc Movable.Content.getDescription} */
-    getDescription(): string;
     /** {@inheritDoc Movable.Content.toJSON} */
     toJSON(toResourceId?: (resource: IResource) => number | null): IControl.JSON | null;
-    /** {@inheritDoc Movable.Content.getTypeDescription} */
+    /** {@inheritDoc IMovable.IContent.getTypeDescription} */
     getTypeDescription(): string;
     /** {@inheritDoc IControl.isIControl} */
     get isIControl(): true;
@@ -42,7 +40,7 @@ export declare namespace Control {
     /**
      * Options for creating a Control.
      */
-    interface ConstructorOptions extends IModel.ConstructorOptions<IControl.JSON> {
+    interface ConstructorOptions extends AbstractMovableContent.ConstructorOptions<IControl.JSON> {
         /**
          * Returns an IResource from the resourceId or null if not found.
          */

package/types/src/movable/CustomElement.d.ts

@@ -1,17 +1,16 @@
 import { IResource, IResourceCollection } from '../resource';
-import { IModel, AbstractModel } from '../model';
 import { ICustomElement } from './ICustomElement';
-interface State extends AbstractModel.State {
+import { AbstractMovableContent } from './AbstractMovableContent';
+interface State extends AbstractMovableContent.State {
     data?: any;
     type: string;
 }
 /**
  * Implementation for {@link ICustomElement}.
  */
-export declare class CustomElement extends AbstractModel<State, ICustomElement.JSON> implements ICustomElement {
+export declare class CustomElement extends AbstractMovableContent<State, ICustomElement.JSON> implements ICustomElement {
     constructor(options: CustomElement.ConstructorOptions);
     getType(): string;
-    getDescription(): string;
     toJSON(_toResourceId?: (resource: IResource) => number | null): ICustomElement.JSON | null;
     getTypeDescription(): string;
 }
@@ -27,7 +26,7 @@ export declare namespace CustomElement {
     /**
      * Options for creating a Custom Element.
      */
-    interface ConstructorOptions extends IModel.ConstructorOptions<ICustomElement.JSON> {
+    interface ConstructorOptions extends AbstractMovableContent.ConstructorOptions<ICustomElement.JSON> {
         /**
          * Returns an IResource from the resourceId or null if not found.
          */

package/types/src/movable/IControl.d.ts

@@ -1,17 +1,15 @@
 import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
 import { IResource } from '../resource';
 import { IModel } from '../model';
 import { IEmbeddedPart } from '../io';
+import { IMovable } from './IMovable';
 /**
  * Interface for working with form controls — a button, a checkbox, a scrollbar placed on a sheet.
  *
  * **PLACEHOLDER** - This is under development and not made public yet.
  */
-export interface IControl extends IModel {
-    /**
-     * Returns a description for assistive technologies.
-     */
-    getDescription(): string;
+export interface IControl extends IModel, IMovable.IContent {
     /**
      * Returns the id of the shape that draws this control, or `null` if it has none.
      *
@@ -31,6 +29,10 @@ export interface IControl extends IModel {
      */
     getXML(): string | null;
     toJSON(toResourceId?: (resource: IResource) => number | null): IControl.JSON | null;
+    /**
+     * Deletes the control, and with it the movable that places it.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
     /** For runtime type checking. */
     readonly isIControl: true;
 }

package/types/src/movable/ICustomElement.d.ts

@@ -1,14 +1,19 @@
 import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
 import { IResource } from '../resource';
 import { IModel } from '../model';
+import { IMovable } from './IMovable';
 /**
  * Interface for working with CustomMovables.
 
  * **PLACEHOLDER**
  */
-export interface ICustomElement extends IModel {
+export interface ICustomElement extends IModel, IMovable.IContent {
     toJSON(toResourceId?: (resource: IResource) => number | null): ICustomElement.JSON | null;
-    getDescription(): string;
+    /**
+     * Deletes the element, and with it the movable that places it.
+     */
+    delete(options?: ITransaction.OperationOptions): void;
 }
 /**
  * {@inheritDoc ICustomElement}

package/types/src/movable/IMovable.d.ts

@@ -3,7 +3,6 @@ import { ITypes } from '../type';
 import { ITransaction } from '../transaction';
 import { IResource } from '../resource';
 import { IListener } from '../listener';
-import { IModel } from '../model';
 import { ICellRange } from '../cellRange';
 import { IHistory } from '../history';
 import { IAnchored } from '../anchored';
@@ -43,7 +42,10 @@ export interface IMovable extends IAnchored, ITransaction.ITransactional, IHisto
      * | `'control'` | {@link IControl} — a form control |
      *
      * Anything else is content that is positioned and saved but not modeled; it answers
-     * `getType()` and nothing more.
+     * {@link IMovable.IContent} and nothing more.
+     *
+     * The content owns what identifies it: its name, its description and its id. The movable owns
+     * where it is drawn. To remove both, delete the content.
      *
      * @example
      * ```ts
@@ -51,9 +53,14 @@ export interface IMovable extends IAnchored, ITransaction.ITransactional, IHisto
      * if (content.getType() === 'shape') {
      *   const text = (content as IShape).getTextFrame()?.getText();
      * }
+     * content.delete();
      * ```
      */
-    getContent<T extends IModel>(): T;
+    getContent<T extends IMovable.IContent = IMovable.IContent>(): T;
+    /**
+     * Deletes the content, which removes this movable. The same as `getContent().delete()`.
+     */
+    delete(): void;
     /**
      * Selects the current movable.
      *
@@ -90,30 +97,6 @@ export interface IMovable extends IAnchored, ITransaction.ITransactional, IHisto
      * Returns the absolute bounds of the movable object in pixels or `null` if not yet laid out.
      */
     getBounds(): Bounds | null;
-    /**
-     * Set the name for a movable object.
-     *
-     * @param name The name of the IMovable.
-     */
-    setName(name: string): IMovable;
-    /**
-     * @see
-     * {@link setName}
-     *
-     * @returns The name or `null` if the movable has been deleted.
-     */
-    getName(): string | null;
-    /**
-     * This is the alternative text use for assistive technologies.
-     */
-    setDescription(description: string | null): IMovable;
-    /**
-     * @see
-     * {@link setDescription}
-     *
-     * @returns The description or `null` if none has been set (or the movable has been deleted).
-     */
-    getDescription(): string | null;
     /**
      * If true then the movable object is hidden.
      */
@@ -194,6 +177,61 @@ export interface IMovable extends IAnchored, ITransaction.ITransactional, IHisto
  * {@link IMovable}
  */
 export declare namespace IMovable {
+    /**
+     * What a movable draws: a chart, a picture, a shape, a slicer, a control.
+     *
+     * @remarks
+     * Content owns what identifies it, and the movable owns where it is drawn. Content can exist
+     * with no movable: a picture used as a sheet background is not placed by one.
+     */
+    interface IContent {
+        /**
+         * Returns an immutable type string.
+         */
+        getType(): string;
+        /**
+         * Returns the id of the content.
+         */
+        getId(): string;
+        /**
+         * Returns the name, or `null` if the content has none.
+         *
+         * @remarks
+         * Not defined for content that is never named.
+         */
+        getName?(): string | null;
+        /**
+         * Set the name.
+         *
+         * @param name The name of the content.
+         */
+        setName?(name: string): this;
+        /**
+         * Returns the alternative text used by assistive technologies, or `null` if none has been set.
+         */
+        getDescription(): string | null;
+        /**
+         * Set the alternative text used by assistive technologies.
+         */
+        setDescription(description: string | null): this;
+        /**
+         * Returns a label for the kind of content, such as `Chart` or `Picture`.
+         */
+        getTypeDescription(): string;
+        /**
+         * Returns the movable that places the content on the sheet, or `null` if it is not placed by
+         * one.
+         */
+        getMovable(): IMovable | null;
+        /**
+         * Deletes the content, and with it the movable that places it.
+         */
+        delete(options?: ITransaction.OperationOptions): void;
+        /**
+         * Returns `true` if the content has been deleted.
+         */
+        isDeleted(): boolean;
+    }
     /**
      * Extends {@link ITypes.SelectOptions} to include options for `IMovable`.
      */
@@ -216,11 +254,7 @@ export declare namespace IMovable {
          */
         onSelectionChange?(source: IMovable): void;
         /**
-         * Called when the name has changed.
-         */
-        onNameChange?(source: IMovable): void;
-        /**
-         * Called when selection changes.
+         * Called when the bounds have changed.
          */
         onBoundsChange?(source: IMovable): void;
         /**
@@ -296,6 +330,14 @@ export declare namespace IMovable {
          * This must align to a known movable object type. Defined in the IEmbeddedDrawing interface.
          */
         type: string;
+        /**
+         * The name of the content.
+         */
+        name?: string;
+        /**
+         * The alternative text used by assistive technologies.
+         */
+        description?: string;
         /**
          * Underlying json.
          */
@@ -314,16 +356,6 @@ export declare namespace IMovable {
          * The behavior of how the movable resizes as the anchor/cells change.
          */
         anchorType?: IAnchored.Type;
-        /**
-         * The name of the movable object.
-         */
-        name?: string;
-        /**
-         * This is the alternative text use for assistive technologies.
-         *
-         * @defaultValue null
-         */
-        description?: string;
         /**
          * If true then the movable object is hidden.
          *

package/types/src/movable/IMovableCollection.d.ts

@@ -99,6 +99,12 @@ export declare namespace IMovableCollection {
          * Initial json value.
          */
         json?: J;
+        /**
+         * The name of the content.
+         *
+         * @defaultValue A name made from the type, such as `Chart 3`.
+         */
+        name?: string;
         /**
          * If a referenceId is provided then the movable will be linked to the resource.
          * @param resourceId