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

package/types/src/style/ISlicerStyleCollection.d.ts

@@ -0,0 +1,77 @@
+import { ICollection } from '../type';
+import { IThemeCollection } from '../theme';
+import { ISlicerStyle } from '../slicer';
+/**
+ * The slicer styles of a workbook — the built-ins (`SlicerStyleLight1`, ...) and the ones the
+ * document defines — and which of them is the default for a new slicer.
+ *
+ * @remarks
+ * Office Scripts has the same shape: `Workbook.getSlicerStyles()`, `getSlicerStyle(name)`,
+ * `getDefaultSlicerStyle()` / `setDefaultSlicerStyle(style)`.
+ *
+ * Order is the gallery's: the built-ins (Light, Other, Dark), each replaced in place by a custom
+ * style of the same name, then the document's own styles by name.
+ *
+ * `onCollectionChange` announces a style added, changed or deleted, and a change of the default.
+ *
+ * Reached from {@link IStyleCollection.getSlicerStyles}.
+ */
+export interface ISlicerStyleCollection extends ICollection<ISlicerStyle> {
+    /**
+     * Returns the style with the given name, or `null` if there is none.
+     *
+     * @param name The name, compared case-insensitively.
+     *
+     * @remarks
+     * A custom style of a built-in's name replaces the built-in, and is what is returned.
+     */
+    getByName(name: string): ISlicerStyle | null;
+    /**
+     * Adds or updates a style.
+     *
+     * @param name The name, compared case-insensitively. Setting a built-in's name customizes
+     * the built-in.
+     * @param properties The style's elements.
+     * @returns The style as stored.
+     */
+    set(name: string, properties: Omit<ISlicerStyle.ResolvableProperties, 'name'>): ISlicerStyle;
+    /**
+     * Returns the styles that match the filter, in gallery order.
+     *
+     * @param options {@link ISlicerStyleCollection.GetItemsOptions}
+     */
+    getItems(options?: ISlicerStyleCollection.GetItemsOptions): ISlicerStyle[];
+    /**
+     * Returns the style a slicer is given when it is created without one.
+     */
+    getDefault(): ISlicerStyle;
+    /**
+     * Sets the style a slicer is given when it is created without one.
+     *
+     * @param style The style, or its name. A name that matches nothing sets the default back to
+     * `SlicerStyleLight1`, the built-in default.
+     * @returns The previous default.
+     */
+    setDefault(style: ISlicerStyle | string): ISlicerStyle;
+    /** For runtime type checking. */
+    readonly isISlicerStyleCollection: true;
+}
+/**
+ * {@inheritDoc ISlicerStyleCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ISlicerStyleCollection}
+ */
+export declare namespace ISlicerStyleCollection {
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * Which styles: the built-ins, the document's own (a customized built-in is one of the
+         * document's own), or every style.
+         *
+         * @defaultValue `IThemeCollection.BuiltInFilterType.All`
+         */
+        type?: IThemeCollection.BuiltInFilterType;
+    }
+}
+//# sourceMappingURL=ISlicerStyleCollection.d.ts.map

package/types/src/style/IStyleCollection.d.ts

@@ -3,79 +3,80 @@ import { IListener } from '../listener';
 import { IColor } from '../color';
 import { ITheme } from '../theme';
 import { ITableStyle } from '../table';
