@sheetxl/sdk 0.7.26 → 0.7.28-beta.1

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

@@ -0,0 +1,292 @@
+import { IProperties } from '../type';
+import { IListener } from '../listener';
+import { IColor } from '../color';
+import { ITheme } from '../theme';
+import { ITableStyle } from '../table';
+import { IStyle } from '../style';
+/**
+ * Contains collections of Named and Table Styles.
+ */
+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.
+     */
+    getNamed(name: string): IStyle.INamed | null;
+    /**
+     * Returns all customized named cell styles.
+     *
+     * @remarks
+     * This includes new style names and builtin overrides.
+     */
+    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.
+     *
+     * @remarks
+     * Names are case insensitive; for duplicate detection purposes.
+     */
+    setNamed(modifiers: IStyle.NamedUpdate, mergeIfExists?: boolean): IStyle.INamed;
+    /**
+     * Returns The table style. This can be either a custom or a built in table style.
+     *
+     * @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.
+     */
+    getTableStyle(name?: string): ITableStyle | null;
+    /**
+     * Returns all customized table styles.
+     *
+     * @remarks
+     * This includes new table styles and builtin overrides.
+     */
+    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.
+     *
+     * @remarks
+     * Case insensitive; for duplicate detection purposes.
+     */
+    setCustomTableStyle(name: string, properties: ITableStyle.ResolvableProperties): ITableStyle;
+    /**
+     * Set the default table style to use if a table is created without specifying a style.
+     *
+     * @param name A string of the name of the table
+     * @remarks
+     * The style must exist or the defaultStyle will be set to 'TableStyleMedium2'.
+     */
+    setDefaultTableStyle(name: string): void;
+    /**
+     * Returns the default ITableStyle.
+     * @see
+     * {@link setDefaultTableStyle}
+     */
+    getDefaultTableStyle(): ITableStyle;
+    /**
+     * Returns the current theme
+     */
+    getTheme(): ITheme;
+    /**
+     * Set the theme used to calculate styles.
+     *
+     * @param theme The ITheme to use.
+     */
+    setTheme(theme: ITheme): void;
+    /**
+     * Themes do not contain font sizes but it is possible to set a default font size at the document or application level.
+     */
+    getDefaultFontSize(): number;
+    /**
+     * Set the default fontSize. Note - A theme does NOT contain this.
+     * @param fontSize The new default font size.
+     */
+    setDefaultFontSize(fontSize: number): void;
+    /**
+     * This is available for functions that want to resolve colors for the theme used specifically for this style.
+     */
+    schemeLookup(): IColor.SchemeLookup;
+    /**
+     * This is available for functions that want to resolve colors using the index color palette.
+     * @see
+     * {@link IColor.IndexedLookup}
+     */
+    indexedLookup(): IColor.IndexedLookup;
+    /**
+     * Parses the color using the Theme being used by this style
+     * @param str Any string that represents a color {@link IColor}.
+     */
+    parseColor(str: any): IColor;
+    /**
+     * Returns a list of colors that were added via {@link addRecentColor}.
+     */
+    recentColors(): readonly IColor[];
+    /**
+     * Add a color to the mru list. This is used to populate color pickers.
+     *
+     * @param color The color to record.
+     *
+     * @remarks
+     * Any color can be added but generally this should be limited to custom/non-themed color
+     */
+    addRecentColor(color: IColor): readonly IColor[];
+    /**
+     * Clears the mru color list
+     */
+    clearRecentColors(): void;
+    /**
+     * Returns an array of colors that will be used to resolve any colors that use IndexXX or ColorXX as a key.
+     */
+    getIndexedColors(): readonly IColor[];
+    /**
+     * Override the default indexed colors.
+     * @param colors An array of colors.
+     */
+    setCustomIndexedColors(colors: readonly IColor[]): void;
+    /**
+     * Returns the customized Indexed colors.
+     */
+    getCustomIndexedColors(): readonly IColor[];
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: IStyleCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /**
+     * Converts a list of `IStyle.Modifiers` that contain shorthand values into native values.
+     *
+     * @param modifiers {@link IStyle.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.
+     *
+     * @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>;
+    /**
+     * Flattens a style against the named style it references, resolving shorthand values as it goes.
+     *
+     * @param modifiers {@link IStyle.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.
+     *
+     * @remarks
+     * The inverse of {@link IStyleCollection.normalize}: where `normalize` reduces a style to what it
+     * authors over its named style, this restores what that authorship actually resolves to. Formats
+     * 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>;
+    /**
+     * Convenience mechanism (and slightly faster) way to call getNamed('Normal').getRanged();
+     */
+    getNormalRanged(): IProperties.ICellRanged<IStyle.Properties>;
+    /**
+     * Return a the Normal styles as an IStyle.;
+     */
+    getNormal(): IStyle;
+    /**
+     * Checks the current name to see if this is a valid sheetName.
+     */
+    validateStyleName(name: string, checkDuplicates?: boolean): void;
+    /**
+     * Start persisting styles.
+     *
+     * * This is used during save/load to allow for styles to be references by an id count.
+     * * This is a stack so multiple begins will need to be matched with an end.
+     * @see
+     * {@link IStyleCollection.IPersistScope}
+     */
+    beginPersist(): IStyleCollection.IPersistScope;
+}
+/**
+ * {@inheritDoc IStyleCollection}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IStyleCollection}
+ */
+export declare namespace IStyleCollection {
+    interface Events {
+        /**
+        * Notify that the named styled has changed
+        */
+        onNamedStylesChange?(source: IStyleCollection): void;
+        onTableStylesChange?(source: IStyleCollection): void;
+        onThemeChange?(source: IStyleCollection): void;
+        onDefaultFontChange?(source: IStyleCollection): void;
+        onAnyChange?(source: IStyleCollection): void;
+    }
+    interface IListeners extends IListener.Callbacks<IStyleCollection, IStyleCollection.Events> {
+    }
+    interface JSON {
+        /**
+         * Used by cells styles.
+         */
+        direct?: IStyle.JSON[];
+        /**
+         * cells styles with a name for quick styling.
+         */
+        named?: IStyle.NamedJSON[];
+        /**
+         * Table styles.
+         */
+        tables?: ITableStyle.JSONS;
+        /**
+         * A list of custom colors.
+         */
+        mruColors?: string[];
+        /**
+         * Overrides for indexed colors.
+         */
+        indexedColors?: string[];
+    }
+    /**
+     * A transient scope for persisting styles with a given
+     * set of StyleIDs.
+     *
+     * @remarks
+     * This is done to ensure that styles across multiple
+     * sheets are rationalized
+     */
+    interface IPersistScope {
+        /**
+         * End the persist scope. This will clear the stack and stop tracking access to this.
+         */
+        endPersist(): void;
+        /**
+         * This can be called multiple times.
+         *
+         * @returns The state as {@link IStyleCollection.JSON}.
+         *
+         * @remarks
+         * Only shared styles that have had the toResourceId called will
+         * be shown in the persisted json.
+         */
+        toJSON(): IStyleCollection.JSON;
+        /**
+         * Load a JSON for a StyleCollection object.
+         *
+         * @remarks
+         * Once this is called the getSharedStyle is available for all
+         * the ids defined in the JSON for the current scope.
+         * @param json {@link IStyleCollection.JSON}
+         */
+        fromJSON(json: IStyleCollection.JSON): void;
+        /**
+         * Given the id return the style.
+         * This assumes that the fromJSON has been called previously.
+         *
+         * @param id
+         */
+        getElementJSON(id: number): IStyle.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.
+         *
+         * @remarks
+         * This is a side effect operation. Calling this will cause the style to be persisted as part of the toJSON
+         *
+         * @param json
+         */
+        getElementID(json: IStyle.JSON): number | null;
+    }
+}
+//# sourceMappingURL=IStyleCollection.d.ts.map

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

