@shbernal/ts-xlsx 2.1.0 → 3.1.0

package/dist/core/style.d.ts

@@ -1,7 +1,9 @@
+import { type ClonePlan } from './clone.ts';
+import { type AssertNever, NAMED_STYLE_ID } from './internal.ts';
 /** 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>;
+export declare const isNamedUnderlineStyle: (value: string) => value is "double" | "doubleAccounting" | "none" | "single" | "singleAccounting";
 /** A colour, expressed as an ARGB hex string (`"FF0000FF"`) or an indexed theme colour. */
 export interface Color {
     /** 8-digit ARGB hex, uppercase, no leading `#`. */
@@ -35,13 +37,37 @@ export interface Color {
  */
 export declare function parseArgb(value: string): string | undefined;
 /**
- * Fill pattern kinds, as OOXML's `ST_PatternType` enumerates them. `none` is the
+ * Fill pattern kinds, in the order 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.
+ *
+ * The order is load-bearing rather than cosmetic, which is why it is stated twice over -- here, and
+ * in {@link FILL_PATTERNS_IN_SCHEMA_ORDER}, tied together by a proof. BIFF12 stores a pattern as its
+ * *index* into this enumeration, so the binary codec needs the sequence as a value; the doc above
+ * this type used to claim schema order while the union put `gray125` and `gray0625` at positions 2
+ * and 6, where the schema puts them last, and the binary codec carried a third copy that was right.
+ */
+export type FillPatternType = 'none' | 'solid' | 'mediumGray' | 'darkGray' | 'lightGray' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis' | 'gray125' | 'gray0625';
+/**
+ * Every {@link FillPatternType}, in `ST_PatternType` order, which is also the order BIFF12's `fls`
+ * field indexes: `fls` 1 is `solid`, 2 is `mediumGray`, and so on. Index 0 is `none`, which the
+ * model spells as no fill at all rather than as a pattern.
+ *
+ * One list, consulted by the guard below and by `io/xlsb/read-styles.ts`. It replaced three
+ * hand-maintained copies of one enumeration -- the union, the guard's own table, and the binary
+ * codec's index array -- of which only the first two were checked against each other, so adding a
+ * pattern forced the guard to be updated and let the binary codec silently drop it.
+ */
+export declare const FILL_PATTERNS_IN_SCHEMA_ORDER: readonly ["none", "solid", "mediumGray", "darkGray", "lightGray", "darkHorizontal", "darkVertical", "darkDown", "darkUp", "darkGrid", "darkTrellis", "lightHorizontal", "lightVertical", "lightDown", "lightUp", "lightGrid", "lightTrellis", "gray125", "gray0625"];
+/**
+ * The two halves of the proof {@link FILL_PATTERNS_IN_SCHEMA_ORDER} owes, since a list -- unlike the
+ * `Record` shape every other token guard here is built from -- can name fewer members than its union
+ * without the compiler minding. `satisfies` above covers "no invented name"; this covers "no
+ * omission".
  */
-export type FillPatternType = 'none' | 'solid' | 'gray125' | 'darkGray' | 'mediumGray' | 'lightGray' | 'gray0625' | 'darkHorizontal' | 'darkVertical' | 'darkDown' | 'darkUp' | 'darkGrid' | 'darkTrellis' | 'lightHorizontal' | 'lightVertical' | 'lightDown' | 'lightUp' | 'lightGrid' | 'lightTrellis';
+export type EveryFillPatternIsOrdered = AssertNever<Exclude<FillPatternType, (typeof FILL_PATTERNS_IN_SCHEMA_ORDER)[number]>>;
 /** Narrow a raw `<patternFill patternType>` token to a known {@link FillPatternType}. */
-export declare function isFillPatternType(value: string): value is FillPatternType;
+export declare const 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
@@ -78,13 +104,25 @@ export interface GradientFill {
 }
 /** A cell/row background fill: a flat pattern or a colour gradient. */
 export type Fill = PatternFill | GradientFill;
+declare const GRADIENT_STOP_CLONE: ClonePlan<GradientStop>;
+/** The proof that {@link GRADIENT_STOP_CLONE} names every field of a gradient stop. */
+export type EveryGradientStopFieldIsCloned = AssertNever<Exclude<keyof Required<GradientStop>, keyof typeof GRADIENT_STOP_CLONE>>;
+declare const PATTERN_FILL_CLONE: ClonePlan<PatternFill>;
+/** The proof that {@link PATTERN_FILL_CLONE} names every field of a pattern fill. */
+export type EveryPatternFillFieldIsCloned = AssertNever<Exclude<keyof Required<PatternFill>, keyof typeof PATTERN_FILL_CLONE>>;
+declare const GRADIENT_FILL_CLONE: ClonePlan<GradientFill>;
+/** The proof that {@link GRADIENT_FILL_CLONE} names every field of a gradient fill. */
+export type EveryGradientFillFieldIsCloned = AssertNever<Exclude<keyof Required<GradientFill>, keyof typeof GRADIENT_FILL_CLONE>>;
+/** A defensive deep copy of a fill, whichever of the two shapes it is. The union is dispatched on
+ * `type` because the two halves share no field beyond it, so one plan could not describe both. */
+export declare function cloneFill(fill: Fill): Fill;
 /**
  * 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;
+export declare const 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;
@@ -105,15 +143,23 @@ export interface Border {
     readonly diagonalUp?: boolean;
     readonly diagonalDown?: boolean;
 }
+declare const BORDER_EDGE_CLONE: ClonePlan<BorderEdge>;
+/** The proof that {@link BORDER_EDGE_CLONE} names every field of a border edge. */
+export type EveryBorderEdgeFieldIsCloned = AssertNever<Exclude<keyof Required<BorderEdge>, keyof typeof BORDER_EDGE_CLONE>>;
+declare const BORDER_CLONE: ClonePlan<Border>;
+/** The proof that {@link BORDER_CLONE} names every side of a border. */
+export type EveryBorderFieldIsCloned = AssertNever<Exclude<keyof Required<Border>, keyof typeof BORDER_CLONE>>;
+/** A defensive deep copy of a border, each present edge and its colour included. */
+export declare function cloneBorder(border: Border): Border;
 /** 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;
+export declare const 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;
+export declare const 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
@@ -132,17 +178,22 @@ export interface Font {
     readonly outline?: boolean;
     readonly vertAlign?: FontVerticalAlignment;
 }
+declare const FONT_CLONE: ClonePlan<Font>;
+/** The proof that {@link FONT_CLONE} names every facet of a font. */
+export type EveryFontFieldIsCloned = AssertNever<Exclude<keyof Required<Font>, keyof typeof FONT_CLONE>>;
+/** A defensive deep copy of a font, its nested colour included. */
+export declare function cloneFont(font: Font): Font;
 /** 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;
+export declare const 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;
+export declare const 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, so a cell that never enabled
@@ -158,6 +209,53 @@ export interface Alignment {
     readonly shrinkToFit?: boolean;
     readonly readingOrder?: number;
 }
+/**
+ * How one `<alignment>` facet encodes: which model key it is, what kind of value it carries, and the
+ * value that means "default", which the writer omits and the reader drops.
+ *
+ * Format-blind on purpose. `Alignment` is a core type and the layering gate forbids core importing a
+ * serialisation, so the table states what a facet *is* and each codec supplies the reading and the
+ * writing off the `kind`. That is where {@link SHEET_PROTECTION_FLAGS} sits and how it is consumed,
+ * and it is the shape the BIFF12 codec drives off too: `io/xlsb/read-styles.ts` walks this list and
+ * looks each facet up in a `Record` keyed by {@link Alignment}, so the bit layout stays a BIFF12 fact
+ * in the BIFF12 codec while the *set* of facets is decided here, once, for both. (That sentence used
+ * to read "if alignment ever reaches it". Alignment had reached it; the comment had not noticed, and
+ * the binary reader was restating all seven facets and their default-omission rules by hand.)
+ *
+ * The OOXML attribute name is the model key for all seven facets, so it is not restated here: a
+ * second list that is always identical is a second list to keep in step. A future facet whose
+ * attribute differs from its key is the one that would have to add the field.
+ */
+export type AlignmentFacet = {
+    readonly key: 'horizontal' | 'vertical';
+    readonly kind: 'token';
+    /** The enumeration guard, and what to call it in the error when a value fails it. */
+    readonly isValid: (value: string) => boolean;
+    readonly label: string;
+    /** The token that means the OOXML default, expressed by omitting the attribute. */
+    readonly omit?: string;
+} | {
+    readonly key: 'textRotation' | 'indent' | 'readingOrder';
+    readonly kind: 'number';
+} | {
+    readonly key: 'wrapText' | 'shrinkToFit';
+    readonly kind: 'flag';
+};
+/**
+ * The seven `<alignment>` facets, declared once. Both directions key off this list, so a facet
+ * written but not read (it survives a re-write and vanishes on load) or read but not written (the
+ * reverse) is no longer something a reviewer has to notice: {@link EveryAlignmentFacetIsDeclared}
+ * makes a facet added to {@link Alignment} and forgotten here a compile error.
+ *
+ * In ECMA-376 CT_CellAlignment order, which is the order the writer emits.
+ */
+export declare const ALIGNMENT_FACETS: readonly AlignmentFacet[];
+/**
+ * Compile-time proof that {@link ALIGNMENT_FACETS} covers every {@link Alignment} facet. A facet
+ * added to the type without a table entry resolves this to that facet's name, which does not satisfy
+ * `never`, so the error names what is missing.
+ */
+export type EveryAlignmentFacetIsDeclared = AssertNever<Exclude<keyof Alignment, (typeof ALIGNMENT_FACETS)[number]['key']>>;
 /**
  * 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
@@ -190,6 +288,32 @@ export interface CellStyle {
 }
 /** The names of the {@link CellStyle} facets, for helpers that copy the tuple facet-by-facet. */
 export declare const CELL_STYLE_FACETS: (keyof CellStyle)[];
+/**
+ * Everything a cell's *formatting* is, which is the six {@link CellStyle} facets plus two that only a
+ * cell can carry: the quote-prefix flag and the link to a named cell style.
+ *
+ * The two extras are on the cell's `xf` record exactly as the six are, and are written and read back
+ * exactly as the six are, but they sat outside the tuple, so every copy path driven by the tuple
+ * dropped them: a splice, a `duplicateRow`, or a `dst.model = src.model` turned a leading-apostrophe
+ * text cell back into an unprefixed one. That is the merge-loss the tuple exists to make impossible,
+ * so they join it. Callers that mean "the six shared facets" (a column default, a named style, a
+ * `<dxf>`) still say {@link CellStyle}; callers copying a *cell* say this.
+ */
+export type CellContent = CellStyle & {
+    quotePrefix?: boolean | undefined;
+    [NAMED_STYLE_ID]?: number | undefined;
+};
+/**
+ * The names of every {@link CellContent} facet, the six shared ones first. Helpers that copy a cell's
+ * whole formatting drive off this, so a facet added to either half reaches all of them at once.
+ */
+export declare const CELL_CONTENT_FACETS: (keyof CellContent)[];
+/**
+ * Copy every present facet of a cell's formatting from `source` onto `target`, leaving facets
+ * `source` omits untouched: {@link assignStyleFacets} widened to the two cell-only facets. This is
+ * what a copy of a *cell* uses, so no structural edit can drop one.
+ */
+export declare function assignContentFacets(target: CellContent, source: Readonly<CellContent>): void;
 /**
  * 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
@@ -205,69 +329,4 @@ export declare function assignStyleFacets(target: CellStyle, source: Readonly<Ce
  * the tuple reaches a `<col>` style without anyone remembering to widen a literal.
  */
 export declare function pickStyleFacets(source: Readonly<CellStyle>): CellStyle;
-/**
- * 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, and 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;
-}
+export {};

package/dist/core/style.js

@@ -1,43 +1,64 @@
-const NAMED_UNDERLINE_STYLES = {
+import { tokenSet, tokenSetOf } from '../token-set.js';
+import { cloneWith } from './clone.js';
+import { copyKeyIfPresent } from './containers.js';
+import { NAMED_STYLE_ID } from './internal.js';
+export const isNamedUnderlineStyle = tokenSet({
     none: true,
     single: true,
     double: true,
     singleAccounting: true,
     doubleAccounting: true,
-};
-export function isNamedUnderlineStyle(value) {
-    return Object.hasOwn(NAMED_UNDERLINE_STYLES, value);
-}
+});
 export function parseArgb(value) {
     const hex = value.startsWith('#') ? value.slice(1) : value;
     const argb = hex.length === 6 ? `FF${hex}` : hex;
     return /^[0-9a-fA-F]{8}$/.test(argb) ? argb : undefined;
 }
-const FILL_PATTERN_TYPES = {
-    none: true,
-    solid: true,
-    gray125: true,
-    darkGray: true,
-    mediumGray: true,
-    lightGray: true,
-    gray0625: true,
-    darkHorizontal: true,
-    darkVertical: true,
-    darkDown: true,
-    darkUp: true,
-    darkGrid: true,
-    darkTrellis: true,
-    lightHorizontal: true,
-    lightVertical: true,
-    lightDown: true,
-    lightUp: true,
-    lightGrid: true,
-    lightTrellis: true,
+export const FILL_PATTERNS_IN_SCHEMA_ORDER = [
+    'none',
+    'solid',
+    'mediumGray',
+    'darkGray',
+    'lightGray',
+    'darkHorizontal',
+    'darkVertical',
+    'darkDown',
+    'darkUp',
+    'darkGrid',
+    'darkTrellis',
+    'lightHorizontal',
+    'lightVertical',
+    'lightDown',
+    'lightUp',
+    'lightGrid',
+    'lightTrellis',
+    'gray125',
+    'gray0625',
+];
+export const isFillPatternType = tokenSetOf(FILL_PATTERNS_IN_SCHEMA_ORDER);
+const GRADIENT_STOP_CLONE = { position: 'value', color: 'record' };
+const PATTERN_FILL_CLONE = {
+    type: 'value',
+    pattern: 'value',
+    fgColor: 'record',
+    bgColor: 'record',
 };
-export function isFillPatternType(value) {
-    return Object.hasOwn(FILL_PATTERN_TYPES, value);
+const GRADIENT_FILL_CLONE = {
+    type: 'value',
+    gradient: 'value',
+    degree: 'value',
+    left: 'value',
+    right: 'value',
+    top: 'value',
+    bottom: 'value',
+    stops: (stops) => stops.map((stop) => cloneWith(stop, GRADIENT_STOP_CLONE)),
+};
+export function cloneFill(fill) {
+    return fill.type === 'gradient'
+        ? cloneWith(fill, GRADIENT_FILL_CLONE)
+        : cloneWith(fill, PATTERN_FILL_CLONE);
 }
-const BORDER_STYLES = {
+export const isBorderStyle = tokenSet({
     thin: true,
     medium: true,
     thick: true,
@@ -51,22 +72,44 @@ const BORDER_STYLES = {
     dashDotDot: true,
     mediumDashDotDot: true,
     slantDashDot: true,
+});
+const BORDER_EDGE_CLONE = { style: 'value', color: 'record' };
+const cloneBorderEdge = (edge) => cloneWith(edge, BORDER_EDGE_CLONE);
+const BORDER_CLONE = {
+    left: cloneBorderEdge,
+    right: cloneBorderEdge,
+    top: cloneBorderEdge,
+    bottom: cloneBorderEdge,
+    diagonal: cloneBorderEdge,
+    diagonalUp: 'value',
+    diagonalDown: 'value',
 };
-export function isBorderStyle(value) {
-    return Object.hasOwn(BORDER_STYLES, value);
+export function cloneBorder(border) {
+    return cloneWith(border, BORDER_CLONE);
 }
-const FONT_VERTICAL_ALIGNMENTS = {
+export const isFontVerticalAlignment = tokenSet({
     superscript: true,
     subscript: true,
+});
+export const isFontScheme = tokenSet({ minor: true, major: true, none: true });
+const FONT_CLONE = {
+    name: 'value',
+    size: 'value',
+    family: 'value',
+    scheme: 'value',
+    charset: 'value',
+    color: 'record',
+    bold: 'value',
+    italic: 'value',
+    underline: 'value',
+    strike: 'value',
+    outline: 'value',
+    vertAlign: 'value',
 };
-export function isFontVerticalAlignment(value) {
-    return Object.hasOwn(FONT_VERTICAL_ALIGNMENTS, value);
-}
-const FONT_SCHEMES = { minor: true, major: true, none: true };
-export function isFontScheme(value) {
-    return Object.hasOwn(FONT_SCHEMES, value);
+export function cloneFont(font) {
+    return cloneWith(font, FONT_CLONE);
 }
-const HORIZONTAL_ALIGNMENTS = {
+export const isHorizontalAlignment = tokenSet({
     general: true,
     left: true,
     center: true,
@@ -75,20 +118,29 @@ const HORIZONTAL_ALIGNMENTS = {
     justify: true,
     centerContinuous: true,
     distributed: true,
-};
-export function isHorizontalAlignment(value) {
-    return Object.hasOwn(HORIZONTAL_ALIGNMENTS, value);
-}
-const VERTICAL_ALIGNMENTS = {
+});
+export const isVerticalAlignment = tokenSet({
     top: true,
     center: true,
     bottom: true,
     justify: true,
     distributed: true,
-};
-export function isVerticalAlignment(value) {
-    return Object.hasOwn(VERTICAL_ALIGNMENTS, value);
-}
+});
+export const ALIGNMENT_FACETS = [
+    {
+        key: 'horizontal',
+        kind: 'token',
+        isValid: isHorizontalAlignment,
+        label: 'horizontal alignment',
+        omit: 'general',
+    },
+    { key: 'vertical', kind: 'token', isValid: isVerticalAlignment, label: 'vertical alignment' },
+    { key: 'textRotation', kind: 'number' },
+    { key: 'wrapText', kind: 'flag' },
+    { key: 'indent', kind: 'number' },
+    { key: 'shrinkToFit', kind: 'flag' },
+    { key: 'readingOrder', kind: 'number' },
+];
 const CELL_STYLE_FACET_KEYS = {
     fill: true,
     numFmt: true,
@@ -98,17 +150,24 @@ const CELL_STYLE_FACET_KEYS = {
     protection: true,
 };
 export const CELL_STYLE_FACETS = Object.keys(CELL_STYLE_FACET_KEYS);
+const CELL_CONTENT_ONLY_KEYS = {
+    quotePrefix: true,
+    [NAMED_STYLE_ID]: true,
+};
+export const CELL_CONTENT_FACETS = [
+    ...CELL_STYLE_FACETS,
+    ...Reflect.ownKeys(CELL_CONTENT_ONLY_KEYS),
+];
+export function assignContentFacets(target, source) {
+    for (const facet of CELL_CONTENT_FACETS)
+        copyKeyIfPresent(target, source, facet);
+}
 export function assignStyleFacets(target, source) {
     for (const facet of CELL_STYLE_FACETS)
-        copyFacet(target, source, facet);
+        copyKeyIfPresent(target, source, facet);
 }
 export function pickStyleFacets(source) {
     const facets = {};
     assignStyleFacets(facets, source);
     return facets;
 }
-function copyFacet(target, source, key) {
-    const value = source[key];
-    if (value !== undefined)
-        target[key] = value;
-}

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

@@ -1,4 +1,4 @@
-import type { DifferentialStyle } from './style.ts';
+import type { DifferentialStyle } from './workbook-styles.ts';
 /**
  * The regions a table style can format (`ST_TableStyleType`).
  *

package/dist/core/table-style.js

@@ -1,4 +1,4 @@
-import { AuthoringError } from '../errors.js';
+import { AuthoringError, invalidToken, quoted } from '../errors.js';
 export const TABLE_STYLE_ELEMENT_TYPES = [
     'wholeTable',
     'headerRow',
@@ -46,17 +46,17 @@ export function checkTableStyle(style) {
         if (element === undefined)
             continue;
         if (!isTableStyleElementType(type)) {
-            throw new AuthoringError(`Invalid table style element ${JSON.stringify(type)}: not a value the OOXML enumeration allows`);
+            throw invalidToken('table style element', type);
         }
         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 ` +
+            throw new AuthoringError(`table style element ${quoted(type)} cannot carry a size: band width applies only to ` +
                 `${[...STRIPE_ELEMENT_TYPES].join(', ')}`);
         }
         if (!Number.isInteger(size) || size < 1) {
-            throw new RangeError(`Invalid table style band size ${size}: expected a positive integer`);
+            throw new RangeError(`invalid table style band size ${size}: expected a positive integer`);
         }
     }
 }

package/dist/core/table.d.ts

@@ -1,4 +1,7 @@
 import { type GridRect } from './address.ts';
+import { type ClonePlan } from './clone.ts';
+import { type AxisSplice } from './grid-shift.ts';
+import type { AssertNever } from './internal.ts';
 import type { CellStyle } from './style.ts';
 import type { CellValue } from './value.ts';
 /** A per-column cell format applied to a table's body cells: the facets Excel's table-column style
@@ -57,6 +60,16 @@ export interface TableStyleInfo {
     /** Band the columns (alternating fill). */
     readonly showColumnStripes?: boolean;
 }
+/** Copy a style, keeping only its defined fields off the literal so `exactOptionalPropertyTypes`
+ * never sees a fabricated `key: undefined`: an absent attribute must stay absent across a copy.
+ *
+ * The sentinel name `"None"` (Excel's table-style gallery entry for *no* style) is normalised to an
+ * absent name: OOXML expresses "unstyled" as a `<tableStyleInfo>` with no `name` attribute, so a
+ * literal `name="None"` would reference a style that does not exist and make the file suspect. The
+ * banding flags set alongside it are untouched. */
+declare const STYLE_INFO_CLONE: ClonePlan<TableStyleInfo>;
+/** The proof that {@link STYLE_INFO_CLONE} names every field of the style. */
+export type EveryTableStyleInfoFieldIsCloned = AssertNever<Exclude<keyof Required<TableStyleInfo>, keyof typeof STYLE_INFO_CLONE>>;
 /**
  * OOXML's totals-row function names (`ST_TotalsRowFunction`) to the `SUBTOTAL` first-argument code
  * Excel writes into a materialised totals cell. The `10x` band ignores manually hidden rows, the
@@ -75,7 +88,7 @@ export declare const TOTALS_ROW_SUBTOTAL_CODE: Readonly<Partial<Record<TotalsRow
  */
 export type TotalsRowFunction = 'average' | 'countNums' | 'count' | 'max' | 'min' | 'stdDev' | 'sum' | 'var' | 'custom' | 'none';
 /** Narrow a raw `totalsRowFunction` attribute to a known {@link TotalsRowFunction}. */
-export declare function isTotalsRowFunction(value: string): value is TotalsRowFunction;
+export declare const isTotalsRowFunction: (value: string) => value is TotalsRowFunction;
 /** One column of a table: a header name and its optional totals-row behaviour. */
 export interface TableColumn {
     /** The column's header/display name. Must be unique within the table (case-insensitively):
@@ -158,20 +171,24 @@ export declare class Table {
      */
     addRow(values?: readonly CellValue[]): void;
     /**
-     * Re-pin the table through a row splice: `count` rows removed at the 1-based `start`, then rows
-     * inserted so surviving rows below shift by `delta`. A splice entirely above the table moves its
-     * whole range by `delta`; one landing inside grows or shrinks the data rows to absorb the change;
+     * Re-pin the table through a row splice. A splice entirely above the table moves its whole range
+     * by the splice's `delta`; one landing inside grows or shrinks the data rows to absorb the change;
      * one that deletes the table's every row removes it. Returns `false` when the table no longer has
      * a row to occupy (the caller drops it), `true` when it survives.
      */
-    shiftRows(start: number, count: number, delta: number): boolean;
+    shiftRows(splice: AxisSplice): boolean;
     /**
-     * Re-pin the table through a column splice. A splice entirely to the table's left moves its anchor
-     * by `delta`; one to its right leaves it untouched. A splice landing inside the table's columns is
-     * structural surgery on named columns with no unambiguous answer, so the table's columns are left
-     * as-is (anchor unchanged) rather than fabricated or dropped. Always returns `true`.
+     * Re-pin the table through a column splice, the mirror of {@link shiftRows}. A splice entirely to
+     * the table's left moves its anchor by the splice's `delta`; one to its right leaves it untouched;
+     * one that deletes the table's every column removes it. Returns `false` when the table no longer
+     * has a column to occupy (the caller drops it), `true` when it survives.
+     *
+     * A splice landing *inside* the table's columns is structural surgery on named columns with no
+     * unambiguous answer, so those columns are left as-is rather than fabricated or dropped. Whole-table
+     * deletion is not that case: a table left declared over whatever slid into its place, carrying the
+     * names of columns that no longer exist, is content the writer then emits.
      */
-    shiftColumns(start: number, count: number, delta: number): boolean;
+    shiftColumns(splice: AxisSplice): boolean;
     /**
      * The options that reconstruct this table: the anchor as a single-cell ref (not the derived
      * full range), the columns, and the data-row count with the header/totals flags. Feeding this
@@ -194,3 +211,4 @@ export declare class Table {
     /** The occupied rectangle, for conflict checks such as overlapping merges. */
     get region(): TableRegion;
 }
+export {};