@shbernal/ts-xlsx 3.0.0 → 3.2.0

package/dist/io/xlsx/tables.js

@@ -1,27 +1,23 @@
 import { encodeAddress, tryDecodeRange } from '../../core/address.js';
-import { isTotalsRowFunction, } from '../../core/table.js';
+import { mangleFormula, unmangleFunctions } from '../../core/formula.js';
+import { isTotalsRowFunction, TABLE_STYLE_FLAGS, } from '../../core/table.js';
+import { numInteger } from '../../xml/xml-attrs.js';
 import { parseXml, TextCapture } from '../../xml/xml-read.js';
-import { boolPresent, localName, numInteger } from '../../xml/xml-scan.js';
-import { boolAttr, escapeAttr, escapeText, XML_DECLARATION } from '../../xml/xml.js';
+import { boolTristate, localName } from '../../xml/xml-scan.js';
+import { boolAttr, checkedToken, escapeAttr, escapeText, XML_DECLARATION } from '../../xml/xml.js';
 import { NS } from './relationships.js';
-export function tableXml(table, id) {
+export function tableXml(table, id, formulaNames) {
     const name = escapeAttr(table.name);
-    const displayName = escapeAttr(table.displayName);
     const headerRowCount = table.headerRow ? '' : ' headerRowCount="0"';
-    let totals;
-    if (table.totalsRow) {
-        totals = ' totalsRowCount="1"';
-    }
-    else if (table.totalsRowShown !== undefined) {
-        totals = ` totalsRowShown="${table.totalsRowShown ? '1' : '0'}"`;
-    }
-    else {
-        totals = '';
-    }
+    const totals = table.totalsRow
+        ? ' totalsRowCount="1"'
+        : boolAttr('totalsRowShown', table.totalsRowShown);
     const autoFilter = table.autoFilterRef !== undefined ? `<autoFilter ref="${table.autoFilterRef}"/>` : '';
-    const columns = table.columns.map((column, i) => tableColumnXml(column, i + 1)).join('');
+    const columns = table.columns
+        .map((column, i) => tableColumnXml(column, i + 1, formulaNames))
+        .join('');
     return (XML_DECLARATION +
-        `<table xmlns="${NS.main}" id="${id}" name="${name}" displayName="${displayName}" ` +
+        `<table xmlns="${NS.main}" id="${id}" name="${name}" displayName="${name}" ` +
         `ref="${table.range}"${headerRowCount}${totals}>` +
         autoFilter +
         `<tableColumns count="${table.columns.length}">${columns}</tableColumns>` +
@@ -36,29 +32,32 @@ function tableStyleInfoXml(style) {
     let attrs = '';
     if (style.name !== undefined)
         attrs += ` name="${escapeAttr(style.name)}"`;
-    attrs +=
-        boolAttr('showFirstColumn', style.showFirstColumn) +
-            boolAttr('showLastColumn', style.showLastColumn) +
-            boolAttr('showRowStripes', style.showRowStripes) +
-            boolAttr('showColumnStripes', style.showColumnStripes);
+    attrs += TABLE_STYLE_FLAGS.map((flag) => boolAttr(flag, style[flag])).join('');
     return `<tableStyleInfo${attrs}/>`;
 }
-function tableColumnXml(column, id) {
+function tableColumnXml(column, id, formulaNames) {
     let attrs = `id="${id}" name="${escapeAttr(column.name)}"`;
     if (column.totalsRowLabel !== undefined) {
         attrs += ` totalsRowLabel="${escapeAttr(column.totalsRowLabel)}"`;
     }
     if (column.totalsRowFunction !== undefined) {
-        attrs += ` totalsRowFunction="${escapeAttr(column.totalsRowFunction)}"`;
+        attrs += ` totalsRowFunction="${checkedToken(column.totalsRowFunction, isTotalsRowFunction, 'totals row function')}"`;
+    }
+    let children = '';
+    if (column.calculatedColumnFormula !== undefined) {
+        const stored = mangleFormula(column.calculatedColumnFormula, formulaNames);
+        children += `<calculatedColumnFormula>${escapeText(stored)}</calculatedColumnFormula>`;
     }
     if (column.totalsRowFormula !== undefined) {
-        return `<tableColumn ${attrs}><totalsRowFormula>${escapeText(column.totalsRowFormula)}</totalsRowFormula></tableColumn>`;
+        const stored = mangleFormula(column.totalsRowFormula, formulaNames);
+        children += `<totalsRowFormula>${escapeText(stored)}</totalsRowFormula>`;
     }
-    return `<tableColumn ${attrs}/>`;
+    return children === ''
+        ? `<tableColumn ${attrs}/>`
+        : `<tableColumn ${attrs}>${children}</tableColumn>`;
 }
-export function parseTable(xml) {
+export function parseTable(xml, definedNames) {
     let name;
-    let displayName;
     let ref;
     let headerRowCount = 1;
     let totalsRowCount = 0;
@@ -66,18 +65,17 @@ export function parseTable(xml) {
     let style;
     let hasAutoFilter = false;
     const columns = [];
-    const totalsFormula = new TextCapture('totalsRowFormula');
+    let currentColumn;
+    const formula = new TextCapture(['totalsRowFormula', 'calculatedColumnFormula']);
     parseXml(xml, {
         onOpen(elementName, attrs, selfClosing) {
             switch (localName(elementName)) {
                 case 'table':
-                    name = attrs.name ?? attrs.displayName;
-                    displayName = attrs.displayName ?? attrs.name;
+                    name = attrs.displayName ?? attrs.name;
                     ref = attrs.ref;
                     headerRowCount = numInteger(attrs.headerRowCount, 0) ?? headerRowCount;
                     totalsRowCount = numInteger(attrs.totalsRowCount, 0) ?? totalsRowCount;
-                    if (attrs.totalsRowShown !== undefined)
-                        totalsRowShown = boolPresent(attrs.totalsRowShown);
+                    totalsRowShown = boolTristate(attrs.totalsRowShown);
                     break;
                 case 'autoFilter':
                     hasAutoFilter = true;
@@ -86,22 +84,21 @@ export function parseTable(xml) {
                     const captured = {};
                     if (attrs.name !== undefined)
                         captured.name = attrs.name;
-                    if (attrs.showFirstColumn !== undefined)
-                        captured.showFirstColumn = boolPresent(attrs.showFirstColumn);
-                    if (attrs.showLastColumn !== undefined)
-                        captured.showLastColumn = boolPresent(attrs.showLastColumn);
-                    if (attrs.showRowStripes !== undefined)
-                        captured.showRowStripes = boolPresent(attrs.showRowStripes);
-                    if (attrs.showColumnStripes !== undefined) {
-                        captured.showColumnStripes = boolPresent(attrs.showColumnStripes);
+                    for (const flag of TABLE_STYLE_FLAGS) {
+                        const value = boolTristate(attrs[flag]);
+                        if (value !== undefined)
+                            captured[flag] = value;
                     }
                     style = captured;
                     break;
                 }
                 case 'tableColumn': {
-                    if (attrs.name === undefined)
+                    if (attrs.name === undefined) {
+                        currentColumn = undefined;
                         break;
+                    }
                     const column = { name: attrs.name };
+                    currentColumn = column;
                     if (attrs.totalsRowLabel !== undefined)
                         column.totalsRowLabel = attrs.totalsRowLabel;
                     if (attrs.totalsRowFunction !== undefined &&
@@ -112,20 +109,24 @@ export function parseTable(xml) {
                     break;
                 }
                 case 'totalsRowFormula':
-                    totalsFormula.open('totalsRowFormula', selfClosing);
+                case 'calculatedColumnFormula':
+                    formula.open(localName(elementName), selfClosing);
                     break;
             }
         },
         onText(text) {
-            totalsFormula.text(text);
+            formula.text(text);
         },
         onClose(elementName) {
-            const formula = totalsFormula.close(localName(elementName));
-            if (formula === undefined)
+            const local = localName(elementName);
+            const text = formula.close(local);
+            if (text === undefined || currentColumn === undefined)
                 return;
-            const column = columns[columns.length - 1];
-            if (column !== undefined)
-                column.totalsRowFormula = formula;
+            const formulaText = unmangleFunctions(text, definedNames);
+            if (local === 'totalsRowFormula')
+                currentColumn.totalsRowFormula = formulaText;
+            else
+                currentColumn.calculatedColumnFormula = formulaText;
         },
     });
     if (name === undefined || ref === undefined || columns.length === 0)
@@ -133,15 +134,17 @@ export function parseTable(xml) {
     const decoded = tryDecodeRange(ref);
     if (decoded === undefined)
         return undefined;
-    const { top, left, bottom } = decoded;
-    if (top === undefined || left === undefined || bottom === undefined)
+    const { top, left, bottom, right } = decoded;
+    if (top === undefined || left === undefined || bottom === undefined || right === undefined) {
+        return undefined;
+    }
+    if (columns.length !== right - left + 1)
         return undefined;
     const headerRow = headerRowCount !== 0;
     const totalsRow = totalsRowCount > 0;
     const dataRows = bottom - top + 1 - (headerRow ? 1 : 0) - (totalsRow ? 1 : 0);
     const options = {
         name,
-        displayName: displayName ?? name,
         ref: encodeAddress(left, top),
         columns,
         rowCount: Math.max(0, dataRows),

package/dist/io/xlsx/theme-xml.d.ts

@@ -1,16 +1,35 @@
-import { type ThemeColorScheme, type ThemeFontScheme, type ThemeOverrides } from '../../core/theme.ts';
+import type { AssertNever } from '../../core/internal.ts';
+import { type ThemeColorScheme, type ThemeColorSlot, type ThemeFontScheme, type ThemeOverrides } from '../../core/theme.ts';
 /**
  * Extract the colour scheme from a theme part. Returns only the slots the part actually declares in a
  * colour model this reader understands; an unrecognised one is dropped rather than guessed at, so a
  * caller can tell "the theme says nothing here" from "the theme says black".
  *
- * Reads the `<a:clrScheme>` block alone. A theme carries a font scheme and a format scheme too, but
- * neither participates in resolving a colour, and scanning the whole part would let a `<a:srgbClr>`
+ * Reads the `<clrScheme>` block alone. A theme carries a font scheme and a format scheme too, but
+ * neither participates in resolving a colour, and scanning the whole part would let an `<srgbClr>`
  * buried in a gradient stop masquerade as a scheme slot.
  */
 export declare function parseThemeColorScheme(themeXml: string): ThemeColorScheme;
-/** Extract the major/minor latin typefaces from a theme part's `<a:fontScheme>`. */
+/** Extract the major/minor latin typefaces from a theme part's `<fontScheme>`. */
 export declare function parseThemeFontScheme(themeXml: string): ThemeFontScheme;
+/** {@link parseThemeColorScheme} and {@link parseThemeFontScheme} from one scan of the part, for the
+ * reader, which wants both. */
+export declare function parseThemeSchemes(themeXml: string): {
+    readonly colors: ThemeColorScheme;
+    readonly fonts: ThemeFontScheme;
+};
+declare const SCHEME_ELEMENT_ORDER: readonly ["dk1", "lt1", "dk2", "lt2", "accent1", "accent2", "accent3", "accent4", "accent5", "accent6", "hlink", "folHlink"];
+/**
+ * The half of the proof the list above owes: `satisfies` covers "no invented slot", this covers "no
+ * omission". A slot missing here is not a slot written in the wrong place -- it is a slot dropped
+ * from every rewritten `<a:clrScheme>`, verbatim source element and all, so a caller who authored it
+ * gets back a theme that silently does not carry it.
+ *
+ * This is the one list in the library where the schema order and the index order differ, which makes
+ * it the one a new slot is least likely to be added to by hand. `DEFAULT_THEME_COLOR_SCHEME` proves
+ * the same completeness on the model side.
+ */
+export type EverySlotIsInSchemaOrder = AssertNever<Exclude<ThemeColorSlot, (typeof SCHEME_ELEMENT_ORDER)[number]>>;
 /**
  * Apply authored colour/font overrides to a theme part, returning the new part text.
  *
@@ -24,6 +43,14 @@ export declare function parseThemeFontScheme(themeXml: string): ThemeFontScheme;
  * its value. That matters for `dk1`/`lt1`, which Excel writes as `<a:sysClr val="windowText"
  * lastClr="000000"/>`: rewriting those as `<a:srgbClr>` would pin them to one machine's resolved
  * window colours and break dark-mode following.
+ *
+ * The edit is made by *offset*, not by pattern. What it replaces was three container-scanning regular
+ * expressions in the one file whose own header condemns that pattern, on a path a preserved source
+ * theme's bytes reach: `[\s\S]*?` terminated on a `</clrScheme>` inside a comment, `[^>]*` missed a
+ * `<latin typeface="X"></latin>` and dropped the override silently, and the DrawingML prefix -- read
+ * out of the part's own root element, where an NCName may legally contain `.` and `-` -- was
+ * interpolated into the pattern unescaped. {@link elementRange} answers the same question with the
+ * scanner, and splicing at its offsets is what makes an unoverridden part come back byte for byte.
  */
 export declare function applyThemeOverrides(baseXml: string, overrides: ThemeOverrides): string;
 /**
@@ -35,3 +62,4 @@ export declare function applyThemeOverrides(baseXml: string, overrides: ThemeOve
  * built from scratch rather than read from a file.
  */
 export declare const DEFAULT_THEME_XML: string;
+export {};

package/dist/io/xlsx/theme-xml.js

@@ -1,41 +1,82 @@
-import { DEFAULT_THEME_COLOR_SCHEME, isThemeColorSlot, normalizeThemeColor, } from '../../core/theme.js';
-import { decodeEntities } from '../../xml/xml-scan.js';
-import { escapeAttr } from '../../xml/xml.js';
-const SCHEME_SLOT = new RegExp('<a:(dk1|lt1|dk2|lt2|accent[1-6]|hlink|folHlink)\\b[^>]*>' + '\\s*<a:(srgbClr|sysClr)\\b([^>]*)>', 'g');
-export function parseThemeColorScheme(themeXml) {
-    const block = /<a:clrScheme\b[^>]*>([\s\S]*?)<\/a:clrScheme>/.exec(themeXml);
-    if (block === null)
-        return {};
+import { DEFAULT_THEME_COLOR_SCHEME, isThemeColorSlot, isThemeRgb, } from '../../core/theme.js';
+import { elementRange, parseXml } from '../../xml/xml-read.js';
+import { localName } from '../../xml/xml-scan.js';
+import { startTag } from '../../xml/xml.js';
+const COLOR_ELEMENTS = new Set(['srgbClr', 'sysClr']);
+function readThemeScheme(themeXml) {
+    const colors = {};
+    const elements = {};
+    const fonts = {};
+    let prefix = '';
+    let container;
+    let slot;
+    let fontSlot;
+    parseXml(themeXml, {
+        onOpen(name, attrs) {
+            const local = localName(name);
+            if (local === 'theme') {
+                const colon = name.indexOf(':');
+                prefix = colon === -1 ? '' : name.slice(0, colon + 1);
+                return;
+            }
+            if (local === 'clrScheme' || local === 'fontScheme') {
+                container = local;
+                return;
+            }
+            if (container === 'clrScheme') {
+                if (isThemeColorSlot(local)) {
+                    slot = local;
+                }
+                else if (slot !== undefined && COLOR_ELEMENTS.has(local)) {
+                    const value = local === 'sysClr' ? attrs.lastClr : attrs.val;
+                    if (value !== undefined && isThemeRgb(value))
+                        colors[slot] = value.toUpperCase();
+                    elements[slot] = startTag(name, attrs, true);
+                    slot = undefined;
+                }
+                return;
+            }
+            if (container === 'fontScheme') {
+                if (local === 'majorFont')
+                    fontSlot = 'major';
+                else if (local === 'minorFont')
+                    fontSlot = 'minor';
+                else if (local === 'latin' && fontSlot !== undefined && attrs.typeface !== undefined) {
+                    fonts[fontSlot] ??= attrs.typeface;
+                }
+            }
+        },
+        onClose(name) {
+            const local = localName(name);
+            if (local === 'clrScheme' || local === 'fontScheme') {
+                container = undefined;
+                slot = undefined;
+                fontSlot = undefined;
+            }
+            else if (local === 'majorFont' || local === 'minorFont') {
+                fontSlot = undefined;
+            }
+            else if (slot !== undefined && local === slot) {
+                slot = undefined;
+            }
+        },
+    });
     const scheme = {};
-    for (const match of (block[1] ?? '').matchAll(SCHEME_SLOT)) {
-        const slot = match[1];
-        if (slot === undefined || !isThemeColorSlot(slot))
-            continue;
-        const attrs = match[3] ?? '';
-        const source = match[2] === 'sysClr' ? /\blastClr="([^"]*)"/ : /\bval="([^"]*)"/;
-        const value = source.exec(attrs)?.[1];
-        if (value !== undefined && /^[0-9a-fA-F]{6}$/.test(value))
-            scheme[slot] = value;
-    }
-    return scheme;
+    if (fonts.major !== undefined)
+        scheme.major = fonts.major;
+    if (fonts.minor !== undefined)
+        scheme.minor = fonts.minor;
+    return { colors, elements, fonts: scheme, prefix };
+}
+export function parseThemeColorScheme(themeXml) {
+    return readThemeScheme(themeXml).colors;
 }
 export function parseThemeFontScheme(themeXml) {
-    const block = /<a:fontScheme\b[^>]*>([\s\S]*?)<\/a:fontScheme>/.exec(themeXml);
-    if (block === null)
-        return {};
-    const face = (which) => {
-        const font = new RegExp(`<a:${which}\\b[^>]*>([\\s\\S]*?)</a:${which}>`).exec(block[1] ?? '');
-        const typeface = /<a:latin\b[^>]*\btypeface="([^"]*)"/.exec(font?.[1] ?? '')?.[1];
-        return typeface === undefined ? undefined : decodeEntities(typeface);
-    };
-    const scheme = {};
-    const major = face('majorFont');
-    const minor = face('minorFont');
-    if (major !== undefined)
-        scheme.major = major;
-    if (minor !== undefined)
-        scheme.minor = minor;
-    return scheme;
+    return readThemeScheme(themeXml).fonts;
+}
+export function parseThemeSchemes(themeXml) {
+    const { colors, fonts } = readThemeScheme(themeXml);
+    return { colors, fonts };
 }
 const SCHEME_ELEMENT_ORDER = [
     'dk1',
@@ -52,49 +93,43 @@ const SCHEME_ELEMENT_ORDER = [
     'folHlink',
 ];
 export function applyThemeOverrides(baseXml, overrides) {
-    let xml = baseXml;
+    const { elements: sourceElements, prefix } = readThemeScheme(baseXml);
+    const edits = [];
     const colors = overrides.colors ?? {};
     if (Object.keys(colors).length > 0) {
-        const sourceElements = parseThemeColorElements(baseXml);
-        const body = SCHEME_ELEMENT_ORDER.map((slot) => {
-            const authored = colors[slot];
-            const inner = authored !== undefined
-                ? `<a:srgbClr val="${normalizeThemeColor(authored)}"/>`
-                : (sourceElements[slot] ?? `<a:srgbClr val="${DEFAULT_THEME_COLOR_SCHEME[slot]}"/>`);
-            return `<a:${slot}>${inner}</a:${slot}>`;
-        }).join('');
-        xml = replaceBlockBody(xml, 'clrScheme', body);
+        const scheme = elementRange(baseXml, ['clrScheme']);
+        if (scheme !== undefined) {
+            const body = SCHEME_ELEMENT_ORDER.map((slot) => {
+                const authored = colors[slot];
+                const inner = authored !== undefined
+                    ? `<${prefix}srgbClr val="${authored}"/>`
+                    : (sourceElements[slot] ??
+                        `<${prefix}srgbClr val="${DEFAULT_THEME_COLOR_SCHEME[slot]}"/>`);
+                return `<${prefix}${slot}>${inner}</${prefix}${slot}>`;
+            }).join('');
+            edits.push({ start: scheme.contentStart, end: scheme.contentEnd, text: body });
+        }
     }
     const { major, minor } = overrides.fonts ?? {};
+    const latin = (which, typeface) => {
+        const found = elementRange(baseXml, [which, 'latin']);
+        if (found === undefined)
+            return;
+        edits.push({
+            start: found.start,
+            end: found.end,
+            text: startTag(found.name, { ...found.attrs, typeface }, true),
+        });
+    };
     if (major !== undefined)
-        xml = replaceLatinTypeface(xml, 'majorFont', major);
+        latin('majorFont', major);
     if (minor !== undefined)
-        xml = replaceLatinTypeface(xml, 'minorFont', minor);
-    return xml;
-}
-function parseThemeColorElements(themeXml) {
-    const block = /<a:clrScheme\b[^>]*>([\s\S]*?)<\/a:clrScheme>/.exec(themeXml);
-    if (block === null)
-        return {};
-    const elements = {};
-    const pattern = /<a:(dk1|lt1|dk2|lt2|accent[1-6]|hlink|folHlink)>([\s\S]*?)<\/a:\1>|<a:(dk1|lt1|dk2|lt2|accent[1-6]|hlink|folHlink)\/>/g;
-    for (const match of (block[1] ?? '').matchAll(pattern)) {
-        const slot = match[1] ?? match[3];
-        if (slot === undefined || !isThemeColorSlot(slot))
-            continue;
-        const inner = match[2];
-        if (inner !== undefined && inner !== '')
-            elements[slot] = inner;
+        latin('minorFont', minor);
+    let xml = baseXml;
+    for (const edit of edits.sort((a, b) => b.start - a.start)) {
+        xml = xml.slice(0, edit.start) + edit.text + xml.slice(edit.end);
     }
-    return elements;
-}
-function replaceBlockBody(xml, name, body) {
-    const pattern = new RegExp(`(<a:${name}\\b[^>]*>)[\\s\\S]*?(</a:${name}>)`);
-    return xml.replace(pattern, (_all, open, close) => `${open}${body}${close}`);
-}
-function replaceLatinTypeface(xml, which, typeface) {
-    const pattern = new RegExp(`(<a:${which}\\b[^>]*>[\\s\\S]*?<a:latin\\b)[^>]*(/>)`);
-    return xml.replace(pattern, (_all, open, close) => `${open} typeface="${escapeAttr(typeface)}"${close}`);
+    return xml;
 }
 export const DEFAULT_THEME_XML = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
     '<a:theme xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" name="Office Theme">' +

package/dist/io/xlsx/threaded-comments.d.ts

@@ -1,14 +1,12 @@
 import { type CommentThread, type MentionRef, type Person } from '../../core/comment-thread.ts';
-/** A registered author of threaded comments: one `<person>` of `xl/persons/person.xml`. */
-export interface ParsedPerson {
-    /** Brace-wrapped GUID a message's `personId` points at. */
-    readonly id: string;
-    readonly displayName: string;
-    /** Identity-provider handle, `S::<email>::<tenant-guid>` for an AzureAD account. */
-    readonly userId?: string;
-    /** Identity provider, e.g. `AD`. */
-    readonly providerId?: string;
-}
+/**
+ * A registered author of threaded comments: one `<person>` of `xl/persons/person.xml`, which is the
+ * model's own {@link Person} with nothing added. Declared as an alias for the same reason
+ * {@link ParsedMention} is: this file's write half already emits `Person` directly, so re-declaring
+ * the four fields here made one feature module name one shape two ways, with nothing keeping the two
+ * in step.
+ */
+export type ParsedPerson = Person;
 /**
  * One `<mention>` of a message's `<mentions>` block: the model's own {@link MentionRef}, which is
  * exactly the four wire attributes with nothing resolved yet. Declaring it a second time here would
@@ -80,8 +78,13 @@ export declare function buildCommentThreads(messages: readonly ParsedThreadedCom
  *
  * A thread with no messages writes nothing: it has neither text to say nor a head id for its replies and
  * its legacy fallback to hang off.
+ *
+ * A message with no author is written under the null GUID, Excel's own spelling for one. `personById` is
+ * the workbook's registry, and a message naming an id it does not hold is refused.
+ *
+ * @throws {AuthoringError} if a message's author is not a registered person.
  */
-export declare function threadedCommentsXml(threads: readonly CommentThread[]): string;
+export declare function threadedCommentsXml(threads: readonly CommentThread[], personById: (id: string) => Person | undefined): string;
 /**
  * Serialise the workbook's identity registry into `xl/persons/person.xml`: singular and unnumbered,
  * unlike the per-sheet thread parts.

package/dist/io/xlsx/threaded-comments.js

@@ -1,7 +1,9 @@
 import { encodeAddress, tryDecodeCellRef } from '../../core/address.js';
 import { MENTION_OFFSET_MAX, } from '../../core/comment-thread.js';
+import { AuthoringError, quoted } from '../../errors.js';
+import { decodeSpreadsheetText, numInteger } from '../../xml/xml-attrs.js';
 import { parseXml, TextCapture } from '../../xml/xml-read.js';
-import { boolStrict, decodeSpreadsheetText, localName, numInteger, } from '../../xml/xml-scan.js';
+import { boolStrict, localName } from '../../xml/xml-scan.js';
 import { escapeAttr, escapeSpreadsheetText, textAttr, XML_DECLARATION } from '../../xml/xml.js';
 import { THREADED_COMMENTS_NS } from './namespaces.js';
 export function parsePersons(xml) {
@@ -131,8 +133,7 @@ function commentFrom(message, personById) {
         id: message.id,
         text: message.text,
         mentions: message.mentions.map((mention) => mentionOf(mention, personById)),
-        ...(author !== undefined ? { author } : {}),
-        ...(message.personId !== undefined ? { personId: message.personId } : {}),
+        ...(author !== undefined ? { author, personId: author.id } : {}),
         ...(message.date !== undefined ? { date: message.date } : {}),
     };
 }
@@ -146,27 +147,34 @@ function mentionOf(mention, personById) {
         ...(mention.mentionId !== undefined ? { mentionId: mention.mentionId } : {}),
     };
 }
-export function threadedCommentsXml(threads) {
+export function threadedCommentsXml(threads, personById) {
     const messages = threads.flatMap((thread) => {
         const [head, ...replies] = thread.comments;
         if (head === undefined)
             return [];
         return [
-            threadedCommentXml(thread.ref, head, thread.resolved ? ' done="1"' : ''),
-            ...replies.map((reply) => threadedCommentXml(thread.ref, reply, ` parentId="${escapeAttr(head.id)}"`)),
+            threadedCommentXml(thread.ref, head, thread.resolved ? ' done="1"' : '', personById),
+            ...replies.map((reply) => threadedCommentXml(thread.ref, reply, ` parentId="${escapeAttr(head.id)}"`, personById)),
         ];
     });
     return (XML_DECLARATION +
         `<ThreadedComments xmlns="${THREADED_COMMENTS_NS}">${messages.join('')}</ThreadedComments>`);
 }
-function threadedCommentXml(ref, comment, tail) {
+function threadedCommentXml(ref, comment, tail, personById) {
     const date = textAttr('dT', comment.date);
-    const person = textAttr('personId', comment.personId);
+    const personId = comment.personId ?? UNKNOWN_AUTHOR;
+    if (personId !== UNKNOWN_AUTHOR && personById(personId) === undefined) {
+        throw new AuthoringError(`cannot write the threaded comment ${quoted(comment.id)}: its author ${quoted(personId)} is not ` +
+            'a registered person. Register it with Workbook.addPerson, or leave personId out for a ' +
+            'comment with no recorded author');
+    }
+    const person = textAttr('personId', personId);
     return (`<threadedComment ref="${escapeAttr(ref)}"${date}${person} id="${escapeAttr(comment.id)}"${tail}>` +
         `<text>${escapeSpreadsheetText(comment.text)}</text>` +
         mentionsXml(comment.mentions) +
         '</threadedComment>');
 }
+const UNKNOWN_AUTHOR = '{00000000-0000-0000-0000-000000000000}';
 function mentionsXml(mentions) {
     const entries = mentions.flatMap(({ personId, mentionId, startIndex, length }) => {
         if (mentionId === undefined)

package/dist/io/xlsx/workbook-xml.d.ts

@@ -1,12 +1,51 @@
 import type { Workbook, WorkbookProperties } from '../../core/workbook.ts';
-import type { PivotPlan, PreservedPartPlan, PreservedRootReferencePlan, PreservedWorkbookReferencePlan, TablePlan } from './package-plan.ts';
+import type { PivotPlan, PlannedRelationship, PreservedPartPlan, PreservedWorkbookReferencePlan, TablePlan } from './package-plan.ts';
 export type PreservedWorkbookRel = PreservedWorkbookReferencePlan & {
     readonly relId: string;
 };
-export declare function contentTypesXml(sheetCount: number, tables: readonly TablePlan[], commentNumbers: readonly number[], drawingNumbers: readonly number[], printerSettingsNumbers: readonly number[], mediaExtensions: readonly string[], hasSharedStrings: boolean, preservedParts: readonly PreservedPartPlan[], pivots: readonly PivotPlan[], preservedWorkbookRefs: readonly PreservedWorkbookReferencePlan[], threadedCommentNumbers: readonly number[], hasPersons: boolean): string;
-export declare function rootRelsXml(rootRefs: readonly PreservedRootReferencePlan[]): string;
-export declare function workbookXml(workbook: Workbook, preservedRels: readonly PreservedWorkbookRel[], pivots: readonly PivotPlan[]): string;
-export declare const FIXED_WORKBOOK_REL_COUNT = 2;
-export declare function workbookRelsXml(sheetCount: number, hasSharedStrings: boolean, personsRelId: string | null, preservedRels: readonly PreservedWorkbookRel[], pivots: readonly PivotPlan[]): string;
+/**
+ * The workbook part's relationships, recorded once by the writer's `planWorkbookRelationships`, with
+ * the ids the workbook body cites picked out of them.
+ *
+ * Declared here because the body is the consumer of the ids: it references them from `<sheet r:id>`.
+ * The body used to spell that reference `rId${i + 1}`, which agreed with the allocator only because
+ * sheets happen to be the first ids it hands out. Anything laid ahead of them would have re-pointed
+ * every sheet at the wrong part, and the package would have stayed schema-valid while doing it -- a
+ * class of corruption no validator catches and no round-trip through this library notices, because
+ * the reader resolves the same wrong ids consistently.
+ */
+export interface WorkbookRelPlan {
+    readonly sheetRelIds: readonly string[];
+    readonly preservedWorkbookRels: readonly PreservedWorkbookRel[];
+    /** Every relationship the workbook's `.rels` part declares, in id order. */
+    readonly relationships: readonly PlannedRelationship[];
+}
+/**
+ * What `[Content_Types].xml` needs to know about a package: every part family it declares.
+ *
+ * One object rather than twelve positional parameters, eight of them arrays and four of those bare
+ * `readonly number[]`, which two adjacent ones could be silently transposed between. That is the same
+ * hazard `SheetReferences`, `SheetPlan` and `WorksheetXmlInputs` remove elsewhere in this writer, and
+ * it travels the whole way down: the two functions that render from this take it as it stands rather
+ * than re-scattering its fields across their own parameter lists.
+ */
+export interface ContentTypeInputs {
+    readonly sheetCount: number;
+    readonly tables: readonly TablePlan[];
+    readonly commentNumbers: readonly number[];
+    readonly drawingNumbers: readonly number[];
+    readonly printerSettingsNumbers: readonly number[];
+    readonly mediaExtensions: readonly string[];
+    readonly hasSharedStrings: boolean;
+    readonly preservedParts: readonly PreservedPartPlan[];
+    readonly pivots: readonly PivotPlan[];
+    readonly preservedWorkbookRefs: readonly PreservedWorkbookReferencePlan[];
+    readonly threadedCommentNumbers: readonly number[];
+    readonly hasPersons: boolean;
+    readonly hasCellMetadata: boolean;
+    readonly hasRichValues: boolean;
+}
+export declare function contentTypesXml(inputs: ContentTypeInputs): string;
+export declare function workbookXml(workbook: Workbook, plan: WorkbookRelPlan, pivots: readonly PivotPlan[]): string;
 export declare function corePropsXml(properties: WorkbookProperties): string;
 export declare function appPropsXml(properties: WorkbookProperties): string;