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

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

@@ -16,13 +16,16 @@ export declare class DataValidationCollection extends AbstractCollection<IDataVa
     private _get;
     private _createItem;
     private _addListeners;
-    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);
+    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 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} */

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

@@ -256,7 +256,7 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
     /**
      * 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.
      *

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

@@ -33,6 +33,14 @@ export interface IDataValidationCollection extends ICollection<IDataValidation>
      * @param template A template to use for the temporary item.
      */
     createItem(template?: IDataValidation): IDataValidation;
+    /**
+     * The sheet-wide validation settings.
+     *
+     * @remarks
+     * Carried from the file (`dataValidations` `disablePrompts`, `xWindow`, `yWindow`); there is no
+     * setter, as Excel offers none. Excel keeps them only while the sheet has a validation.
+     */
+    getSettings(): Readonly<IDataValidationCollection.Settings>;
     /** For runtime type checking. */
     readonly isIDataValidationCollection: true;
 }
@@ -44,6 +52,22 @@ export interface IDataValidationCollection extends ICollection<IDataValidation>
  * {@link IDataValidationCollection}
  */
 export declare namespace IDataValidationCollection {
+    /**
+     * See {@link IDataValidationCollection.getSettings}.
+     */
+    interface Settings {
+        /**
+         * No validation on the sheet shows its prompt message, whatever its
+         * {@link IDataValidation.isShowPromptMessage}.
+         *
+         * @defaultValue false
+         */
+        disablePrompts?: boolean;
+        /** The left of the prompt window, in pixels, as the file states it. Not used to place the prompt. */
+        windowX?: number;
+        /** The top of the prompt window, in pixels, as the file states it. Not used to place the prompt. */
+        windowY?: number;
+    }
     /**
      * Options for adding a data validation to the collection.
      *

package/types/src/documentProperties/DocumentProperties.d.ts

@@ -0,0 +1,66 @@
+import { IDocumentProperties } from './IDocumentProperties';
+import { ICustomProperty } from './ICustomProperty';
+type CustomValue = string | number | boolean | Date;
+/**
+ * {@link ICustomProperty} held as its JSON, owned by a {@link DocumentProperties}.
+ */
+declare class CustomProperty implements ICustomProperty {
+    private _json;
+    private readonly _owner;
+    constructor(json: ICustomProperty.JSON, owner: DocumentProperties);
+    getKey(): string;
+    getType(): ICustomProperty.Type;
+    getLinkTarget(): string | null;
+    getValue(): CustomValue;
+    setValue(value: CustomValue): void;
+    delete(): void;
+    toJSON(): ICustomProperty.JSON;
+}
+/**
+ * {@link IDocumentProperties} held as its JSON.
+ *
+ * @param assertOpen Throws when the owning workbook is closed; called before every change.
+ */
+export declare class DocumentProperties implements IDocumentProperties {
+    /** Everything but {@link IDocumentProperties.JSON.custom}, which is {@link _custom}. */
+    private _json;
+    private _custom;
+    private readonly _assertOpen;
+    constructor(assertOpen: () => void);
+    private _text;
+    private _setText;
+    getAuthor(): string | null;
+    setAuthor(author: string | null): this;
+    getCategory(): string | null;
+    setCategory(category: string | null): this;
+    getComments(): string | null;
+    setComments(comments: string | null): this;
+    getCompany(): string | null;
+    setCompany(company: string | null): this;
+    getContentStatus(): string | null;
+    setContentStatus(contentStatus: string | null): this;
+    getCreationDate(): Date | null;
+    getKeywords(): string | null;
+    setKeywords(keywords: string | null): this;
+    getLastAuthor(): string | null;
+    getManager(): string | null;
+    setManager(manager: string | null): this;
+    getRevisionNumber(): number | null;
+    setRevisionNumber(revisionNumber: number | null): this;
+    getSubject(): string | null;
+    setSubject(subject: string | null): this;
+    getTitle(): string | null;
+    setTitle(title: string | null): this;
+    getCustom(): ICustomProperty[];
+    getCustomProperty(key: string): ICustomProperty | undefined;
+    addCustomProperty(key: string, value: CustomValue): ICustomProperty;
+    deleteAllCustomProperties(): void;
+    /** @internal Throws when `property` can no longer change: the workbook is closed or it was deleted. */
+    _assertCustomEditable(property: CustomProperty): void;
+    /** @internal */
+    _removeCustom(property: CustomProperty): void;
+    fromJSON(json: IDocumentProperties.JSON | undefined): void;
+    toJSON(): IDocumentProperties.JSON;
+}
+export {};
+//# sourceMappingURL=DocumentProperties.d.ts.map

package/types/src/documentProperties/ICustomProperty.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A property a user or an application added to the workbook: a name and a value. Saved with the
+ * workbook; it affects nothing else.
+ *
+ * @remarks
+ * Shaped after Office Scripts' `CustomProperty`.
+ *
+ * @see {@link IDocumentProperties.getCustom}
+ */
+export interface ICustomProperty {
+    /** The property's name. Unique within the workbook, ignoring case. */
+    getKey(): string;
+    /** The kind of value, chosen by {@link setValue} from the value it is given. */
+    getType(): ICustomProperty.Type;
+    /**
+     * The property's value. A {@link ICustomProperty.Type.Date} property returns a `Date`.
+     */
+    getValue(): string | number | boolean | Date;
+    /**
+     * Sets {@link getValue}, and with it {@link getType}: a whole number that fits in 32 bits is a
+     * {@link ICustomProperty.Type.Number}, any other number a {@link ICustomProperty.Type.Float}.
+     */
+    setValue(value: string | number | boolean | Date): void;
+    /**
+     * The defined name the value is linked to ("Link to content"), or `null` when it is not linked.
+     *
+     * @remarks
+     * VBA's `DocumentProperty.LinkSource`. Carried from the file: SheetXL does not refresh the value
+     * from the name, and {@link setValue} keeps the link.
+     */
+    getLinkTarget(): string | null;
+    /** Removes the property from the workbook. */
+    delete(): void;
+    /** For persisting. */
+    toJSON(): ICustomProperty.JSON;
+}
+export declare namespace ICustomProperty {
+    /**
+     * The kind of value a custom property holds. Shaped after Office Scripts' `DocumentPropertyType`.
+     */
+    const Type: {
+        /** A whole number. */
+        readonly Number: "number";
+        /** `true` or `false`. */
+        readonly Boolean: "boolean";
+        /** A point in time. */
+        readonly Date: "date";
+        /** Text. */
+        readonly String: "string";
+        /** A number with a fraction, or one too large for {@link ICustomProperty.Type.Number}. */
+        readonly Float: "float";
+    };
+    type Type = typeof Type[keyof typeof Type];
+    /**
+     * The serialized form.
+     */
+    interface JSON {
+        key: string;
+        type: Type;
+        /** A {@link ICustomProperty.Type.Date} is an ISO 8601 string in UTC. */
+        value: string | number | boolean;
+        /**
+         * A defined name the value is kept in step with. The value is the last one the name gave;
+         * an application that understands the link refreshes it.
+         */
+        linkTarget?: string;
+    }
+}
+//# sourceMappingURL=ICustomProperty.d.ts.map

package/types/src/documentProperties/IDocumentProperties.d.ts

@@ -0,0 +1,110 @@
+import { ICustomProperty } from './ICustomProperty';
+/**
+ * Information about the workbook as a document: who wrote it, what it is about, when it was
+ * created. Saved with the workbook; none of it affects calculation or display.
+ *
+ * @remarks
+ * Shaped after Office Scripts' `DocumentProperties`. Every value is `null` when the workbook does
+ * not have one. A value read from a file is kept as it was, so saving a workbook does not change
+ * who created it or when.
+ *
+ * @see {@link IWorkbook.getProperties}
+ */
+export interface IDocumentProperties {
+    /** The author of the workbook. */
+    getAuthor(): string | null;
+    /** Sets {@link getAuthor}. */
+    setAuthor(author: string | null): this;
+    /** A category for the workbook, such as `Invoices`. */
+    getCategory(): string | null;
+    /** Sets {@link getCategory}. */
+    setCategory(category: string | null): this;
+    /** A description of the workbook's content. */
+    getComments(): string | null;
+    /** Sets {@link getComments}. */
+    setComments(comments: string | null): this;
+    /** The company the workbook belongs to. */
+    getCompany(): string | null;
+    /** Sets {@link getCompany}. */
+    setCompany(company: string | null): this;
+    /** The status of the workbook, such as `Draft` or `Final`. */
+    getContentStatus(): string | null;
+    /** Sets {@link getContentStatus}. */
+    setContentStatus(contentStatus: string | null): this;
+    /**
+     * When the workbook was created.
+     *
+     * @remarks
+     * Read-only. A workbook that has none is stamped with the time it is first saved.
+     */
+    getCreationDate(): Date | null;
+    /** Keywords that describe the workbook. */
+    getKeywords(): string | null;
+    /** Sets {@link getKeywords}. */
+    setKeywords(keywords: string | null): this;
+    /**
+     * Who last saved the workbook, as the file it was read from says.
+     *
+     * @remarks
+     * Read-only.
+     */
+    getLastAuthor(): string | null;
+    /** The manager of the workbook's author. */
+    getManager(): string | null;
+    /** Sets {@link getManager}. */
+    setManager(manager: string | null): this;
+    /** The workbook's revision number. */
+    getRevisionNumber(): number | null;
+    /** Sets {@link getRevisionNumber}. */
+    setRevisionNumber(revisionNumber: number | null): this;
+    /** The subject of the workbook. */
+    getSubject(): string | null;
+    /** Sets {@link getSubject}. */
+    setSubject(subject: string | null): this;
+    /** The title of the workbook. */
+    getTitle(): string | null;
+    /** Sets {@link getTitle}. */
+    setTitle(title: string | null): this;
+    /** The workbook's custom properties, in the order they were added. */
+    getCustom(): ICustomProperty[];
+    /**
+     * The custom property named `key`, ignoring case, or `undefined` if there is none.
+     */
+    getCustomProperty(key: string): ICustomProperty | undefined;
+    /**
+     * Adds a custom property, or sets the value of the one already named `key` (ignoring case).
+     *
+     * @param key The property's name. Not empty.
+     * @param value The property's value; its type follows {@link ICustomProperty.setValue}.
+     */
+    addCustomProperty(key: string, value: string | number | boolean | Date): ICustomProperty;
+    /** Removes every custom property. */
+    deleteAllCustomProperties(): void;
+    /** For persisting. */
+    toJSON(): IDocumentProperties.JSON;
+}
+export declare namespace IDocumentProperties {
+    /**
+     * The serialized form. Dates are ISO 8601 strings in UTC.
+     */
+    interface JSON {
+        author?: string;
+        category?: string;
+        comments?: string;
+        company?: string;
+        contentStatus?: string;
+        creationDate?: string;
+        custom?: ICustomProperty.JSON[];
+        keywords?: string;
+        lastAuthor?: string;
+        /** When the workbook was last saved, as the file it was read from says. */
+        lastModifiedDate?: string;
+        /** When the workbook was last printed, as the file it was read from says. */
+        lastPrinted?: string;
+        manager?: string;
+        revisionNumber?: number;
+        subject?: string;
+        title?: string;
+    }
+}
+//# sourceMappingURL=IDocumentProperties.d.ts.map

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

@@ -0,0 +1,3 @@
+export * from './IDocumentProperties';
+export * from './ICustomProperty';
+//# sourceMappingURL=index.d.ts.map

package/types/src/externalBook/IExternalBook.d.ts

@@ -226,7 +226,7 @@ export declare namespace IExternalBook {
         /** `<sheetData refreshError="1">` — Excel could not refresh this sheet's cache last time it tried. */
         refreshError?: boolean;
         /**
-         * Sparse cell values — the same encoding `ISheet.JSON.data` uses (`ICell.JSON` is already just
+         * Sparse cell values — the same encoding `IWorksheet.JSON.data` uses (`ICell.JSON` is already just
          * the value+type pair; style/formula live in sibling fields there, none of which apply to a
          * values-only cache — design doc §2.5).
          */

package/types/src/fill/IFill.d.ts

@@ -606,6 +606,13 @@ export declare namespace IFill {
         dpi?: number;
         /** The compression the image was stored for (`blip/@cstate`): `email`, `screen`, `print`, `hqprint`, `none`. */
         compressionState?: string;
+        /**
+         * The adjustments applied to the image itself, as the file states them: the `blip`'s effect
+         * children (`lum` for brightness and contrast, `grayscl`, `clrChange` for a transparent color,
+         * `alphaModFix` for transparency, `biLevel`, `duotone`, …) as one opaque DrawingML fragment,
+         * written back as it was. Not rendered.
+         */
+        imageEffects?: string;
         /** `blip/extLst` as the file states it: an opaque DrawingML fragment, written back as it was. */
         extLst?: string;
     }

package/types/src/fill/IFillable.d.ts

@@ -0,0 +1,47 @@
+import { ITransaction } from '../transaction';
+import { IFill } from './IFill';
+/**
+ * A style that has a fill: a cell's background, or what a shape or chart part is filled with.
+ *
+ * @remarks
+ * Code that formats a fill takes an `IFillable`, so the same code fills a cell, a shape or a chart
+ * title.
+ *
+ * @typeParam S The style the setters return, to keep chaining on.
+ * @typeParam F The fills the style can hold.
+ * @typeParam O The options its writes take.
+ *
+ * @example
+ * ```ts
+ * const highlight = (style: IFillable) => style.setFill('#ffd966');
+ * highlight(range.getStyle());
+ * highlight(chart.getTitle().getStyle());
+ * ```
+ */
+export interface IFillable<S = unknown, F extends IFill = IFill.ISolid | IFill.IGradient | IFill.IPattern | IFill.IImage | IFill.INone, O extends ITransaction.OperationOptions = ITransaction.OperationOptions> {
+    /**
+     * Returns the fill, resolved.
+     */
+    getFill(): F;
+    /**
+     * Sets the fill: a color, a fill, or fill properties; `null` clears it.
+     */
+    setFill(fill: IFill.Update, options?: O): S;
+    /**
+     * Makes the fill solid and returns it.
+     */
+    setFillSolid(options?: O): IFill.ISolid;
+    /**
+     * Makes the fill a gradient and returns it.
+     */
+    setFillGradient(options?: O): IFill.IGradient;
+    /**
+     * Makes the fill a pattern and returns it.
+     */
+    setFillPattern(options?: O): IFill.IPattern;
+    /**
+     * Removes the fill and returns it.
+     */
+    setFillNone(options?: O): IFill.INone;
+}
+//# sourceMappingURL=IFillable.d.ts.map

package/types/src/fill/IStroke.d.ts

@@ -185,7 +185,8 @@ export declare namespace IStroke {
         tailLength?: IStroke.LineEndSize;
         /**
          * The dash: a preset ({@link IStroke.DashStyle}), or a custom pattern of dash and space
-         * lengths as multiples of the line width (DrawingML `custDash`).
+         * lengths as percentages of the line width (DrawingML `custDash`: `[400, 300]` is a dash of
+         * four widths and a space of three). {@link IStroke.toDashLengths} gives either in widths.
          *
          * @defaultValue IStroke.DashStyle.Solid
          */
@@ -379,6 +380,19 @@ export declare namespace IStroke {
         readonly SysDashDotDot: "sysDashDotDot";
     };
     type DashStyle = typeof DashStyle[keyof typeof DashStyle];
+    /**
+     * A dash as alternating dash and space lengths in line widths, or `null` for a solid line.
+     *
+     * @param dash A preset, or a custom pattern as {@link Properties.dash} holds it (percentages of
+     * the width).
+     *
+     * @example
+     * ```ts
+     * IStroke.toDashLengths(IStroke.DashStyle.SysDot); // [1, 1]
+     * IStroke.toDashLengths([400, 300]); // [4, 3]
+     * ```
+     */
+    function toDashLengths(dash: DashStyle | readonly number[] | null | undefined): number[] | null;
     /**
      * A JSON representation useful for persistence.
      */

package/types/src/fill/PaintUtils.d.ts

@@ -0,0 +1,22 @@
+import { IColor } from '../color/IColor';
+import { IFill } from './IFill';
+/**
+ * Turns a serialized color (`accent1`, `tx1 lumMod 65 lumOff 35`, `#156082`) into the CSS a painter
+ * draws, or `null` where it cannot be read.
+ */
+export type ColorToCSS = (color: string) => string | null;
+/**
+ * A color as concrete CSS: `#RRGGBB`, or `rgba(r,g,b,a)` when it is not opaque. Never a theme
+ * reference, a CSS variable or `light-dark()`.
+ */
+export declare function toConcreteCSS(color: IColor): string;
+/**
+ * A fill with each of its colors drawn through `css`: a solid fill's color, a gradient's stops, a
+ * pattern's foreground and background. What it does not color (an image, the gradient's geometry,
+ * the pattern's tile) is kept as it is.
+ *
+ * @returns `undefined` for no fill stated, `null` for a fill that draws nothing (none, a group's
+ * fill, which the caller resolves, or one whose colors cannot be read).
+ */
+export declare function toConcreteFill(fill: IFill.JSON | null | undefined, css: ColorToCSS): IFill.JSON | null | undefined;
+//# sourceMappingURL=PaintUtils.d.ts.map

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

@@ -1,5 +1,7 @@
 export * from './IFill';
+export * from './IFillable';
 export * from './IStroke';
 export * from './IEffect';
 export * from './RectAlignment';
+export * as PaintUtils from './PaintUtils';
 //# sourceMappingURL=index.d.ts.map

package/types/src/font/AdvanceBuilder.d.ts

@@ -21,5 +21,39 @@ export interface AdvanceBuilder {
      * @throws when a source exists but cannot be read as a table.
      */
     build(face: AdvanceTable.Face): Promise<AdvanceTable | null>;
+    /**
+     * Gives a table built elsewhere (a built-in one) the hinted widths this builder has for its
+     * face, when it has them.
+     *
+     * @returns Whether the table is hinted now.
+     */
+    hint?(table: AdvanceTable): Promise<boolean>;
+    /**
+     * The table of what the platform PAINTS `face` with when a cell names `families` (the face's
+     * family and the style's fallbacks, in order): a browser's own advances for that CSS stack,
+     * substitutes included. Only a builder that can see the platform's paint has one; the
+     * collection uses it to reconcile paint to the measure
+     * (`IFont.ExtendedMetrics.renderLetterSpacing`).
+     *
+     * @returns `null` when this builder cannot say.
+     */
+    paint?(face: AdvanceTable.Face, families: readonly string[]): Promise<AdvanceTable | null>;
+    /**
+     * How the platform measures a character that a captured table for `face` lacks: its advance
+     * per em as the platform paints it, its font fallback included (a symbol or emoji that the
+     * face does not have). The collection gives it to every captured table
+     * ({@link AdvanceTable.setMeasureMissing}), so such a character takes up room instead of
+     * measuring as nothing. Only a builder that can measure on the platform has one.
+     *
+     * @returns `null` when this builder cannot measure.
+     */
+    measureMissing?(face: AdvanceTable.Face): ((text: string) => number | undefined) | null;
+    /**
+     * Whether the platform has `family` installed, so paints it as itself: what a font menu shows a
+     * missing family differently by. Only a builder that can see the platform's fonts has one.
+     *
+     * @returns `undefined` when this builder cannot tell.
+     */
+    isInstalled?(family: string): boolean | undefined;
 }
 //# sourceMappingURL=AdvanceBuilder.d.ts.map