@shbernal/ts-xlsx 2.1.0 → 3.1.0

package/dist/core/grid-shift.d.ts

@@ -1,19 +1,68 @@
+import { type CellPosition, type GridRect } from './address.ts';
 /**
- * Where a 1-based coordinate on `axis` lands after `count` lines are deleted at `start` and the
- * replacement lines shift what follows by `delta`: before the edit it stays put, at or after the
- * edited span it shifts, and inside a deleted span it clamps to the cut line. The clamp is the best
- * effort for a geometry straddling the cut; a caller that must instead *drop* what a delete swallowed
- * whole tests {@link isDeletedSpan} first.
+ * One structural edit to an axis: `count` lines removed at the 1-based `start`, with everything
+ * after the removed span moved by `delta`. `delta` is the *net* movement, so a pure insert of two
+ * lines is `{count: 0, delta: 2}` and a pure delete of three is `{count: 3, delta: -3}`.
+ *
+ * The four travel as one value because they describe one edit, and because three of them are
+ * `number`: passed positionally, two adjacent ones transposed compiles, typechecks, lints, and moves
+ * a merge, a dropdown, a highlight or a comment anchor onto cells the author never chose -- silently,
+ * since nothing about the resulting file is malformed. A named field cannot be transposed.
+ */
+export interface AxisSplice {
+    /** The axis the lines were spliced on. */
+    readonly axis: 'row' | 'col';
+    /** 1-based first line of the removed span. */
+    readonly start: number;
+    /** How many lines were removed. */
+    readonly count: number;
+    /** Net movement of every line after the removed span. */
+    readonly delta: number;
+}
+/**
+ * Where a 1-based coordinate on the spliced axis lands: before the edit it stays put, at or after
+ * the edited span it shifts by `delta`, and inside a deleted span it clamps to the cut line. The
+ * clamp is the best effort for a geometry straddling the cut; a caller that must instead *drop*
+ * what a delete swallowed whole tests {@link isDeletedSpan} first.
  *
  * A shift never leaves the grid: the result is clamped to the axis's last line, so a region already
  * touching the bottom (or the right edge) keeps its edge there instead of naming a line the format
  * has no room for. That shrinks such a region by what it could not move, which is the lesser of the
  * two evils and is what Excel does to the same region on the same edit.
  */
-export declare function shiftIndex(v: number, start: number, count: number, delta: number, axis: 'row' | 'col'): number;
+export declare function shiftIndex(v: number, splice: AxisSplice): number;
 /**
- * Whether the inclusive span `lo..hi` lies entirely within the `count` lines deleted at `start`: the
- * test that separates "this moved" from "this is gone". A single coordinate is the degenerate span
+ * Whether the inclusive span `lo..hi` lies entirely within the deleted lines: the test that
+ * separates "this moved" from "this is gone". A single coordinate is the degenerate span
  * `lo === hi`.
  */
-export declare function isDeletedSpan(lo: number, hi: number, start: number, count: number): boolean;
+export declare function isDeletedSpan(lo: number, hi: number, splice: AxisSplice): boolean;
+/**
+ * Both edges of a region's span on the spliced axis, moved together, or `undefined` when the delete
+ * swallowed the span whole. The two answers are exclusive on purpose: a span straddling the cut
+ * clamps and survives, one wholly inside it is dropped, and a caller must not clamp its way out of
+ * a drop.
+ *
+ * The one-axis form, for a region whose *other* axis is not a number the caller holds -- a `sqref`
+ * area may be unbounded across the axis it is not being spliced on, and re-encoding it as bounded
+ * would rewrite the file's own spelling. Callers holding a real rectangle want {@link shiftRect}.
+ */
+export declare function shiftSpan(lo: number, hi: number, splice: AxisSplice): {
+    lo: number;
+    hi: number;
+} | undefined;
+/**
+ * A rectangle re-anchored through the splice, or `undefined` when the delete swallowed it whole.
+ * The unspliced axis passes through untouched; both edges of the spliced axis move and clamp.
+ *
+ * This projection -- pick the spliced axis's two edges out of the rectangle, ask whether they
+ * survived, move them, put the rectangle back together -- is the shape every range-bound thing in
+ * the model re-anchors by, and writing it per caller is how the axis ternary gets inverted in one
+ * of them.
+ */
+export declare function shiftRect(rect: GridRect, splice: AxisSplice): GridRect | undefined;
+/**
+ * The degenerate one-coordinate form of {@link shiftRect}: a cell that moves, or `undefined` when
+ * the delete took the line it sat on. The coordinate off the spliced axis passes through.
+ */
+export declare function shiftPoint(point: CellPosition, splice: AxisSplice): CellPosition | undefined;

