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

package/types/src/text/impl/TabStrategy.d.ts

@@ -1,8 +1,10 @@
 import { ITextFrame } from '../ITextFrame';
 import { Phrase } from './Phrase';
 import { IFont } from '../../font';
+/** Measures a phrase's text in the frame's font. */
+export type TabTextMeasurer = (text: string) => IFont.ExtendedMetrics;
 export interface TabStrategy {
-    width(x: number, xOffset: number, maxX: number, tabStop: ITextFrame.TabStop, phrase: Phrase, textMeasurer: IFont.Measurer): number;
+    width(x: number, xOffset: number, maxX: number, tabStop: ITextFrame.TabStop, phrase: Phrase, textMeasurer: TabTextMeasurer): number;
     yanks(): boolean;
     shrinksToZero(): boolean;
 }

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

@@ -4,4 +4,5 @@ export * from './richtext';
 export * from './TextBoxAlignment';
 export * as TextUtils from './TextUtils';
 export * as TextRotation from './TextRotation';
+export * as TextStacked from './TextStacked';
 //# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,50 @@
+import { IFontStyle } from '../../font';
+/**
+ * Text with formatting: a list of {@link IRichText.Run | runs}, each a span of text with the font
+ * properties it sets.
+ *
+ * @remarks
+ * A run records only what it sets. Everything it leaves out is inherited from the font of whatever
+ * holds the text (a note's default, a cell's style).
+ */
+export declare namespace IRichText {
+    /**
+     * One formatted span.
+     */
+    interface Run {
+        /**
+         * The text of the span.
+         */
+        text: string;
+        /**
+         * The font properties this span sets, or nothing when it has none of its own.
+         *
+         * @remarks
+         * The same properties a cell's font has, so a bold span is `{ weight: 700 }`, italic is
+         * `{ style: 'italic' }`. The color is any string a font's color takes; one read from a file keeps
+         * its theme or indexed color that way.
+         */
+        font?: IFontStyle.JSON;
+    }
+    /**
+     * A run as given to a setter: the font may use the update spellings (`bold`, `italic`,
+     * `underline: true`), which are folded onto the properties a stored {@link Run} carries.
+     */
+    interface RunUpdate {
+        text: string;
+        font?: IFontStyle.Update<string> | null;
+    }
+    /**
+     * The serialized form: the runs, in order.
+     */
+    interface JSON {
+        runs: Run[];
+    }
+    /**
+     * What a setter takes: runs, a {@link JSON}, or plain text for one run.
+     */
+    type Update = JSON | {
+        runs: readonly RunUpdate[];
+    } | readonly RunUpdate[] | string;
+}
+//# sourceMappingURL=IRichText.d.ts.map

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

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

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

@@ -1,5 +1,7 @@
 import { IColor } from '../color';
+import { IFont } from '../font';
 import { IFill, IStroke, IEffect } from '../fill';
+import { IShape } from '../shape';
 import { buildPalette as _buildPalette } from './_ThemeUtils';
 /**
  * Defines and manages themes associated to a specific document or spreadsheet.
@@ -27,6 +29,20 @@ export interface ITheme {
      * A set of fonts that are used in a document.
      */
     getFontScheme(): ITheme.IFontScheme;
+    /**
+     * The fills, lines, effects and background fills a shape's or chart's style references
+     * ({@link ITheme.StyleRefsJSON}) name by position. Each list the theme does not state is
+     * Office's.
+     */
+    getFormatScheme(): ITheme.FormatScheme;
+    /**
+     * What a new shape, line or text box starts from in this theme.
+     *
+     * @remarks
+     * Read once, when the object is inserted (`ShapeStyleUtils.withThemeDefaults`); the object
+     * keeps what it took. A theme that states none has the base theme's.
+     */
+    getObjectDefaults(): Readonly<ITheme.ObjectDefaultsJSON>;
     /**
      * This is available for functions that want to resolve themed colors
      *
@@ -54,6 +70,8 @@ export interface ITheme {
      * @param includeInherited If true then the inherited properties will be included.
      */
     toJSON(includeInherited?: boolean): ITheme.JSON;
+    /** For runtime type checking. */
+    readonly isITheme: true;
 }
 /**
  * {@inheritDoc ITheme}
@@ -198,15 +216,93 @@ export declare namespace ITheme {
          * @returns An array of fallback fonts for the minor font.
          */
         getMinorFallbacks(): readonly string[];
+        /**
+         * The heading fonts, as the scheme states them or as the theme it builds on does.
+         */
+        getMajor(): Readonly<ITheme.FontCollectionJSON>;
+        /**
+         * The body fonts, as the scheme states them or as the theme it builds on does.
+         */
+        getMinor(): Readonly<ITheme.FontCollectionJSON>;
     }