-import { IStyle } from '../style';
+import { ISlicerStyle } from '../slicer';
+import { ICellStyle } from '../style';
+import { INamedStyleCollection } from './INamedStyleCollection';
+import { ITableStyleCollection } from './ITableStyleCollection';
+import { ISlicerStyleCollection } from './ISlicerStyleCollection';
 /**
- * Contains collections of Named and Table Styles.
+ * The workbook's styling: its named cell styles, table styles and slicer styles (each a collection of its
+ * own), the theme and default font size the styles resolve against, color resolution, and the
+ * style algebra (`normalize` / `resolve`) with persistence.
  */
 export interface IStyleCollection {
     /**
-     * Returns The named style from either a custom style or a builtIn.
-     *
-     * @remarks
-     * Will try to return:
-     * 1. The custom style for the name
-     * 2. The builtin style for the name.
-     * 3. nul if it doesn't exist.
+     * Returns the named cell styles.
+     */
+    getNamedStyles(): INamedStyleCollection;
+    /**
+     * Returns the table styles, and the default for a new table.
      */
-    getNamed(name: string): IStyle.INamed | null;
+    getTableStyles(): ITableStyleCollection;
     /**
-     * Returns all customized named cell styles.
+     * Returns the slicer styles, and the default for a new slicer.
+     */
+    getSlicerStyles(): ISlicerStyleCollection;
+    /**
+     * Returns the named style with the given name, or `null` if there is none.
      *
-     * @remarks
-     * This includes new style names and builtin overrides.
+     * @deprecated Use {@link getNamedStyles}`().getByName(name)`; removed in the next release.
      */
-    getCustomNamed(): IStyle.INamed[];
+    getNamed(name: string): ICellStyle.INamed | null;
     /**
-     * This will add or update a cell style.
+     * Returns the document's own named styles, customized built-ins included.
      *
-     * @param modifiers The Style or Style Modifiers
-     * @param mergeIfExists If true then the style will be merged with the existing style otherwise is a replace. @defaultValue false
-     * @returns The new style after any merges.
+     * @deprecated Use {@link getNamedStyles}`().getItems({ type: 'custom' })`; removed in the next
+     * release.
+     */
+    getCustomNamed(): ICellStyle.INamed[];
+    /**
+     * Adds or updates a named style.
      *
-     * @remarks
-     * Names are case insensitive; for duplicate detection purposes.
+     * @deprecated Use {@link getNamedStyles}`().set(update, mergeIfExists)`; removed in the next
+     * release.
      */
-    setNamed(modifiers: IStyle.NamedUpdate, mergeIfExists?: boolean): IStyle.INamed;
+    setNamed(modifiers: ICellStyle.NamedUpdate, mergeIfExists?: boolean): ICellStyle.INamed;
     /**
-     * Returns The table style. This can be either a custom or a built in table style.
+     * Returns the table style with the given name, or `null` if there is none; with no name, the
+     * style of a table that has none.
      *
-     * @remarks
-     * Will try to return:
-     * 1. The custom style for the name
-     * 2. The builtIn style for the name.
-     * 3. `null` if it doesn't exist.
+     * @deprecated Use {@link getTableStyles}`().getByName(name)` (or `.getNone()`); removed in the
+     * next release.
      */
     getTableStyle(name?: string): ITableStyle | null;
     /**
-     * Returns all customized table styles.
+     * Returns the document's own table styles, customized built-ins included.
      *
-     * @remarks
-     * This includes new table styles and builtin overrides.
+     * @deprecated Use {@link getTableStyles}`().getItems({ type: 'custom' })`; removed in the next
+     * release.
      */
     getCustomTableStyles(): ITableStyle[];
     /**
-     * This will add or update a table style.
-  
-     * @param name A string of the name of the table.
-     * @param properties The values to set for the table style.
-     * @returns A new `ITableStyle` representing the updated style.
+     * Adds or updates a table style.
      *
-     * @remarks
-     * Case insensitive; for duplicate detection purposes.
+     * @deprecated Use {@link getTableStyles}`().set(name, properties)`; removed in the next release.
      */
     setCustomTableStyle(name: string, properties: ITableStyle.ResolvableProperties): ITableStyle;
     /**
-     * Set the default table style to use if a table is created without specifying a style.
+     * Sets the style a table is given when it is created without one.
      *
-     * @param name A string of the name of the table
-     * @remarks
-     * The style must exist or the defaultStyle will be set to 'TableStyleMedium2'.
+     * @deprecated Use {@link getTableStyles}`().setDefault(name)`; removed in the next release.
      */
     setDefaultTableStyle(name: string): void;
     /**
-     * Returns the default ITableStyle.
-     * @see
-     * {@link setDefaultTableStyle}
+     * Returns the style a table is given when it is created without one.
+     *
+     * @deprecated Use {@link getTableStyles}`().getDefault()`; removed in the next release.
      */
     getDefaultTableStyle(): ITableStyle;
     /**
@@ -150,22 +151,22 @@ export interface IStyleCollection {
      */
     addListeners(listeners: IStyleCollection.IListeners, options?: IListener.Options): IListener.Remove;
     /**
-     * Converts a list of `IStyle.Modifiers` that contain shorthand values into native values.
+     * Converts a list of `ICellStyle.Modifiers` that contain shorthand values into native values.
      *
-     * @param modifiers {@link IStyle.Modifiers}
+     * @param modifiers {@link ICellStyle.Modifiers}
      * @param name Name used to normalize against. This overrides any specified in the modifiers.
-     * @returns A valid IStyle.Modifiers with values that match the normal style removed.
+     * @returns A valid ICellStyle.Modifiers with values that match the normal style removed.
      *
      * @remarks
      * Will also remove any value that resolve to the same values as the referenced named style (or Normal if this is not specified).
      */
-    normalize(modifiers: IStyle.Modifiers, name?: string): Partial<IStyle.Modifiers>;
+    normalize(modifiers: ICellStyle.Modifiers, name?: string): Partial<ICellStyle.Modifiers>;
     /**
      * Flattens a style against the named style it references, resolving shorthand values as it goes.
      *
-     * @param modifiers {@link IStyle.Modifiers}
+     * @param modifiers {@link ICellStyle.Modifiers}
      * @param name Name used to resolve against. This overrides any specified in the modifiers.
-     * @returns A valid `IStyle.Properties` with the referenced style's values merged in.
+     * @returns A valid `ICellStyle.Properties` with the referenced style's values merged in.
      *
      * @remarks
      * The inverse of {@link IStyleCollection.normalize}: where `normalize` reduces a style to what it
@@ -173,15 +174,15 @@ export interface IStyleCollection {
      * that store a style as a self-contained record rather than as a delta (OOXML `xf`) need this on
      * the way out.
      */
-    resolve(modifiers: IStyle.Modifiers, name?: string): Partial<IStyle.Properties>;
+    resolve(modifiers: ICellStyle.Modifiers, name?: string): Partial<ICellStyle.Properties>;
     /**
      * Convenience mechanism (and slightly faster) way to call getNamed('Normal').getRanged();
      */
-    getNormalRanged(): IProperties.ICellRanged<IStyle.Properties>;
+    getNormalRanged(): IProperties.ICellRanged<ICellStyle.Properties>;
     /**
-     * Return a the Normal styles as an IStyle.;
+     * Return a the Normal styles as an ICellStyle.;
      */
-    getNormal(): IStyle;
+    getNormal(): ICellStyle;
     /**
      * Checks the current name to see if this is a valid sheetName.
      */
@@ -195,6 +196,8 @@ export interface IStyleCollection {
      * {@link IStyleCollection.IPersistScope}
      */
     beginPersist(): IStyleCollection.IPersistScope;
+    /** For runtime type checking. */
+    readonly isIStyleCollection: true;
 }
 /**
  * {@inheritDoc IStyleCollection}
@@ -206,12 +209,31 @@ export interface IStyleCollection {
 export declare namespace IStyleCollection {
     interface Events {
         /**
-        * Notify that the named styled has changed
-        */
+         * Called when a named style is added, changed or removed.
+         *
+         * @deprecated Listen to {@link IStyleCollection.getNamedStyles}`().addListeners({ onCollectionChange })`;
+         * removed in the next release.
+         */
         onNamedStylesChange?(source: IStyleCollection): void;
+        /**
+         * Called when a table style is added, changed or removed, or the default changes.
+         *
+         * @deprecated Listen to {@link IStyleCollection.getTableStyles}`().addListeners({ onCollectionChange })`;
+         * removed in the next release.
+         */
         onTableStylesChange?(source: IStyleCollection): void;
+        /**
+         * Called when the theme changes.
+         */
         onThemeChange?(source: IStyleCollection): void;
+        /**
+         * Called when the default font size changes.
+         */
         onDefaultFontChange?(source: IStyleCollection): void;
+        /**
+         * Called for any of the above, and for any change to the named, table or slicer styles — the one
+         * event a renderer needs.
+         */
         onAnyChange?(source: IStyleCollection): void;
     }
     interface IListeners extends IListener.Callbacks<IStyleCollection, IStyleCollection.Events> {
@@ -220,15 +242,19 @@ export declare namespace IStyleCollection {
         /**
          * Used by cells styles.
          */
-        direct?: IStyle.JSON[];
+        direct?: ICellStyle.JSON[];
         /**
          * cells styles with a name for quick styling.
          */
-        named?: IStyle.NamedJSON[];
+        named?: ICellStyle.NamedJSON[];
         /**
          * Table styles.
          */
         tables?: ITableStyle.JSONS;
+        /**
+         * Slicer styles.
+         */
+        slicers?: ISlicerStyle.JSONS;
         /**
          * A list of custom colors.
          */
@@ -267,6 +293,11 @@ export declare namespace IStyleCollection {
          * @remarks
          * Once this is called the getSharedStyle is available for all
          * the ids defined in the JSON for the current scope.
+         *
+         * Loads INTO the collection: a named or table style in the JSON is added, or replaces the
+         * one of that name, and nothing already there is removed. A document load starts from a
+         * fresh collection; a sheet loaded into a live workbook brings its styles along and merges.
+         * The named and table style collections announce what was loaded.
          * @param json {@link IStyleCollection.JSON}
          */
         fromJSON(json: IStyleCollection.JSON): void;
@@ -276,7 +307,7 @@ export declare namespace IStyleCollection {
          *
          * @param id
          */
-        getElementJSON(id: number): IStyle.JSON;
+        getElementJSON(id: number): ICellStyle.JSON;
         /**
          * A 0-based style id for the given style. If this is a named style
          * or a style that is not available with the styles then this will return null.
@@ -286,7 +317,7 @@ export declare namespace IStyleCollection {
          *
          * @param json
          */
-        getElementID(json: IStyle.JSON): number | null;
+        getElementID(json: ICellStyle.JSON): number | null;
     }
 }
 //# sourceMappingURL=IStyleCollection.d.ts.map

package/types/src/style/ITableStyleCollection.d.ts

@@ -0,0 +1,89 @@
+import { ICollection } from '../type';
+import { IThemeCollection } from '../theme';
+import { ITableStyle } from '../table';
+/**
+ * The table styles of a workbook — the built-ins (`TableStyleMedium2`, ...) and the ones the
+ * document defines — and which of them is the default for a new table.
+ *
+ * @remarks
+ * Office Scripts has the same shape: `Workbook.getTableStyles()`, `getTableStyle(name)`,
+ * `getDefaultTableStyle()` / `setDefaultTableStyle(style)`; its pivot table styles are the
+ * members here that are shown for pivots (`getItems({ shownIn: 'pivot' })`).
+ *
+ * Order is the gallery's: the built-ins in their definition order, each replaced in place by a
+ * custom style of the same name, then the document's own styles by name.
+ *
+ * `onCollectionChange` announces a style added, changed or deleted, and a change of the default.
+ *
+ * Reached from {@link IStyleCollection.getTableStyles}.
+ */
+export interface ITableStyleCollection extends ICollection<ITableStyle> {
+    /**
+     * Returns the style with the given name, or `null` if there is none.
+     *
+     * @param name The name, compared case-insensitively.
+     *
+     * @remarks
+     * A custom style of a built-in's name replaces the built-in, and is what is returned.
+     */
+    getByName(name: string): ITableStyle | null;
+    /**
+     * Adds or updates a style.
+     *
+     * @param name The name, compared case-insensitively. Setting a built-in's name customizes
+     * the built-in.
+     * @param properties The style's values.
+     * @returns The style as stored.
+     */
+    set(name: string, properties: ITableStyle.ResolvableProperties): ITableStyle;
+    /**
+     * Returns the styles that match the filter, in gallery order.
+     *
+     * @param options {@link ITableStyleCollection.GetItemsOptions}
+     */
+    getItems(options?: ITableStyleCollection.GetItemsOptions): ITableStyle[];
+    /**
+     * Returns the style a table is given when it is created without one.
+     */
+    getDefault(): ITableStyle;
+    /**
+     * Sets the style a table is given when it is created without one.
+     *
+     * @param style The style, or its name. A name that matches nothing leaves the default at
+     * `TableStyleMedium2`, the built-in default.
+     * @returns The previous default.
+     */
+    setDefault(style: ITableStyle | string): ITableStyle;
+    /**
+     * Returns the style of a table that has none: it applies nothing, and is never in the list.
+     */
+    getNone(): ITableStyle;
+    /** For runtime type checking. */
+    readonly isITableStyleCollection: true;
+}
+/**
+ * {@inheritDoc ITableStyleCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ITableStyleCollection}
+ */
+export declare namespace ITableStyleCollection {
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * Which styles: the built-ins, the document's own (a customized built-in is one of the
+         * document's own), or every style.
+         *
+         * @defaultValue `IThemeCollection.BuiltInFilterType.All`
+         */
+        type?: IThemeCollection.BuiltInFilterType;
+        /**
+         * Only the styles offered for tables, or only those offered for pivot tables — see
+         * {@link ITableStyle.isShownInTableStyles} and {@link ITableStyle.isShownInPivotStyles}.
+         *
+         * @defaultValue every style, wherever it is shown.
+         */
+        shownIn?: 'table' | 'pivot';
+    }
+}
+//# sourceMappingURL=ITableStyleCollection.d.ts.map

package/types/src/style/NamedStyleCollection.d.ts

@@ -0,0 +1,39 @@
+import { AbstractCollection } from '../type';
+import { ICellStyle } from './ICellStyle';
+import { INamedStyleCollection } from './INamedStyleCollection';
+/**
+ * Implementation for {@link INamedStyleCollection}.
+ *
+ * @remarks
+ * A front over the {@link StyleCollection}'s maps — the style collection keeps the definitions
+ * (they resolve against its theme) and this class keeps the API and the announcing.
+ */
+export declare class NamedStyleCollection extends AbstractCollection<ICellStyle.INamed, INamedStyleCollection.GetItemsOptions> implements INamedStyleCollection {
+    private _host;
+    constructor(host: NamedStyleCollection.Host);
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: INamedStyleCollection.GetItemsOptions): ICellStyle.INamed[];
+    /** {@inheritDoc INamedStyleCollection.getByName} */
+    getByName(name: string): ICellStyle.INamed | null;
+    /** {@inheritDoc INamedStyleCollection.set} */
+    set(update: ICellStyle.NamedUpdate, mergeIfExists?: boolean): ICellStyle.INamed;
+    /**
+     * Announces a change the host made itself — a built-in hidden, a custom style removed, a load.
+     * @internal
+     */
+    _announceChange(): void;
+    /** {@inheritDoc INamedStyleCollection.isINamedStyleCollection} */
+    get isINamedStyleCollection(): true;
+}
+export declare namespace NamedStyleCollection {
+    /**
+     * What the style collection lends this front: its maps, keyed by lower-cased name and in
+     * gallery order, and the one write that needs its resolvers.
+     */
+    interface Host {
+        builtIns(): ReadonlyMap<string, ICellStyle.INamed>;
+        customs(): ReadonlyMap<string, ICellStyle.INamed>;
+        set(update: ICellStyle.NamedUpdate, mergeIfExists: boolean): ICellStyle.INamed;
+    }
+}
+//# sourceMappingURL=NamedStyleCollection.d.ts.map

