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

package/types/src/cellControl/CellControlCollection.d.ts

@@ -0,0 +1,29 @@
+import { ICellRanges } from '../cellRange';
+import { ICollection, AbstractCollection } from '../type';
+import { IListener } from '../listener';
+import { ITransaction } from '../transaction';
+import { ICellControlCollection } from './ICellControlCollection';
+import { ICellControl } from './ICellControl';
+/**
+ * Implementation for {@link ICellControlCollection}.
+ *
+ * @remarks
+ * A front over the sheet's own cell-control state — the sheet keeps the store and the events,
+ * this class keeps the API. `onCollectionChange` is the sheet's `onCellControlsChange`, forwarded
+ * with this collection as the source.
+ */
+export declare class CellControlCollection extends AbstractCollection<ICellControl, ICellControlCollection.GetItemsOptions> implements ICellControlCollection {
+    private _add;
+    private _get;
+    private _addListeners;
+    constructor(add: (address: ICellRanges.Address, control: ICellControl.JSON, options?: ITransaction.OperationOptions) => ICellControl, get: (address: ICellRanges.Address | null | undefined, ignoreHidden?: boolean, fullyContained?: boolean) => ICellControl[], addListeners: (listeners: ICollection.IListeners, options?: IListener.Options) => IListener.Remove);
+    /** {@inheritDoc ICellControlCollection.add} */
+    add(address: ICellRanges.Address, control: ICellControl.JSON, options?: ITransaction.OperationOptions): ICellControl;
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: ICellControlCollection.GetItemsOptions): ICellControl[];
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** {@inheritDoc ICellControlCollection.isICellControlCollection} */
+    get isICellControlCollection(): true;
+}
+//# sourceMappingURL=CellControlCollection.d.ts.map

package/types/src/cellControl/CellControlRegistry.d.ts

@@ -0,0 +1,47 @@
+import { Scalar } from '@sheetxl/primitives';
+/**
+ * What a control type does to the cells it covers: which values it draws.
+ *
+ * @remarks
+ * The SDK half of a control type. How it looks and how it responds to the pointer and keys belong
+ * to the UI, which registers its own renderer under the same `type`.
+ */
+export interface ICellControlKind {
+    /**
+     * The type this kind is registered under, such as `'checkbox'`.
+     */
+    readonly type: string;
+    /**
+     * The kind's name where a UI lists the kinds that can be inserted, such as `'Rating'`. Plain
+     * text; the built-in checkbox takes its name from the command catalog instead.
+     */
+    readonly label?: string;
+    /**
+     * Whether the control draws a cell holding `value`. Any other value draws as text.
+     */
+    accepts(value: Scalar): boolean;
+}
+/**
+ * Excel's checkbox: draws a boolean or a blank cell, in place of its text.
+ */
+export declare const CheckboxKind: ICellControlKind;
+/**
+ * The control types a cell control can have, by type.
+ *
+ * @remarks
+ * The built-in types are registered before the registry is first used; a host registers its own
+ * the same way. A type nobody has registered still loads and saves, and accepts no value, so its
+ * cells draw as text.
+ */
+export declare namespace CellControlRegistry {
+    /**
+     * Registers a kind. A kind registered again under the same type replaces the earlier one,
+     * a built-in included.
+     */
+    function register(kind: ICellControlKind): void;
+    /** The kind registered for `type`, or `null`. */
+    function get(type: string): ICellControlKind | null;
+    /** The registered types. */
+    function getTypes(): string[];
+}
+//# sourceMappingURL=CellControlRegistry.d.ts.map

package/types/src/cellControl/ICellControl.d.ts

@@ -0,0 +1,99 @@
+import { Scalar } from '@sheetxl/primitives';
+import { IAnchored } from '../anchored';
+import { ICellRange } from '../cellRange';
+import { IListener } from '../listener';
+/**
+ * A control drawn in the cells of a range, such as a checkbox.
+ *
+ * @remarks
+ * A cell control decorates the cell's value; it never holds one. A checkbox draws `TRUE` as
+ * checked and `FALSE` or blank as unchecked, and a click writes the boolean into the cell, where
+ * formulas read it as any other value. Excel's model is the same: the checkbox is a cell
+ * *format*, and *Clear Formats* removes it while the value stays.
+ *
+ * * A cell has at most one control. One control covers any number of cells, and its ranges
+ *   shift, split, copy and fill with them.
+ * * A control draws only the values its type accepts ({@link isAccepted}). Any other value draws
+ *   as plain text: a checkbox over `2` or `"true"` draws `2` or `true`, as in Excel.
+ * * Most code never needs this interface: {@link ICellRange.setControl} and
+ *   {@link ICellRange.getControls} stand in for Office Scripts' `Range.setControl` /
+ *   `getControl`.
+ */
+export interface ICellControl extends IAnchored {
+    /**
+     * The control's type, such as `'checkbox'`.
+     *
+     * @remarks
+     * A type nobody has registered (`CellControlRegistry`) is kept and saved as it was read; it
+     * accepts no value, so its cells draw as text.
+     */
+    getType(): string;
+    /**
+     * Returns the first range the control covers.
+     *
+     * @remarks
+     * See {@link IAnchored.getRanges} for all of them. To change where a control is, use
+     * {@link ICellRange.setControl}.
+     */
+    getRange(): ICellRange;
+    /**
+     * Whether the control draws a cell holding `value`.
+     *
+     * @remarks
+     * A checkbox accepts a boolean or a blank cell. A value it does not accept draws as the cell
+     * would without the control.
+     */
+    isAccepted(value: Scalar): boolean;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: ICellControl.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * The control as JSON: its `type` and any properties of that type.
+     */
+    toJSON(): ICellControl.JSON;
+    /**
+     * For runtime type checking.
+     */
+    readonly isICellControl: true;
+}
+/**
+ * {@inheritDoc ICellControl}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICellControl}
+ *
+ * **Additional Interfaces**
+ * * {@link ICellControlCollection}
+ */
+export declare namespace ICellControl {
+    /**
+     * A control as JSON: its `type`, and any properties that type defines.
+     *
+     * @remarks
+     * Office Scripts' `CellControl`: `{ type: 'checkbox' }`. A checkbox has no other properties.
+     * Office Scripts' `EmptyCellControl` is `null` here.
+     */
+    interface JSON {
+        /**
+         * The control's type, such as `'checkbox'`.
+         */
+        type: string;
+        /**
+         * Properties of the type.
+         */
+        [property: string]: unknown;
+    }
+    /**
+     * IListener for {@link ICellControl} events.
+     */
+    interface Events extends IAnchored.Events<ICellControl> {
+    }
+    interface IListeners extends IListener.Callbacks<ICellControl, ICellControl.Events> {
+    }
+}
+//# sourceMappingURL=ICellControl.d.ts.map

