@jsfkit/types 1.5.0 → 2.0.0

package/dist/index.d.ts

@@ -149,7 +149,7 @@ type DefinedName = {
      * A formula expression, a reference, or value. Whatever the value is will be evaluated by a
      * spreadsheet engine as if it were an expression.
      */
-    value?: string;
+    value: string;
     /**
      * An optional worksheet name that defines the scope for this name. When this field is absent,
      * the defined name should be considered to be scoped to the workbook.
@@ -161,6 +161,30 @@ type DefinedName = {
     comment?: string;
 };
 
+/**
+ * A defined name in an external workbook.
+ *
+ * @see {@link DefinedName}
+ * @group Workbooks
+ */
+type ExternalDefinedName = {
+    /**
+     * A case-sensitive name. Names must start with a letter or `_`, and may only be made up of
+     * letters as well as `\`, `_`, `.`, or `?`. Names must be a valid A1 or R1C1 reference.
+     */
+    name: string;
+    /**
+     * A formula expression, a reference, or value. Whatever the value is will be evaluated by a
+     * spreadsheet engine as if it were an expression.
+     */
+    value?: string;
+    /**
+     * An optional worksheet name that defines the scope for this name. When this field is absent,
+     * the defined name should be considered to be scoped to the workbook.
+     */
+    scope?: string;
+};
+
 /**
  * A simple container sheet for cell values within an external workbook.
  *
@@ -201,7 +225,7 @@ type External = {
      */
     sheets: ExternalWorksheet[];
     /** Relevant defined names from an external workbook. */
-    names: DefinedName[];
+    names: ExternalDefinedName[];
     /**
      * Indicates that the path to the external workbook file is unknown or missing.
      * In XLSX, this corresponds to the xlPathMissing relationship type.
@@ -236,7 +260,7 @@ type GridSize = {
     /** A 1-based inclusive end index. */
     end: integer;
     /** The size of the grid item in pixels. */
-    size: PixelValue;
+    size?: PixelValue;
     /** An index to a style in the workbook styles. */
     s?: integer;
 };
@@ -258,6 +282,509 @@ type Note = {
     text: string;
 };
 