@@ -0,0 +1,125 @@
+import { IProperties } from '../type';
+import { IListener } from '../listener';
+import { IColor } from '../color';
+import { ITheme } from '../theme';
+import { ITableStyle } from '../table';
+import { IStyle } from './IStyle';
+import { IStyleCollection } from './IStyleCollection';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+interface PersistScopeState {
+    byJSONs: Map<string, number>;
+    byIds: Map<number, IStyle.JSON>;
+    openScopes: Set<PersistScope>;
+}
+declare class PersistScope implements IStyleCollection.IPersistScope {
+    protected _state: PersistScopeState;
+    protected _normalJSON: IStyle.JSON;
+    protected _toJSONInternal: (jsonSheetStyleShared: IStyle.JSON[]) => IStyleCollection.JSON;
+    protected _fromJSONInternal: (json: IStyleCollection.JSON) => void;
+    protected _onLastEnd: () => void;
+    protected _isClosed: boolean;
+    constructor(state: PersistScopeState, normalJSON: IStyle.JSON, toJSONInternal: (jsonSheetStyleShared: IStyle.JSON[]) => IStyleCollection.JSON, fromJSONInternal: (json: IStyleCollection.JSON) => void, onLastEnd: () => void);
+    /** {@inheritDoc IStyleCollection.IPersistScope.endPersist} */
+    endPersist(): void;
+    /** {@inheritDoc IStyleCollection.IPersistScope.getElementID} */
+    getElementID(json: IStyle.JSON): number | null;
+    /** {@inheritDoc IStyleCollection.IPersistScope.getElementJSON} */
+    getElementJSON(id: number): IStyle.JSON;
+    /** {@inheritDoc IStyleCollection.IPersistScope.fromJSON} */
+    fromJSON(json: IStyleCollection.JSON): void;
+    /** {@inheritDoc IStyleCollection.IPersistScope.toJSON} */
+    toJSON(): IStyleCollection.JSON;
+}
+/**
+ * Base implementation of {@link IStyleCollection}
+ *
+ * TODO - defaultFontSize move to theme?
+ *
+ */
+export declare class StyleCollection implements IStyleCollection {
+    protected _emitter: ListenerEmitter<IStyleCollection, IStyleCollection.IListeners>;
+    protected _theme: ITheme;
+    protected _defaultFontSize: number;
+    protected _schemeLookup: IColor.SchemeLookup;
+    protected _indexedLookup: IColor.IndexedLookup;
+    protected _builtInsCellStyles: Map<string, IStyle.INamed>;
+    protected _customCellStyles: Map<string, IStyle.INamed>;
+    protected _builtInsTableStyles: Map<string, ITableStyle>;
+    protected _customTableStyles: Map<string, ITableStyle>;
+    protected _emptyTableStyle: ITableStyle.Empty;
+    protected _customIndexedColors: readonly IColor[];
+    protected _mruColors: readonly IColor[];
+    protected _normalStyle: IStyle;
+    protected _normalRanged: IProperties.ICellRanged<IStyle.Properties>;
+    protected _defaultTableStyle: ITableStyle | null;
+    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;
+    protected _initializeTableStyles(): Map<string, ITableStyle>;
+    protected _initializeBuiltIns(): void;
+    /** {@inheritDoc IStyleCollection.getNormal} */
+    getNormal(): IStyle;
+    /** {@inheritDoc IStyleCollection.getNormalRanged} */
+    getNormalRanged(): IProperties.ICellRanged<IStyle.Properties>;
+    /** {@inheritDoc IStyleCollection.setTheme} */
+    setTheme(theme: ITheme): void;
+    /** {@inheritDoc IStyleCollection.getTheme} */
+    getTheme(): ITheme;
+    /** {@inheritDoc IStyleCollection.setDefaultFontSize} */
+    setDefaultFontSize(fontSize: number): void;
+    /** {@inheritDoc IStyleCollection.getDefaultFontSize} */
+    getDefaultFontSize(): number;
+    /** {@inheritDoc IStyleCollection.beginPersist} */
+    beginPersist(): IStyleCollection.IPersistScope;
+    /** {@inheritDoc IStyleCollection.getNamed} */
+    getNamed(name: string | IStyle.BuiltInName): IStyle.INamed | null;
+    /** {@inheritDoc IStyleCollection.getCustomNamed} */
+    getCustomNamed(): IStyle.INamed[];
+    /** {@inheritDoc IStyleCollection.setNamed} */
+    setNamed(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;
+    /** {@inheritDoc IStyleCollection.getCustomTableStyles} */
+    getCustomTableStyles(): ITableStyle[];
+    /** {@inheritDoc IStyleCollection.setDefaultTableStyle} */
+    setDefaultTableStyle(styleName: string): boolean;
+    /** {@inheritDoc IStyleCollection.getDefaultTableStyle} */
+    getDefaultTableStyle(): ITableStyle;
+    protected _deleteCustomTableStyle(styleName: string): boolean;
+    /** {@inheritDoc IStyleCollection.setCustomTableStyle} */
+    setCustomTableStyle(name: string, properties: ITableStyle.ResolvableProperties): ITableStyle;
+    /** {@inheritDoc IStyleCollection.validateStyleName} */
+    validateStyleName(name: string, checkDuplicates?: boolean): void;
+    /** {@inheritDoc IStyleCollection.normalize} */
+    normalize(values: IStyle.Modifiers, name?: string): Partial<IStyle.Properties>;
+    /** {@inheritDoc IStyleCollection.resolve} */
+    resolve(values: IStyle.Modifiers, name?: string): Partial<IStyle.Properties>;
+    /** {@inheritDoc IStyleCollection.schemeLookup} */
+    schemeLookup(): IColor.SchemeLookup;
+    /** {@inheritDoc IStyleCollection.indexedLookup} */
+    indexedLookup(): IColor.IndexedLookup;
+    /** {@inheritDoc IStyleCollection.parseColor} */
+    parseColor(str: string): IColor;
+    /** {@inheritDoc IStyleCollection.recentColors} */
+    recentColors(): readonly IColor[];
+    /** {@inheritDoc IStyleCollection.addRecentColor} */
+    addRecentColor(color: IColor): readonly IColor[];
+    /** {@inheritDoc IStyleCollection.clearRecentColors} */
+    clearRecentColors(): void;
+    /** {@inheritDoc IStyleCollection.getCustomIndexedColors} */
+    getCustomIndexedColors(): readonly IColor[];
+    /** {@inheritDoc IStyleCollection.setCustomIndexedColors} */
+    setCustomIndexedColors(colors: readonly IColor[]): void;
+    /** {@inheritDoc IStyleCollection.getIndexedColors} */
+    getIndexedColors(): readonly IColor[];
+    /** {@inheritDoc IListener.ISource.addListeners} */
+    addListeners(listeners: IStyleCollection.IListeners, options?: IListener.Options): IListener.Remove;
+    protected _toJSONInternal(jsonSheetStyleShared: IStyle.JSON[]): IStyleCollection.JSON;
+    protected _fromJSONIndexedColors(indexedColors: string[] | null | undefined): IColor[];
+    protected _fromJSONInternal(json: IStyleCollection.JSON): void;
+}
+export {};
+//# sourceMappingURL=StyleCollection.d.ts.map

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

@@ -0,0 +1,18 @@
+import { ITextFrame, IStyledFont } from '../text';
+import { IBorder } 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 _EmptyAlignmentProperties: ITextFrame.IAlignment.Properties;
+export declare const _EmptyProtectionProperties: ICellProtection.Properties;
+/**
+ * Because all cells derived from the empty cell this is also the default values.
+ */
+export declare const _EmptyCellStyleProperties: IStyle.Properties<any>;
+export declare const _BuiltInStyleDefs: readonly IStyle.Properties[];
+//# sourceMappingURL=_BuiltInStyleDefs.d.ts.map

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

@@ -0,0 +1,20 @@
+/**
+ * A localized-display descriptor for a built-in style name: a catalog message
+ * key plus optional ICU params. Resolve it at the display boundary with
+ * `t(key, params)`; the canonical {@link IStyle.BuiltInName} stays the identity.
+ */
+export interface BuiltInStyleNameDisplay {
+    key: string;
+    params?: Record<string, string | number>;
+}
+/**
+ * The localized-display descriptor for a canonical built-in style name, or
+ * `null` for a custom / non-built-in name (render its raw name unchanged).
+ *
+ * @remarks
+ * The canonical {@link IStyle.BuiltInName} remains the API/storage identity; this
+ * only maps it to a display string. Headings and accent tints compose via ICU
+ * params (`Heading {n}`, `{pct}% - Accent{n}`) so each locale ships one template.
+ */
+export declare function builtInStyleNameDisplay(name: string): BuiltInStyleNameDisplay | null;
+//# sourceMappingURL=_BuiltInStyleNames.d.ts.map

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

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