@sheetxl/sdk 0.7.27 → 0.7.28-beta.1

package/types/src/text/richtext/IStyledFont.d.ts

@@ -0,0 +1,330 @@
+import { Properties as CSSProperties } from 'csstype';
+import { IColor } from '../../color';
+import { IFont } from '../../font';
+import { IStyle } from '../../style';
+/**
+ * Represents a font with styling color.
+ */
+export interface IStyledFont {
+    /**
+     * This can be set as a string using html values such as 'Arial 11pt' but will be resolved to a single font. Fallbacks and fontSize will be
+     * marshalled into their correct property.
+     *
+     * A font with a {@link IStyledFont.getScheme | scheme} of `major` or `minor` is a theme font and
+     * reports the theme's heading or body font; a font with no family of its own reports the theme
+     * body font.
+     */
+    getFamily(): string;
+    /**
+     * Naming a family clears the {@link IStyledFont.getScheme | scheme}, since a font that names its
+     * own family is no longer a theme font.
+     *
+     * @see {@link IStyledFont.getFamily}
+     */
+    setFamily(family: string | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * A list of fonts and their fallbacks. These can also be provided in the fontFamily attribute but will
+     * be normalized to here.
+     */
+    getFallbacks(): string[];
+    /**
+     * @see {@link IStyledFont.setFallbacks}
+     */
+    setFallbacks(fallbacks: string[] | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * Font size is either a number in points or a string that can be converted such as '14px', '1.5em'.
+     */
+    getSize(): number;
+    /**
+     * @see {@link IStyledFont.setSize}
+     */
+    setSize(size: number | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * The weight of the characters.
+     */
+    getWeight(): number;
+    /**
+     * @see {@link IStyledFont.setWeight}
+     */
+    setWeight(weight: number | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * Convenience for {@link IStyledFont.getWeight}. Returns `true` when the weight is bold (> 400).
+     */
+    getBold(): boolean;
+    /**
+     * Convenience for {@link IStyledFont.setWeight}. Sets the weight to bold (`700`) when `true`,
+     * normal (`400`) when `false`, or clears the weight when `null`.
+     *
+     * @remarks
+     * There is no `bold` property - bold is a spelling of {@link IStyledFont.Properties.weight}.
+     * The equivalent update-object form is {@link IStyledFont.Modifiers.bold}, which is folded onto
+     * `weight` before it is stored.
+     *
+     * @see {@link IStyledFont.getBold}
+     */
+    setBold(bold: boolean | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * @default `IFont.Style.Normal`
+     */
+    getStyle(): IFont.Style;
+    /**
+     * @see {@link IStyledFont.setStyle}
+     */
+    setStyle(style: IFont.Style | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * Convenience for {@link IStyledFont.getStyle}. Returns `true` when the style is italic.
+     */
+    getItalic(): boolean;
+    /**
+     * Convenience for {@link IStyledFont.setStyle}. Sets the style to italic (`IFont.Style.Italic`)
+     * when `true`, normal (`IFont.Style.Normal`) when `false`, or clears the style when `null`.
+     *
+     * @remarks
+     * There is no `italic` property - italic is a spelling of {@link IStyledFont.Properties.style}.
+     * The equivalent update-object form is {@link IStyledFont.Modifiers.italic}, which is folded onto
+     * `style` before it is stored.
+     *
+     * @see {@link IStyledFont.getItalic}
+     */
+    setItalic(italic: boolean | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * The text color.
+     */
+    getColor(): IColor;
+    /**
+     * @see {@link IStyledFont.getColor}
+     */
+    setColor(color: IColor | string | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * Adds or removes additional spacing between the characters.
+     */
+    getLetterSpacing(): number;
+    /**
+     * @see {@link IStyledFont.setLetterSpacing}
+     */
+    setLetterSpacing(letterSpacing: number | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * Sets the underline style. If true defaults to single. If false or null defaults to none.
+     *
+     * @default `IFont.UnderlineStyle.None`
+     */
+    getUnderline(): IFont.UnderlineStyle;
+    /**
+     * @see {@link IStyledFont.setUnderline}
+     */
+    setUnderline(underline: IFont.UnderlineStyle | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * The effect draws the text with a line through it.
+     */
+    getStrike(): boolean;
+    /**
+     * @see {@link IStyledFont.setStrike}
+     */
+    setStrike(strike: boolean | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * The theme font this font refers to, if any. A `major` or `minor` scheme makes the font follow
+     * the theme's heading or body font, overriding {@link IStyledFont.getFamily | family}.
+     *
+     * @default `IFont.Scheme.None`
+     */
+    getScheme(): IFont.Scheme;
+    /**
+     * Setting `major` or `minor` clears the {@link IStyledFont.getFamily | family}, since a theme
+     * font resolves its own.
+     *
+     * @see {@link IStyledFont.getScheme}
+     */
+    setScheme(scheme: IFont.Scheme | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * Returns the vertical alignment of the text within a text line.
+     *
+     * @remarks
+     * If the IFont.VerticalAlignment is superscript or subscript then the font size should also render smaller.
+     */
+    getVerticalAlignment(): IFont.VerticalAlignment;
+    /**
+     * @see {@link IStyledFont.setVerticalAlignment}
+     */
+    setVerticalAlignment(verticalAlignment: IFont.VerticalAlignment | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * The effect draws a shadow around the text.
+     *
+     * @remarks
+     * Not rendered by Excel or SheetXL.
+     */
+    getShadow(): boolean;
+    /**
+     * @see {@link IStyledFont.setShadow}
+     */
+    setShadow(shadow: boolean | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * The effect draws the text as an outline.
+     *
+     * @remarks
+     * Not rendered by Excel or SheetXL.
+     */
+    getOutline(): boolean;
+    /**
+     * @see {@link IStyledFont.setOutline}
+     */
+    setOutline(outline: boolean | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * The effect extends or stretches out the text.
+     *
+     * @remarks
+     * Not rendered by Excel or SheetXL.
+     */
+    getExtend(): boolean;
+    /**
+     * @see {@link IStyledFont.setExtend}
+     */
+    setExtend(extend: boolean | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * The character set the font was authored against, or `null` when the font does not name one.
+     *
+     * @remarks
+     * Purely a font-substitution hint - see {@link IFont.Charset}. Cell text is Unicode either way,
+     * so this does not change what a cell contains or, when the named family is installed, how it
+     * renders.
+     */
+    getCharset(): IFont.Charset | null;
+    /**
+     * @see {@link IStyledFont.getCharset}
+     */
+    setCharset(charset: IFont.Charset | null, options?: IStyle.UpdateOptions): IStyledFont;
+    /**
+     * Returns `true` if the font is either a superscript or a subscript.
+     */
+    isSuperSub(): boolean;
+    /**
+     * Returns the size to scale the font for super/sub text.
+     */
+    getSuperSubScale(): number;
+    /**
+     * Returns the number of pixels to shift the font for super/sub text.
+     */
+    getSuperSubShift(): number;
+    /**
+     * Compare against another font to see if they will have the same font measure
+     * This is used to optimize updates by not re-calcing the width/height
+     *
+     * @param other The other style font
+     */
+    isEqualMeasure(other: IStyledFont): boolean;
+    /**
+     * Returns the font styles as a set of css string that are suitable for css.
+     *
+     * @remarks
+     * Not all fill styles will offer an exact css equivalent.
+     * Additionally due to the nature of css having different properties for the same logic value
+     * (for example color, backgroundColor)
+     */
+    toCSS(mode?: IColor.CSSMode, zoom?: number, ignoreNormal?: boolean): CSSProperties;
+    /**
+     * Serializes to a JSON object.
+     */
+    toJSON(): IStyledFont.JSON;
+    /**
+     * For runtime type checking.
+     */
+    readonly isIStyledFont: true;
+}
+/**
+ * {@inheritDoc IStyledFont}
+ * @see
+ * ### **Interface**
+ *
+ * {@link IStyledFont}
+ */
+export declare namespace IStyledFont {
+    /**
+     * The canonical, serializable shape of a font.
+     *
+     * @remarks
+     * This is the *stored* form and carries exactly one spelling per concept - there is no `bold`
+     * or `italic` property here, and no string/boolean shorthands. Update calls accept the more
+     * forgiving {@link IStyledFont.Modifiers}, which is normalized to this shape before it is stored.
+     */
+    interface Properties<C = IColor.Serializable> {
+        /** {@inheritDoc IStyledFont.getFamily} */
+        family?: string;
+        /** {@inheritDoc IStyledFont.getFallbacks} */
+        fallbacks?: string[];
+        /** {@inheritDoc IStyledFont.getSize} */
+        size?: number;
+        /**
+         * The numeric weight of the characters, `400` being normal and `700` bold.
+         *
+         * @see {@link IStyledFont.getWeight}
+         */
+        weight?: number;
+        /** {@inheritDoc IStyledFont.getStyle} */
+        style?: IFont.Style;
+        /** {@inheritDoc IStyledFont.getColor} */
+        color?: C;
+        /** {@inheritDoc IStyledFont.getLetterSpacing} */
+        letterSpacing?: number;
+        /** {@inheritDoc IStyledFont.getUnderline} */
+        underline?: IFont.UnderlineStyle;
+        /** {@inheritDoc IStyledFont.getStrike} */
+        strike?: boolean;
+        /** {@inheritDoc IStyledFont.getScheme} */
+        scheme?: IFont.Scheme;
+        /** {@inheritDoc IStyledFont.getVerticalAlignment} */
+        verticalAlign?: IFont.VerticalAlignment;
+        /** {@inheritDoc IStyledFont.getShadow} */
+        shadow?: boolean;
+        /** {@inheritDoc IStyledFont.getOutline} */
+        outline?: boolean;
+        /** {@inheritDoc IStyledFont.getExtend} */
+        extend?: boolean;
+        /** {@inheritDoc IStyledFont.getCharset} */
+        charset?: IFont.Charset;
+    }
+    /**
+     * The shape accepted by font updates - {@link IStyledFont.Properties} widened with shorthands
+     * and with convenience aliases for the properties that have a boolean spelling.
+     *
+     * @remarks
+     * Every key here is normalized onto a {@link IStyledFont.Properties} key before it is stored, so
+     * none of the widened forms survive into {@link IStyledFont.JSON}. An explicit canonical key wins
+     * when both it and its alias are supplied.
+     */
+    type Modifiers<C = IColor.Serializable> = Omit<Properties<C>, 'weight' | 'underline'> & {
+        /**
+         * The weight of the characters, either numeric (`400`, `700`) or a css keyword such as
+         * `'bold'` or `'lighter'`.
+         *
+         * @see {@link IStyledFont.getWeight}
+         */
+        weight?: number | string;
+        /**
+         * The underline style. `true` is shorthand for `IFont.UnderlineStyle.Single`; `false` and
+         * `null` for `IFont.UnderlineStyle.None`.
+         *
+         * @see {@link IStyledFont.getUnderline}
+         */
+        underline?: boolean | IFont.UnderlineStyle | null;
+        /**
+         * Alias for {@link IStyledFont.Properties.weight}. `true` sets bold (`700`), `false` normal
+         * (`400`), `null` clears it. Ignored when `weight` is also supplied.
+         *
+         * @see {@link IStyledFont.setBold}
+         */
+        bold?: boolean | null;
+        /**
+         * Alias for {@link IStyledFont.Properties.style}. `true` sets `IFont.Style.Italic`, `false`
+         * `IFont.Style.Normal`, `null` clears it. Ignored when `style` is also supplied.
+         *
+         * @see {@link IStyledFont.setItalic}
+         */
+        italic?: boolean | null;
+    };
+    /**
+     * Options for updating a font.
+     */
+    type Update<C = IColor.Serializable> = IStyledFont | Modifiers<C> | string | null;
+    interface JSON extends Properties<string> {
+    }
+}
+//# sourceMappingURL=IStyledFont.d.ts.map

package/types/src/text/richtext/index.d.ts

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

package/types/src/theme/ITheme.d.ts

@@ -0,0 +1,252 @@
+import { IColor } from '../color';
+import { IFill, IStroke, IEffect } from '../fill';
+import { buildPalette as _buildPalette } from './_ThemeUtils';
+/**
+ * Defines and manages themes associated to a specific document or spreadsheet.
+ *
+ * These themes are saved and shared with the document, ensuring a consistent look and feel across different views or users.
+ *
+ * `ITheme` focuses on styling the content within the document itself, such as:
+ * - Applying schema colors (Accent1, Accent2, etc.) to elements like charts, shapes, and tables.
+ * - Controlling font styles and colors used within the document.
+ * - Customizing other visual aspects specific to the document's content.
+ *
+ * This is distinct from an `AppTheme`, which controls the styling of the application's user interface (UI) itself,
+ * such as the toolbar, menus, and overall color scheme, and can be specific to the application or individual user preferences.
+ */
+export interface ITheme {
+    /**
+     * Human readable text describing the theme.
+     */
+    getName(): string;
+    /**
+     * A set of colors that are used in a document.
+     */
+    getColorScheme(): ITheme.IColorScheme;
+    /**
+     * A set of fonts that are used in a document.
+     */
+    getFontScheme(): ITheme.IFontScheme;
+    /**
+     * This is available for functions that want to resolve themed colors
+     *
+     * @remarks
+     * In most instances the scheme lookup from the style should be used unless specifically
+     * rendering for a theme (for example a theme chooser).
+     */
+    schemeLookup(): IColor.SchemeLookup;
+    /**
+     * If a custom theme or built in theme.
+     */
+    isCustom(): boolean;
+    /**
+     * Parses the color using the current Theme schema (if required)
+     * @param str The string to parse
+     * @throws `Error` If the string does not parse to a valid color.
+     *
+     * @remarks
+     * In most instances the scheme lookup from the style should be used unless specifically
+     * rendering for a theme.
+     */
+    parseColor(str: string): IColor;
+    /**
+     * Creates a persistable version of Themes.
+     * @param includeInherited If true then the inherited properties will be included.
+     */
+    toJSON(includeInherited?: boolean): ITheme.JSON;
+}
+/**
+ * {@inheritDoc ITheme}
+ * @see
+ * ### **Interface**
+ *
+ * {@link ITheme}
+ */
+export declare namespace ITheme {
+    interface ColorSchemeJSON extends Partial<ColorSchemeProperties<string>> {
+    }
+    /**
+     * Built a set of colors from the theme.
+     * @remarks
+     * This api will undergo cleanup.
+     */
+    const buildPalette: typeof _buildPalette;
+    interface ColorSchemeProperties<C = IColor.Serializable> {
+        dk1: C;
+        lt1: C;
+        dk2: C;
+        lt2: C;
+        accent1: C;
+        accent2: C;
+        accent3: C;
+        accent4: C;
+        accent5: C;
+        accent6: C;
+        hlink: C;
+        folHlink: C;
+        name: string;
+    }
+    /**
+     * Represents a color scheme interface that extends the properties of ColorSchemeProperties.
+     *
+     * @template C - The type of the color, defaults to IColor.Serializable.
+     */
+    interface IColorScheme {
+        /**
+         * Gets the name of the color scheme.
+         */
+        getName(): string;
+        /**
+         * Gets the first dark color in the scheme.
+         *
+         * @returns {IColor} The first dark color.
+         */
+        getDk1(): IColor;
+        /**
+         * Gets the first light color in the scheme.
+         *
+         * @returns {IColor} The first light color.
+         */
+        getLt1(): IColor;
+        /**
+         * Gets the second dark color in the scheme.
+         *
+         * @returns {IColor} The second dark color.
+         */
+        getDk2(): IColor;
+        /**
+         * Gets the second light color in the scheme.
+         *
+         * @returns {IColor} The second light color.
+         */
+        getLt2(): IColor;
+        /**
+         * Gets the first accent color in the scheme.
+         *
+         * @returns {IColor} The first accent color.
+         */
+        getAccent1(): IColor;
+        /**
+         * Gets the second accent color in the scheme.
+         *
+         * @returns {IColor} The second accent color.
+         */
+        getAccent2(): IColor;
+        /**
+         * Gets the third accent color in the scheme.
+         *
+         * @returns {IColor} The third accent color.
+         */
+        getAccent3(): IColor;
+        /**
+         * Gets the fourth accent color in the scheme.
+         *
+         * @returns {IColor} The fourth accent color.
+         */
+        getAccent4(): IColor;
+        /**
+         * Gets the fifth accent color in the scheme.
+         *
+         * @returns {IColor} The fifth accent color.
+         */
+        getAccent5(): IColor;
+        /**
+         * Gets the sixth accent color in the scheme.
+         *
+         * @returns {IColor} The sixth accent color.
+         */
+        getAccent6(): IColor;
+        /**
+         * Gets the hyperlink color in the scheme.
+         *
+         * @returns {IColor} The hyperlink color.
+         */
+        getHlink(): IColor;
+        /**
+         * Gets the followed hyperlink color in the scheme.
+         *
+         * @returns {IColor} The followed hyperlink color.
+         */
+        getFolHlink(): IColor;
+    }
+    /**
+     * Interface representing a font scheme.
+     */
+    interface IFontScheme {
+        /**
+         * Gets the name of the font scheme.
+         * @returns The name of the font scheme.
+         */
+        getName(): string;
+        /**
+         * Gets the major font of the font scheme.
+         * @returns The major font of the font scheme.
+         */
+        getMajorFont(): string;
+        /**
+         * Gets the fallback fonts for the major font.
+         * @returns An array of fallback fonts for the major font.
+         */
+        getMajorFallbacks(): readonly string[];
+        /**
+         * Gets the minor font of the font scheme.
+         * @returns The minor font of the font scheme.
+         */
+        getMinorFont(): string;
+        /**
+         * Gets the fallback fonts for the minor font.
+         * @returns An array of fallback fonts for the minor font.
+         */
+        getMinorFallbacks(): readonly string[];
+    }
+    interface FontSchemeProperties {
+        majorFont: string;
+        majorFallbacks: string[];
+        minorFont: string;
+        minorFallbacks: string[];
+        name: string;
+    }
+    interface FontSchemeJSON extends Partial<FontSchemeProperties> {
+    }
+    interface JSON {
+        name: string;
+        fonts?: ITheme.FontSchemeJSON;
+        colors?: ITheme.ColorSchemeJSON;
+        darkColors?: ITheme.ColorSchemeJSON;
+        /**
+         * The theme's fill style list (`<a:fillStyleLst>`) — the fills a shape/chart style
+         * (`<a:style><a:fillRef idx="N">`) resolves against by position.
+         */
+        fillStyleLst?: IFill.JSON[];
+        /**
+         * The theme's line style list (`<a:lnStyleLst>`) — the strokes a shape/chart style
+         * (`<a:style><a:lnRef idx="N">`) resolves against by position.
+         */
+        lnStyleLst?: IStroke.JSON[];
+        /**
+         * The theme's effect style list (`<a:effectStyleLst>`) — the effects a shape/chart style
+         * (`<a:style><a:effectRef idx="N">`) resolves against by position. Each entry is the (possibly
+         * empty) list of effects applied together for that style — one `<a:effectStyle>`'s `<a:effectLst>`.
+         */
+        effectStyleLst?: IEffect.JSON[][];
+        /**
+         * The theme's background fill style list (`<a:bgFillStyleLst>`).
+         */
+        bgFillStyleLst?: IFill.JSON[];
+        /**
+         * Opaque capture of the source theme's format scheme — the raw `<a:fmtScheme>`
+         * fragment (fill/line/effect/background-fill style lists) — replayed verbatim on save so
+         * idx-referencing shape/chart styles (`<a:lnRef idx="N">`, `<a:fillRef>`, `<a:effectRef>`) keep
+         * resolving against the same source definitions instead of a regenerated, differently-ordered
+         * list.
+         *
+         * @remarks
+         * Used only when the source `fmtScheme` contains something {@link fillStyleLst}/{@link lnStyleLst}/
+         * {@link effectStyleLst}/{@link bgFillStyleLst} can't fully represent — otherwise those typed
+         * fields are populated instead and this is left unset. Not yet exposed on `ITheme` itself —
+         * pending real format-scheme modeling (see `format`/`objectDefaults` below).
+         */
+        formatSchemeXml?: string;
+    }
+}
+//# sourceMappingURL=ITheme.d.ts.map

package/types/src/theme/IThemeCollection.d.ts

@@ -0,0 +1,84 @@
+import { ICollection } from '../type';
+import { ITheme } from './ITheme';
+/**
+ * A collection of themes.
+ */
+export interface IThemeCollection extends ICollection<ITheme> {
+    /**
+     * Add or update a theme.
+     *
+     * @param theme The new theme.
+     * @returns The original theme
+     *
+     * @remarks
+     * Case insensitive; for duplicate detection purposes.
+     */
+    setCustomTheme(theme: ITheme): ITheme | null;
+    /**
+     * Returns the theme for the given name.
+     *
+     * @remarks
+     * Will try to return:
+     * 1. The custom theme for the name
+     * 2. The builtin theme for the name.
+     * 3. nul if it doesn't exist.
+     */
+    getByName(name: string): ITheme | null;
+    /**
+     * Returns all themes that match the filter criteria.
+     *
+     * @param options {@link IThemeCollection.GetItemsOptions}
+     *
+     * @remarks
+     * * If no filter criteria is provided, all items will be returned.
+     * * Generates a new array so this can be mutated without affecting the internal state.
+     */
+    getItems(options?: IThemeCollection.GetItemsOptions): ITheme[];
+    /**
+     * Remove a custom theme.
+     *
+     * @param theme A {@link Theme} or string.
+     * @returns `true` if the Theme was removed.
+     */
+    deleteCustomTheme(theme: ITheme | string): ITheme | null;
+    /**
+     * Returns the name of the default Theme.
+     *
+     * @returns A theme that has been set as the Default using {@link setDefaultTheme}.
+     */
+    getDefaultTheme: () => ITheme;
+    /**
+     * Set the new default theme.
+     *
+     * @returns The previous default theme.
+     */
+    setDefaultTheme: (theme: ITheme) => ITheme;
+}
+/**
+ * {@inheritDoc IThemeCollection}
+ *
+ * @see
+ * ### **Interface**
+ *
+ * {@link IThemeCollection}
+ */
+export declare namespace IThemeCollection {
+    type JSON = ITheme.JSON[];
+    interface GetItemsOptions extends ICollection.GetItemsOptions {
+        /**
+         * @defaultValue `IThemeCollection.BuiltInFilterType.All`
+         */
+        type?: BuiltInFilterType;
+        /**
+         * Allows for the filter to return a specific theme even if not in the list.
+         */
+        selected?: ITheme;
+    }
+    const BuiltInFilterType: {
+        readonly BuiltIn: "builtIn";
+        readonly All: "all";
+        readonly Custom: "custom";
+    };
+    type BuiltInFilterType = typeof BuiltInFilterType[keyof typeof BuiltInFilterType];
+}
+//# sourceMappingURL=IThemeCollection.d.ts.map