@shbernal/ts-xlsx 1.0.0

package/dist/io/xlsx/relationships.d.ts

@@ -0,0 +1,33 @@
+export declare const NS: {
+    readonly contentTypes: "http://schemas.openxmlformats.org/package/2006/content-types";
+    readonly packageRels: "http://schemas.openxmlformats.org/package/2006/relationships";
+    readonly main: "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+    readonly docRels: "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+    readonly coreProps: "http://schemas.openxmlformats.org/package/2006/metadata/core-properties";
+    readonly extProps: "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties";
+    readonly dc: "http://purl.org/dc/elements/1.1/";
+    readonly dcterms: "http://purl.org/dc/terms/";
+    readonly dcmitype: "http://purl.org/dc/dcmitype/";
+    readonly xsi: "http://www.w3.org/2001/XMLSchema-instance";
+};
+export declare const REL: {
+    readonly worksheet: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet";
+    readonly styles: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
+    readonly theme: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme";
+    readonly officeDocument: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
+    readonly coreProps: "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties";
+    readonly extProps: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties";
+    readonly table: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/table";
+    readonly comments: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
+    readonly vmlDrawing: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing";
+    readonly drawing: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing";
+    readonly printerSettings: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/printerSettings";
+    readonly image: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
+    readonly hyperlink: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+    readonly sharedStrings: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings";
+    readonly pivotTable: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotTable";
+    readonly pivotCacheDefinition: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheDefinition";
+    readonly pivotCacheRecords: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheRecords";
+    readonly threadedComment: "http://schemas.microsoft.com/office/2017/10/relationships/threadedComment";
+    readonly person: "http://schemas.microsoft.com/office/2017/10/relationships/person";
+};

package/dist/io/xlsx/relationships.js

@@ -0,0 +1,47 @@
+// The relationship-type URIs and namespace groupings the writer's serialisers reference. The
+// canonical namespace set lives in `namespaces.ts`; the writer-local groupings here (the props
+// vocabularies, the content-types namespace, and the rel-type URIs derived from them) are plumbing
+// every part of the writer references.
+//
+// The `.rels` part envelope these types are written into is container-level, not SpreadsheetML, and
+// lives in `../opc/rels.ts`.
+import { CONTENT_TYPES_NS, PKG_RELS_NS, RELATIONSHIPS_NS } from "../opc/namespaces.js";
+import { SPREADSHEETML_NS } from "./namespaces.js";
+export const NS = {
+    contentTypes: CONTENT_TYPES_NS,
+    packageRels: PKG_RELS_NS,
+    main: SPREADSHEETML_NS,
+    docRels: RELATIONSHIPS_NS,
+    coreProps: 'http://schemas.openxmlformats.org/package/2006/metadata/core-properties',
+    extProps: 'http://schemas.openxmlformats.org/officeDocument/2006/extended-properties',
+    dc: 'http://purl.org/dc/elements/1.1/',
+    dcterms: 'http://purl.org/dc/terms/',
+    dcmitype: 'http://purl.org/dc/dcmitype/',
+    xsi: 'http://www.w3.org/2001/XMLSchema-instance',
+};
+// The Office extension relationships namespace the 2018 threaded-comment feature wires both of its parts
+// through. Local to this table: nothing outside it needs the base URI.
+const MS_OFFICE_2017_RELS_NS = 'http://schemas.microsoft.com/office/2017/10/relationships';
+export const REL = {
+    worksheet: `${NS.docRels}/worksheet`,
+    styles: `${NS.docRels}/styles`,
+    theme: `${NS.docRels}/theme`,
+    officeDocument: `${NS.docRels}/officeDocument`,
+    coreProps: `${NS.packageRels}/metadata/core-properties`,
+    extProps: `${NS.docRels}/extended-properties`,
+    table: `${NS.docRels}/table`,
+    comments: `${NS.docRels}/comments`,
+    vmlDrawing: `${NS.docRels}/vmlDrawing`,
+    drawing: `${NS.docRels}/drawing`,
+    printerSettings: `${NS.docRels}/printerSettings`,
+    image: `${NS.docRels}/image`,
+    hyperlink: `${NS.docRels}/hyperlink`,
+    sharedStrings: `${NS.docRels}/sharedStrings`,
+    pivotTable: `${NS.docRels}/pivotTable`,
+    pivotCacheDefinition: `${NS.docRels}/pivotCacheDefinition`,
+    pivotCacheRecords: `${NS.docRels}/pivotCacheRecords`,
+    // Threaded comments are a Microsoft extension, so both types live under the 2017/10 Office
+    // relationships namespace rather than the standard officeDocument one.
+    threadedComment: `${MS_OFFICE_2017_RELS_NS}/threadedComment`,
+    person: `${MS_OFFICE_2017_RELS_NS}/person`,
+};

