@shbernal/ts-xlsx 1.0.0

package/dist/core/style.d.ts

@@ -0,0 +1,246 @@
+/** Underline can be a plain flag or one of Excel's named underline styles. */
+export type UnderlineStyle = boolean | 'none' | 'single' | 'double' | 'singleAccounting' | 'doubleAccounting';
+/** Narrow a raw `<u val>` token to a named {@link UnderlineStyle} (the non-boolean members). */
+export declare function isNamedUnderlineStyle(value: string): value is Exclude<UnderlineStyle, boolean>;
+/** A colour, expressed as an ARGB hex string (`"FF0000FF"`) or an indexed theme colour. */
+export interface Color {
+    /** 8-digit ARGB hex, uppercase, no leading `#`. */
+    readonly argb?: string;
+    /** Index into the workbook theme's colour scheme. */
+    readonly theme?: number;
+    /** Tint applied to the theme colour, in `[-1, 1]`. */
+    readonly tint?: number;
+    /** Index into the legacy indexed colour palette. In a solid fill, `bgColor` is the
+     *  automatic placeholder `indexed="64"`; the visible colour lives on `fgColor`. */
+    readonly indexed?: number;
+}
+/**
+ * Fill pattern kinds, as OOXML's `ST_PatternType` enumerates them. `none` is the
+ * absence of a fill; `solid` paints the whole cell with the foreground colour (the
+ * common case). The remaining hatch patterns are carried for fidelity on read.
+ */
+export type FillPatternType = 'none' | 'solid' | 'gray125' | 'darkGray' | 'mediumGray' | 'lightGray' | 'gray0625' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis';
+/** Narrow a raw `<patternFill patternType>` token to a known {@link FillPatternType}. */
+export declare function isFillPatternType(value: string): value is FillPatternType;
+/**
+ * A pattern fill. For a `solid` fill the visible colour is the pattern *foreground*
+ * (`fgColor`) — OOXML's counter-intuitive rule — while `bgColor` is the automatic
+ * indexed placeholder.
+ */
+export interface PatternFill {
+    readonly type: 'pattern';
+    readonly pattern: FillPatternType;
+    readonly fgColor?: Color;
+    readonly bgColor?: Color;
+}
+/** A colour stop in a gradient, at a fractional `position` in `[0, 1]` along the gradient axis. */
+export interface GradientStop {
+    readonly position: number;
+    readonly color: Color;
+}
+/**
+ * A gradient fill, as OOXML's `CT_GradientFill`. A `linear` gradient runs at `degree`
+ * degrees across the cell; a `path` gradient radiates from an inner rectangle whose
+ * insets are `left`/`right`/`top`/`bottom` (each a fraction in `[0, 1]`). The `stops`
+ * place colours along the axis; a well-formed gradient names at least two.
+ */
+export interface GradientFill {
+    readonly type: 'gradient';
+    readonly gradient: 'linear' | 'path';
+    /** Rotation of a `linear` gradient, in degrees. Absent (and meaningless) for `path`. */
+    readonly degree?: number;
+    /** Inner-rectangle insets of a `path` gradient, each a fraction in `[0, 1]`. */
+    readonly left?: number;
+    readonly right?: number;
+    readonly top?: number;
+    readonly bottom?: number;
+    readonly stops: readonly GradientStop[];
+}
+/** A cell/row background fill: a flat pattern or a colour gradient. */
+export type Fill = PatternFill | GradientFill;
+/**
+ * Line styles a cell border edge can take, as OOXML's `ST_BorderStyle` enumerates them.
+ * `none` is the absence of an edge and is expressed by omitting the edge, not by this value.
+ */
+export type BorderStyle = 'thin' | 'medium' | 'thick' | 'dashed' | 'dotted' | 'double' | 'hair' | 'mediumDashed' | 'dashDot' | 'mediumDashDot' | 'dashDotDot' | 'mediumDashDotDot' | 'slantDashDot';
+/** Narrow a raw border-edge `style` attribute to a known {@link BorderStyle}. */
+export declare function isBorderStyle(value: string): value is BorderStyle;
+/** One edge of a cell border: its line style, and optionally the line colour. */
+export interface BorderEdge {
+    readonly style: BorderStyle;
+    readonly color?: Color;
+}
+/**
+ * A cell's border. Each of the four sides plus the diagonal is an independent edge; an
+ * absent edge means that side has no border (it is not rendered), so a cell bordered on
+ * one side never implies the other three. `diagonalUp`/`diagonalDown` select which way a
+ * present diagonal edge runs.
+ */
+export interface Border {
+    readonly left?: BorderEdge;
+    readonly right?: BorderEdge;
+    readonly top?: BorderEdge;
+    readonly bottom?: BorderEdge;
+    readonly diagonal?: BorderEdge;
+    readonly diagonalUp?: boolean;
+    readonly diagonalDown?: boolean;
+}
+/** Vertical alignment of a font relative to the baseline (super/subscript). */
+export type FontVerticalAlignment = 'superscript' | 'subscript';
+/** Narrow a raw `<vertAlign val>` token to a known {@link FontVerticalAlignment}. */
+export declare function isFontVerticalAlignment(value: string): value is FontVerticalAlignment;
+/** The theme-font role a `<scheme val>` names — `"minor"`/`"major"` bind the font to whichever
+ * face the workbook theme assigns that role, `"none"` leaves it a literal, unbound face. */
+export type FontScheme = 'minor' | 'major' | 'none';
+/** Narrow a raw `<scheme val>` token to a known {@link FontScheme}. */
+export declare function isFontScheme(value: string): value is FontScheme;
+/** A font, as it applies to a cell or a single rich-text run. Every facet is optional and
+ * independent, like {@link Border}/{@link Alignment}/{@link Protection} — a font sets only the
+ * facets it overrides (Excel's own default font backs the rest), so no consumer ever holds every
+ * field populated at once. */
+export interface Font {
+    readonly name?: string;
+    readonly size?: number;
+    readonly family?: number;
+    readonly scheme?: FontScheme;
+    readonly charset?: number;
+    readonly color?: Color;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    readonly underline?: UnderlineStyle;
+    readonly strike?: boolean;
+    readonly outline?: boolean;
+    readonly vertAlign?: FontVerticalAlignment;
+}
+/** How a cell's content sits horizontally within its bounds, as OOXML's `ST_HorizontalAlignment`
+ *  enumerates it. `general` is the type-dependent default (text left, numbers right) and reads
+ *  back as no explicit horizontal alignment. */
+export type HorizontalAlignment = 'general' | 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
+/** Narrow a raw `<alignment horizontal>` token to a known {@link HorizontalAlignment}. */
+export declare function isHorizontalAlignment(value: string): value is HorizontalAlignment;
+/** How a cell's content sits vertically within its bounds, as OOXML's `ST_VerticalAlignment`
+ *  enumerates it. */
+export type VerticalAlignment = 'top' | 'center' | 'bottom' | 'justify' | 'distributed';
+/** Narrow a raw `<alignment vertical>` token to a known {@link VerticalAlignment}. */
+export declare function isVerticalAlignment(value: string): value is VerticalAlignment;
+/**
+ * A cell's alignment. Every facet is optional and independent; an absent facet means the cell
+ * takes Excel's default for it. The boolean flags default to off — a cell that never enabled
+ * `wrapText`/`shrinkToFit` must never read back with them on. `textRotation` is in degrees
+ * (0–180, where 91–180 encodes -1° to -90°); `indent` is a non-negative indent level.
+ */
+export interface Alignment {
+    readonly horizontal?: HorizontalAlignment;
+    readonly vertical?: VerticalAlignment;
+    readonly textRotation?: number;
+    readonly wrapText?: boolean;
+    readonly indent?: number;
+    readonly shrinkToFit?: boolean;
+    readonly readingOrder?: number;
+}
+/**
+ * A cell's protection state, enforced only when the worksheet itself is protected — the flags
+ * do nothing on an unprotected sheet. `locked` defaults to TRUE in OOXML (every cell is locked
+ * unless told otherwise), so the meaningful, information-carrying state is an explicitly
+ * *unlocked* cell (`locked: false`); marking a cell locked merely restates the default and
+ * records nothing. `hidden` (defaults false) hides the cell's formula from the formula bar of a
+ * protected sheet. A cell that never set either flag reads back with neither.
+ */
+export interface Protection {
+    readonly locked?: boolean;
+    readonly hidden?: boolean;
+}
+/**
+ * The six direct-format facets a cell can carry — its fill, number format, font, border, alignment,
+ * and protection. Every facet is optional and independent: a cell sets only the facets it overrides
+ * and inherits the rest. This one tuple is the unit of style throughout the library, so the
+ * interfaces that carry a cell's formatting compose it rather than re-listing the fields — a column,
+ * table column, or named style whose facets *default* the cells that leave them unset (see
+ * {@link ColumnProperties}, {@link NamedCellStyle}), and a cell's own resolved format. Because they
+ * share this type, "add a facet" is a single edit here and the compiler enforces that no read/write
+ * path silently drops one — the round-trip symmetry the merge-loss contract depends on.
+ */
+export interface CellStyle {
+    fill?: Fill | undefined;
+    numFmt?: string | undefined;
+    font?: Font | undefined;
+    border?: Border | undefined;
+    alignment?: Alignment | undefined;
+    protection?: Protection | undefined;
+}
+/** The names of the {@link CellStyle} facets, for helpers that copy the tuple facet-by-facet. */
+export declare const CELL_STYLE_FACETS: (keyof CellStyle)[];
+/**
+ * Copy each present facet of `source` onto `target`, leaving facets `source` omits untouched — the
+ * plain-record counterpart to a cell's `applyCellStyle`, for the {@link CellStyle}-shaped targets a
+ * `Cell`'s setters don't reach (a column's cell-defaults, a named style being assembled on read).
+ * Driven by {@link CELL_STYLE_FACETS}, so a facet added to the tuple reaches these paths the moment
+ * it joins — the same single-point-of-change the cell path gets.
+ */
+export declare function assignStyleFacets(target: CellStyle, source: Readonly<CellStyle>): void;
+/**
+ * A named cell style — the OOXML `cellStyleXfs`/`cellStyles` layer. A spreadsheet applies a built-in
+ * or custom style (e.g. "Normal", "Accent1") whose visual facets live in this shared, named layer
+ * rather than on each cell's direct format; a cell links to it and inherits any facet the direct
+ * format leaves unset. The facets are a cell's own (see {@link CellStyle}); `name` is the style's
+ * display name and `builtinId` its Excel gallery index when it is a built-in style.
+ */
+export type NamedCellStyle = Readonly<CellStyle> & {
+    readonly name?: string;
+    readonly builtinId?: number;
+};
+/**
+ * A differential style (OOXML CT_Dxf): formatting laid *over* whatever a cell already carries. Only
+ * the facets present override; the rest of the cell's own style shows through. It carries the subset
+ * of the cell-style facets (see {@link CellStyle}) a `<dxf>` can express — font, number format, fill,
+ * and border.
+ *
+ * Differential styles live in one workbook-level table (`<dxfs>`) that several features index into:
+ * a conditional-formatting rule's highlight format, and a table style's per-element formatting
+ * (`<tableStyleElement dxfId="…">`). They are interned and shared, so two features asking for the
+ * same formatting land on one entry.
+ *
+ * Not every facet reaches every consumer. As a **table style element**, Excel applies only the font,
+ * fill, and border: its own object model exposes `Font`, `Interior`, and `Borders` on a table style
+ * element and nothing for a number format, so a `numFmt` set here is carried faithfully through a
+ * round-trip but has no visible effect. The type is left whole rather than split, because the same
+ * value is legitimately reused across both consumers and narrowing it would only move the surprise.
+ */
+export type DifferentialStyle = Pick<CellStyle, 'font' | 'numFmt' | 'fill' | 'border'>;
+/**
+ * The `<tableStyles>` block of a styles part: the custom table/pivot style definitions a file
+ * declares, and the two gallery names it nominates as the default for a new table and a new pivot.
+ *
+ * Each entry of {@link styles} is one `<tableStyle>…</tableStyle>` fragment kept verbatim, for the
+ * same reason a `<dxf>` is: a `tableStyleElement`'s `dxfId` indexes the differential-style table,
+ * which the writer re-emits **at its original indices**, so the references stay valid without
+ * reparsing anything. That index-stability is load-bearing — renumbering the dxf table would
+ * silently re-point every preserved table style at a different format.
+ *
+ * The two default names are ordinary strings, not fragments: they are re-escaped on write, so they
+ * are held decoded.
+ */
+export interface TableStyleTable {
+    readonly styles: readonly string[];
+    readonly defaultTableStyle?: string | undefined;
+    readonly defaultPivotStyle?: string | undefined;
+    /**
+     * The namespace prefixes the verbatim {@link styles} fragments use, mapped to their URI and to
+     * whether the source marked the prefix ignorable (`mc:Ignorable`).
+     *
+     * Carrying a fragment verbatim carries its *prefixes* too. Excel stamps a revision id
+     * (`xr9:uid="{…}"`) on every `<tableStyle>` it writes, so a fragment re-emitted under a
+     * `<styleSheet>` that declares only the default namespace is not namespace-well-formed — no
+     * consumer can parse the part at all, which is a far louder failure than the dropped table style
+     * this preservation exists to prevent. The writer re-declares each prefix on `<styleSheet>` and
+     * re-states the ignorable ones, exactly as the source did.
+     */
+    readonly namespaces?: readonly TableStyleNamespace[];
+}
+/** One namespace declaration a preserved `<tableStyle>` fragment depends on. */
+export interface TableStyleNamespace {
+    readonly prefix: string;
+    readonly uri: string;
+    /** Whether the source listed this prefix in the stylesheet's `mc:Ignorable`. */
+    readonly ignorable: boolean;
+}

