Model workbook-defined (custom) table styles

src/types/pivotTables/PivotTableStyle.ts

@@ -7,14 +7,17 @@ import type { PivotTableStyleName } from './PivotTableStyleName.ts';
  */
 export type PivotTableStyle = {
   /**
-   * The name of the pivot table style (e.g. `"PivotStyleMedium9"`).
+   * The name of the pivot table style: either one of the built-in style names
+   * (e.g. `"PivotStyleMedium9"`, see {@link PivotTableStyleName}) or the name of a
+   * workbook-defined style (see {@link Workbook.tableStyles}).
    *
    * If the value is null or omitted the table should not be rendered with any special styling (note
-   * that this only applies if the style object itself is present).
+   * that this only applies if the style object itself is present). A name that is neither a
+   * built-in style name nor defined in the workbook should be treated the same way.
    *
    * @default null
    */
-  name?: PivotTableStyleName | null;
+  name?: PivotTableStyleName | string | null;
   /**
    * Whether row header formatting should be applied.
    *

src/types/tables/TableStyle.ts

@@ -8,13 +8,16 @@ import type { TableStyleName } from './TableStyleName.ts';
  */
 export type TableStyle = {
   /**
-   * The name of the table style to use with this table.
+   * The name of the table style to use with this table: either one of the built-in style names
+   * ({@link TableStyleName}) or the name of a workbook-defined style (see
+   * {@link Workbook.tableStyles}).
    *
    * If the value is null or omitted the table should not be rendered with any special styling (note
-   * that this only applies if the style object itself is present).
+   * that this only applies if the style object itself is present). A name that is neither a
+   * built-in style name nor defined in the workbook should be treated the same way.
    * @default null
    */
-  name?: TableStyleName | null;
+  name?: TableStyleName | string | null;
   /**
    * Whether row stripe formatting should be applied.
    *

src/types/tables/TableStyleDefinition.ts

@@ -0,0 +1,31 @@
+import type { TableStyleElement } from './TableStyleElement.ts';
+
+/**
+ * A workbook-defined (custom) style for tables and/or pivot tables.
+ *
+ * Definitions live in {@link Workbook.tableStyles} and are referenced by name from
+ * {@link TableStyle.name} and {@link PivotTableStyle.name}, the same way built-in style
+ * names are referenced.
+ *
+ * A definition only describes the regions it lists; regions without an element get no
+ * formatting from the style. Regions overlap (e.g. a header-row cell is also part of the
+ * whole table), in which case the more specific region's formatting wins, property by
+ * property.
+ *
+ * @group Workbooks
+ */
+export type TableStyleDefinition = {
+  /**
+   * The name of the style, as referenced from tables and pivot tables. Must match the
+   * definition's key in {@link Workbook.tableStyles}.
+   */
+  name: string;
+  /**
+   * Whether this style may be applied to pivot tables, regular tables, or both.
+   *
+   * @default "all"
+   */
+  table?: 'table' | 'pivot' | 'all';
+  /** The formatting of each table region that this style defines. */
+  elements?: TableStyleElement[];
+};

src/types/tables/TableStyleElement.ts

@@ -0,0 +1,28 @@
+import type { integer } from '../integer.ts';
+import type { Style } from '../styles/index.ts';
+import type { TableStyleElementType } from './TableStyleElementType.ts';
+
+/**
+ * The formatting of one region of a table or pivot table, within a
+ * {@link TableStyleDefinition}.
+ *
+ * @group Workbooks
+ */
+export type TableStyleElement = {
+  /** The table region this element's formatting applies to. */
+  type: TableStyleElementType;
+  /**
+   * The number of consecutive rows or columns in each stripe band. Only meaningful for the
+   * four stripe element types.
+   *
+   * @default 1
+   */
+  size?: integer;
+  /**
+   * The formatting to overlay on the region's cells. Only the properties present apply;
+   * everything else on a cell is left as-is (differential-format semantics). An element
+   * without a style has no visual effect (a stripe element may still carry a meaningful
+   * {@link size}).
+   */
+  style?: Style;
+};

src/types/tables/TableStyleElementType.ts

@@ -0,0 +1,71 @@
+/**
+ * The region of a table or pivot table that a {@link TableStyleElement} applies to.
+ *
+ * Some regions only occur in tables (e.g. `totalRow`), others only in pivot tables (e.g.
+ * `pageFieldLabels`, the subheading and subtotal regions); a style definition usable for
+ * both kinds of table may include elements for both.
+ *
+ * The `Kind` column below indicates which kind of table each region applies to.
+ *
+ * | Value                    | Kind  | Region
+ * |--------------------------|-------|-----------------------------------------------------------
+ * | `wholeTable`             | both  | The entire table.
+ * | `headerRow`              | both  | The header row.
+ * | `totalRow`               | table | The totals row.
+ * | `firstColumn`            | both  | The first column.
+ * | `lastColumn`             | both  | The last column.
+ * | `firstRowStripe`         | both  | Odd row stripes (the first, third, … band of rows).
+ * | `secondRowStripe`        | both  | Even row stripes (the second, fourth, … band of rows).
+ * | `firstColumnStripe`      | both  | Odd column stripes (the first, third, … band of columns).
+ * | `secondColumnStripe`     | both  | Even column stripes (the second, fourth, … band of columns).
+ * | `firstHeaderCell`        | table | The first cell of the header row.
+ * | `lastHeaderCell`         | table | The last cell of the header row.
+ * | `firstTotalCell`         | table | The first cell of the totals row.
+ * | `lastTotalCell`          | table | The last cell of the totals row.
+ * | `firstSubtotalColumn`    | pivot | First-level subtotal columns.
+ * | `secondSubtotalColumn`   | pivot | Second-level subtotal columns.
+ * | `thirdSubtotalColumn`    | pivot | Third-level subtotal columns.
+ * | `firstSubtotalRow`       | pivot | First-level subtotal rows.
+ * | `secondSubtotalRow`      | pivot | Second-level subtotal rows.
+ * | `thirdSubtotalRow`       | pivot | Third-level subtotal rows.
+ * | `blankRow`               | pivot | Blank rows.
+ * | `firstColumnSubheading`  | pivot | First-level column subheadings.
+ * | `secondColumnSubheading` | pivot | Second-level column subheadings.
+ * | `thirdColumnSubheading`  | pivot | Third-level column subheadings.
+ * | `firstRowSubheading`     | pivot | First-level row subheadings.
+ * | `secondRowSubheading`    | pivot | Second-level row subheadings.
+ * | `thirdRowSubheading`     | pivot | Third-level row subheadings.
+ * | `pageFieldLabels`        | pivot | Page field label cells (the filter-field name cells).
+ * | `pageFieldValues`        | pivot | Page field value cells (the filter-field selection cells).
+ *
+ * @group Workbooks
+ */
+export type TableStyleElementType =
+  'wholeTable' |
+  'headerRow' |
+  'totalRow' |
+  'firstColumn' |
+  'lastColumn' |
+  'firstRowStripe' |
+  'secondRowStripe' |
+  'firstColumnStripe' |
+  'secondColumnStripe' |
+  'firstHeaderCell' |
+  'lastHeaderCell' |
+  'firstTotalCell' |
+  'lastTotalCell' |
+  'firstSubtotalColumn' |
+  'secondSubtotalColumn' |
+  'thirdSubtotalColumn' |
+  'firstSubtotalRow' |
+  'secondSubtotalRow' |
+  'thirdSubtotalRow' |
+  'blankRow' |
+  'firstColumnSubheading' |
+  'secondColumnSubheading' |
+  'thirdColumnSubheading' |
+  'firstRowSubheading' |
+  'secondRowSubheading' |
+  'thirdRowSubheading' |
+  'pageFieldLabels' |
+  'pageFieldValues';

src/types/tables/index.ts

@@ -2,4 +2,7 @@ export type * from './Table.ts';
 export type * from './TableColumn.ts';
 export type * from './TableColumnDataType.ts';
 export type * from './TableStyle.ts';
+export type * from './TableStyleDefinition.ts';
+export type * from './TableStyleElement.ts';
+export type * from './TableStyleElementType.ts';
 export type * from './TableStyleName.ts';

src/types/workbooks/Workbook.ts

@@ -3,7 +3,7 @@ import type { DefinedName } from '../DefinedName.ts';
 import type { External } from '../External.ts';
 import type { NamedStyle } from '../styles/index.ts';
 import type { Style } from '../styles/index.ts';
-import type { Table } from '../tables/index.ts';
+import type { Table, TableStyleDefinition } from '../tables/index.ts';
 import type { Theme } from '../themes/index.ts';
 import type { PivotTable } from '../pivotTables/index.ts';
 import type { Worksheet } from '../worksheets/index.ts';
@@ -33,6 +33,14 @@ export type Workbook = {
   styles?: Style[];
   /** Named cell style definitions (e.g. "Normal", "Heading 1"), keyed by style name. */
   namedStyles?: Record<string, NamedStyle>;
+  /**
+   * Workbook-defined (custom) table and pivot table style definitions, keyed by style name.
+   *
+   * Tables and pivot tables reference these definitions by name, through
+   * {@link TableStyle.name} and {@link PivotTableStyle.name}, the same way they reference
+   * the built-in style names.
+   */
+  tableStyles?: Record<string, TableStyleDefinition>;
   /** External cells referenced by the workbook. An external cell is a cell in another workbook. */
   externals?: External[];
   /**