+/**
+ * Automatic colour choice. The application decides on what exact colour to use. Typically this
+ * means black for text, white for background.
+ *
+ * @group Colors
+ */
+type AutoColor = {
+    type: 'auto';
+};
+
+/**
+ * Represents a single transformation that can be applied to a colour.
+ *
+ * Most transforms have a `type` that specifies the kind of transformation, and a `value` that
+ * provides the necessary parameter for that transformation. The exact meaning and valid range of
+ * `value` depends on the `type` of transform. The exception are a handful of whole-colour
+ * transformations that affect the entire colour; they have `type` but no `value.`
+ *
+ * The supported transform types include:
+ *
+ * - Tint and shade: blend the colour towards white (tint) or black (shade) by a specified
+ *   percentage.
+ * - Alpha: adjust the opacity of the colour using various methods (absolute value, multiplicative,
+ *   or additive).
+ * - Hue, saturation, and luminance: rotate a colour attribute of the colour by a specified amount
+ *   (absolute, multiplicative, or additive).
+ * - Per-channel RGB adjustments: modify individual red, green, or blue channels (absolute,
+ *   multiplicative, or additive).
+ * - Whole-colour operations: apply transformations that affect the entire colour (complement,
+ *   invert, grayscale, gamma adjustments).
+ *
+ * @group Colors
+ */
+type ColorTransform = {
+    /**
+     * Produces a lighter version of the input colour. A 10% tint is 10% of the input colour
+     * combined with 90% white. */
+    type: 'tint';
+    /**
+     * Percentage (clamped to 0-100).
+     * @min 0
+     * @max 100
+     */
+    value: number;
+} | {
+    /**
+     * Produces a darker version of the input colour. A 10% shade is 10% of the input colour
+     * combined with 90% black.
+     */
+    type: 'shade';
+    /**
+     * Percentage (clamped to 0-100).
+     * @min 0
+     * @max 100
+     */
+    value: number;
+} | {
+    /** Alters the input colour to have the specified opacity, but with its colour unchanged. */
+    type: 'alpha';
+    /**
+     * Percentage (clamped to 0-100).
+     * @min 0
+     * @max 100
+     */
+    value: number;
+} | {
+    /**
+     * Produces a more or less opaque version of the input colour. An alpha modulate never increases
+     * the alpha beyond 100%. A 200% alpha modulate makes an input colour twice as opaque as before.
+     * A 50% alpha modulate makes an input colour half as opaque as before.
+     */
+    type: 'alphaMod';
+    /**
+     * Positive percentage.
+     * @min 0
+     */
+    value: number;
+} | {
+    /**
+     * Produces a more or less opaque version of the input colour.
+     *
+     * Increases or decreases the input alpha percentage by the specified percentage offset. A 10%
+     * alpha offset increases a 50% opacity to 60%. A -10% alpha offset decreases a 50% opacity to
+     * 40%. The transformed alpha values are limited to a range of 0 to 100%. A 10% alpha offset
+     * increase to a 100% opaque object still results in 100% opacity.
+     */
+    type: 'alphaOff';
+    /**
+     * Percentage (clamped to -100 to 100).
+     * @min -100
+     * @max 100
+     */
+    value: number;
+} | {
+    /**
+    * Alters the input colour so it has the specified hue, but with its saturation and luminance
+    * unchanged.
+    */
+    type: 'hue';
+    /**
+     * Degrees (clamped to 0-360).
+     * @min 0
+     * @max 360
+     */
+    value: number;
+} | {
+    /**
+     * Modulates the input colour's hue by the given percentage. A 50% hue modulate decreases the
+     * angular hue value by half. A 200% hue modulate doubles the angular hue value.
+     */
+    type: 'hueMod';
+    /**
+     * Positive percentage.
+     * @min 0
+     */
+    value: number;
+} | {
+    /**
+     * Produces the input colour with its hue shifted, but with its saturation and luminance
+     * unchanged.
+     */
+    type: 'hueOff';
+    /** Degrees. */
+    value: number;
+} | {
+    /**
+     * Alters the input colour so it has the specified saturation, but with its hue and luminance
+     * unchanged.
+     */
+    type: 'sat';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Modulates the input colour's saturation by the given percentage.
+     *
+     * A 50% saturation modulate reduces the saturation by half. A 200% saturation modulate doubles
+     * the saturation.
+     */
+    type: 'satMod';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Produces the input colour with its saturation shifted, but with its hue and luminance
+     * unchanged. A 10% offset to 20% saturation yields 30% saturation.
+     */
+    type: 'satOff';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Alters the input colour so it has the specified luminance, but with its hue and saturation
+     * unchanged.
+     */
+    type: 'lum';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Alters the input colour's luminance modulated by the given percentage.
+     *
+     * A 50% luminance modulate reduces the luminance by half. A 200% luminance modulate doubles the
+     * luminance.
+     */
+    type: 'lumMod';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Produces the input colour with its luminance shifted, but with its hue and saturation
+     * unchanged.
+     */
+    type: 'lumOff';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Produces the input colour with the specified red component. The green and blue colour
+     * components unchanged.
+     */
+    type: 'red';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Alters the input colour so its red component is modulated by the given percentage. A 50% red
+     * modulate reduces the red component by half. A 200% red modulate doubles the red component.
+     */
+    type: 'redMod';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Alters the input colour so its red component is shifted. Its green and blue colour components
+     * unchanged.
+     */
+    type: 'redOff';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Provides the input colour with the specified green component. Its red and blue colour
+     * components unchanged.
+     */
+    type: 'green';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Modulates the input colour's green component by the given percentage.
+     *
+     * A 50% green modulate reduces the green component by half. A 200% green modulate doubles the
+     * green component.
+     */
+    type: 'greenMod';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Alters the input colour so its green component is shifted. Its red and blue colour components
+     * unchanged.
+     */
+    type: 'greenOff';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Provides the input colour with the specified blue component. Its red and green colour
+     * components unchanged.
+     */
+    type: 'blue';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Modulates the input colour's blue component by the given percentage.
+     *
+     * A 50% blue modulate reduces the blue component by half. A 200% blue modulate doubles the blue
+     * component.
+     */
+    type: 'blueMod';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Alters the input colour so its blue component is shifted, but with its red and green colour
+     * components unchanged.
+     */
+    type: 'blueOff';
+    /** Unbounded percentage. */
+    value: number;
+} | {
+    /**
+     * Specifies that the colour rendered should be the complement of the input colour with the
+     * complement being defined as such.
+     */
+    type: 'comp';
+} | {
+    /**
+     * Specifies the inverse of the input colour. For example, the inverse of red (1, 0, 0) is cyan
+     * (0, 1, 1 ).
+     */
+    type: 'inv';
+} | {
+    /**
+     * Specifies a grey scale of the input colour, taking into relative intensities of the red,
+     * green, and blue primaries.
+     */
+    type: 'gray';
+} | {
+    /**
+     * Specifies that the output colour rendered by the generating application should be the sRGB
+     * gamma shift of the input colour.
+     */
+    type: 'gamma';
+} | {
+    /**
+     * Specifies that the output colour rendered by the generating application should be the inverse
+     * sRGB gamma shift of the input colour.
+     */
+    type: 'invGamma';
+};
+
+/**
+ * Hue / saturation / lightness.
+ *
+ * Hue, saturation and lightness follow CSS Color Level 4 conventions, but using the range (0-100)
+ * rather than (0-1).
+ *
+ * @group Colors
+ */
+type HslColor = {
+    type: 'hsl';
+    /**
+     * Degrees (0-360). Must be positive.
+     * @min 0
+     * @max 360
+     */
+    hue: number;
+    /** Percentage. */
+    saturation: number;
+    /** Percentage. */
+    lightness: number;
+};
+
+/**
+ * A legacy colour indexing scheme, still occasionally required for backwards compatibility.
+ *
+ * An enumerated set of RGB colours values that correspond to a zero-based index.
+ *
+ * The table below lists the mapping from indexed colour value to RGB value. Note that indexes 8-15
+ * are copies of indexes 0-7. All colours are fully opaque.
+ *
+ * | Index |    RGB hex colour |
+ * |------:|------------------:|
+ * |     0 |           #000000 |
+ * |     1 |           #FFFFFF |
+ * |     2 |           #FF0000 |
+ * |     3 |           #00FF00 |
+ * |     4 |           #0000FF |
+ * |     5 |           #FFFF00 |
+ * |     6 |           #FF00FF |
+ * |     7 |           #00FFFF |
+ * |     8 |           #000000 |
+ * |     9 |           #FFFFFF |
+ * |    10 |           #FF0000 |
+ * |    11 |           #00FF00 |
+ * |    12 |           #0000FF |
+ * |    13 |           #FFFF00 |
+ * |    14 |           #FF00FF |
+ * |    15 |           #00FFFF |
+ * |    16 |           #800000 |
+ * |    17 |           #008000 |
+ * |    18 |           #000080 |
+ * |    19 |           #808000 |
+ * |    20 |           #800080 |
+ * |    21 |           #008080 |
+ * |    22 |           #C0C0C0 |
+ * |    23 |           #808080 |
+ * |    24 |           #9999FF |
+ * |    25 |           #993366 |
+ * |    26 |           #FFFFCC |
+ * |    27 |           #CCFFFF |
+ * |    28 |           #660066 |
+ * |    29 |           #FF8080 |
+ * |    30 |           #0066CC |
+ * |    31 |           #CCCCFF |
+ * |    32 |           #000080 |
+ * |    33 |           #FF00FF |
+ * |    34 |           #FFFF00 |
+ * |    35 |           #00FFFF |
+ * |    36 |           #800080 |
+ * |    37 |           #800000 |
+ * |    38 |           #008080 |
+ * |    39 |           #0000FF |
+ * |    40 |           #00CCFF |
+ * |    41 |           #CCFFFF |
+ * |    42 |           #CCFFCC |
+ * |    43 |           #FFFF99 |
+ * |    44 |           #99CCFF |
+ * |    45 |           #FF99CC |
+ * |    46 |           #CC99FF |
+ * |    47 |           #FFCC99 |
+ * |    48 |           #3366FF |
+ * |    49 |           #33CCCC |
+ * |    50 |           #99CC00 |
+ * |    51 |           #FFCC00 |
+ * |    52 |           #FF9900 |
+ * |    53 |           #FF6600 |
+ * |    54 |           #666699 |
+ * |    55 |           #969696 |
+ * |    56 |           #003366 |
+ * |    57 |           #339966 |
+ * |    58 |           #003300 |
+ * |    59 |           #333300 |
+ * |    60 |           #993300 |
+ * |    61 |           #993366 |
+ * |    62 |           #333399 |
+ * |    63 |           #333333 |
+ * |    64 | System foreground |
+ * |    65 | System background |
+ *
+ * @group Colors
+ */
+type IndexedColor = {
+    type: 'indexed';
+    value: number;
+};
+
+/**
+ * A named colour from a predefined collection of colours.
+ *
+ * The preset colours are analogous to the extended colour keywords from CSS Colors Level 3,
+ * but using camel casing and abbreviated forms (e.g. `dkMagenta` vs `darkmagenta`).
+ *
+ * @group Colors
+ */
+type PresetColor = {
+    type: 'preset';
+    /** Preset name, e.g. "aliceBlue", "coral". */
+    value: 'aliceBlue' | 'antiqueWhite' | 'aqua' | 'aquamarine' | 'azure' | 'beige' | 'bisque' | 'black' | 'blanchedAlmond' | 'blue' | 'blueViolet' | 'brown' | 'burlyWood' | 'cadetBlue' | 'chartreuse' | 'chocolate' | 'coral' | 'cornflowerBlue' | 'cornsilk' | 'crimson' | 'cyan' | 'dkBlue' | 'dkCyan' | 'dkGoldenrod' | 'dkGray' | 'dkGreen' | 'dkKhaki' | 'dkMagenta' | 'dkOliveGreen' | 'dkOrange' | 'dkOrchid' | 'dkRed' | 'dkSalmon' | 'dkSeaGreen' | 'dkSlateBlue' | 'dkSlateGray' | 'dkTurquoise' | 'dkViolet' | 'deepPink' | 'deepSkyBlue' | 'dimGray' | 'dodgerBlue' | 'firebrick' | 'floralWhite' | 'forestGreen' | 'fuchsia' | 'gainsboro' | 'ghostWhite' | 'gold' | 'goldenrod' | 'gray' | 'green' | 'greenYellow' | 'honeydew' | 'hotPink' | 'indianRed' | 'indigo' | 'ivory' | 'khaki' | 'lavender' | 'lavenderBlush' | 'lawnGreen' | 'lemonChiffon' | 'ltBlue' | 'ltCoral' | 'ltCyan' | 'ltGoldenrodYellow' | 'ltGray' | 'ltGreen' | 'ltPink' | 'ltSalmon' | 'ltSeaGreen' | 'ltSkyBlue' | 'ltSlateGray' | 'ltSteelBlue' | 'ltYellow' | 'lime' | 'limeGreen' | 'linen' | 'magenta' | 'maroon' | 'medAquamarine' | 'medBlue' | 'medOrchid' | 'medPurple' | 'medSeaGreen' | 'medSlateBlue' | 'medSpringGreen' | 'medTurquoise' | 'medVioletRed' | 'midnightBlue' | 'mintCream' | 'mistyRose' | 'moccasin' | 'navajoWhite' | 'navy' | 'oldLace' | 'olive' | 'oliveDrab' | 'orange' | 'orangeRed' | 'orchid' | 'paleGoldenrod' | 'paleGreen' | 'paleTurquoise' | 'paleVioletRed' | 'papayaWhip' | 'peachPuff' | 'peru' | 'pink' | 'plum' | 'powderBlue' | 'purple' | 'red' | 'rosyBrown' | 'royalBlue' | 'saddleBrown' | 'salmon' | 'sandyBrown' | 'seaGreen' | 'seaShell' | 'sienna' | 'silver' | 'skyBlue' | 'slateBlue' | 'slateGray' | 'snow' | 'springGreen' | 'steelBlue' | 'tan' | 'teal' | 'thistle' | 'tomato' | 'turquoise' | 'violet' | 'wheat' | 'white' | 'whiteSmoke' | 'yellow' | 'yellowGreen';
+};
+
+/**
+ * A colour in Microsoft's scRGB colour space.
+ *
+ * Equivalent to CSS `srgb-linear` colour space.
+ *
+ * @group Colors
+ */
+type ScRgbColor = {
+    type: 'scrgb';
+    /** Red value as a percentage. Can be outside the range 0-100. */
+    red: number;
+    /** Green value as a percentage. Can be outside the range 0-100. */
+    green: number;
+    /** Blue value as a percentage. Can be outside the range 0-100. */
+    blue: number;
+};
+
+/**
+ * Standard sRGB colour space.
+ *
+ * @group Colors
+ */
+type SrgbColor = {
+    type: 'srgb';
+    /**
+     * CSS-style hex, e.g. `FF0000`. Always six digits, always uppercase. No alpha channel.
+     * @pattern ^[A-F0-9]{6}$
+     */
+    value: string;
+};
+
+/**
+ * OS-defined system colour (e.g. window text, highlight).
+ *
+ * The value must be one of the pre-defined values. The colour matching each of these values should
+ * match the closest analogous colour in the OS in use.
+ *
+ * @group Colors
+ */
+type SystemColor = {
+    type: 'system';
+    /** System colour name. */
+    value: 'scrollBar' | 'background' | 'activeCaption' | 'inactiveCaption' | 'menu' | 'window' | 'windowFrame' | 'menuText' | 'windowText' | 'captionText' | 'activeBorder' | 'inactiveBorder' | 'appWorkspace' | 'highlight' | 'highlightText' | 'btnFace' | 'btnShadow' | 'grayText' | 'btnText' | 'inactiveCaptionText' | 'btnHighlight' | '3dDkShadow' | '3dLight' | 'infoText' | 'infoBk' | 'hotLight' | 'gradientActiveCaption' | 'gradientInactiveCaption' | 'menuHighlight' | 'menuBar';
+};
+
+/** Reference to a theme colour. */
+/**
+ * Reference to a theme colour.
+ *
+ * A theme colour is defined in the workbook's theme. Theme colours are used to ensure a consistent
+ * palette across a workbook.
+ *
+ * @group Colors
+ */
+type SchemeColor = {
+    type: 'theme';
+    /**
+     * Theme colour name.
+     *
+     * Must be one of a limited set of values. The actual colour that matches the name is defined
+     * elsewhere in the theme.
+     */
+    value: 'bg1' | 'tx1' | 'bg2' | 'tx2' | 'accent1' | 'accent2' | 'accent3' | 'accent4' | 'accent5' | 'accent6' | 'hlink' | 'folHlink' | 'phClr' | 'dk1' | 'lt1' | 'dk2' | 'lt2';
+};
+
+/**
+ * A colour, which can be used is various parts of a workbook. The base colour can be transformed
+ * using a list of colour transformations.
+ *
+ * The base colour must be defined using one of the following colour models:
+ *
+ * - {@link SrgbColor}: Standard sRGB colour space, defined by a CSS-style hex string (e.g.
+ *   `FF0000`).
+ * - {@link ScRgbColor}: A colour in Microsoft's scRGB colour space, defined by red, green, and blue
+ *   values as percentages.
+ * - {@link HslColor}: A colour in HSL colour space, defined by hue, saturation, and lightness
+ *   values.
+ * - {@link SystemColor}: An OS-defined system colour (e.g. window text, highlight), defined using
+ *   one of an enumerated set of values.
+ * - {@link SchemeColor}: A reference to a theme colour.
+ * - {@link PresetColor}: A preset colour, similar to CSS's defined colours.
+ * - {@link AutoColor}: Colour choice left to the application.
+ * - {@link IndexedColor}: A legacy colour indexing scheme.
+ *
+ * @group Colors
+ */
+type Color = (SrgbColor | ScRgbColor | HslColor | SystemColor | SchemeColor | PresetColor | AutoColor | IndexedColor) & {
+    /**
+     * Optional list of colour transformations to apply to the base colour.
+     *
+     * The transformations must be applied in order, and each transformation must be applied to the
+     * result of the previous one. There can be multiple transformations of the same type.
+     *
+     * The transformations are defined by {@link ColorTransform}, which includes operations such as
+     * tinting, shading, and saturation adjustments.
+     */
+    transforms?: ColorTransform[];
+};
+
 /**
  * Base type for text runs that annotate ranges within threaded comment text.
  *
@@ -646,15 +1173,6 @@ type BlipFill = {
  */
 type DmlAngle = number;
 