package/dist/core/style.js

@@ -0,0 +1,125 @@
+// Cell style primitives.
+//
+// Styles are a large surface in OOXML (fonts, fills, borders, alignment, number
+// formats, protection). The rewrite grows them corpus-first; this module models the
+// facets landed so far — colours, fills, borders, fonts, alignment, and protection.
+const NAMED_UNDERLINE_STYLES = new Set([
+    'none',
+    'single',
+    'double',
+    'singleAccounting',
+    'doubleAccounting',
+]);
+/** Narrow a raw `<u val>` token to a named {@link UnderlineStyle} (the non-boolean members). */
+export function isNamedUnderlineStyle(value) {
+    return NAMED_UNDERLINE_STYLES.has(value);
+}
+const FILL_PATTERN_TYPES = new Set([
+    'none',
+    'solid',
+    'gray125',
+    'darkGray',
+    'mediumGray',
+    'lightGray',
+    'gray0625',
+    'darkHorizontal',
+    'darkVertical',
+    'darkDown',
+    'darkUp',
+    'darkGrid',
+    'darkTrellis',
+    'lightHorizontal',
+    'lightVertical',
+    'lightDown',
+    'lightUp',
+    'lightGrid',
+    'lightTrellis',
+]);
+/** Narrow a raw `<patternFill patternType>` token to a known {@link FillPatternType}. */
+export function isFillPatternType(value) {
+    return FILL_PATTERN_TYPES.has(value);
+}
+const BORDER_STYLES = new Set([
+    'thin',
+    'medium',
+    'thick',
+    'dashed',
+    'dotted',
+    'double',
+    'hair',
+    'mediumDashed',
+    'dashDot',
+    'mediumDashDot',
+    'dashDotDot',
+    'mediumDashDotDot',
+    'slantDashDot',
+]);
+/** Narrow a raw border-edge `style` attribute to a known {@link BorderStyle}. */
+export function isBorderStyle(value) {
+    return BORDER_STYLES.has(value);
+}
+/** Narrow a raw `<vertAlign val>` token to a known {@link FontVerticalAlignment}. */
+export function isFontVerticalAlignment(value) {
+    return value === 'superscript' || value === 'subscript';
+}
+/** Narrow a raw `<scheme val>` token to a known {@link FontScheme}. */
+export function isFontScheme(value) {
+    return value === 'minor' || value === 'major' || value === 'none';
+}
+const HORIZONTAL_ALIGNMENTS = new Set([
+    'general',
+    'left',
+    'center',
+    'right',
+    'fill',
+    'justify',
+    'centerContinuous',
+    'distributed',
+]);
+/** Narrow a raw `<alignment horizontal>` token to a known {@link HorizontalAlignment}. */
+export function isHorizontalAlignment(value) {
+    return HORIZONTAL_ALIGNMENTS.has(value);
+}
+const VERTICAL_ALIGNMENTS = new Set([
+    'top',
+    'center',
+    'bottom',
+    'justify',
+    'distributed',
+]);
+/** Narrow a raw `<alignment vertical>` token to a known {@link VerticalAlignment}. */
+export function isVerticalAlignment(value) {
+    return VERTICAL_ALIGNMENTS.has(value);
+}
+// One entry per facet, as a Record rather than a bare list so the compiler rejects it the moment a
+// facet is added to CellStyle and forgotten here — which would otherwise let the facet-list-driven
+// copies below (assignStyleFacets) silently skip the new facet, a merge-loss.
+const CELL_STYLE_FACET_KEYS = {
+    fill: true,
+    numFmt: true,
+    font: true,
+    border: true,
+    alignment: true,
+    protection: true,
+};
+/** The names of the {@link CellStyle} facets, for helpers that copy the tuple facet-by-facet. */
+export const CELL_STYLE_FACETS = Object.keys(CELL_STYLE_FACET_KEYS);
+/**
+ * Copy each present facet of `source` onto `target`, leaving facets `source` omits untouched — the
+ * plain-record counterpart to a cell's `applyCellStyle`, for the {@link CellStyle}-shaped targets a
+ * `Cell`'s setters don't reach (a column's cell-defaults, a named style being assembled on read).
+ * Driven by {@link CELL_STYLE_FACETS}, so a facet added to the tuple reaches these paths the moment
+ * it joins — the same single-point-of-change the cell path gets.
+ */
+export function assignStyleFacets(target, source) {
+    for (const facet of CELL_STYLE_FACETS)
+        copyFacet(target, source, facet);
+}
+// A single facet key at a time, so the write's key type is one member (not the whole union) and
+// `target[key] = source[key]` typechecks without a cast — the correlated-key access TS can't verify
+// when the key is a union.
+function copyFacet(target, source, key) {
+    const value = source[key];
+    if (value !== undefined)
+        target[key] = value;
+}