package/dist/core/grid-shift.js

@@ -1,8 +1,30 @@
 import { MAX_COLUMN, MAX_ROW } from './address.js';
-export function shiftIndex(v, start, count, delta, axis) {
+export function shiftIndex(v, splice) {
+    const { start, count, delta } = splice;
     const moved = v < start ? v : v >= start + count ? v + delta : start;
-    return Math.min(moved, axis === 'row' ? MAX_ROW : MAX_COLUMN);
+    return Math.min(moved, splice.axis === 'row' ? MAX_ROW : MAX_COLUMN);
 }
-export function isDeletedSpan(lo, hi, start, count) {
-    return lo >= start && hi < start + count;
+export function isDeletedSpan(lo, hi, splice) {
+    return lo >= splice.start && hi < splice.start + splice.count;
+}
+export function shiftSpan(lo, hi, splice) {
+    if (isDeletedSpan(lo, hi, splice))
+        return undefined;
+    return { lo: shiftIndex(lo, splice), hi: shiftIndex(hi, splice) };
+}
+export function shiftRect(rect, splice) {
+    const rowAxis = splice.axis === 'row';
+    const moved = shiftSpan(rowAxis ? rect.top : rect.left, rowAxis ? rect.bottom : rect.right, splice);
+    if (moved === undefined)
+        return undefined;
+    return rowAxis
+        ? { ...rect, top: moved.lo, bottom: moved.hi }
+        : { ...rect, left: moved.lo, right: moved.hi };
+}
+export function shiftPoint(point, splice) {
+    const line = splice.axis === 'row' ? point.row : point.col;
+    if (isDeletedSpan(line, line, splice))
+        return undefined;
+    const moved = shiftIndex(line, splice);
+    return splice.axis === 'row' ? { col: point.col, row: moved } : { col: moved, row: point.row };
 }

package/dist/core/image.d.ts

@@ -18,7 +18,7 @@ export declare const PX_TO_EMU = 9525;
  * defaults to `oneCell` when the attribute is omitted. */
 export type ImageEditAs = 'oneCell' | 'twoCell' | 'absolute';
 /** Narrow a raw `<xdr:twoCellAnchor editAs>` token to a known {@link ImageEditAs}. */
-export declare function isImageEditAs(value: string): value is ImageEditAs;
+export declare const isImageEditAs: (value: string) => value is ImageEditAs;
 /** A fixed image size in EMUs: the extent of a one-cell anchor, which pixel dimensions convert into
  * via {@link PX_TO_EMU}. */
 export interface Extent {
@@ -99,15 +99,19 @@ export interface WorksheetImages {
     readonly background: WorkbookImage | undefined;
 }
 /**
- * The id under which `image` is already registered in `media`, or `undefined` if it is not.
+ * A picture's content identity as a map key: its kind, its length, and a digest of its bytes.
  *
- * Content-addressed rather than reference-addressed: two byte-identical pictures are one picture,
- * however they reached the registry. This is what keeps repeated imports from growing the media
- * list without bound (the same logo carried onto twenty sheets registers once), and it is why the
- * comparison is over bytes rather than object identity, which a picture arriving from another
- * workbook would never satisfy.
+ * **Content-addressed, not reference-addressed.** Two byte-identical pictures are one picture,
+ * however they reached the registry. That is what keeps repeated imports from growing the media list
+ * without bound, so the same logo carried onto twenty sheets registers once, and it is why identity
+ * cannot be object identity: a picture arriving from another workbook would never satisfy that.
  *
- * The length check comes first and short-circuits, so pictures of different sizes never reach the
- * byte loop; only same-extension, same-length candidates are compared in full.
+ * **A key rather than a scan**, which is the part that changed. The comparison used to walk the whole
+ * media list byte by byte per candidate, and importing a sheet's pictures asks it once per anchored
+ * image, so merging a workbook of fifty distinct megabyte images compared bytes fifty times over
+ * fifty candidates. The workbook indexes each picture as it is registered instead.
+ *
+ * SHA-512 rather than a cheap checksum because a collision here silently substitutes one picture for
+ * another; the length is in the key as well, so a collision would have to match that too.
  */
-export declare function findRegisteredImage(media: readonly WorkbookImage[], image: WorkbookImage): number | undefined;
+export declare function imageContentKey(image: WorkbookImage): string;

package/dist/core/image.js

@@ -1,8 +1,8 @@
+import { hex } from '../hex.js';
+import { sha512 } from '../sha512.js';
+import { tokenSet } from '../token-set.js';
 export const PX_TO_EMU = 9525;
-const IMAGE_EDIT_AS = { oneCell: true, twoCell: true, absolute: true };
-export function isImageEditAs(value) {
-    return Object.hasOwn(IMAGE_EDIT_AS, value);
-}
+export const isImageEditAs = tokenSet({ oneCell: true, twoCell: true, absolute: true });
 export function isOneCellAnchor(anchor) {
     return 'ext' in anchor;
 }
@@ -42,9 +42,9 @@ export function normalizeImageExtension(extension, data) {
     }
     return sniffImageExtension(data);
 }
-export function findRegisteredImage(media, image) {
-    const index = media.findIndex((held) => held.extension === image.extension &&
-        held.data.length === image.data.length &&
-        held.data.every((byte, i) => byte === image.data[i]));
-    return index === -1 ? undefined : index;
+export function imageContentKey(image) {
+    let digest = '';
+    for (const byte of sha512(image.data))
+        digest += hex(byte, 2);
+    return `${image.extension}:${image.data.length}:${digest}`;
 }

package/dist/core/internal.d.ts

@@ -1,6 +1,12 @@
 /**
- * Keys the codec-only operations on `Workbook` and `Worksheet` (see `WorkbookInternals` /
- * `WorksheetInternals`, declared beside their classes).
+ * Keys the operations the library's own machinery may perform on a published class and a caller may
+ * not (see `WorkbookInternals` / `WorksheetInternals`, declared beside their classes).
+ *
+ * Not only the model: `WorksheetStreamWriter` hangs its construction and its row-flush plumbing off
+ * the same key, on the static side and the instance side respectively, because that class has the
+ * identical problem one layer up. Its constructor took the writer's style registry and its
+ * `flushedSheet()` returned the writer's flushed-row record, so seven internal types were named by a
+ * published signature and none of them was a type a consumer could write down.
  */
 export declare const INTERNAL: unique symbol;
 /**

package/dist/core/limits.d.ts

@@ -28,3 +28,26 @@ export declare const MAX_ROW_HEIGHT = 409.5;
  * value for it is a bug rather than a shortcut.
  */
 export declare const MAX_COLUMN_WIDTH = 255;
+/**
+ * The longest sheet name Excel accepts, in UTF-16 code units. A longer one is refused outright rather
+ * than truncated: a truncated name silently collides with its neighbours.
+ */
+export declare const MAX_SHEET_NAME_LENGTH = 31;
+/**
+ * The characters Excel forbids anywhere in a sheet name. A name may also not begin or end with an
+ * apostrophe, which this pattern does not express because the position is what makes it illegal: a
+ * sheet-qualified reference quotes the name with apostrophes, so one at either edge cannot be told
+ * from the quoting.
+ */
+export declare const INVALID_SHEET_NAME_CHARS: RegExp;
+/** The longest table name Excel accepts, in UTF-16 code units. */
+export declare const MAX_TABLE_NAME_LENGTH = 255;
+/**
+ * Excel's table-name grammar: start with a letter, underscore, or backslash; every later character a
+ * letter, digit, period, or underscore. Unicode letters and digits are allowed.
+ *
+ * Excel additionally forbids a name that *is* a cell reference (`A1`, `R1C1`), which this pattern
+ * deliberately does not: the regression corpus treats cell-reference-shaped names like `T1` as valid
+ * table names, so enforcing that rule would reject a fixture the contract accepts.
+ */
+export declare const TABLE_NAME_PATTERN: RegExp;

package/dist/core/limits.js

@@ -1,2 +1,6 @@
 export const MAX_ROW_HEIGHT = 409.5;
 export const MAX_COLUMN_WIDTH = 255;
+export const MAX_SHEET_NAME_LENGTH = 31;
+export const INVALID_SHEET_NAME_CHARS = /[*?:\\/[\]]/;
+export const MAX_TABLE_NAME_LENGTH = 255;
+export const TABLE_NAME_PATTERN = /^[\p{L}\\_][\p{L}\p{N}._]*$/u;

package/dist/core/merge-index.d.ts

@@ -0,0 +1,31 @@
+import { type GridRect } from './address.ts';
+import type { MergeRect } from './merge.ts';
+/**
+ * A row-banded index over a sheet's merged regions. Holds the region list by reference and never
+ * mutates it: the sheet stays the owner, reports what it adds, and says when it has rewritten the
+ * list wholesale (a splice, an unmerge, a model assignment), which the index answers by rebuilding
+ * on the next query rather than by tracking the edit.
+ */
+export declare class MergeIndex {
+    #private;
+    constructor(rects: readonly MergeRect[]);
+    /** Note a region added to the list. Ignored while stale: the rebuild reads the list itself. */
+    note(rect: MergeRect): void;
+    /** Report that the region list has been rewritten from outside this index. */
+    invalidate(): void;
+    /**
+     * The region overlapping `rect`, or `undefined` when the rectangle is free. Which of several
+     * overlapping regions is returned is unspecified beyond being one of them; a sheet admits no
+     * overlap, so at most one ever applies.
+     */
+    overlapping(rect: GridRect): MergeRect | undefined;
+    /**
+     * Resolve a position to the top-left of the merged region covering it, or to itself when no region
+     * does. Only fully-bounded regions participate: an unbounded whole-row/column merge carries no
+     * rectangle and so resolves nothing.
+     */
+    masterOf(row: number, col: number): {
+        row: number;
+        col: number;
+    };
+}

package/dist/core/merge-index.js

@@ -0,0 +1,60 @@
+import { rectsOverlap } from './address.js';
+const BAND_ROWS = 64;
+function bandOf(row) {
+    return Math.floor(row / BAND_ROWS);
+}
+export class MergeIndex {
+    #rects;
+    #bands = new Map();
+    #tallest = 0;
+    #stale = true;
+    constructor(rects) {
+        this.#rects = rects;
+    }
+    note(rect) {
+        if (!this.#stale)
+            this.#place(rect);
+    }
+    invalidate() {
+        this.#stale = true;
+    }
+    overlapping(rect) {
+        this.#refresh();
+        const first = bandOf(Math.max(1, rect.top - this.#tallest + 1));
+        const last = bandOf(rect.bottom);
+        for (let band = first; band <= last; band++) {
+            const bucket = this.#bands.get(band);
+            if (bucket === undefined)
+                continue;
+            for (const candidate of bucket) {
+                if (rectsOverlap(candidate, rect))
+                    return candidate;
+            }
+        }
+        return undefined;
+    }
+    masterOf(row, col) {
+        const covering = this.overlapping({ top: row, left: col, bottom: row, right: col });
+        return covering === undefined ? { row, col } : { row: covering.top, col: covering.left };
+    }
+    #place(rect) {
+        const height = rect.bottom - rect.top + 1;
+        if (height > this.#tallest)
+            this.#tallest = height;
+        const band = bandOf(rect.top);
+        const bucket = this.#bands.get(band);
+        if (bucket === undefined)
+            this.#bands.set(band, [rect]);
+        else
+            bucket.push(rect);
+    }
+    #refresh() {
+        if (!this.#stale)
+            return;
+        this.#stale = false;
+        this.#bands = new Map();
+        this.#tallest = 0;
+        for (const rect of this.#rects)
+            this.#place(rect);
+    }
+}

package/dist/core/merge.d.ts

@@ -1,17 +1,8 @@
 import { type GridRect } from './address.ts';
 import type { Cell } from './cell.ts';
+import { type AxisSplice } from './grid-shift.ts';
 /** A merged region, as the {@link GridRect} every range-shaped thing in the library is. */
 export type MergeRect = GridRect;
-/**
- * Resolve a position to the master (top-left) of the merged region covering it, or to itself when no
- * region does. First covering region wins; `Worksheet.mergeCells` rejects overlaps, so at most one
- * region ever applies. Only fully-bounded rects participate: an unbounded whole-row/column merge
- * carries no rect and so resolves nothing.
- */
-export declare function masterOf(rects: readonly MergeRect[], row: number, col: number): {
-    row: number;
-    col: number;
-};
 /**
  * Drop any value already sitting in a merge's covered non-anchor cells, keeping only the top-left
  * anchor, the collapse Excel performs on merge. A leftover covered value would serialise as a
@@ -25,12 +16,12 @@ export declare function clearCoveredValues(rows: Map<number, Map<number, Cell>>,
  * that can exist contributes no rectangle, the reader's rule for every other foreign attribute. */
 export declare function decodeSqrefRects(sqref: string): MergeRect[];
 /**
- * Re-anchor an OOXML `sqref` through a splice of `count` lines at `start` on `axis`, the inverse of
- * {@link decodeSqrefRects}. Returns `undefined` when the splice deleted every area the `sqref` named:
- * an empty `sqref` is not writable, so the entry holding it goes too.
+ * Re-anchor an OOXML `sqref` through a splice, the inverse of {@link decodeSqrefRects}. Returns
+ * `undefined` when the splice deleted every area the `sqref` named: an empty `sqref` is not
+ * writable, so the entry holding it goes too.
  *
  * Each space-separated area shifts on its own, and one the splice does not move is returned as the
  * *original text*. That matters for a file the library did not author: `B:B` and `B1:B1048576` decode
  * identically, so a re-encode would rewrite a foreign spelling and cost the byte-clean round trip.
  */
-export declare function shiftSqref(sqref: string, axis: 'row' | 'col', start: number, count: number, delta: number): string | undefined;
+export declare function shiftSqref(sqref: string, splice: AxisSplice): string | undefined;

package/dist/core/merge.js

@@ -1,24 +1,15 @@
 import { encodeCornerRef, tryDecodeRange } from './address.js';
-import { isDeletedSpan, shiftIndex } from './grid-shift.js';
-export function masterOf(rects, row, col) {
-    for (const rect of rects) {
-        if (row >= rect.top && row <= rect.bottom && col >= rect.left && col <= rect.right) {
-            return { row: rect.top, col: rect.left };
-        }
-    }
-    return { row, col };
-}
+import { shiftSpan } from './grid-shift.js';
 export function clearCoveredValues(rows, rect) {
-    for (let row = rect.top; row <= rect.bottom; row++) {
-        const cols = rows.get(row);
-        if (cols === undefined)
+    for (const [row, cols] of rows) {
+        if (row < rect.top || row > rect.bottom)
             continue;
-        for (let col = rect.left; col <= rect.right; col++) {
+        for (const [col, covered] of cols) {
+            if (col < rect.left || col > rect.right)
+                continue;
             if (row === rect.top && col === rect.left)
                 continue;
-            const covered = cols.get(col);
-            if (covered !== undefined)
-                covered.value = null;
+            covered.value = null;
         }
     }
 }
@@ -40,33 +31,33 @@ export function decodeSqrefRects(sqref) {
     }
     return rects;
 }
-export function shiftSqref(sqref, axis, start, count, delta) {
+export function shiftSqref(sqref, splice) {
     const areas = [];
     for (const area of sqref.split(/\s+/)) {
         if (area === '')
             continue;
-        const shifted = shiftSqrefArea(area, axis, start, count, delta);
+        const shifted = shiftSqrefArea(area, splice);
         if (shifted !== undefined)
             areas.push(shifted);
     }
     return areas.length > 0 ? areas.join(' ') : undefined;
 }
-function shiftSqrefArea(area, axis, start, count, delta) {
+function shiftSqrefArea(area, splice) {
     const decoded = tryDecodeRange(area);
     if (decoded === undefined)
         return area;
     const { top, left, bottom, right } = decoded;
-    const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
+    const rowAxis = splice.axis === 'row';
+    const [lo, hi] = rowAxis ? [top, bottom] : [left, right];
     if (lo === undefined || hi === undefined)
         return area;
-    if (isDeletedSpan(lo, hi, start, count))
+    const moved = shiftSpan(lo, hi, splice);
+    if (moved === undefined)
         return undefined;
-    const movedLo = shiftIndex(lo, start, count, delta, axis);
-    const movedHi = shiftIndex(hi, start, count, delta, axis);
-    if (movedLo === lo && movedHi === hi)
+    if (moved.lo === lo && moved.hi === hi)
         return area;
-    const [tl, br] = axis === 'row'
-        ? [encodeCornerRef(left, movedLo), encodeCornerRef(right, movedHi)]
-        : [encodeCornerRef(movedLo, top), encodeCornerRef(movedHi, bottom)];
+    const [tl, br] = rowAxis
+        ? [encodeCornerRef(left, moved.lo), encodeCornerRef(right, moved.hi)]
+        : [encodeCornerRef(moved.lo, top), encodeCornerRef(moved.hi, bottom)];
     return area.includes(':') ? `${tl}:${br}` : tl;
 }

package/dist/core/page-setup.d.ts

@@ -1,3 +1,4 @@
+import type { AssertNever } from './internal.ts';
 /**
  * Paper orientation, as `<pageSetup orientation>` carries it.
  *
@@ -7,11 +8,11 @@
  */
 export type PageOrientation = 'portrait' | 'landscape';
 /** Narrow a raw `<pageSetup orientation>` token to a known {@link PageOrientation}. */
-export declare function isPageOrientation(value: string): value is PageOrientation;
+export declare const isPageOrientation: (value: string) => value is PageOrientation;
 /** The order pages are numbered and printed in across a sheet wider and taller than one page. */
 export type PageOrder = 'downThenOver' | 'overThenDown';
 /** Narrow a raw `<pageSetup pageOrder>` token to a known {@link PageOrder}. */
-export declare function isPageOrder(value: string): value is PageOrder;
+export declare const isPageOrder: (value: string) => value is PageOrder;
 /**
  * Print-scaling and orientation settings. These map onto two OOXML elements: `fitToPage` is the
  * `<pageSetUpPr>` flag (a `<sheetPr>` child) that switches Excel from fixed-zoom to fit-to-page
@@ -47,6 +48,61 @@ export interface PageSetup {
      */
     printerSettings?: Uint8Array;
 }
+/**
+ * How one `<pageSetup>` attribute encodes: which model key it is and what kind of value it carries.
+ *
+ * Format-blind on purpose, the same way {@link AlignmentFacet} is: `PageSetup` is a core type and
+ * the layering gate forbids core importing a serialisation, so the table states what an attribute
+ * *is* and each codec supplies the reading and the writing off the `kind`. The OOXML attribute name
+ * is the model key throughout, so it is not restated.
+ */
+export type PageSetupFacet = {
+    readonly key: 'paperSize' | 'scale' | 'fitToWidth' | 'fitToHeight';
+    /** A non-negative integer: a page count, a percentage, or a paper-size id. */
+    readonly kind: 'count';
+} | {
+    readonly key: 'pageOrder' | 'orientation';
+    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 six `<pageSetup>` attributes, declared once, in CT_PageSetup order. Both directions key off
+ * this list, so an attribute written but not read (it survives a re-write and vanishes on load) or
+ * read but not written is a compile error rather than something a reviewer has to notice.
+ */
+export declare const PAGE_SETUP_FACETS: readonly [{
+    readonly key: 'paperSize';
+    readonly kind: 'count';
+}, {
+    readonly key: 'scale';
+    readonly kind: 'count';
+}, {
+    readonly key: 'fitToWidth';
+    readonly kind: 'count';
+}, {
+    readonly key: 'fitToHeight';
+    readonly kind: 'count';
+}, {
+    readonly key: 'pageOrder';
+    readonly kind: 'token';
+    readonly isValid: (value: string) => value is PageOrder;
+    readonly label: 'page order';
+}, {
+    readonly key: 'orientation';
+    readonly kind: 'token';
+    readonly isValid: (value: string) => value is PageOrientation;
+    readonly label: 'page orientation';
+}];
+/**
+ * Compile-time proof that {@link PAGE_SETUP_FACETS} covers every `<pageSetup>` attribute.
+ *
+ * `fitToPage` and `printerSettings` are excluded because neither is one: `fitToPage` is a
+ * `<sheetPr>` child's flag and `printerSettings` is the blob behind an `r:id`, so both are written
+ * and read somewhere else entirely and a table entry for them would describe nothing.
+ */
+export type EveryPageSetupFacetIsDeclared = AssertNever<Exclude<keyof PageSetup, 'fitToPage' | 'printerSettings' | (typeof PAGE_SETUP_FACETS)[number]['key']>>;
 /**
  * Print-toggle flags from the `<printOptions>` element. Each maps to a boolean OOXML attribute that
  * defaults false, except `gridLinesSet`, which defaults true and gates whether `gridLines` is
@@ -65,6 +121,11 @@ export interface PrintOptions {
     /** Whether the `gridLines` flag is authoritative; when `false`, Excel ignores `gridLines`. */
     gridLinesSet?: boolean;
 }
+/** The `<printOptions>` flags, in CT_PrintOptions attribute order. Each is a plain OOXML boolean, so
+ * the list is the whole of what either direction needs to know. */
+export declare const PRINT_OPTION_FLAGS: readonly ["horizontalCentered", "verticalCentered", "headings", "gridLines", "gridLinesSet"];
+/** Compile-time proof that {@link PRINT_OPTION_FLAGS} covers every {@link PrintOptions} flag. */
+export type EveryPrintOptionFlagIsDeclared = AssertNever<Exclude<keyof PrintOptions, (typeof PRINT_OPTION_FLAGS)[number]>>;
 /**
  * A manual page break (`<brk>`). For a row break, `id` is the row the layout splits *before*; for a
  * column break it is the column. `max` bounds the break's extent across the other axis (Excel writes
@@ -92,6 +153,10 @@ export interface PageMargins {
     header?: number;
     footer?: number;
 }
+/** The `<pageMargins>` sides, in the order CT_PageMargins declares them. */
+export declare const MARGIN_SIDES: readonly ["left", "right", "top", "bottom", "header", "footer"];
+/** Compile-time proof that {@link MARGIN_SIDES} covers every {@link PageMargins} side. */
+export type EveryMarginSideIsDeclared = AssertNever<Exclude<keyof PageMargins, (typeof MARGIN_SIDES)[number]>>;
 /**
  * Page header/footer text, one string per page class. Excel only honours the even- and
  * first-page variants when the writer also sets the gating flags (`differentOddEven`,
@@ -106,3 +171,8 @@ export interface HeaderFooter {
     firstHeader?: string;
     firstFooter?: string;
 }
+/** The `<headerFooter>` children, in CT_HeaderFooter child order. The element name is the model key
+ * throughout, so one list serves the reader's capture, the reader's commit, and the writer. */
+export declare const HEADER_FOOTER_ELEMENTS: readonly ["oddHeader", "oddFooter", "evenHeader", "evenFooter", "firstHeader", "firstFooter"];
+/** Compile-time proof that {@link HEADER_FOOTER_ELEMENTS} covers every {@link HeaderFooter} slot. */
+export type EveryHeaderFooterElementIsDeclared = AssertNever<Exclude<keyof HeaderFooter, (typeof HEADER_FOOTER_ELEMENTS)[number]>>;

package/dist/core/page-setup.js

@@ -1,8 +1,34 @@
-const PAGE_ORIENTATIONS = { portrait: true, landscape: true };
-export function isPageOrientation(value) {
-    return Object.hasOwn(PAGE_ORIENTATIONS, value);
-}
-const PAGE_ORDERS = { downThenOver: true, overThenDown: true };
-export function isPageOrder(value) {
-    return Object.hasOwn(PAGE_ORDERS, value);
-}
+import { tokenSet } from '../token-set.js';
+export const isPageOrientation = tokenSet({ portrait: true, landscape: true });
+export const isPageOrder = tokenSet({ downThenOver: true, overThenDown: true });
+export const PAGE_SETUP_FACETS = [
+    { key: 'paperSize', kind: 'count' },
+    { key: 'scale', kind: 'count' },
+    { key: 'fitToWidth', kind: 'count' },
+    { key: 'fitToHeight', kind: 'count' },
+    { key: 'pageOrder', kind: 'token', isValid: isPageOrder, label: 'page order' },
+    { key: 'orientation', kind: 'token', isValid: isPageOrientation, label: 'page orientation' },
+];
+export const PRINT_OPTION_FLAGS = [
+    'horizontalCentered',
+    'verticalCentered',
+    'headings',
+    'gridLines',
+    'gridLinesSet',
+];
+export const MARGIN_SIDES = [
+    'left',
+    'right',
+    'top',
+    'bottom',
+    'header',
+    'footer',
+];
+export const HEADER_FOOTER_ELEMENTS = [
+    'oddHeader',
+    'oddFooter',
+    'evenHeader',
+    'evenFooter',
+    'firstHeader',
+    'firstFooter',
+];

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

@@ -18,7 +18,7 @@ export interface ParsedPivotField {
  * `unknown` covers a `type` the file declares that is none of these. */
 export type PivotSourceKind = 'worksheet' | 'external' | 'consolidation' | 'scenario' | 'unknown';
 /** Narrow a raw `<cacheSource type>` token to a {@link PivotSourceKind} a file may declare. */
-export declare function isDeclarablePivotSourceKind(value: string): value is Exclude<PivotSourceKind, 'unknown'>;
+export declare const isDeclarablePivotSourceKind: (value: string) => value is "consolidation" | "external" | "scenario" | "worksheet";
 /** Where a pivot cache draws its rows from. {@link kind} names the source type; {@link sheet} and
  * {@link ref} locate the range only when it is `worksheet` and are empty strings otherwise, so a
  * consumer can tell a genuinely non-worksheet source apart from a worksheet source that failed to