-/**
- * A hex-encoded RGB or RGBA value that conforms to the CSS4 color specification (e.g. `"#3cb371"`).
- *
- * @see {@link https://www.w3.org/TR/css-color-4/#hex-notation | CSS hexadecimal notation spec}
- * @pattern ^#([a-fA-F0-9]{3,4}|([a-fA-F0-9][a-fA-F0-9]){3,4})$
- * @group Workbooks
- */
-type Color = `#${string}`;
-
 /**
  * Gradient color stop.
  *
@@ -1782,6 +2300,24 @@ type Style = {
      * @default "Calibri"
      */
     fontFamily?: string;
+    /**
+     * Identifies the font scheme, if any, to which this style's font belongs.
+     *
+     * When set, the {@link Style.fontFamily} property is ignored and the font is instead resolved by
+     * the workbook theme. `"major"` maps to the theme's heading font and `"minor"` to the body font.
+     * The actual typeface is determined by the theme's {@link ThemeFontCollection} at render time.
+     *
+     * When the theme changes, an application is expected to update the fonts associated with a scheme
+     * automatically.
+     *
+     * It is an error to set this when a workbook has no theme.
+     *
+     * @see {@link Workbook.theme}
+     * @see {@link Theme.fontScheme}
+     * @see {@link ThemeFontScheme}
+     * @see {@link ThemeFontCollection}
+     */
+    fontScheme?: 'major' | 'minor';
     /**
      * The font size in pixels.
      *
@@ -1896,8 +2432,12 @@ type Style = {
     /**
      * The degrees to which the cell text should be rotated. Values range from 0 to 180, and 255 to
      * indicate vertical text. The origin of the rotation is the first letter of the text.
+     *
+     * @min 0
+     * @max 255
+     * @defaultValue 0
      */