package/dist/core/table-style.d.ts

@@ -0,0 +1,67 @@
+import type { DifferentialStyle } from './style.ts';
+/**
+ * The regions a table style can format (`ST_TableStyleType`).
+ *
+ * The first thirteen apply to a **table**; the rest style a **pivot table**, which has regions a
+ * table does not have (subtotal rows, page-field labels, subheadings). Both live in the same
+ * enumeration and the same `<tableStyle>` element — what decides which regions a consumer honours is
+ * the style's own `table`/`pivot` flags, not the element names — so the type carries all of them
+ * rather than splitting into two enumerations that a caller would have to choose between up front.
+ */
+export declare const TABLE_STYLE_ELEMENT_TYPES: readonly ["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"];
+/** One region of a table or pivot that a table style can format. */
+export type TableStyleElementType = (typeof TABLE_STYLE_ELEMENT_TYPES)[number];
+/** The four element types banded across several rows or columns — the only ones {@link TableStyleElement.size} means anything on. */
+export declare const STRIPE_ELEMENT_TYPES: ReadonlySet<TableStyleElementType>;
+export declare function isTableStyleElementType(value: string): value is TableStyleElementType;
+/**
+ * How one region of a table is formatted: a {@link DifferentialStyle} laid over whatever the cells
+ * already carry, plus — for a stripe — how many rows or columns wide one band is.
+ *
+ * A `numFmt` here is carried faithfully but has no visible effect: Excel's own table-style element
+ * exposes a font, an interior and borders, and nothing for a number format. See
+ * {@link DifferentialStyle}.
+ */
+export interface TableStyleElement extends DifferentialStyle {
+    /**
+     * The band width, in rows or columns, for a striped element — `2` makes each band two rows deep.
+     * Defaults to 1.
+     *
+     * Meaningful **only** on the four stripe types ({@link STRIPE_ELEMENT_TYPES}); ECMA-376 says so and
+     * Excel ignores it elsewhere. Setting it on any other element is rejected rather than silently
+     * dropped: a caller who wrote it meant something by it, and a value that vanishes into a file that
+     * still opens cleanly is the kind of bug nobody finds.
+     */
+    readonly size?: number | undefined;
+}
+/**
+ * A custom table style, ready to be registered on a workbook and named by a table's
+ * {@link TableStyleInfo.name}.
+ *
+ * Elements are applied in the order ECMA-376 fixes, not the order they are written here: whole table,
+ * then the column stripes, then the row stripes, then last/first column, header row, total row, and
+ * the four corner cells. So a row stripe wins over a column stripe, and both win over the whole-table
+ * formatting — worth knowing when a stripe colour appears not to take.
+ */
+export interface TableStyle {
+    /** The name a table references, and the name Excel shows in its style gallery. */
+    readonly name: string;
+    /** The regions this style formats. An element left out is not styled by it. */
+    readonly elements: Readonly<Partial<Record<TableStyleElementType, TableStyleElement>>>;
+    /** Whether the style is offered for tables. Defaults to true. */
+    readonly table?: boolean | undefined;
+    /** Whether the style is offered for pivot tables. Defaults to true. */
+    readonly pivot?: boolean | undefined;
+}
+/**
+ * Reject a table style the writer would otherwise emit as valid-but-inert XML.
+ *
+ * Both failures here are of the same kind: Excel accepts the file and quietly does nothing with the
+ * part the caller cared about. An empty name means no table can ever reference the style, and a
+ * `size` outside a stripe is ignored — neither shows up as a repair prompt or a schema error, so the
+ * only place to catch them is the call that made them.
+ *
+ * @throws {@link AuthoringError} if the name is empty, or a non-stripe element carries a `size`, or a `size` is not
+ *   a positive integer.
+ */
+export declare function checkTableStyle(style: TableStyle): void;

