@shbernal/ts-xlsx 1.3.1 → 2.1.0

package/dist/core/formula.d.ts

@@ -1,12 +1,12 @@
 /**
  * Quote a sheet name for use in a reference exactly when Excel would: a name that is not a plain
- * identifier — or that would read as a cell address — is wrapped in single quotes with its internal
+ * identifier, or that would read as a cell address, is wrapped in single quotes with its internal
  * quotes doubled, and a simple name is left bare. Shared by everything that *builds* a qualified
  * reference: the `_FilterDatabase` name the writer derives from an autofilter, and the `.xlsb`
  * reader's Ptg decoder, which has only a sheet index to work from and must spell the prefix itself.
  *
  * `last` names the far end of a 3-D span (`Data:More!A1`). A span is quoted as a whole or not at all,
- * because the quotes delimit the sheet *reference* rather than either name — so one awkward endpoint
+ * because the quotes delimit the sheet *reference* rather than either name, so one awkward endpoint
  * puts both inside the quotes.
  */
 export declare function quoteSheetName(name: string, last?: string): string;
@@ -14,7 +14,7 @@ export declare function quoteSheetName(name: string, last?: string): string;
  * Prefix every modern function called by its plain name with `_xlfn.` so Excel accepts the stored
  * formula. Names already prefixed are left alone (never doubled), unknown/legacy functions pass
  * through untouched, and opaque regions (string literals, sheet names, structured references) are
- * preserved verbatim. No other rewriting occurs — in particular no `@` implicit-intersection operator
+ * preserved verbatim. No other rewriting occurs: in particular no `@` implicit-intersection operator
  * is ever introduced.
  */
 export declare function mangleFunctions(formula: string): string;
@@ -25,8 +25,8 @@ export declare function mangleFunctions(formula: string): string;
  */
 export declare function unmangleFunctions(formula: string): string;
 /**
- * Prefix every LET/LAMBDA parameter identifier with `_xlpm.` — at its declaration and at each
- * reference within the binding call's parentheses — so Excel accepts the stored formula. The prefix
+ * Prefix every LET/LAMBDA parameter identifier with `_xlpm.`, at its declaration and at each
+ * reference within the binding call's parentheses, so Excel accepts the stored formula. The prefix
  * is lexically scoped: a name is only rewritten inside the call that binds it, opaque regions are
  * copied verbatim, and a lambda-valued parameter used as a call (`f(…)`) is prefixed too. Formulas
  * with no LET/LAMBDA pass through unchanged.
@@ -34,7 +34,7 @@ export declare function unmangleFunctions(formula: string): string;
 export declare function mangleParams(formula: string): string;
 /**
  * Mangle a model formula into its on-disk form: LET/LAMBDA parameter names first (`_xlpm.`), then the
- * modern-function prefix (`_xlfn.`). Ordering matters — parameter mangling reads the plain LET/LAMBDA
+ * modern-function prefix (`_xlfn.`). Ordering matters: parameter mangling reads the plain LET/LAMBDA
  * names before the function pass qualifies them. The inverse for both prefixes is unmangleFunctions.
  */
 export declare function mangleFormula(formula: string): string;

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

@@ -1,9 +1,21 @@
+import { type AutoFilter } from './autofilter.ts';
 import { Cell } from './cell.ts';
+import type { ConditionalFormattingOverlay } from './conditional-formatting-overlay.ts';
+import type { DataValidationOverlay } from './data-validation-overlay.ts';
 import { type AnchoredImage } from './image.ts';
 import type { MergeRect } from './merge.ts';
 import type { Table } from './table.ts';
 import { type CellValue } from './value.ts';
+import type { WorksheetComments } from './worksheet-comments.ts';
 import type { ColumnProperties, RowProperties } from './worksheet.ts';