-    textRotation?: boolean;
+    textRotation?: integer;
     /**
      * Formatting directions for rendering the cell's value to text.
      */
@@ -2034,6 +2574,206 @@ type Table = {
     style?: TableStyle;
 };
 
+/**
+ * A custom colour, used to add extra colours to a theme.
+ *
+ * @group Themes
+ */
+type ThemeCustomColor = {
+    name?: string;
+    color: Color;
+};
+
+/**
+ * Canonical theme colour palette.
+ *
+ * Consists of twelve colours that come together to form the colour scheme for a theme.
+ *
+ * @group Themes
+ */
+type ThemeColorScheme = {
+    /** Colour scheme name. */
+    name: string;
+    /** The "light 1" colour. */
+    lt1: Color;
+    /** The "dark 1" colour. */
+    dk1: Color;
+    /** The "light 2" colour. */
+    lt2: Color;
+    /** The "dark 2" colour. */
+    dk2: Color;
+    /** Accent 1 colour. */
+    accent1: Color;
+    /** Accent 2 colour. */
+    accent2: Color;
+    /** Accent 3 colour. */
+    accent3: Color;
+    /** Accent 4 colour. */
+    accent4: Color;
+    /** Accent 5 colour. */
+    accent5: Color;
+    /** Accent 6 colour. */
+    accent6: Color;
+    /** Unvisited hyperlink colour. */
+    hlink: Color;
+    /** Visited hyperlink colour. */
+    folHlink: Color;
+};
+
+/**
+ * Script-specific supplemental font.
+ *
+ * @group Themes
+ */
+type ThemeSupplementalFont = {
+    /**
+     * ISO 15924 script code (e.g. `Egyp`, `Arab`).
+     *
+     * @see {@link https://en.wikipedia.org/wiki/ISO_15924}
+     */
+    script: string;
+    /** Font face to use for this script. */
+    typeface: string;
+};
+
+/**
+ * A font definition.
+ *
+ * @group Themes
+ */
+type ThemeTextFont = {
+    /**
+     * Typeface name, e.g. `"Calibri"`.
+     *
+     * Specifies the name of the font to be used. If this font isn't available, font substitution
+     * should be used in order to select an alternate font.
+     */
+    typeface: string;
+    /**
+     * PANOSE 1.0 classification as hex. Used to guide selection of a similar alternate font if the
+     * chosen font is unavailable.
+     *
+     * @see {@link https://en.wikipedia.org/wiki/PANOSE}
+     */
+    panose?: string;
+    /**
+     * Charset byte value.
+     *
+     * Specifies the character set supported by the font. Used in font substitution logic to locate an
+     * appropriate substitute font when this font isn't available.
+     *
+     * | Value           | Description                                                 |
+     * |-----------------|-------------------------------------------------------------|
+     * | 0               | ANSI character set (IANA name `iso-8859-1`)                 |
+     * | 1               | Default character set                                       |
+     * | 2               | Symbol character set                                        |
+     * | 77              | Mac character set (IANA name `macintosh`)                   |
+     * | 128             | Shift JIS character set (IANA name `shift_jis`)             |
+     * | 129             | Hangul character set (IANA name `ks_c_5601-1987`)           |
+     * | 130             | Johab character set (IANA name `KS C-5601-1992`)            |
+     * | 134             | GB-2312 character set (IANA name `GBK`)                     |
+     * | 136             | Chinese Big Five character set (IANA name `Big5`)           |
+     * | 161             | Greek character set (IANA name `windows-1253`)              |
+     * | 162             | Turkish character set (IANA name `iso-8859-9`)              |
+     * | 163             | Vietnamese character set (IANA name `windows-1258`)         |
+     * | 177             | Hebrew character set (IANA name `windows-1255`)             |
+     * | 178             | Arabic character set (IANA name `windows-1256`)             |
+     * | 186             | Baltic character set (IANA name `windows-1257`)             |
+     * | 204             | Russian character set (IANA name `windows-1251`)            |
+     * | 222             | Thai character set (IANA name `windows-874`)                |
+     * | 238             | Eastern European character set (IANA name `windows-1250`)   |
+     * | 255             | Specifies an OEM character set not defined by ISO/IEC 29500 |
+     * | Any other value | Application-defined, can be ignored                         |
+     */
+    charset?: number;
+    /**
+     * Specifies the font pitch.
+     *
+     * | Value | Description                             |
+     * |------:|-----------------------------------------|
+     * |  0    | Default pitch + unknown font family     |
+     * |  1    | Fixed pitch + unknown font family       |
+     * |  2    | Variable pitch + unknown font family    |
+     * | 16    | Default pitch + roman font family       |
+     * | 17    | Fixed pitch + roman font family         |
+     * | 18    | Variable pitch + roman font family      |
+     * | 32    | Default pitch + Swiss font family       |
+     * | 33    | Fixed pitch + Swiss font family         |
+     * | 34    | Variable pitch + Swiss font family      |
+     * | 48    | Default pitch + modern font family      |
+     * | 49    | Fixed pitch + modern font family        |
+     * | 50    | Variable pitch + modern font family     |
+     * | 64    | Default pitch + script font family      |
+     * | 65    | Fixed pitch + script font family        |
+     * | 66    | Variable pitch + script font family     |
+     * | 80    | Default pitch + decorative font family  |
+     * | 81    | Fixed pitch + decorative font family    |
+     * | 82    | Variable pitch + decorative font family |
+     */
+    pitchFamily?: number;
+};
+
+/**
+ * A font collection from the theme.
+ *
+ * A font collection consists of a font definition for Latin, East Asian, and complex script. On top
+ * of these, a font collection can also define a font for use in a specific language or languages.
+ *
+ * @group Themes
+ */
+type ThemeFontCollection = {
+    /** Latin script defaults. */
+    latin: ThemeTextFont;
+    /** East Asian script defaults. */
+    eastAsian?: ThemeTextFont;
+    /** Complex script defaults. */
+    complexScript?: ThemeTextFont;
+    /**
+     * Additional fonts used for language-specific fonts in themes. For example, one can specify a
+     * font that gets used only within the Japanese language context.
+     */
+    supplemental?: ThemeSupplementalFont[];
+};
+
+/**
+ * Theme font pair (major and minor font).
+ *
+ * @group Themes
+ */
+type ThemeFontScheme = {
+    /** Name of the font scheme. */
+    name: string;
+    /** Major theme font. */
+    major: ThemeFontCollection;
+    /** Minor theme font. */
+    minor: ThemeFontCollection;
+};
+
+/**
+ * Workbook theme.
+ *
+ * This covers colours and fonts, but does not include fill styles, background fill styles, line
+ * styles, and effect styles. This is left for a future date.
+ *
+ * @group Themes
+ */
+type Theme = {
+    /**
+     * Theme name.
+     *
+     * @default ""
+     */
+    name?: string;
+    /** Theme colour palette. */
+    colorScheme: ThemeColorScheme;
+    /** Theme major/minor font choice. */
+    fontScheme: ThemeFontScheme;
+    /**
+     * Custom colour palettes.
+     */
+    customColors?: ThemeCustomColor[];
+};
+
 /**
  * The axis a pivot field can be placed on.
  *
@@ -2049,17 +2789,27 @@ type PivotFieldAxis = 'row' | 'col' | 'page';
  */
 type PivotAreaAxis = PivotFieldAxis | 'values';
 