package/types/src/cellControl/ICellControlCollection.d.ts

@@ -0,0 +1,67 @@
+import { ICellRange, ICellRanges } from '../cellRange';
+import { ICollection } from '../type';
+import { ITransaction } from '../transaction';
+import { ICellControl } from './ICellControl';
+/**
+ * Holds a sheet's {@link ICellControl}s.
+ *
+ * @remarks
+ * Most code reaches controls through the range instead: {@link ICellRange.setControl} puts a
+ * control on cells and {@link ICellRange.getControls} reads it back. The collection is for listing
+ * every control, as a task pane does.
+ */
+export interface ICellControlCollection extends ICollection<ICellControl> {
+    /**
+     * Puts a control on the cells of `address`, replacing their controls, and returns it.
+     *
+     * @param address The address of the cells. May name several discontiguous ranges.
+     * @param control The control, such as `{ type: 'checkbox' }`.
+     *
+     * @remarks
+     * The same write as {@link ICellRange.setControl}, over any address. A cell has at most one
+     * control, so the cells leave whatever control they had, and join a control of the same
+     * definition when the sheet already has one.
+     */
+    add(address: ICellRanges.Address, control: ICellControl.JSON, options?: ITransaction.OperationOptions): ICellControl;
+    /**
+     * Returns items that match the filter criteria.
+     *
+     * If no filter criteria is provided, all items will be returned.
+     *
+     * @param options {@link ICellControlCollection.GetItemsOptions}
+     */
+    getItems(options?: ICellControlCollection.GetItemsOptions): ICellControl[];
+    /** For runtime type checking. */
+    readonly isICellControlCollection: true;
+}
+/**
+ * {@inheritDoc ICellControlCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ICellControlCollection}
+ */
+export declare namespace ICellControlCollection {
+    /**
+     * Options for searching for {@link ICellControl}s.
+     */
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * If provided, the search will be limited to items that intersect the range.
+         */
+        address?: ICellRange.Address;
+        /**
+         * Indicate if items that are in hidden headers or marked as hidden should be returned.
+         *
+         * @defaultValue false
+         */
+        ignoreHidden?: boolean;
+        /**
+         * Only return items that are completely contained with the search bounds.
+         *
+         * @defaultValue false
+         */
+        fullyContained?: boolean;
+    }
+}
+//# sourceMappingURL=ICellControlCollection.d.ts.map

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

@@ -0,0 +1,4 @@
+export * from './ICellControl';
+export * from './ICellControlCollection';
+export * from './CellControlRegistry';
+//# sourceMappingURL=index.d.ts.map

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

@@ -103,6 +103,11 @@ export interface ICellHeaderRange {
      * {@inheritDoc ICellRange.getAddress}
      */
     getAddress(r1c1?: boolean): string;
+    /**
+     * @deprecated Use {@link getAddress}.
+     * @hidden
+     */
+    getA1(): string;
     /**
      * Returns the address as a string.
      */
@@ -160,14 +165,6 @@ export declare namespace ICellHeaderRange {
          * @defaultValue false
         */
         includeSizes?: boolean;
-        /**
-         * Include headers that have custom styling.
-         *
-         * @defaultValue false
-         *
-         * @deprecated We are removing styles from headers (but will need in sheet for backward compatibility with Excel)
-         */
-        includeStyles?: boolean;
         /**
          * When scanning skip cells that are hidden via headers.
          *
@@ -271,7 +268,7 @@ export declare namespace ICellHeaderRange {
         /**
          * Called when the item is copied to a new header range.
          */
-        copyTo(range: ICellHeaderRange, options?: ICellHeaderRange.CopyOptions): Promise<RunCoords> | RunCoords;
+        copyTo(range: ICellHeaderRange, options?: ICellHeaderRange.CopyOptions): RunCoords;
         /**
          * The RunCoords that bounds the current item.
          */

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

@@ -74,6 +74,11 @@ export interface ICellHeaderRanges {
      * {@inheritDoc ICellHeaderRange.getAddress}
      */
     getAddress(r1c1?: boolean): string;
+    /**
+     * @deprecated Use {@link getAddress}.
+     * @hidden
+     */
+    getA1(): string;
     /**
      * {@inheritDoc ICellHeaderRange.toString}
      */