package/dist/io/xlsx/rich-runs.d.ts

@@ -0,0 +1,13 @@
+import type { RichTextRun } from '../../core/value.ts';
+import type { XmlAttributes } from '../../xml/xml-read.ts';
+export declare class RunAccumulator {
+    #private;
+    reset(): void;
+    /** The runs gathered so far. */
+    get runs(): RichTextRun[];
+    beginRun(): void;
+    beginProperties(): void;
+    applyProperty(local: string, attrs: XmlAttributes): void;
+    appendText(text: string): boolean;
+    endRun(): void;
+}

package/dist/io/xlsx/rich-runs.js

@@ -0,0 +1,59 @@
+// Rich-text run accumulation, shared by the two readers that parse `<r>` runs identically: an inline
+// string's `<is>` in a worksheet body and a pooled `<si>` in sharedStrings.xml. One `<r>` opens a run
+// (resetting its font and text so an unformatted run inherits nothing from the last), an `<rPr>` opens
+// the run's font bundle whose self-closing children each set one facet, and a `<t>` appends the run's
+// text; the run commits on `</r>`. The surrounding parser owns only whether it is inside an `<is>`/`<si>`
+// and where a bare (non-run) `<t>` goes.
+import { applyFontChild } from "./read-styles.js";
+export class RunAccumulator {
+    #runs = [];
+    #font = null;
+    #text = '';
+    #inRun = false;
+    // Discard accumulated runs, readying the accumulator for a fresh `<is>`/`<si>`. A new array is
+    // installed, so a value already built from a previous reset's runs keeps its own array.
+    reset() {
+        this.#runs = [];
+        this.#font = null;
+        this.#inRun = false;
+    }
+    /** The runs gathered so far. */
+    get runs() {
+        return this.#runs;
+    }
+    // Open a run: reset the per-run font and text so an unformatted run inherits nothing from the last.
+    beginRun() {
+        this.#inRun = true;
+        this.#font = null;
+        this.#text = '';
+    }
+    // Open the run's `<rPr>` font bundle; its children stream in via {@link applyProperty}.
+    beginProperties() {
+        if (this.#inRun)
+            this.#font = {};
+    }
+    // Apply one `<rPr>` child (`<b/>`, `<sz>`, `<color>`, `<rFont>`, …) to the open run's font; a no-op
+    // when no `<rPr>` is open.
+    applyProperty(local, attrs) {
+        if (this.#font !== null)
+            applyFontChild(this.#font, local, attrs);
+    }
+    // Append a `<t>`'s text to the open run. Returns false when no run is open, so the caller routes the
+    // text to its surrounding plain/inline string instead.
+    appendText(text) {
+        if (!this.#inRun)
+            return false;
+        this.#text += text;
+        return true;
+    }
+    // Commit the open run — with its font, only if that font set at least one facet — to the runs list.
+    endRun() {
+        if (!this.#inRun)
+            return;
+        const run = { text: this.#text };
+        if (this.#font !== null && Object.keys(this.#font).length > 0)
+            run.font = this.#font;
+        this.#runs.push(run);
+        this.#inRun = false;
+    }
+}

package/dist/io/xlsx/rich-text.d.ts

@@ -0,0 +1,7 @@
+import type { RichTextRun } from '../../core/value.ts';
+/**
+ * Serialise a rich-text value's runs as the inner content of an `<is>` element. A zero-length run
+ * is dropped: an empty `<t/>` is schema-invalid — Excel flags the file as corrupt — and an empty
+ * run contributes nothing to the rendered text, so omitting it is loss-free.
+ */
+export declare function richTextRunsXml(runs: readonly RichTextRun[]): string;

package/dist/io/xlsx/rich-text.js

@@ -0,0 +1,23 @@
+// Rich-text runs — a cell value composed of independently-formatted text runs.
+//
+// OOXML stores rich text as a sequence of `<r>` runs, each an optional `<rPr>` (the run's font, in
+// the CT_RPrElt shape — identical to a styles `<font>` except the face element is `<rFont>`, not
+// `<name>`) followed by a `<t>` text element. The writer serialises a rich-text value inline
+// (`t="inlineStr"`), never into the shared-strings table, matching how it writes every other string
+// value; the reader reconstructs the runs while scanning the inline string.
+import { textElement } from "../../xml/xml.js";
+import { fontXml } from "./styles.js";
+/**
+ * Serialise a rich-text value's runs as the inner content of an `<is>` element. A zero-length run
+ * is dropped: an empty `<t/>` is schema-invalid — Excel flags the file as corrupt — and an empty
+ * run contributes nothing to the rendered text, so omitting it is loss-free.
+ */
+export function richTextRunsXml(runs) {
+    return runs
+        .filter((run) => run.text !== '')
+        .map((run) => {
+        const rPr = run.font !== undefined ? `<rPr>${fontXml(run.font, 'rFont')}</rPr>` : '';
+        return `<r>${rPr}${textElement(run.text)}</r>`;
+    })
+        .join('');
+}

package/dist/io/xlsx/shared-formulas.d.ts

@@ -0,0 +1,6 @@
+import type { Worksheet } from '../../core/worksheet.ts';
+export interface SharedFormulaRole {
+    readonly si: number;
+    readonly ref?: string;
+}
+export declare function planSharedFormulas(sheet: Worksheet): Map<string, SharedFormulaRole>;

package/dist/io/xlsx/shared-formulas.js

@@ -0,0 +1,52 @@
+// Shared-formula group planning: assigning each master/clone group a sheet-unique index and the
+// master's `ref` range before the row loop serialises a single cell.
+import { encodeAddress } from "../../core/address.js";
+import { isFormulaValue, isSharedFormulaValue } from "../../core/value.js";
+import { AuthoringError } from "../../errors.js";
+// Plan a sheet's shared-formula groups: every clone cell (a {@link SharedFormulaValue}) names its
+// master by address, so group the clones by master, assign each group a sheet-unique `si`, and record
+// the `ref` range (master through the furthest clone) on the master. Excel requires the master to sit
+// at the top-left of that range, so a clone above or left of its master — or a master with no formula
+// (an orphan) — is rejected here, named, rather than emitted as a package Excel repairs on open.
+export function planSharedFormulas(sheet) {
+    const groups = new Map();
+    for (const { cells } of sheet.rows()) {
+        for (const cell of cells) {
+            if (isSharedFormulaValue(cell.value)) {
+                const clones = groups.get(cell.value.sharedFormula);
+                if (clones !== undefined)
+                    clones.push(cell);
+                else
+                    groups.set(cell.value.sharedFormula, [cell]);
+            }
+        }
+    }
+    const roles = new Map();
+    let si = 0;
+    for (const [masterAddress, clones] of groups) {
+        const master = sheet.getCell(masterAddress);
+        if (!isFormulaValue(master.value)) {
+            const offender = clones[0];
+            throw new AuthoringError(`shared-formula clone ${offender.address} names master ${masterAddress}, which holds no formula`);
+        }
+        let maxCol = master.col;
+        let maxRow = master.row;
+        for (const clone of clones) {
+            if (clone.col < master.col || clone.row < master.row) {
+                throw new AuthoringError(`shared-formula master ${masterAddress} must sit above and/or left of clone ${clone.address}`);
+            }
+            if (clone.col > maxCol)
+                maxCol = clone.col;
+            if (clone.row > maxRow)
+                maxRow = clone.row;
+        }
+        roles.set(masterAddress, {
+            si,
+            ref: `${encodeAddress(master.col, master.row)}:${encodeAddress(maxCol, maxRow)}`,
+        });
+        for (const clone of clones)
+            roles.set(clone.address, { si });
+        si += 1;
+    }
+    return roles;
+}

package/dist/io/xlsx/shared-strings-read.d.ts

@@ -0,0 +1,2 @@
+import type { SharedString } from './cell-value.ts';
+export declare function parseSharedStrings(xml: string): SharedString[];

package/dist/io/xlsx/shared-strings-read.js

@@ -0,0 +1,70 @@
+// Parser for the shared-string table (`xl/sharedStrings.xml`), the pool that `t="s"` cells index into.
+// Split out of read.ts beside its sibling parsers (read-styles.ts, rich-runs.ts) so read.ts stays
+// orchestration; the run structure it decodes is owned by RunAccumulator, shared with inline strings.
+import { localName, parseXml } from "../../xml/xml-read.js";
+import { RunAccumulator } from "./rich-runs.js";
+// Shared strings resolve `t="s"` cells. Each `<si>` is one entry: a plain `<si><t>…</t>` decodes to a
+// string, while a rich `<si><r><rPr>…</rPr><t>…</t></r>…` decodes to a {@link RichTextValue} whose runs
+// carry their per-run fonts — so rich text Excel pooled reads back formatted, not flattened to text.
+// The run structure inside an `<si>` is identical to an inline string's `<is>`, so it is parsed the
+// same way (see the inline-run accumulation in `parseWorksheet`).
+export function parseSharedStrings(xml) {
+    if (xml === '')
+        return [];
+    const strings = [];
+    // Per-`<si>` accumulation: `plain` gathers a bare `<t>`; `runs` gathers `<r>` runs. An `<si>` is
+    // rich the moment it holds one `<r>`, at which point its runs — not `plain` — become the entry.
+    let plain = '';
+    const runs = new RunAccumulator();
+    let isRich = false;
+    let capture = false;
+    let text = '';
+    parseXml(xml, {
+        onOpen(name, attrs) {
+            const local = localName(name);
+            switch (local) {
+                case 'si':
+                    plain = '';
+                    runs.reset();
+                    isRich = false;
+                    break;
+                case 'r':
+                    isRich = true;
+                    runs.beginRun();
+                    break;
+                case 'rPr':
+                    runs.beginProperties();
+                    break;
+                case 't':
+                    capture = true;
+                    text = '';
+                    break;
+                default:
+                    runs.applyProperty(local, attrs);
+                    break;
+            }
+        },
+        onText(chunk) {
+            if (capture)
+                text += chunk;
+        },
+        onClose(name) {
+            const local = localName(name);
+            switch (local) {
+                case 't':
+                    // A `<t>` inside a run is that run's text; a bare `<t>` directly in the `<si>` is plain.
+                    if (!runs.appendText(text))
+                        plain += text;
+                    capture = false;
+                    break;
+                case 'r':
+                    runs.endRun();
+                    break;
+                case 'si':
+                    strings.push(isRich ? { richText: runs.runs } : plain);
+                    break;
+            }
+        },
+    });
+    return strings;
+}

package/dist/io/xlsx/shared-strings.d.ts

@@ -0,0 +1,17 @@
+import type { RichTextValue } from '../../core/value.ts';
+/**
+ * Interns cell string values into the shared-strings pool. {@link intern} returns the index a
+ * `t="s"` cell writes as its `<v>`; identical entries collapse to one, so `count` (total references)
+ * and `uniqueCount` (distinct entries) diverge exactly as Excel records them. Each entry is stored as
+ * its rendered `<si>` inner XML, which is also its dedup key — a plain string (`<t>…`) and rich runs
+ * (`<r>…`) render to distinct markup, so the two kinds never collide in the pool.
+ */
+export declare class SharedStringTable {
+    #private;
+    /** Intern a plain or rich string and return its `<si>` index, reusing the entry when it repeats. */
+    intern(value: string | RichTextValue): number;
+    /** Whether no string has been interned — the writer omits the part entirely when so. */
+    get isEmpty(): boolean;
+    /** Serialise the pool as the `xl/sharedStrings.xml` part. */
+    toXml(): string;
+}

package/dist/io/xlsx/shared-strings.js

@@ -0,0 +1,50 @@
+// The shared-strings table: `xl/sharedStrings.xml`, the workbook-wide pool a `t="s"` cell indexes.
+//
+// When the writer runs with `useSharedStrings`, a plain string cell value is interned here — an
+// identical string is stored once and every cell holding it references the single `<si>` entry by
+// index — rather than repeating the text inline in each cell. This trades a second part and an
+// indirection for a smaller package when strings repeat, the storage Excel itself prefers.
+//
+// Both plain strings and rich text are pooled: a plain value becomes a `<si><t>…</t></si>` entry, a
+// rich value a `<si><r>…</r>…</si>` entry carrying its per-run formatting — the rich `<si>` runs Excel
+// itself writes. A `t="s"` cell then indexes either, and the reader reconstructs the runs, so pooled
+// rich text round-trips its formatting rather than flattening to text.
+import { textElement, XML_DECLARATION } from "../../xml/xml.js";
+import { SPREADSHEETML_NS } from "./namespaces.js";
+import { richTextRunsXml } from "./rich-text.js";
+/**
+ * Interns cell string values into the shared-strings pool. {@link intern} returns the index a
+ * `t="s"` cell writes as its `<v>`; identical entries collapse to one, so `count` (total references)
+ * and `uniqueCount` (distinct entries) diverge exactly as Excel records them. Each entry is stored as
+ * its rendered `<si>` inner XML, which is also its dedup key — a plain string (`<t>…`) and rich runs
+ * (`<r>…`) render to distinct markup, so the two kinds never collide in the pool.
+ */
+export class SharedStringTable {
+    #indexByEntry = new Map();
+    #entries = [];
+    #references = 0;
+    /** Intern a plain or rich string and return its `<si>` index, reusing the entry when it repeats. */
+    intern(value) {
+        this.#references += 1;
+        const inner = typeof value === 'string' ? textElement(value) : richTextRunsXml(value.richText);
+        const existing = this.#indexByEntry.get(inner);
+        if (existing !== undefined)
+            return existing;
+        const index = this.#entries.length;
+        this.#indexByEntry.set(inner, index);
+        this.#entries.push(inner);
+        return index;
+    }
+    /** Whether no string has been interned — the writer omits the part entirely when so. */
+    get isEmpty() {
+        return this.#entries.length === 0;
+    }
+    /** Serialise the pool as the `xl/sharedStrings.xml` part. */
+    toXml() {
+        const items = this.#entries.map((inner) => `<si>${inner}</si>`).join('');
+        return (XML_DECLARATION +
+            `<sst xmlns="${SPREADSHEETML_NS}" count="${this.#references}" uniqueCount="${this.#entries.length}">` +
+            items +
+            '</sst>');
+    }
+}

package/dist/io/xlsx/sheet-properties.d.ts

@@ -0,0 +1,13 @@
+import type { AutoFilter } from '../../core/autofilter.ts';
+import type { HeaderFooter, PageBreak, PageMargins, PageSetup, PrintOptions } from '../../core/page-setup.ts';
+import { type SheetProtection } from '../../core/protection.ts';
+import type { SheetView, Worksheet } from '../../core/worksheet.ts';
+export declare function sheetViewsXml(view: SheetView, active: boolean): string;
+export declare function sheetPrXml(sheet: Worksheet): string;
+export declare function sheetProtectionXml(protection: SheetProtection | undefined): string;
+export declare function autoFilterXml(filter: AutoFilter | undefined): string;
+export declare function headerFooterXml(hf: HeaderFooter): string;
+export declare function printOptionsXml(printOptions: PrintOptions): string;
+export declare function pageMarginsXml(margins: PageMargins): string;
+export declare function pageSetupXml(pageSetup: PageSetup, printerSettingsRelId: string | null): string;
+export declare function pageBreaksXml(breaks: readonly PageBreak[], element: 'rowBreaks' | 'colBreaks'): string;

package/dist/io/xlsx/sheet-properties.js

@@ -0,0 +1,211 @@
+// The worksheet's non-cell property blocks: `<sheetPr>`, `<sheetViews>`, `<sheetProtection>`,
+// `<autoFilter>`, and the print settings (`<printOptions>`, `<pageMargins>`, `<pageSetup>`,
+// `<headerFooter>`, `<rowBreaks>`/`<colBreaks>`). Each renders one CT_Worksheet child (or child
+// group) independently of the row/cell body `worksheet-xml.ts` orchestrates them alongside.
+import { encodeAddress } from "../../core/address.js";
+import { SHEET_PROTECTION_FLAGS } from "../../core/protection.js";
+import { attr, boolAttr, escapeAttr, escapeText, numberText } from "../../xml/xml.js";
+import { colorAttrs } from "./styles.js";
+// `<sheetViews>` holds the sheet's single view. A frozen view adds a `<pane>` recording the split
+// and a `<selection>` naming the pane the split activates, exactly as Excel writes it — a normal
+// view carries neither, so unfreezing leaves no leftover `<pane>` that would trip a repair prompt.
+// The active pane is whichever scrolling region the freeze creates: bottom-right when both axes are
+// frozen, else top-right (columns only) or bottom-left (rows only).
+//
+// `active` marks this sheet as the one selected on open (`tabSelected`). Exactly one sheet in a
+// workbook carries it — with none, the consumer opens with no sheet view initialised; with several,
+// the sheets form a *group selection*, where an edit to one is applied to all of them. The caller
+// (`worksheetXml`, fed from `Workbook.activeTabIndex`) is what guarantees the "exactly one".
+export function sheetViewsXml(view, active) {
+    const selected = active ? ' tabSelected="1"' : '';
+    const xSplit = view.xSplit ?? 0;
+    const ySplit = view.ySplit ?? 0;
+    if (view.state !== 'frozen' || (xSplit === 0 && ySplit === 0)) {
+        return `<sheetViews><sheetView${selected} workbookViewId="0"/></sheetViews>`;
+    }
+    const topLeftCell = view.topLeftCell ?? encodeAddress(xSplit + 1, ySplit + 1);
+    const activePane = xSplit > 0 && ySplit > 0 ? 'bottomRight' : xSplit > 0 ? 'topRight' : 'bottomLeft';
+    const pane = '<pane' +
+        (xSplit > 0 ? ` xSplit="${xSplit}"` : '') +
+        (ySplit > 0 ? ` ySplit="${ySplit}"` : '') +
+        ` topLeftCell="${escapeAttr(topLeftCell)}" activePane="${activePane}" state="frozen"/>`;
+    const selection = `<selection pane="${activePane}" activeCell="${escapeAttr(topLeftCell)}" sqref="${escapeAttr(topLeftCell)}"/>`;
+    return `<sheetViews><sheetView${selected} workbookViewId="0">${pane}${selection}</sheetView></sheetViews>`;
+}
+// `<sheetPr>` carries the sheet's appearance properties: the tab colour, the outline
+// summary-position flags, and the fit-to-page flag. It is the first child of `<worksheet>` in
+// CT_Worksheet order; its own children follow CT_SheetPr order — `<tabColor>`, `<outlinePr>`, then
+// `<pageSetUpPr>`. Omitted entirely when the sheet carries none, so an unadorned sheet stays
+// byte-clean.
+export function sheetPrXml(sheet) {
+    const children = (sheet.tabColor !== undefined ? `<tabColor ${colorAttrs(sheet.tabColor)}/>` : '') +
+        outlinePrXml(sheet.outline) +
+        pageSetUpPrXml(sheet.pageSetup);
+    return children === '' ? '' : `<sheetPr>${children}</sheetPr>`;
+}
+// `<pageSetUpPr>` holds the fit-to-page toggle, which lives on the sheet properties rather than on
+// `<pageSetup>` — Excel reads it from here to decide whether the `fitToWidth`/`fitToHeight` counts
+// or the fixed `scale` govern printing. Emitted only when the author set the flag.
+function pageSetUpPrXml(pageSetup) {
+    return pageSetup.fitToPage ? '<pageSetUpPr fitToPage="1"/>' : '';
+}
+// `<outlinePr>` carries only the summary-position flags today. Each is emitted solely when the
+// caller set it, so an inverted placement (`summaryBelow="0"`) is honoured while an untouched sheet
+// keeps the element out of the file entirely.
+function outlinePrXml(outline) {
+    const attrs = boolAttr('summaryBelow', outline.summaryBelow) + boolAttr('summaryRight', outline.summaryRight);
+    return attrs === '' ? '' : `<outlinePr${attrs}/>`;
+}
+// Each sheet-protection flag maps to a `<sheetProtection>` attribute whose value is INVERTED
+// from the author-facing allow-flag: the attribute records that an operation is *forbidden*
+// ("1"), so `allow: true` serialises as "0". Only a value that differs from OOXML's per-
+// attribute default (see SHEET_PROTECTION_FLAGS) is written — most editing operations default
+// to forbidden under protection, while selecting cells defaults to permitted.
+//
+// <sheetProtection> is what makes the per-cell locked/hidden flags bite. `sheet="1"` marks the
+// sheet protected; the password credential (when present) guards lifting it; the flag attributes
+// carve out the operations that stay available. base64 salt/hash use only XML-safe characters.
+export function sheetProtectionXml(protection) {
+    if (protection === undefined)
+        return '';
+    const { flags, credential } = protection;
+    let attrs = '';
+    if (credential !== undefined) {
+        attrs +=
+            ` algorithmName="${credential.algorithmName}"` +
+                ` hashValue="${credential.hashValue}"` +
+                ` saltValue="${credential.saltValue}"` +
+                ` spinCount="${credential.spinCount}"`;
+    }
+    attrs += ' sheet="1"';
+    for (const { key, defaultForbidden } of SHEET_PROTECTION_FLAGS) {
+        const allow = flags[key];
+        if (allow === undefined)
+            continue;
+        const forbidden = !allow;
+        if (forbidden === defaultForbidden)
+            continue;
+        attrs += boolAttr(key, forbidden);
+    }
+    return `<sheetProtection${attrs}/>`;
+}
+// The sheet's autofilter: `<autoFilter ref="A1:C10"/>` when it only draws dropdowns, or with nested
+// `<filterColumn>` children when columns carry criteria. Its companion `_FilterDatabase` defined name
+// (the range Excel derives filtering from) is written in the workbook part, so a sheet with no filter
+// emits nothing here and nothing there.
+export function autoFilterXml(filter) {
+    if (filter === undefined)
+        return '';
+    const ref = escapeAttr(filter.ref);
+    if (filter.columns.length === 0)
+        return `<autoFilter ref="${ref}"/>`;
+    return `<autoFilter ref="${ref}">${filter.columns.map(filterColumnXml).join('')}</autoFilter>`;
+}
+function filterColumnXml(column) {
+    return `<filterColumn colId="${column.colId}">${filterCriteriaXml(column.criteria)}</filterColumn>`;
+}
+// A values filter is `<filters>` with a `<filter val>` per allowed value (and `blank="1"` to admit
+// empty cells); a custom filter is `<customFilters>` with one or two `<customFilter operator val>`
+// predicates, `and="1"` when they are AND-combined rather than OR.
+function filterCriteriaXml(criteria) {
+    if (criteria.kind === 'values') {
+        const blankAttr = criteria.blank ? ' blank="1"' : '';
+        const filters = criteria.values.map((value) => `<filter val="${escapeAttr(value)}"/>`).join('');
+        return `<filters${blankAttr}>${filters}</filters>`;
+    }
+    const andAttr = criteria.and ? ' and="1"' : '';
+    const predicates = criteria.predicates
+        .map((p) => `<customFilter operator="${p.operator}" val="${escapeAttr(p.val)}"/>`)
+        .join('');
+    return `<customFilters${andAttr}>${predicates}</customFilters>`;
+}
+// CT_HeaderFooter child order, paired with the flag their presence gates: the even- and
+// first-page variants are silently ignored by Excel unless differentOddEven / differentFirst
+// are set, so the writer derives each flag from whether any variant in its class was provided.
+const HF_CHILDREN = [
+    { tag: 'oddHeader', key: 'oddHeader' },
+    { tag: 'oddFooter', key: 'oddFooter' },
+    { tag: 'evenHeader', key: 'evenHeader' },
+    { tag: 'evenFooter', key: 'evenFooter' },
+    { tag: 'firstHeader', key: 'firstHeader' },
+    { tag: 'firstFooter', key: 'firstFooter' },
+];
+export function headerFooterXml(hf) {
+    const children = HF_CHILDREN.filter(({ key }) => hf[key] !== undefined);
+    if (children.length === 0)
+        return '';
+    const differentOddEven = hf.evenHeader !== undefined || hf.evenFooter !== undefined;
+    const differentFirst = hf.firstHeader !== undefined || hf.firstFooter !== undefined;
+    let attrs = '';
+    if (differentOddEven)
+        attrs += ' differentOddEven="1"';
+    if (differentFirst)
+        attrs += ' differentFirst="1"';
+    const body = children
+        .map(({ tag, key }) => `<${tag}>${escapeText(hf[key])}</${tag}>`)
+        .join('');
+    return `<headerFooter${attrs}>${body}</headerFooter>`;
+}
+// Excel's "Normal" margins, in inches — the defaults Excel writes for an untouched sheet.
+const DEFAULT_MARGINS = {
+    left: 0.7,
+    right: 0.7,
+    top: 0.75,
+    bottom: 0.75,
+    header: 0.3,
+    footer: 0.3,
+};
+const MARGIN_SIDES = ['left', 'right', 'top', 'bottom', 'header', 'footer'];
+// `<printOptions>` carries the print-toggle flags and sits just before `<pageMargins>` in
+// CT_Worksheet order. Each attribute is emitted only when the model carries it — as an explicit
+// `="1"`/`="0"` so a caller can force a flag off against Excel's default — and an untouched sheet
+// keeps the element out of the file entirely.
+export function printOptionsXml(printOptions) {
+    const attrs = boolAttr('horizontalCentered', printOptions.horizontalCentered) +
+        boolAttr('verticalCentered', printOptions.verticalCentered) +
+        boolAttr('headings', printOptions.headings) +
+        boolAttr('gridLines', printOptions.gridLines) +
+        boolAttr('gridLinesSet', printOptions.gridLinesSet);
+    return attrs === '' ? '' : `<printOptions${attrs}/>`;
+}
+// OOXML's <pageMargins> is all-or-nothing: setting any one margin requires all six, or Excel
+// repairs the file. So the element is emitted only when the caller set at least one, and the
+// untouched sides fall back to the Normal-preset defaults.
+export function pageMarginsXml(margins) {
+    if (MARGIN_SIDES.every((side) => margins[side] === undefined))
+        return '';
+    const attrs = MARGIN_SIDES.map((side) => `${side}="${numberText(margins[side] ?? DEFAULT_MARGINS[side])}"`).join(' ');
+    return `<pageMargins ${attrs}/>`;
+}
+// `<pageSetup>` carries the print-scaling attributes (all but `fitToPage`, which is a `<sheetPr>`
+// flag). It sits between `<pageMargins>` and `<headerFooter>` in CT_Worksheet order. Each attribute
+// is emitted only when the author set it, so an untouched sheet keeps the element out of the file
+// and a partially-set one never fabricates the counts Excel would otherwise default. A non-null
+// `printerSettingsRelId` links the sheet's opaque printer-settings blob and forces the element out
+// even when no scaling attribute is set — the reference is the only thing the model has to carry.
+export function pageSetupXml(pageSetup, printerSettingsRelId) {
+    const attrs = attr('paperSize', pageSetup.paperSize) +
+        attr('scale', pageSetup.scale) +
+        attr('fitToWidth', pageSetup.fitToWidth) +
+        attr('fitToHeight', pageSetup.fitToHeight) +
+        (pageSetup.pageOrder !== undefined ? ` pageOrder="${pageSetup.pageOrder}"` : '') +
+        (pageSetup.orientation !== undefined ? ` orientation="${pageSetup.orientation}"` : '') +
+        (printerSettingsRelId !== null ? ` r:id="${printerSettingsRelId}"` : '');
+    return attrs === '' ? '' : `<pageSetup${attrs}/>`;
+}
+// Manual page breaks (`<rowBreaks>`/`<colBreaks>`): one `<brk>` per row/column the layout splits
+// before. Excel records both the running total (`count`) and the manual subset (`manualBreakCount`);
+// every break the model carries is a manual, author-set one, so the two counts coincide. `max` bounds
+// the break across the other axis (Excel writes the last row/column index); a break without one is
+// emitted bare. Row and column breaks share this shape, differing only in the wrapping element.
+export function pageBreaksXml(breaks, element) {
+    if (breaks.length === 0)
+        return '';
+    const brks = breaks
+        .map((brk) => {
+        const maxAttr = brk.max !== undefined ? ` max="${brk.max}"` : '';
+        return `<brk id="${brk.id}"${maxAttr} man="1"/>`;
+    })
+        .join('');
+    return `<${element} count="${breaks.length}" manualBreakCount="${breaks.length}">${brks}</${element}>`;
+}