+/**
+ * A field index in a pivot table context. Either a non-negative index into the
+ * pivot table's {@link PivotField} array (or the cache's field array when
+ * `cacheIndex` is true), or one of the following sentinel values:
+ *
+ * - **`-2`** — the "Values" virtual field, representing the data area when a
+ *   pivot table has multiple data fields.
+ * - **`-1`** — no field (references nothing).
+ *
+ * @group PivotTables
+ */
+type PivotFieldIndex = integer;
+
 /**
  * A reference within a pivot area, identifying specific field items that define the area's scope.
  *
  * @group PivotTables
  */
 type PivotAreaReference = {
-    /**
-     * Index of the field this reference applies to.
-     * The special value `4294967294` (0xFFFFFFFE) refers to the data (values) field.
-     */
-    field?: integer;
+    /** The field this reference applies to. See {@link PivotFieldIndex} for valid values. */
+    field?: PivotFieldIndex;
     /**
      * Whether this reference participates in the selection. When false, the reference
      * constrains the area without being selected itself.
@@ -2176,8 +2926,8 @@ type PivotArea = {
      * @default 'normal'
      */
     type?: PivotAreaType;
-    /** The field index this area applies to. */
-    field?: integer;
+    /** The field this area applies to. See {@link PivotFieldIndex} for valid values. */
+    field?: PivotFieldIndex;
     /**
      * Whether the area applies only to data cells (excluding labels).
      *
@@ -2337,6 +3087,8 @@ type PivotCacheRangePr = {
  * A shared item value in a pivot cache field. Each item represents a unique value found in the
  * source data for that field.
  *
+ * A cache may contain items which longer appear in the source data, marked with `u: true`.
+ *
  * @group PivotTables
  */
 type PivotCacheSharedItem = PivotCacheSharedItemStr | PivotCacheSharedItemNum | PivotCacheSharedItemBool | PivotCacheSharedItemDate | PivotCacheSharedItemErr | PivotCacheSharedItemNil;
@@ -2344,30 +3096,36 @@ type PivotCacheSharedItem = PivotCacheSharedItemStr | PivotCacheSharedItemNum |
 type PivotCacheSharedItemStr = {
     t: 's';
     v: string;
+    u?: boolean;
 };
 /** A numeric shared item. @group PivotTables */
 type PivotCacheSharedItemNum = {
     t: 'n';
     v: number;
+    u?: boolean;
 };
 /** A boolean shared item. @group PivotTables */
 type PivotCacheSharedItemBool = {
     t: 'b';
     v: boolean;
+    u?: boolean;
 };
 /** A date shared item (ISO 8601 string). @group PivotTables */
 type PivotCacheSharedItemDate = {
     t: 'd';
     v: string;
+    u?: boolean;
 };
 /** An error shared item (e.g. `"#REF!"`). @group PivotTables */
 type PivotCacheSharedItemErr = {
     t: 'e';
     v: string;
+    u?: boolean;
 };
 /** An empty/missing shared item. @group PivotTables */
 type PivotCacheSharedItemNil = {
     t: 'z';
+    u?: boolean;
 };
 
 /**
@@ -2559,6 +3317,13 @@ type PivotCacheBase = {
      * `"{93AACE53-8F3A-A04A-893A-A439866B3165}"` assigned by Excel 2014+ for revision tracking.
      */
     uid?: string;
+    /**
+     * Whether the cache needs to be refreshed. When true, the pivot table's cached data
+     * is out of date with respect to its source.
+     *
+     * @default false
+     */
+    invalid?: boolean;
 };
 
 /**
@@ -2753,7 +3518,7 @@ type PivotDataField = {
      * The index of the base item used for "show data as" calculations. Only meaningful when
      * {@link showDataAs} is set to a relative calculation mode.
      *
-     * @default 1048832
+     * @default 1048832 (0x100100, sentinel meaning "use the previous item")
      */
     baseItem?: integer;
     /** The number format code for this data field's values (e.g. `"General"`, `"#,##0"`). */