+/**
+ * The sheet's autofilter, reached as a slot rather than held by reference like the containers beside
+ * it: it is a single replaceable value, and a splice that deletes every filtered line clears it.
+ */
+export interface AutoFilterSlot {
+    get(): AutoFilter | undefined;
+    set(next: AutoFilter | undefined): void;
+}
 interface GridStorage {
     readonly rows: Map<number, Map<number, Cell>>;
     readonly rowProperties: Map<number, RowProperties>;
@@ -12,6 +24,10 @@ interface GridStorage {
     readonly mergeRects: MergeRect[];
     readonly tables: Table[];
     readonly images: AnchoredImage[];
+    readonly dataValidations: DataValidationOverlay;
+    readonly conditionalFormattings: ConditionalFormattingOverlay;
+    readonly comments: WorksheetComments;
+    readonly autoFilter: AutoFilterSlot;
 }
 export declare class GridEdits {
     #private;

package/dist/core/grid-edits.js

@@ -1,11 +1,10 @@
-import { decodeAddress, decodeRange, encodeAddress } from './address.js';
+import { decodeRange, encodeAddress, tryDecodeCellRef } from './address.js';
+import { shiftAutoFilter } from './autofilter.js';
 import { Cell, copyCellContent } from './cell.js';
 import { replaceContents } from './containers.js';
+import { isDeletedSpan, shiftIndex } from './grid-shift.js';
 import { isOneCellAnchor } from './image.js';
 import { isSharedFormulaValue } from './value.js';
-function shiftIndex(v, start, count, delta) {
-    return v < start ? v : v >= start + count ? v + delta : start;
-}
 export class GridEdits {
     #rows;
     #rowProperties;
@@ -14,6 +13,10 @@ export class GridEdits {
     #mergeRects;
     #tables;
     #images;
+    #dataValidations;
+    #conditionalFormattings;
+    #comments;
+    #autoFilter;
     constructor(storage) {
         this.#rows = storage.rows;
         this.#rowProperties = storage.rowProperties;
@@ -22,6 +25,10 @@ export class GridEdits {
         this.#mergeRects = storage.mergeRects;
         this.#tables = storage.tables;
         this.#images = storage.images;
+        this.#dataValidations = storage.dataValidations;
+        this.#conditionalFormattings = storage.conditionalFormattings;
+        this.#comments = storage.comments;
+        this.#autoFilter = storage.autoFilter;
     }
     spliceRows(start, count, inserted) {
         const delta = inserted.length - count;
@@ -43,6 +50,7 @@ export class GridEdits {
         this.#shiftTables('row', start, count, delta);
         this.#shiftImages('row', start, count, delta);
         this.#reanchorSharedFormulas('row', start, count, delta);
+        this.#shiftRangeBoundOverlays('row', start, count, delta);
     }
     spliceColumns(start, count, inserts) {
         const delta = inserts.length - count;
@@ -74,6 +82,16 @@ export class GridEdits {
         this.#shiftTables('col', start, count, delta);
         this.#shiftImages('col', start, count, delta);
         this.#reanchorSharedFormulas('col', start, count, delta);
+        this.#shiftRangeBoundOverlays('col', start, count, delta);
+    }
+    #shiftRangeBoundOverlays(axis, start, count, delta) {
+        this.#dataValidations.shift(axis, start, count, delta);
+        this.#conditionalFormattings.shift(axis, start, count, delta);
+        this.#comments.shift(axis, start, count, delta);
+        const filter = this.#autoFilter.get();
+        if (filter !== undefined) {
+            this.#autoFilter.set(shiftAutoFilter(filter, axis, start, count, delta));
+        }
     }
     #relocateRow(cols, destRow) {
         const moved = new Map();
@@ -95,12 +113,12 @@ export class GridEdits {
                 const value = cell.value;
                 if (!isSharedFormulaValue(value))
                     continue;
-                const master = decodeAddress(value.sharedFormula);
-                if (master.col === undefined || master.row === undefined)
+                const master = tryDecodeCellRef(value.sharedFormula);
+                if (master === undefined)
                     continue;
                 const anchored = axis === 'row'
-                    ? encodeAddress(master.col, shiftIndex(master.row, start, count, delta))
-                    : encodeAddress(shiftIndex(master.col, start, count, delta), master.row);
+                    ? encodeAddress(master.col, shiftIndex(master.row, start, count, delta, 'row'))
+                    : encodeAddress(shiftIndex(master.col, start, count, delta, 'col'), master.row);
                 if (anchored === value.sharedFormula)
                     continue;
                 const reanchored = { ...value, sharedFormula: anchored };
@@ -121,7 +139,7 @@ export class GridEdits {
             map.set(index, value);
     }
     #shiftMerges(axis, start, count, delta) {
-        const shift = (v) => shiftIndex(v, start, count, delta);
+        const shift = (v) => shiftIndex(v, start, count, delta, axis);
         const merges = [];
         const rects = [];
         for (const range of this.#merges) {
@@ -131,7 +149,7 @@ export class GridEdits {
                 continue;
             }
             const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
-            if (lo >= start && hi < start + count)
+            if (isDeletedSpan(lo, hi, start, count))
                 continue;
             const rect = axis === 'row'
                 ? { top: shift(top), left, bottom: shift(bottom), right }
@@ -151,7 +169,7 @@ export class GridEdits {
     #shiftImages(axis, start, count, delta) {
         const shiftPoint = (point) => {
             const zeroBased = axis === 'row' ? point.row : point.col;
-            const shifted = shiftIndex(zeroBased + 1, start, count, delta) - 1;
+            const shifted = shiftIndex(zeroBased + 1, start, count, delta, axis) - 1;
             if (shifted === zeroBased)
                 return point;
             return axis === 'row' ? { ...point, row: shifted } : { ...point, col: shifted };

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

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ *
+ * 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;
+/**
+ * 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
+ * `lo === hi`.
+ */
+export declare function isDeletedSpan(lo: number, hi: number, start: number, count: number): boolean;

package/dist/core/grid-shift.js

@@ -0,0 +1,8 @@
+import { MAX_COLUMN, MAX_ROW } from './address.js';
+export function shiftIndex(v, start, count, delta, axis) {
+    const moved = v < start ? v : v >= start + count ? v + delta : start;
+    return Math.min(moved, axis === 'row' ? MAX_ROW : MAX_COLUMN);
+}
+export function isDeletedSpan(lo, hi, start, count) {
+    return lo >= start && hi < start + count;
+}

package/dist/core/image.d.ts

@@ -17,7 +17,9 @@ export declare const PX_TO_EMU = 9525;
  * them; `oneCell` moves but keeps its size; `absolute` is pinned to the page and does neither. Excel
  * defaults to `oneCell` when the attribute is omitted. */
 export type ImageEditAs = 'oneCell' | 'twoCell' | 'absolute';
-/** A fixed image size in EMUs — the extent of a one-cell anchor, which pixel dimensions convert into
+/** Narrow a raw `<xdr:twoCellAnchor editAs>` token to a known {@link ImageEditAs}. */
+export declare function 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 {
     readonly cx: number;
@@ -63,7 +65,7 @@ export interface AnchoredImage {
 }
 /** A picture's bytes and its file kind, as held in the workbook's media registry. */
 export interface WorkbookImage {
-    /** Lower-case file extension without a dot — `"png"`, `"jpeg"`, `"gif"`. Drives the media part's
+    /** Lower-case file extension without a dot: `"png"`, `"jpeg"`, `"gif"`. Drives the media part's
      * name and content type. */
     readonly extension: string;
     readonly data: Uint8Array;
@@ -74,3 +76,38 @@ export interface WorkbookImage {
  * leading run of alphanumerics; a missing or all-punctuation hint falls back to sniffing the bytes'
  * magic number, so the package is always well-formed. */
 export declare function normalizeImageExtension(extension: string | undefined, data: Uint8Array): string;
+/**
+ * An anchored image in workbook-independent form: the picture's own bytes rather than a media id
+ * into one particular workbook's registry.
+ *
+ * An {@link AnchoredImage} means nothing away from that registry: its `imageId` is an index, and
+ * the same index names a different picture (or none) in the next workbook. Attaching the picture
+ * itself is what lets an anchor cross that boundary, which is why the transfer form carries bytes
+ * where the stored form carries an id.
+ */
+export interface PortableImage {
+    readonly image: WorkbookImage;
+    readonly anchor: ImageAnchor;
+}
+/**
+ * Every picture a worksheet shows, in the workbook-independent form of {@link PortableImage}: the
+ * images anchored to the grid, in the order they were added, and the background tiled behind it.
+ * {@link Workbook.exportImages} produces one, {@link Workbook.importImages} applies one.
+ */
+export interface WorksheetImages {
+    readonly anchored: readonly PortableImage[];
+    readonly background: WorkbookImage | undefined;
+}
+/**
+ * The id under which `image` is already registered in `media`, or `undefined` if it is not.
+ *
+ * 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.
+ *
+ * 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.
+ */
+export declare function findRegisteredImage(media: readonly WorkbookImage[], image: WorkbookImage): number | undefined;

package/dist/core/image.js

@@ -1,4 +1,8 @@
 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 function isOneCellAnchor(anchor) {
     return 'ext' in anchor;
 }
@@ -38,3 +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;
+}

package/dist/core/internal.d.ts

@@ -4,8 +4,16 @@
  */
 export declare const INTERNAL: unique symbol;
 /**
- * Keys a `Cell`'s link to a named cell style — its OOXML `xfId`. A single hidden property rather than
+ * Keys a `Cell`'s link to a named cell style, its OOXML `xfId`. A single hidden property rather than
  * a channel object, so it stays a prototype accessor: cells are the one model class allocated in the
  * millions, and a per-instance internals object would be a real cost for state most cells never carry.
  */
 export declare const NAMED_STYLE_ID: unique symbol;
+/**
+ * The exhaustiveness proof the mirror types are built on: instantiate it with a `keyof` difference
+ * that should be empty. An unmirrored field leaves that difference non-`never`, which does not
+ * satisfy the constraint, so the build fails naming the field that was missed: a type error at the
+ * declaration rather than a silent hole discovered by a round trip. `Row`, `Column` and
+ * `WORKSHEET_MODEL_FACETS` each carry one of these proofs; this is the mechanism all three use.
+ */
+export type AssertNever<T extends never> = T;

package/dist/core/limits.d.ts

@@ -4,8 +4,8 @@
  * shown.
  *
  * A file may state more, and stating more loses the value rather than the file. Excel opens such a
- * package without complaint and silently clamps the row — to 409.6, a tick *above* what it lets
- * you assign, being 8192 twentieths of a point and so the width of the field it is read into — and
+ * package without complaint and silently clamps the row to 409.6, a tick *above* what it lets you
+ * assign, being 8192 twentieths of a point and so the width of the field it is read into, then
  * writes 409.6 back on its next save. Check against this constant to keep a stated height from
  * quietly becoming a different one.
  */
@@ -16,12 +16,12 @@ export declare const MAX_ROW_HEIGHT = 409.5;
  *
  * It is also the weaker of the two ceilings: it binds assignment only, and not a file at all.
  * Excel honours a `width` of 1000 read from a package, renders the column at it, and round-trips
- * it verbatim through its own save — where an over-limit row height is clamped away. So a width
+ * it verbatim through its own save, where an over-limit row height is clamped away. So a width
  * above this is a column no Excel user could have produced by dragging, not a value at risk.
  *
  * Character units, not points or pixels: a width is a count of digits of the default font's
  * *maximum digit width*, which is why there is no companion `DEFAULT_COLUMN_WIDTH` constant here.
- * The width a column takes when it states none is a function of that font — the familiar 8.43 holds
+ * The width a column takes when it states none is a function of that font: the familiar 8.43 holds
  * for Calibri 11 and not for a workbook whose normal style says otherwise (Excel reports 8.09 for
  * Aptos Narrow 11). `sheet.properties.defaultColWidth` is what a file declares, and
  * docs/knowledge/specs/default-font-must-not-be-assumed-for-column-widths.md is why assuming a

package/dist/core/merge.d.ts

@@ -1,17 +1,11 @@
+import { type GridRect } from './address.ts';
 import type { Cell } from './cell.ts';
-/** A merged region as inclusive 1-based grid bounds. */
-export interface MergeRect {
-    readonly top: number;
-    readonly left: number;
-    readonly bottom: number;
-    readonly right: number;
-}
-/** Whether two inclusive grid rectangles share at least one cell. */
-export declare function rectsOverlap(a: MergeRect, b: MergeRect): boolean;
+/** 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
+ * 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): {
@@ -20,12 +14,23 @@ export declare function masterOf(rects: readonly MergeRect[], row: number, col:
 };
 /**
  * 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
+ * anchor, the collapse Excel performs on merge. A leftover covered value would serialise as a
  * populated `<c>` under the range's `<mergeCell>` ref, the geometry that trips Excel's repair prompt.
  * Styles are untouched: a border spanning the merged region rides the covered cells.
  */
 export declare function clearCoveredValues(rows: Map<number, Map<number, Cell>>, rect: MergeRect): void;
 /** Decode an OOXML `sqref` (one or more space-separated ranges) into containment rectangles. A whole
  * column or row leaves one axis unbounded, so its missing edges open to `Infinity` rather than
- * clamping — a cell anywhere down the column still resolves inside it. */
+ * clamping: a cell anywhere down the column still resolves inside it. An area that names no region
+ * 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.
+ *
+ * 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;

package/dist/core/merge.js

@@ -1,7 +1,5 @@
-import { decodeRange } from './address.js';
-export function rectsOverlap(a, b) {
-    return a.left <= b.right && b.left <= a.right && a.top <= b.bottom && b.top <= a.bottom;
-}
+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) {
@@ -29,7 +27,10 @@ export function decodeSqrefRects(sqref) {
     for (const part of sqref.split(/\s+/)) {
         if (part === '')
             continue;
-        const { top, left, bottom, right } = decodeRange(part);
+        const decoded = tryDecodeRange(part);
+        if (decoded === undefined)
+            continue;
+        const { top, left, bottom, right } = decoded;
         rects.push({
             top: top ?? 1,
             left: left ?? 1,
@@ -39,3 +40,33 @@ export function decodeSqrefRects(sqref) {
     }
     return rects;
 }
+export function shiftSqref(sqref, axis, start, count, delta) {
+    const areas = [];
+    for (const area of sqref.split(/\s+/)) {
+        if (area === '')
+            continue;
+        const shifted = shiftSqrefArea(area, axis, start, count, delta);
+        if (shifted !== undefined)
+            areas.push(shifted);
+    }
+    return areas.length > 0 ? areas.join(' ') : undefined;
+}
+function shiftSqrefArea(area, axis, start, count, delta) {
+    const decoded = tryDecodeRange(area);
+    if (decoded === undefined)
+        return area;
+    const { top, left, bottom, right } = decoded;
+    const [lo, hi] = axis === 'row' ? [top, bottom] : [left, right];
+    if (lo === undefined || hi === undefined)
+        return area;
+    if (isDeletedSpan(lo, hi, start, count))
+        return undefined;
+    const movedLo = shiftIndex(lo, start, count, delta, axis);
+    const movedHi = shiftIndex(hi, start, count, delta, axis);
+    if (movedLo === lo && movedHi === hi)
+        return area;
+    const [tl, br] = axis === 'row'
+        ? [encodeCornerRef(left, movedLo), encodeCornerRef(right, movedHi)]
+        : [encodeCornerRef(movedLo, top), encodeCornerRef(movedHi, bottom)];
+    return area.includes(':') ? `${tl}:${br}` : tl;
+}

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

@@ -1,9 +1,23 @@
+/**
+ * Paper orientation, as `<pageSetup orientation>` carries it.
+ *
+ * `ST_Orientation` has a third member, `default`, which means "whatever the printer decides" and is
+ * indistinguishable from the attribute being absent. The model spells that absence as an unset field,
+ * so a file carrying `default` reads back with no orientation and writes back without the attribute.
+ */
+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;
+/** 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;
 /**
  * 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
  * scaling, while the rest are `<pageSetup>` attributes. Excel honours `scale` only when `fitToPage`
  * is off and the `fitToWidth`/`fitToHeight` page counts only when it is on, but the model carries
- * whatever the author set — an unset field is omitted so a round-trip never fabricates one. An
+ * whatever the author set: an unset field is omitted so a round-trip never fabricates one. An
  * empty object emits neither element.
  */
 export interface PageSetup {
@@ -16,12 +30,12 @@ export interface PageSetup {
     /** Fixed print zoom as a percentage; Excel honours it only when `fitToPage` is off. */
     scale?: number;
     /** Paper orientation. */
-    orientation?: 'portrait' | 'landscape';
+    orientation?: PageOrientation;
     /** Order pages are numbered/printed in across a multi-page sheet. */
-    pageOrder?: 'downThenOver' | 'overThenDown';
+    pageOrder?: PageOrder;
     /**
      * Paper size as Excel's 1-based enumeration index (e.g. `9` = A4, `1` = US Letter). Carried as an
-     * opaque integer — the model does not map it to physical dimensions, only preserves whatever the
+     * opaque integer: the model does not map it to physical dimensions, only preserves whatever the
      * author or source file set.
      */
     paperSize?: number;
@@ -35,7 +49,7 @@ export interface PageSetup {
 }
 /**
  * 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
+ * defaults false, except `gridLinesSet`, which defaults true and gates whether `gridLines` is
  * honoured. The model stores only what the source or caller set, so an unset flag is omitted and a
  * round-trip never fabricates one; an empty object emits no element at all.
  */
@@ -54,7 +68,7 @@ export interface PrintOptions {
 /**
  * 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
- * the last row/column index) and `man` marks it author-set rather than automatic — the model preserves
+ * the last row/column index) and `man` marks it author-set rather than automatic. The model preserves
  * whatever the source carried so a round-trip reproduces the break's span exactly.
  */
 export interface PageBreak {

package/dist/core/page-setup.js

@@ -1 +1,8 @@
-export {};
+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);
+}

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

@@ -3,12 +3,10 @@ import type { Worksheet } from './worksheet.ts';
  * names verbatim, so a metric doubles as its `<dataField subtotal="…">` value. Excel performs the
  * aggregation itself on refresh; the writer only records which function to apply. */
 export type PivotMetric = 'sum' | 'count' | 'countNums' | 'average' | 'max' | 'min' | 'product' | 'stdDev' | 'stdDevp' | 'var' | 'varp';
-/** Narrow a raw `subtotal` attribute (or any string) to a known {@link PivotMetric}. */
-export declare function isPivotMetric(value: string): value is PivotMetric;
 /** Map an OOXML `<dataField subtotal="…">` value back to its metric. The attribute is absent for
  * `sum` (Excel's implicit default), so `undefined` reads as `sum`; an unrecognised value also reads
- * as `sum` rather than throwing, because reconstructing an existing file is a lenient operation —
- * the strict rejection of unknown metrics belongs on the authoring path, not the read path. */
+ * as `sum` rather than throwing, because reconstructing an existing file is a lenient operation.
+ * The strict rejection of unknown metrics belongs on the authoring path, not the read path. */
 export declare function pivotMetricFromSubtotal(subtotal: string | undefined): PivotMetric;
 /** One field in a loaded pivot's cache catalogue, in declared order; the pivot refers to it by index. */
 export interface ParsedPivotField {
@@ -19,6 +17,8 @@ export interface ParsedPivotField {
  * data the reader does not model (an external connection, a range consolidation, or a scenario), and
  * `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'>;
 /** 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

package/dist/core/pivot-table.js

@@ -1,27 +1,36 @@
 import { AuthoringError, InternalError } from '../errors.js';
 import { encodeAddress } from './address.js';
 import { isErrorValue, isFormulaValue, isHyperlinkValue, isRichTextValue, isSharedFormulaValue, richTextToPlain, } from './value.js';
-const PIVOT_METRICS = new Set([
-    'sum',
-    'count',
-    'countNums',
-    'average',
-    'max',
-    'min',
-    'product',
-    'stdDev',
-    'stdDevp',
-    'var',
-    'varp',
-]);
-export function isPivotMetric(value) {
-    return PIVOT_METRICS.has(value);
+const PIVOT_METRICS = {
+    sum: true,
+    count: true,
+    countNums: true,
+    average: true,
+    max: true,
+    min: true,
+    product: true,
+    stdDev: true,
+    stdDevp: true,
+    var: true,
+    varp: true,
+};
+function isPivotMetric(value) {
+    return Object.hasOwn(PIVOT_METRICS, value);
 }
 export function pivotMetricFromSubtotal(subtotal) {
     if (subtotal === undefined)
         return 'sum';
     return isPivotMetric(subtotal) ? subtotal : 'sum';
 }
+const DECLARABLE_PIVOT_SOURCE_KINDS = {
+    worksheet: true,
+    external: true,
+    consolidation: true,
+    scenario: true,
+};
+export function isDeclarablePivotSourceKind(value) {
+    return Object.hasOwn(DECLARABLE_PIVOT_SOURCE_KINDS, value);
+}
 const BLANK = { kind: 'blank' };
 export class PivotTable {
     metric;
@@ -34,8 +43,8 @@ export class PivotTable {
     valueField;
     constructor(options) {
         const metric = options.metric ?? 'sum';
-        if (!PIVOT_METRICS.has(metric)) {
-            throw new AuthoringError(`unsupported pivot metric "${metric}" — expected one of ${[...PIVOT_METRICS].join(', ')}`);
+        if (!Object.hasOwn(PIVOT_METRICS, metric)) {
+            throw new AuthoringError(`unsupported pivot metric "${metric}": expected one of ${Object.keys(PIVOT_METRICS).join(', ')}`);
         }
         this.metric = metric;
         const source = options.source;
@@ -110,7 +119,7 @@ export class PivotTable {
             records.push(fields.map((_field, fieldIndex) => {
                 const scalar = scalarsForField(columnScalars, fieldIndex)[row];
                 if (scalar === undefined) {
-                    throw new InternalError(`pivot record row ${row} is out of range for field ${fieldIndex} — every column was ` +
+                    throw new InternalError(`pivot record row ${row} is out of range for field ${fieldIndex}: every column was ` +
                         'scanned for the same dataRowCount above, so this index is always in range');
                 }
                 const catalogue = catalogues[fieldIndex];
@@ -127,7 +136,7 @@ export class PivotTable {
     get valueFieldName() {
         const field = this.cacheFields[this.valueField];
         if (field === undefined) {
-            throw new InternalError(`pivot valueField index ${this.valueField} is out of range — resolve() validated it against ` +
+            throw new InternalError(`pivot valueField index ${this.valueField} is out of range: resolve() validated it against ` +
                 'the same fields array cacheFields was built from');
         }
         return field.name;
@@ -136,7 +145,7 @@ export class PivotTable {
 function scalarsForField(columnScalars, fieldIndex) {
     const scalars = columnScalars[fieldIndex];
     if (scalars === undefined) {
-        throw new InternalError(`pivot field index ${fieldIndex} is out of range for columnScalars — it was built from the same fields array`);
+        throw new InternalError(`pivot field index ${fieldIndex} is out of range for columnScalars: it was built from the same fields array`);
     }
     return scalars;
 }