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

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

@@ -4,78 +4,73 @@ import { IColor } from '../color';
 import { ITheme } from '../theme';
 import { ITableStyle } from '../table';
 import { IStyle } from '../style';
+import { INamedStyleCollection } from './INamedStyleCollection';
+import { ITableStyleCollection } from './ITableStyleCollection';
 /**
- * Contains collections of Named and Table Styles.
+ * The workbook's styling: its named cell styles and table 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.
+     * Returns the named cell styles.
+     */
+    getNamedStyles(): INamedStyleCollection;
+    /**
+     * Returns the table styles, and the default for a new table.
+     */
+    getTableStyles(): ITableStyleCollection;
+    /**
+     * Returns the named style with the given name, or `null` if there is none.
      *
-     * @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.
+     * @deprecated Use {@link getNamedStyles}`().getByName(name)`; removed in the next release.
      */
     getNamed(name: string): IStyle.INamed | null;
     /**
-     * Returns all customized named cell styles.
+     * Returns the document's own named styles, customized built-ins included.
      *
-     * @remarks
-     * This includes new style names and builtin overrides.
+     * @deprecated Use {@link getNamedStyles}`().getItems({ type: 'custom' })`; removed in the next
+     * release.
      */
     getCustomNamed(): IStyle.INamed[];
     /**
-     * This will add or update a cell style.
-     *
-     * @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.
+     * 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;
     /**
-     * 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;
     /**
@@ -195,6 +190,8 @@ export interface IStyleCollection {
      * {@link IStyleCollection.IPersistScope}
      */
     beginPersist(): IStyleCollection.IPersistScope;
+    /** For runtime type checking. */
+    readonly isIStyleCollection: true;
 }
 /**
  * {@inheritDoc IStyleCollection}
@@ -206,12 +203,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 or table styles — the one
+         * event a renderer needs.
+         */
         onAnyChange?(source: IStyleCollection): void;
     }
     interface IListeners extends IListener.Callbacks<IStyleCollection, IStyleCollection.Events> {
@@ -267,6 +283,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;

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 { IStyle } from './IStyle';
+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<IStyle.INamed, INamedStyleCollection.GetItemsOptions> implements INamedStyleCollection {
+    private _host;
+    constructor(host: NamedStyleCollection.Host);
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: INamedStyleCollection.GetItemsOptions): IStyle.INamed[];
+    /** {@inheritDoc INamedStyleCollection.getByName} */
+    getByName(name: string): IStyle.INamed | null;
+    /** {@inheritDoc INamedStyleCollection.set} */
+    set(update: IStyle.NamedUpdate, mergeIfExists?: boolean): IStyle.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, IStyle.INamed>;
+        customs(): ReadonlyMap<string, IStyle.INamed>;
+        set(update: IStyle.NamedUpdate, mergeIfExists: boolean): IStyle.INamed;
+    }
+}
+//# sourceMappingURL=NamedStyleCollection.d.ts.map

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

@@ -5,6 +5,10 @@ import { ITheme } from '../theme';
 import { ITableStyle } from '../table';
 import { IStyle } from './IStyle';
 import { IStyleCollection } from './IStyleCollection';