@@ -2984,6 +3749,14 @@ type PivotField = {
      * @default 10
      */
     itemPageCount?: integer;
+    /**
+     * Pivot area defining the sort key when `sortType` is `'ascending'` or
+     * `'descending'`. Specifies which data field's values to sort by (via a
+     * reference with `field: -2`), and may include additional references to
+     * constrain the scope. Absent when sorting is alphabetical (by the field's
+     * own labels).
+     */
+    autoSortScope?: PivotArea;
     /** Whether sorting is deferred to the data source. */
     dataSourceSort?: boolean;
     /**
@@ -3091,7 +3864,7 @@ type PivotFilter = {
     /** Auto-filter criteria that implement this pivot filter. */
     autoFilter?: {
         /** The reference range for the auto-filter. */
-        ref?: string;
+        ref?: CellRange;
         /** Filter columns with their criteria. */
         filterColumns?: PivotAutoFilterColumn[];
     };
@@ -3328,17 +4101,15 @@ type PivotTable = {
      */
     fields: PivotField[];
     /**
-     * Indices into {@link fields} identifying which fields appear on the row axis, in display order.
-     * Negative indices are special placeholders (e.g. `-2` represents the "Values" virtual field,
-     * used when there are multiple data fields) and do not index into {@link fields}.
+     * Fields on the row axis, in display order. Each entry is a {@link PivotFieldIndex}: either
+     * an index into {@link fields}, or `-2` for the "Values" virtual field.
      */
-    rowFieldIndices?: integer[];
+    rowFieldIndices?: PivotFieldIndex[];
     /**
-     * Indices into {@link fields} identifying which fields appear on the column axis, in display
-     * order. Negative indices are special placeholders (e.g. `-2` represents the "Values" virtual
-     * field) and do not index into {@link fields}.
+     * Fields on the column axis, in display order. Each entry is a {@link PivotFieldIndex}: either
+     * an index into {@link fields}, or `-2` for the "Values" virtual field.
      */
-    colFieldIndices?: integer[];
+    colFieldIndices?: PivotFieldIndex[];
     /** The data fields, defining the aggregated values displayed in the pivot table's data area. */
     dataFields?: PivotDataField[];
     /** The page (filter) fields, allowing the pivot table to be filtered by specific field values. */
@@ -3741,6 +4512,8 @@ type WorksheetView = {
      * layout has its own scale.
      */
     layoutScales?: WorksheetLayoutScales;
+    /** Indicates whether a hairline-grid should be drawn when displaying the worksheet. */
+    showGridLines?: boolean;
 };
 
 /**
@@ -3773,12 +4546,10 @@ type Worksheet = {
      * @see {@link https://exceloffthegrid.com/make-excel-sheets-very-hidden/}
      */
     hidden?: 0 | 1 | 2;
-    /** Indicates whether a hairline-grid should be drawn when displaying the sheet. */
-    showGridLines?: boolean;
     /** The different display configurations saved for the worksheet. */
     views?: WorksheetView[];
     /** A list of drawings that appear in this worksheet. */
-    drawing?: Drawing[];
+    drawings?: Drawing[];
 };
 
 /**
@@ -3867,6 +4638,54 @@ type Workbook = {
      * @see {@link https://www.rfc-editor.org/rfc/rfc2397}
      */
     images?: Record<string, string>;
+    /**
+     * The workbook theme. Specifies the colour scheme and fonts referenced throughout the workbook in
+     * order to create a consistent visual presentation.
+     */
+    theme?: Theme;
+    /**
+     * Optional metadata about this workbook.
+     *
+     * @example
+     * An XLSX file with metadata explicitly marking it as saved by Excel for Macintosh might have
+     * `meta: { app: { name: 'Microsoft Excel', version: '16.0300', variant: 'Macintosh' } }`.
+     *
+     * @example
+     * An XLSX file lacking app metadata but recognized heuristically as being a Google Sheets
+     * export might have `meta: { app: { name: 'Google Sheets', confidence: 0.8 } }`.
+     */
+    meta?: {
+        /**
+         * Information about the application that originated this workbook. Converters should
+         * populate this from file metadata and/or by heuristic detection (in which case they should
+         * set `confidence` to a value less than `1`).
+         */
+        app?: {
+            /**
+             * The plain application name, without platform qualifiers or version suffixes
+             * (e.g. `"Microsoft Excel"`, `"LibreOffice Calc"`).
+             */
+            name?: string;
+            /**
+             * The application version string, if known (e.g. `"16.0300"`).
+             */
+            version?: string;
+            /**
+             * Operating system or other variant of the application (e.g. `"Macintosh"`). Present when
+             * the application name in the source file includes a platform qualifier that was separated
+             * out from {@link name}.
+             */
+            variant?: string;
+            /**
+             * How confident the converter is in the identification. A value of `1` means the app
+             * information came directly from the metadata in the source file. Values less than `1`
+             * indicate heuristic detection, with lower values representing less certainty.
+             *
+             * @defaultValue 1
+             */
+            confidence?: number;
+        };
+    };
 };
 