package/types/src/style/SlicerStyleCollection.d.ts

@@ -0,0 +1,46 @@
+import { AbstractCollection } from '../type';
+import { ISlicerStyle } from '../slicer';
+import { ISlicerStyleCollection } from './ISlicerStyleCollection';
+/**
+ * Implementation for {@link ISlicerStyleCollection}.
+ *
+ * @remarks
+ * A front over the {@link StyleCollection}'s maps — the style collection keeps the definitions
+ * (they resolve against its theme) and this class keeps the API and the announcing.
+ */
+export declare class SlicerStyleCollection extends AbstractCollection<ISlicerStyle, ISlicerStyleCollection.GetItemsOptions> implements ISlicerStyleCollection {
+    private _host;
+    constructor(host: SlicerStyleCollection.Host);
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: ISlicerStyleCollection.GetItemsOptions): ISlicerStyle[];
+    /** {@inheritDoc ISlicerStyleCollection.getByName} */
+    getByName(name: string): ISlicerStyle | null;
+    /** {@inheritDoc ISlicerStyleCollection.set} */
+    set(name: string, properties: Omit<ISlicerStyle.ResolvableProperties, 'name'>): ISlicerStyle;
+    /** {@inheritDoc ISlicerStyleCollection.getDefault} */
+    getDefault(): ISlicerStyle;
+    /** {@inheritDoc ISlicerStyleCollection.setDefault} */
+    setDefault(style: ISlicerStyle | string): ISlicerStyle;
+    /**
+     * Announces a change the host made itself — a custom style deleted, a load.
+     * @internal
+     */
+    _announceChange(): void;
+    /** {@inheritDoc ISlicerStyleCollection.isISlicerStyleCollection} */
+    get isISlicerStyleCollection(): true;
+}
+export declare namespace SlicerStyleCollection {
+    /**
+     * What the style collection lends this front: its maps, keyed by lower-cased name and in
+     * gallery order, the default, and the write that needs its resolvers.
+     */
+    interface Host {
+        builtIns(): ReadonlyMap<string, ISlicerStyle>;
+        customs(): ReadonlyMap<string, ISlicerStyle>;
+        set(name: string, properties: Omit<ISlicerStyle.ResolvableProperties, 'name'>): ISlicerStyle;
+        getDefault(): ISlicerStyle;
+        /** Returns the previous default. */
+        setDefault(style: ISlicerStyle | string): ISlicerStyle;
+    }
+}
+//# sourceMappingURL=SlicerStyleCollection.d.ts.map