+import { INamedStyleCollection } from './INamedStyleCollection';
+import { ITableStyleCollection } from './ITableStyleCollection';
+import { NamedStyleCollection } from './NamedStyleCollection';
+import { TableStyleCollection } from './TableStyleCollection';
 import { ListenerEmitter } from '../listener/ListenerEmitter';
 interface PersistScopeState {
     byJSONs: Map<string, number>;
@@ -42,9 +46,15 @@ export declare class StyleCollection implements IStyleCollection {
     protected _defaultFontSize: number;
     protected _schemeLookup: IColor.SchemeLookup;
     protected _indexedLookup: IColor.IndexedLookup;
+    /**
+     * The built-in named styles, keyed by lower-cased name in definition order. Only `Normal` is
+     * built at construction; the rest on first need — see {@link _ensureBuiltInCellStyles}.
+     */
     protected _builtInsCellStyles: Map<string, IStyle.INamed>;
+    protected _builtInsCellStylesComplete: boolean;
     protected _customCellStyles: Map<string, IStyle.INamed>;
-    protected _builtInsTableStyles: Map<string, ITableStyle>;
+    /** The built-in table styles, keyed by lower-cased name; built on first need. */
+    protected _builtInsTableStyles: Map<string, ITableStyle> | null;
     protected _customTableStyles: Map<string, ITableStyle>;
     protected _emptyTableStyle: ITableStyle.Empty;
     protected _customIndexedColors: readonly IColor[];
@@ -52,11 +62,29 @@ export declare class StyleCollection implements IStyleCollection {
     protected _normalStyle: IStyle;
     protected _normalRanged: IProperties.ICellRanged<IStyle.Properties>;
     protected _defaultTableStyle: ITableStyle | null;
+    protected _namedStyles: NamedStyleCollection;
+    protected _tableStyles: TableStyleCollection;
     protected _persistCache: PersistScopeState | null;
     constructor(theme?: ITheme | null, indexedColors?: string[] | null, defaultFontSize?: number);
-    protected _initializeNamedStyles(namedStyles: readonly IStyle.Properties[], builtInStyleMap: Map<string, IStyle.INamed>): void;
+    /** {@inheritDoc IStyleCollection.getNamedStyles} */
+    getNamedStyles(): INamedStyleCollection;
+    /** {@inheritDoc IStyleCollection.getTableStyles} */
+    getTableStyles(): ITableStyleCollection;
+    /**
+     * Builds the built-in named styles from `from` on, into the map in definition order.
+     */
+    protected _initializeNamedStyles(namedStyles: readonly IStyle.Properties[], builtInStyleMap: Map<string, IStyle.INamed>, from?: number, to?: number): void;
     protected _initializeTableStyles(): Map<string, ITableStyle>;
+    /**
+     * Builds what every collection needs at once: `Normal` (the base of every style) and the
+     * empty table style. The other built-ins wait for a first need — most collections are the
+     * fallback a detached item constructs and never ask for a gallery.
+     */
     protected _initializeBuiltIns(): void;
+    /** The built-in named styles, all of them, built on the first call. */
+    protected _ensureBuiltInCellStyles(): Map<string, IStyle.INamed>;
+    /** The built-in table styles, built on the first call. */
+    protected _ensureBuiltInTableStyles(): Map<string, ITableStyle>;
     /** {@inheritDoc IStyleCollection.getNormal} */
     getNormal(): IStyle;
     /** {@inheritDoc IStyleCollection.getNormalRanged} */
@@ -77,20 +105,26 @@ export declare class StyleCollection implements IStyleCollection {
     getCustomNamed(): IStyle.INamed[];
     /** {@inheritDoc IStyleCollection.setNamed} */
     setNamed(modifiers: IStyle.NamedUpdate, mergeIfExists?: boolean): IStyle.INamed;
+    /** The validated write behind {@link INamedStyleCollection.set}; the collection announces it. */
+    protected _setNamedStyle(modifiers: IStyle.NamedUpdate, mergeIfExists?: boolean): IStyle.INamed;
     protected _setCustomCellStyleInternal(modifiers: IStyle.NamedUpdate, mergeIfExists?: boolean, _i?: number | null): IStyle.INamed;
     protected _setCustomTableStyleInternal(name: string, properties: ITableStyle.ResolvableProperties): ITableStyle;
     protected _hideOrRemoveNamed(style: IStyle.INamed | string): boolean;
     /** {@inheritDoc IStyleCollection.getTableStyle} */
-    getTableStyle(name: string): ITableStyle | null;
+    getTableStyle(name?: string): ITableStyle | null;
     /** {@inheritDoc IStyleCollection.getCustomTableStyles} */
     getCustomTableStyles(): ITableStyle[];
     /** {@inheritDoc IStyleCollection.setDefaultTableStyle} */
-    setDefaultTableStyle(styleName: string): boolean;
+    setDefaultTableStyle(styleName: string): void;
     /** {@inheritDoc IStyleCollection.getDefaultTableStyle} */
     getDefaultTableStyle(): ITableStyle;
-    protected _deleteCustomTableStyle(styleName: string): boolean;
     /** {@inheritDoc IStyleCollection.setCustomTableStyle} */
     setCustomTableStyle(name: string, properties: ITableStyle.ResolvableProperties): ITableStyle;
+    /** The write behind {@link ITableStyleCollection.setDefault}; returns the previous default. */
+    protected _setDefaultTableStyle(style: ITableStyle | string): ITableStyle;
+    /** The read behind {@link ITableStyleCollection.getDefault}. */
+    protected _getDefaultTableStyle(): ITableStyle;
+    protected _deleteCustomTableStyle(styleName: string): boolean;
     /** {@inheritDoc IStyleCollection.validateStyleName} */
     validateStyleName(name: string, checkDuplicates?: boolean): void;
     /** {@inheritDoc IStyleCollection.normalize} */
@@ -120,6 +154,8 @@ export declare class StyleCollection implements IStyleCollection {
     protected _toJSONInternal(jsonSheetStyleShared: IStyle.JSON[]): IStyleCollection.JSON;
     protected _fromJSONIndexedColors(indexedColors: string[] | null | undefined): IColor[];
     protected _fromJSONInternal(json: IStyleCollection.JSON): void;
+    /** {@inheritDoc IStyleCollection.isIStyleCollection} */
+    get isIStyleCollection(): true;
 }
 export {};
 //# sourceMappingURL=StyleCollection.d.ts.map

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

@@ -0,0 +1,49 @@
+import { AbstractCollection } from '../type';
+import { ITableStyle } from '../table';
+import { ITableStyleCollection } from './ITableStyleCollection';
+/**
+ * Implementation for {@link ITableStyleCollection}.
+ *
+ * @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 TableStyleCollection extends AbstractCollection<ITableStyle, ITableStyleCollection.GetItemsOptions> implements ITableStyleCollection {
+    private _host;
+    constructor(host: TableStyleCollection.Host);
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: ITableStyleCollection.GetItemsOptions): ITableStyle[];
+    /** {@inheritDoc ITableStyleCollection.getByName} */
+    getByName(name: string): ITableStyle | null;
+    /** {@inheritDoc ITableStyleCollection.set} */
+    set(name: string, properties: ITableStyle.ResolvableProperties): ITableStyle;
+    /** {@inheritDoc ITableStyleCollection.getDefault} */
+    getDefault(): ITableStyle;
+    /** {@inheritDoc ITableStyleCollection.setDefault} */
+    setDefault(style: ITableStyle | string): ITableStyle;
+    /** {@inheritDoc ITableStyleCollection.getNone} */
+    getNone(): ITableStyle;
+    /**
+     * Announces a change the host made itself — a custom style deleted, a load.
+     * @internal
+     */
+    _announceChange(): void;
+    /** {@inheritDoc ITableStyleCollection.isITableStyleCollection} */
+    get isITableStyleCollection(): true;
+}
+export declare namespace TableStyleCollection {
+    /**
+     * What the style collection lends this front: its maps, keyed by lower-cased name and in
+     * gallery order, the default, and the writes that need its resolvers.
+     */
+    interface Host {
+        builtIns(): ReadonlyMap<string, ITableStyle>;
+        customs(): ReadonlyMap<string, ITableStyle>;
+        set(name: string, properties: ITableStyle.ResolvableProperties): ITableStyle;
+        getDefault(): ITableStyle;
+        /** Returns the previous default. */
+        setDefault(style: ITableStyle | string): ITableStyle;
+        getNone(): ITableStyle;
+    }
+}
+//# sourceMappingURL=TableStyleCollection.d.ts.map

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

@@ -1,13 +1,13 @@
 import { ITextFrame, IStyledFont } from '../text';
-import { IBorder } from '../border';
+import { IBorders } from '../border';
 import { IStyle } from './IStyle';
 import { ICellProtection } from '../cell';
 /**
  * To avoid duplicating values.
  */
 export declare const _EmptyFontProperties: IStyledFont.Properties;
-export declare const _EmptyBorderStrokeProperties: IBorder.StrokeProperties;
-export declare const _EmptyBorderProperties: IBorder.Properties;
+export declare const _EmptyBorderStrokeProperties: IBorders.StrokeProperties;
+export declare const _EmptyBorderProperties: IBorders.Properties;
 export declare const _EmptyAlignmentProperties: ITextFrame.IAlignment.Properties;
 export declare const _EmptyProtectionProperties: ICellProtection.Properties;
 /**

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

@@ -1,5 +1,9 @@
 export * from './IStyle';
 export * from './IStyleCollection';
+export * from './INamedStyleCollection';
+export * from './ITableStyleCollection';
 export * from './_BuiltInStyleNames';
 export * from './StyleCollection';
+export * from './NamedStyleCollection';
+export * from './TableStyleCollection';
 //# sourceMappingURL=index.d.ts.map