-export type { AdjustCoordinate, AdjustPoint, AdjustValueHandlePolar, AdjustValueHandleXY, ArcToCommand, BlackWhiteMode, BlipFill, BorderStyle, CalcProps, Cell, CellId, CellOffset, CellRange, CellValueType, CloseCommand, Color, Comment, ConnectionPoint, CubicBezierToCommand, DashStop, DataTable, DefinedName, DmlAngle, Drawing, EmuValue, Extent, External, ExternalWorksheet, Fill, FillPatternStyle, FlipAxis, FontStyleIndex, GeomGuideName, GradientColorStop, GradientLinearFill, GradientPathFill, Graphic, GraphicAnchor, GraphicAnchorAbsolute, GraphicAnchorOneCell, GraphicAnchorTwoCell, GraphicBitmap, GraphicChart, GraphicConnectionShape, GraphicGroup, GraphicShape, GridSize, GroupFill, GuidePoint, HAlign, HyperlinkTextRun, InsetRect, Line, LineAlignment, LineCapType, LineCompoundType, LineEnd, LineEndSize, LineEndType, LineJoinType, LineStyle, LineToCommand, MentionTextRun, MoveToCommand, NoFill, Note, Paragraph, Path, PathCommand, PathFillMode, PathFillType, PatternFill, PatternStyle, Percentage, Person, PivotArea, PivotAreaAxis, PivotAreaReference, PivotAreaType, PivotAutoFilterColumn, PivotCache, PivotCacheBase, PivotCacheConsolidation, PivotCacheConsolidationRangeSet, PivotCacheConsolidationSource, PivotCacheExternal, PivotCacheField, PivotCacheFieldGroup, PivotCacheRangePr, PivotCacheRecord, PivotCacheRecordValue, PivotCacheScenario, PivotCacheSharedItem, PivotCacheSharedItemBool, PivotCacheSharedItemDate, PivotCacheSharedItemErr, PivotCacheSharedItemNil, PivotCacheSharedItemNum, PivotCacheSharedItemStr, PivotCacheSharedItemsMeta, PivotCacheWorksheet, PivotCacheWorksheetSource, PivotCacheWorksheetSourceName, PivotCacheWorksheetSourceRange, PivotCalculatedField, PivotCustomFilterCriterion, PivotCustomFilterOperator, PivotDataField, PivotDataFieldAggregation, PivotField, PivotFieldAxis, PivotFieldItem, PivotFilter, PivotFilterType, PivotGroupBy, PivotItemType, PivotPageField, PivotRowColItem, PivotShowDataAs, PivotSubtotalFunction, PivotTable, PivotTableLocation, PivotTableStyle, PivotTableStyleName, PixelValue, Point, PositiveCoordinate, QuadraticBezierToCommand, RectAlignment, RelativeRect, Shape, ShapeRect, ShapeStyle, SolidFill, Style, Table, TableColumn, TableColumnDataType, TableStyle, TableStyleName, TextAnchoring, TextBody, TextHorzOverflow, TextRun, TextVertOverflow, TextVerticalType, TextWrapping, ThreadedComment, Tile, Underline, VAlign, Workbook, WorkbookView, Worksheet, WorksheetDefaults, WorksheetLayoutScales, WorksheetView, Xfrm, XfrmGroup, integer };
+export type { AdjustCoordinate, AdjustPoint, AdjustValueHandlePolar, AdjustValueHandleXY, ArcToCommand, AutoColor, BlackWhiteMode, BlipFill, BorderStyle, CalcProps, Cell, CellId, CellOffset, CellRange, CellValueType, CloseCommand, Color, ColorTransform, Comment, ConnectionPoint, CubicBezierToCommand, DashStop, DataTable, DefinedName, DmlAngle, Drawing, EmuValue, Extent, External, ExternalDefinedName, ExternalWorksheet, Fill, FillPatternStyle, FlipAxis, FontStyleIndex, GeomGuideName, GradientColorStop, GradientLinearFill, GradientPathFill, Graphic, GraphicAnchor, GraphicAnchorAbsolute, GraphicAnchorOneCell, GraphicAnchorTwoCell, GraphicBitmap, GraphicChart, GraphicConnectionShape, GraphicGroup, GraphicShape, GridSize, GroupFill, GuidePoint, HAlign, HslColor, HyperlinkTextRun, IndexedColor, InsetRect, Line, LineAlignment, LineCapType, LineCompoundType, LineEnd, LineEndSize, LineEndType, LineJoinType, LineStyle, LineToCommand, MentionTextRun, MoveToCommand, NoFill, Note, Paragraph, Path, PathCommand, PathFillMode, PathFillType, PatternFill, PatternStyle, Percentage, Person, PivotArea, PivotAreaAxis, PivotAreaReference, PivotAreaType, PivotAutoFilterColumn, PivotCache, PivotCacheBase, PivotCacheConsolidation, PivotCacheConsolidationRangeSet, PivotCacheConsolidationSource, PivotCacheExternal, PivotCacheField, PivotCacheFieldGroup, PivotCacheRangePr, PivotCacheRecord, PivotCacheRecordValue, PivotCacheScenario, PivotCacheSharedItem, PivotCacheSharedItemBool, PivotCacheSharedItemDate, PivotCacheSharedItemErr, PivotCacheSharedItemNil, PivotCacheSharedItemNum, PivotCacheSharedItemStr, PivotCacheSharedItemsMeta, PivotCacheWorksheet, PivotCacheWorksheetSource, PivotCacheWorksheetSourceName, PivotCacheWorksheetSourceRange, PivotCalculatedField, PivotCustomFilterCriterion, PivotCustomFilterOperator, PivotDataField, PivotDataFieldAggregation, PivotField, PivotFieldAxis, PivotFieldIndex, PivotFieldItem, PivotFilter, PivotFilterType, PivotGroupBy, PivotItemType, PivotPageField, PivotRowColItem, PivotShowDataAs, PivotSubtotalFunction, PivotTable, PivotTableLocation, PivotTableStyle, PivotTableStyleName, PixelValue, Point, PositiveCoordinate, PresetColor, QuadraticBezierToCommand, RectAlignment, RelativeRect, ScRgbColor, SchemeColor, Shape, ShapeRect, ShapeStyle, SolidFill, SrgbColor, Style, SystemColor, Table, TableColumn, TableColumnDataType, TableStyle, TableStyleName, TextAnchoring, TextBody, TextHorzOverflow, TextRun, TextVertOverflow, TextVerticalType, TextWrapping, Theme, ThemeColorScheme, ThemeCustomColor, ThemeFontCollection, ThemeFontScheme, ThemeSupplementalFont, ThemeTextFont, ThreadedComment, Tile, Underline, VAlign, Workbook, WorkbookView, Worksheet, WorksheetDefaults, WorksheetLayoutScales, WorksheetView, Xfrm, XfrmGroup, integer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jsfkit/types",
-  "version": "1.5.0",
+  "version": "2.0.0",
   "description": "TypeScript types for JSF: a JSON spreadsheet representation",
   "license": "MIT",
   "type": "module",