package/dist/core/table-style.js

@@ -0,0 +1,90 @@
+// A custom table style: the named, reusable look a table (or a pivot) applies to itself by name.
+//
+// A table style is a list of *elements*, each naming one region of the table — the whole table, the
+// header row, the first row stripe — and the differential formatting to lay over it. Excel's built-in
+// gallery ("TableStyleMedium2" and its sixty siblings) is exactly this shape; a workbook that declares
+// its own joins the gallery for that file, and a table reaches it by name through
+// `TableStyleInfo.name`.
+import { AuthoringError } from "../errors.js";
+/**
+ * The regions a table style can format (`ST_TableStyleType`).
+ *
+ * The first thirteen apply to a **table**; the rest style a **pivot table**, which has regions a
+ * table does not have (subtotal rows, page-field labels, subheadings). Both live in the same
+ * enumeration and the same `<tableStyle>` element — what decides which regions a consumer honours is
+ * the style's own `table`/`pivot` flags, not the element names — so the type carries all of them
+ * rather than splitting into two enumerations that a caller would have to choose between up front.
+ */
+export const TABLE_STYLE_ELEMENT_TYPES = [
+    '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',
+];
+/** The four element types banded across several rows or columns — the only ones {@link TableStyleElement.size} means anything on. */
+export const STRIPE_ELEMENT_TYPES = new Set([
+    'firstRowStripe',
+    'secondRowStripe',
+    'firstColumnStripe',
+    'secondColumnStripe',
+]);
+export function isTableStyleElementType(value) {
+    return TABLE_STYLE_ELEMENT_TYPES.includes(value);
+}
+/**
+ * Reject a table style the writer would otherwise emit as valid-but-inert XML.
+ *
+ * Both failures here are of the same kind: Excel accepts the file and quietly does nothing with the
+ * part the caller cared about. An empty name means no table can ever reference the style, and a
+ * `size` outside a stripe is ignored — neither shows up as a repair prompt or a schema error, so the
+ * only place to catch them is the call that made them.
+ *
+ * @throws {@link AuthoringError} if the name is empty, or a non-stripe element carries a `size`, or a `size` is not
+ *   a positive integer.
+ */
+export function checkTableStyle(style) {
+    if (style.name === '') {
+        throw new AuthoringError('a table style needs a name: a table references its style by name');
+    }
+    for (const [type, element] of Object.entries(style.elements)) {
+        if (element === undefined)
+            continue;
+        if (!isTableStyleElementType(type)) {
+            throw new AuthoringError(`Invalid table style element ${JSON.stringify(type)}: not a value the OOXML enumeration allows`);
+        }
+        const { size } = element;
+        if (size === undefined)
+            continue;
+        if (!STRIPE_ELEMENT_TYPES.has(type)) {
+            throw new AuthoringError(`table style element "${type}" cannot carry a size: band width applies only to ` +
+                `${[...STRIPE_ELEMENT_TYPES].join(', ')}`);
+        }
+        if (!Number.isInteger(size) || size < 1) {
+            throw new AuthoringError(`Invalid table style band size ${size}: expected a positive integer`);
+        }
+    }
+}