-    interface FontSchemeProperties {
-        majorFont: string;
-        majorFallbacks: string[];
-        minorFont: string;
-        minorFallbacks: string[];
-        name: string;
+    /**
+     * The fonts of one role in a font scheme, heading (major) or body (minor), by the kind of text
+     * they are for.
+     */
+    interface FontCollectionJSON {
+        /**
+         * The font for Latin text: what a cell whose font names the scheme draws with.
+         */
+        latin?: string;
+        /**
+         * The PANOSE classification of {@link latin}, 20 hexadecimal digits. It chooses the generic
+         * family drawn with when the font is not installed.
+         */
+        panose?: string;
+        /**
+         * The font for East Asian text. Usually empty, with the font given by script in {@link scripts}.
+         */
+        eastAsian?: string;
+        /**
+         * The font for complex-script text (Arabic, Hebrew, Thai, ...). Usually empty, with the font
+         * given by script in {@link scripts}.
+         */
+        complexScript?: string;
+        /**
+         * Fonts by the script of the text, keyed by ISO 15924 code (`Jpan`, `Hang`, `Arab`, ...), in the
+         * order they are listed.
+         */
+        scripts?: Record<string, string>;
     }
-    interface FontSchemeJSON extends Partial<FontSchemeProperties> {
+    /**
+     * A theme's fonts: one collection for headings and one for body text.
+     *
+     * @remarks
+     * A collection is taken whole: one that is stated replaces the base theme's, script fonts included.
+     */
+    interface FontSchemeJSON {
+        name?: string;
+        /**
+         * The heading fonts. Office calls these the **Headings** font.
+         */
+        major?: FontCollectionJSON;
+        /**
+         * The body fonts. Office calls these the **Body** font.
+         */
+        minor?: FontCollectionJSON;
+    }
+    /**
+     * One reference into a theme style list (`fillRef`, `lnRef`, `effectRef`): the one-based position
+     * in the list, `0` for none, and the color the list entry's placeholder (`phClr`) takes.
+     */
+    interface StyleRefJSON {
+        index: number;
+        color?: string;
+    }
+    /** The font a theme style refers to: the theme's `major` or `minor` font, or `none`, and the text color. */
+    interface FontRefJSON {
+        index: IFont.Scheme;
+        color?: string;
+    }
+    /**
+     * References into the theme's format scheme — what a shape or chart draws with wherever it
+     * states nothing of its own: DrawingML's `style` element.
+     */
+    interface StyleRefsJSON {
+        fill?: StyleRefJSON;
+        stroke?: StyleRefJSON;
+        effect?: StyleRefJSON;
+        font?: FontRefJSON;
+    }
+    /**
+     * A theme's format scheme (DrawingML's `fmtScheme`): the lists a {@link StyleRefsJSON} indexes
+     * into, one-based. See the fields of the same names on {@link ITheme.JSON}.
+     */
+    interface FormatScheme {
+        fillStyleLst: readonly IFill.JSON[];
+        lnStyleLst: readonly IStroke.JSON[];
+        effectStyleLst: readonly IEffect.JSON[][];
+        bgFillStyleLst: readonly IFill.JSON[];
     }
     interface JSON {
         name: string;
@@ -241,12 +337,58 @@ export declare namespace ITheme {
          * 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).
+         * Set only when the source `fmtScheme` contains something {@link fillStyleLst}/{@link lnStyleLst}/
+         * {@link effectStyleLst}/{@link bgFillStyleLst} can't fully represent. The lists that can be
+         * represented are still populated, so the theme draws with them.
          */
         formatSchemeXml?: string;
+        /**
+         * What a new shape, line or text box starts from. Stated, it replaces the base theme's whole,
+         * so `{}` means none.
+         */
+        objectDefaults?: ITheme.ObjectDefaultsJSON;
+        /**
+         * Colors the theme offers beside its scheme, in order: Office lists them as **Custom Colors**
+         * in its color pickers. Not inherited from the base theme.
+         */
+        customColors?: ITheme.CustomColorJSON[];
+        /**
+         * Which theme this is, across the files and versions it appears in. Not inherited from the
+         * base theme.
+         */
+        family?: ITheme.FamilyJSON;
+    }
+    /**
+     * A color a theme offers beside its scheme (DrawingML's `custClr`).
+     */
+    interface CustomColorJSON {
+        /** The name shown for the color. */
+        name?: string;
+        color: string;
+    }
+    /**
+     * A theme's identity (the 2012 theme extension's `themeFamily`). Office matches themes by
+     * {@link id}, and the versions of one theme by {@link vid}.
+     */
+    interface FamilyJSON {
+        /** The family's name, such as `Office Theme`. */
+        name: string;
+        /** A GUID in braces, the same for every version of the theme. */
+        id: string;
+        /** A GUID in braces naming this version. */
+        vid?: string;
+    }
+    /**
+     * What a new object starts from, by kind: its fill, line, effects, text body and style
+     * references, as a shape states them. DrawingML's `objectDefaults`.
+     */
+    interface ObjectDefaultsJSON {
+        /** A new shape (`spDef`). */
+        shape?: IShape.JSON;
+        /** A new line or connector (`lnDef`). */
+        line?: IShape.JSON;
+        /** A new text box (`txDef`). */
+        text?: IShape.JSON;
     }
 }
 //# sourceMappingURL=ITheme.d.ts.map

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

@@ -53,6 +53,8 @@ export interface IThemeCollection extends ICollection<ITheme> {
      * @returns The previous default theme.
      */
     setDefaultTheme: (theme: ITheme) => ITheme;
+    /** For runtime type checking. */
+    readonly isIThemeCollection: true;
 }
 /**
  * {@inheritDoc IThemeCollection}

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

@@ -1,3 +1,4 @@
+import { AbstractCollection } from '../type';
 import { IColor } from '../color';
 import { ITheme } from './ITheme';
 import { IThemeCollection } from './IThemeCollection';
@@ -14,6 +15,10 @@ export declare class Theme implements ITheme {
     private _lnStyleLst;
     private _effectStyleLst;
     private _bgFillStyleLst;
+    private _formatScheme;
+    private _objectDefaults;
+    private _customColors;
+    private _family;
     private _cacheColors;
     /** System epoch at which `_cacheColors` was populated (for host-theme invalidation). */
     private _cacheEpoch;
@@ -27,17 +32,23 @@ export declare class Theme implements ITheme {
     getColorScheme(): ITheme.IColorScheme;
     /** {@inheritDoc ITheme.getFontScheme} */
     getFontScheme(): ITheme.IFontScheme;
+    /** {@inheritDoc ITheme.getFormatScheme} */
+    getFormatScheme(): ITheme.FormatScheme;
+    /** {@inheritDoc ITheme.getObjectDefaults} */
+    getObjectDefaults(): Readonly<ITheme.ObjectDefaultsJSON>;
     /** {@inheritDoc ITheme.schemeLookup} */
     schemeLookup(): IColor.SchemeLookup;
     /** {@inheritDoc ITheme.parseColor} */
     parseColor(str: string): IColor;
     /** {@inheritDoc ITheme.toJSON} */
     toJSON(): ITheme.JSON;
+    /** {@inheritDoc ITheme.isITheme} */
+    get isITheme(): true;
 }
 /**
  * Collection of themes
  */
-export declare class ThemeCollection implements IThemeCollection {
+export declare class ThemeCollection extends AbstractCollection<ITheme, IThemeCollection.GetItemsOptions> implements IThemeCollection {
     private _customMap;
     private _defaultTheme;
     private _isReadOnly;
@@ -48,15 +59,13 @@ export declare class ThemeCollection implements IThemeCollection {
     setDefaultTheme(theme: ITheme): ITheme;
     /** {@inheritDoc IThemeCollection.getByName} */
     getByName(name: string): ITheme | null;
-    /** {@inheritDoc ICollection.[Symbol.iterator]} */
-    [Symbol.iterator](): IterableIterator<ITheme>;
-    /** {@inheritDoc IThemeCollection.getByName} */
-    getItems(options?: IThemeCollection.GetItemsOptions): ITheme[];
-    /** {@inheritDoc IThemeCollection.getCount} */
-    getCount(): number;
+    /** {@inheritDoc AbstractCollection._getItems} */
+    protected _getItems(options?: IThemeCollection.GetItemsOptions): ITheme[];
     /** {@inheritDoc IThemeCollection.setCustomTheme} */
     setCustomTheme(theme: ITheme): ITheme | null;
     /** {@inheritDoc IThemeCollection.deleteCustomTheme} */
     deleteCustomTheme(theme: ITheme | string): ITheme | null;
+    /** {@inheritDoc IThemeCollection.isIThemeCollection} */
+    get isIThemeCollection(): true;
 }
 //# sourceMappingURL=ThemeCollection.d.ts.map

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

@@ -0,0 +1,8 @@
+import { ITheme } from './ITheme';
+/**
+ * The fonts of the Office theme's font scheme (Excel 2013-2022), as Excel writes them into a new
+ * workbook, script fonts included.
+ */
+export declare const OFFICE_MAJOR_FONTS: Readonly<ITheme.FontCollectionJSON>;
+export declare const OFFICE_MINOR_FONTS: Readonly<ITheme.FontCollectionJSON>;
+//# sourceMappingURL=_OfficeFontScheme.d.ts.map

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

@@ -0,0 +1,3 @@
+import { ITheme } from './ITheme';
+export declare const OFFICE_FORMAT_SCHEME: ITheme.FormatScheme;
+//# sourceMappingURL=_OfficeFormatScheme.d.ts.map