ooxml.js 2.12.2 → 2.13.0

package/README.md

@@ -106,7 +106,7 @@ const doc = readDocx(decodePackage(bytes));
 // inside tables); each run already carries its cascade-resolved bold/italic/colour/font.
 ```
 
-`readXlsx` is the lossy, cell-values-only view. `readXlsxContent`/`buildXlsxPackage` are a separate `ContentDocument`-shaped pair — a richer reader (column widths, row heights, hidden rows/columns, merged ranges, every cell value kind, print settings) matched with this package's first writer, round-tripping a spreadsheet through the same `ContentDocument` shape `documents.js`/`odf.js` use:
+`readXlsx` is the lossy, cell-values-only view. `readXlsxContent`/`buildXlsxPackage` are a separate `ContentDocument`-shaped pair — a richer reader (column widths, row heights, hidden rows/columns, merged ranges, every cell value kind, cell comments, print settings) matched with this package's first writer, round-tripping a spreadsheet through the same `ContentDocument` shape `documents.js`/`odf.js` use:
 
 ```ts
 import { buildXlsxPackage, decodePackage, readXlsxContent } from 'ooxml.js';
@@ -229,7 +229,7 @@ The package layers a lossless core outward to lossy convenience views:
 - **`src/codec.ts`** — public round-trip surface: `packageCodec`/`xmlCodec` (`z.codec()` pairs) plus `decodePackage`/`encodePackage` wrappers.
 - **`src/compact.ts`** — the ooxml.js format: `compactCodec`/`compactPackageCodec` plus `toCompact`/`fromCompact`/`decodeCompactPackage`/`encodeCompactPackage` wrappers.
 - **`src/typed/`** — one-way, lossy projections. `readDocx` resolves the full style cascade (`docDefaults` → `basedOn` → paragraph-mark → character styles → direct formatting) into ordered `sections` plus comments/footnotes/headers/footers/numbering; `readPptx` resolves placeholder → layout → master → theme inheritance into `slides` (presentation order via `p:sldIdLst`); `readXlsx` covers cell values/formulas, merged ranges, defined names. `typed/shared/` holds shared OOXML primitives (`drawingml.ts` geometry/theme/colour, `color.ts` `ColorTransform` cascade, `units.ts`, `metadata.ts`, `source-path.ts`). Types come from `document-schema.js`. None encodes back to a `Package` — round-trip goes through `decodePackage`/`encodePackage` (see `src/typed/xlsx/` for the one write-back exception).
-- **`src/typed/xlsx/`** — a `ContentDocument`-shaped read/write pair alongside the lossy `readXlsx` (both exported; different callers). `readXlsxContent` reads column widths, row heights, hidden rows/columns, merged ranges, every cell value kind, print settings; `buildXlsxPackage` builds a complete xlsx `Package` from scratch (never editing the decoded package). `number-format.ts`/`styles.ts`/`serial.ts` run both ways: reading classifies style index → format code → kind (`percentage`/`currency`/`date`/`time`/`dateTime`); writing emits interned `numFmt` codes, fed back through the classifier in tests. The classifier is not a formatter (`displayText` is the typed-value spelling). Scope limits: `currency` with no ISO code writes as plain `number`; non-canonical temporal values degrade to text.
+- **`src/typed/xlsx/`** — a `ContentDocument`-shaped read/write pair alongside the lossy `readXlsx` (both exported; different callers). `readXlsxContent` reads column widths, row heights, hidden rows/columns, merged ranges, every cell value kind, print settings, and cell comments (`comments.ts`: legacy `xl/comments{N}.xml` notes plus `[MS-XLSX]` threaded comments, both resolved through the worksheet part's own relationships, never by part name); `buildXlsxPackage` builds a complete xlsx `Package` from scratch (never editing the decoded package). `number-format.ts`/`styles.ts`/`serial.ts` run both ways: reading classifies style index → format code → kind (`percentage`/`currency`/`date`/`time`/`dateTime`); writing emits interned `numFmt` codes, fed back through the classifier in tests. The classifier is not a formatter (`displayText` is the typed-value spelling). Scope limits: `currency` with no ISO code writes as plain `number`; non-canonical temporal values degrade to text; cell comments read but do not write (`buildXlsxPackage` emits no comment part, so they do not survive this pair).
 
 ## Conventions
 

package/dist/typed/xlsx/comments.cjs

@@ -0,0 +1,139 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_typed_util = require("../util.cjs");
+let document_schema_js = require("document-schema.js");
+//#region src/typed/xlsx/comments.ts
+const REL_COMMENTS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
+const REL_THREADED_COMMENTS = "http://schemas.microsoft.com/office/2017/10/relationships/threadedComment";
+const REL_PERSON = "http://schemas.microsoft.com/office/2017/10/relationships/person";
+function localName(tag) {
+	const colon = tag.lastIndexOf(":");
+	return colon === -1 ? tag : tag.slice(colon + 1);
+}
+function childrenWithLocalName(element, local) {
+	const out = [];
+	for (const child of element.children) if (child.type === "element" && localName(child.tag) === local) out.push(child);
+	return out;
+}
+function normalizeGuid(value) {
+	return value.replaceAll("{", "").replaceAll("}", "").toLowerCase();
+}
+function relatedPartPaths(pkg, partPath, relType) {
+	const paths = [];
+	for (const rel of require_typed_util.resolveRelationships(pkg, partPath).values()) if (rel.type === relType) paths.push(rel.target);
+	return paths;
+}
+function readLegacyCommentText(text) {
+	let value = "";
+	for (const t of require_typed_util.elementsWithTag(text.children, "t")) value += require_typed_util.textContent(t);
+	return value === "" ? require_typed_util.textContent(text) : value;
+}
+function readLegacyComments(pkg, sheetPath, into) {
+	for (const path of relatedPartPaths(pkg, sheetPath, REL_COMMENTS)) {
+		const root = require_typed_util.rootElement(pkg.parts[path]);
+		if (root === void 0) continue;
+		const authorsEl = require_typed_util.childrenWithTag(root, "authors")[0];
+		const authors = authorsEl === void 0 ? [] : require_typed_util.childrenWithTag(authorsEl, "author").map(require_typed_util.textContent);
+		const commentList = require_typed_util.childrenWithTag(root, "commentList")[0];
+		if (commentList === void 0) continue;
+		for (const comment of require_typed_util.childrenWithTag(commentList, "comment")) {
+			const ref = require_typed_util.attr(comment, "ref");
+			const position = ref === void 0 ? void 0 : (0, document_schema_js.parseCellReference)(ref);
+			const textEl = require_typed_util.childrenWithTag(comment, "text")[0];
+			if (position === void 0 || textEl === void 0) continue;
+			const entry = { text: readLegacyCommentText(textEl) };
+			const authorIdRaw = require_typed_util.attr(comment, "authorId");
+			const authorIndex = authorIdRaw === void 0 ? void 0 : Number.parseInt(authorIdRaw, 10);
+			const author = authorIndex === void 0 ? void 0 : authors[authorIndex];
+			if (author !== void 0) entry.author = author;
+			into.set(`${position.row}:${position.column}`, {
+				row: position.row,
+				column: position.column,
+				comment: entry
+			});
+		}
+	}
+}
+function readPersons(pkg, sheetPath) {
+	const persons = /* @__PURE__ */ new Map();
+	for (const path of relatedPartPaths(pkg, sheetPath, REL_PERSON)) {
+		const root = require_typed_util.rootElement(pkg.parts[path]);
+		if (root === void 0) continue;
+		for (const person of childrenWithLocalName(root, "person")) {
+			const id = require_typed_util.attr(person, "id");
+			const displayName = require_typed_util.attr(person, "displayName");
+			if (id !== void 0 && displayName !== void 0) persons.set(normalizeGuid(id), displayName);
+		}
+	}
+	return persons;
+}
+function readThreadedAuthor(element, persons) {
+	const displayName = require_typed_util.attr(element, "displayName");
+	if (displayName !== void 0) return displayName;
+	const personId = require_typed_util.attr(element, "personId");
+	return personId === void 0 ? void 0 : persons.get(normalizeGuid(personId));
+}
+function readThreadedCreatedAt(element) {
+	const dT = require_typed_util.attr(element, "dT");
+	if (dT !== void 0) return dT;
+	const dCreation = require_typed_util.attr(element, "dCreation");
+	if (dCreation === void 0) return;
+	const ms = Number(dCreation);
+	return Number.isFinite(ms) ? new Date(ms).toISOString() : void 0;
+}
+function readThreadedComments(pkg, sheetPath, into) {
+	const partPaths = relatedPartPaths(pkg, sheetPath, REL_THREADED_COMMENTS);
+	if (partPaths.length === 0) return;
+	const persons = readPersons(pkg, sheetPath);
+	for (const path of partPaths) {
+		const root = require_typed_util.rootElement(pkg.parts[path]);
+		if (root === void 0) continue;
+		const groups = /* @__PURE__ */ new Map();
+		for (const element of childrenWithLocalName(root, "threadedComment")) {
+			const ref = require_typed_util.attr(element, "ref");
+			const position = ref === void 0 ? void 0 : (0, document_schema_js.parseCellReference)(ref);
+			const textEl = childrenWithLocalName(element, "text")[0];
+			if (position === void 0 || textEl === void 0) continue;
+			const entry = {
+				row: position.row,
+				column: position.column,
+				text: require_typed_util.textContent(textEl)
+			};
+			const author = readThreadedAuthor(element, persons);
+			if (author !== void 0) entry.author = author;
+			const createdAt = readThreadedCreatedAt(element);
+			if (createdAt !== void 0) entry.createdAt = createdAt;
+			const parentId = require_typed_util.attr(element, "parentId") ?? require_typed_util.attr(element, "parent");
+			if (parentId !== void 0) entry.parentId = parentId;
+			const key = `${position.row}:${position.column}`;
+			const group = groups.get(key);
+			if (group === void 0) groups.set(key, [entry]);
+			else group.push(entry);
+		}
+		for (const [key, group] of groups) {
+			const rootEntry = group.find((entry) => entry.parentId === void 0) ?? group.at(0);
+			if (rootEntry === void 0) continue;
+			const comment = { text: rootEntry.text };
+			if (rootEntry.author !== void 0) comment.author = rootEntry.author;
+			if (rootEntry.createdAt !== void 0) comment.createdAt = rootEntry.createdAt;
+			const replies = group.filter((entry) => entry !== rootEntry);
+			if (replies.length > 0) comment.replies = replies.map((reply) => {
+				const answer = { text: reply.text };
+				if (reply.author !== void 0) answer.author = reply.author;
+				return answer;
+			});
+			into.set(key, {
+				row: rootEntry.row,
+				column: rootEntry.column,
+				comment
+			});
+		}
+	}
+}
+function readSheetCellComments(pkg, sheetPath) {
+	const comments = /* @__PURE__ */ new Map();
+	readLegacyComments(pkg, sheetPath, comments);
+	readThreadedComments(pkg, sheetPath, comments);
+	return comments;
+}
+//#endregion
+exports.readSheetCellComments = readSheetCellComments;

package/dist/typed/xlsx/comments.d.cts

@@ -0,0 +1,11 @@
+import { r as Package } from "../../package-L24lkba-.cjs";
+import { ContentSheetCellComment } from "document-schema.js";
+//#region src/typed/xlsx/comments.d.ts
+interface SheetCellComment {
+  row: number;
+  column: number;
+  comment: ContentSheetCellComment;
+}
+declare function readSheetCellComments(pkg: Package, sheetPath: string): Map<string, SheetCellComment>;
+//#endregion
+export { SheetCellComment, readSheetCellComments };

package/dist/typed/xlsx/comments.d.ts

@@ -0,0 +1,11 @@
+import { r as Package } from "../../package-BUojjTXf.js";
+import { ContentSheetCellComment } from "document-schema.js";
+//#region src/typed/xlsx/comments.d.ts
+interface SheetCellComment {
+  row: number;
+  column: number;
+  comment: ContentSheetCellComment;
+}
+declare function readSheetCellComments(pkg: Package, sheetPath: string): Map<string, SheetCellComment>;
+//#endregion
+export { SheetCellComment, readSheetCellComments };

package/dist/typed/xlsx/comments.js

@@ -0,0 +1,138 @@
+import { attr, childrenWithTag, elementsWithTag, resolveRelationships, rootElement, textContent } from "../util.js";
+import { parseCellReference } from "document-schema.js";
+//#region src/typed/xlsx/comments.ts
+const REL_COMMENTS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
+const REL_THREADED_COMMENTS = "http://schemas.microsoft.com/office/2017/10/relationships/threadedComment";
+const REL_PERSON = "http://schemas.microsoft.com/office/2017/10/relationships/person";
+function localName(tag) {
+	const colon = tag.lastIndexOf(":");
+	return colon === -1 ? tag : tag.slice(colon + 1);
+}
+function childrenWithLocalName(element, local) {
+	const out = [];
+	for (const child of element.children) if (child.type === "element" && localName(child.tag) === local) out.push(child);
+	return out;
+}
+function normalizeGuid(value) {
+	return value.replaceAll("{", "").replaceAll("}", "").toLowerCase();
+}
+function relatedPartPaths(pkg, partPath, relType) {
+	const paths = [];
+	for (const rel of resolveRelationships(pkg, partPath).values()) if (rel.type === relType) paths.push(rel.target);
+	return paths;
+}
+function readLegacyCommentText(text) {
+	let value = "";
+	for (const t of elementsWithTag(text.children, "t")) value += textContent(t);
+	return value === "" ? textContent(text) : value;
+}
+function readLegacyComments(pkg, sheetPath, into) {
+	for (const path of relatedPartPaths(pkg, sheetPath, REL_COMMENTS)) {
+		const root = rootElement(pkg.parts[path]);
+		if (root === void 0) continue;
+		const authorsEl = childrenWithTag(root, "authors")[0];
+		const authors = authorsEl === void 0 ? [] : childrenWithTag(authorsEl, "author").map(textContent);
+		const commentList = childrenWithTag(root, "commentList")[0];
+		if (commentList === void 0) continue;
+		for (const comment of childrenWithTag(commentList, "comment")) {
+			const ref = attr(comment, "ref");
+			const position = ref === void 0 ? void 0 : parseCellReference(ref);
+			const textEl = childrenWithTag(comment, "text")[0];
+			if (position === void 0 || textEl === void 0) continue;
+			const entry = { text: readLegacyCommentText(textEl) };
+			const authorIdRaw = attr(comment, "authorId");
+			const authorIndex = authorIdRaw === void 0 ? void 0 : Number.parseInt(authorIdRaw, 10);
+			const author = authorIndex === void 0 ? void 0 : authors[authorIndex];
+			if (author !== void 0) entry.author = author;
+			into.set(`${position.row}:${position.column}`, {
+				row: position.row,
+				column: position.column,
+				comment: entry
+			});
+		}
+	}
+}
+function readPersons(pkg, sheetPath) {
+	const persons = /* @__PURE__ */ new Map();
+	for (const path of relatedPartPaths(pkg, sheetPath, REL_PERSON)) {
+		const root = rootElement(pkg.parts[path]);
+		if (root === void 0) continue;
+		for (const person of childrenWithLocalName(root, "person")) {
+			const id = attr(person, "id");
+			const displayName = attr(person, "displayName");
+			if (id !== void 0 && displayName !== void 0) persons.set(normalizeGuid(id), displayName);
+		}
+	}
+	return persons;
+}
+function readThreadedAuthor(element, persons) {
+	const displayName = attr(element, "displayName");
+	if (displayName !== void 0) return displayName;
+	const personId = attr(element, "personId");
+	return personId === void 0 ? void 0 : persons.get(normalizeGuid(personId));
+}
+function readThreadedCreatedAt(element) {
+	const dT = attr(element, "dT");
+	if (dT !== void 0) return dT;
+	const dCreation = attr(element, "dCreation");
+	if (dCreation === void 0) return;
+	const ms = Number(dCreation);
+	return Number.isFinite(ms) ? new Date(ms).toISOString() : void 0;
+}
+function readThreadedComments(pkg, sheetPath, into) {
+	const partPaths = relatedPartPaths(pkg, sheetPath, REL_THREADED_COMMENTS);
+	if (partPaths.length === 0) return;
+	const persons = readPersons(pkg, sheetPath);
+	for (const path of partPaths) {
+		const root = rootElement(pkg.parts[path]);
+		if (root === void 0) continue;
+		const groups = /* @__PURE__ */ new Map();
+		for (const element of childrenWithLocalName(root, "threadedComment")) {
+			const ref = attr(element, "ref");
+			const position = ref === void 0 ? void 0 : parseCellReference(ref);
+			const textEl = childrenWithLocalName(element, "text")[0];
+			if (position === void 0 || textEl === void 0) continue;
+			const entry = {
+				row: position.row,
+				column: position.column,
+				text: textContent(textEl)
+			};
+			const author = readThreadedAuthor(element, persons);
+			if (author !== void 0) entry.author = author;
+			const createdAt = readThreadedCreatedAt(element);
+			if (createdAt !== void 0) entry.createdAt = createdAt;
+			const parentId = attr(element, "parentId") ?? attr(element, "parent");
+			if (parentId !== void 0) entry.parentId = parentId;
+			const key = `${position.row}:${position.column}`;
+			const group = groups.get(key);
+			if (group === void 0) groups.set(key, [entry]);
+			else group.push(entry);
+		}
+		for (const [key, group] of groups) {
+			const rootEntry = group.find((entry) => entry.parentId === void 0) ?? group.at(0);
+			if (rootEntry === void 0) continue;
+			const comment = { text: rootEntry.text };
+			if (rootEntry.author !== void 0) comment.author = rootEntry.author;
+			if (rootEntry.createdAt !== void 0) comment.createdAt = rootEntry.createdAt;
+			const replies = group.filter((entry) => entry !== rootEntry);
+			if (replies.length > 0) comment.replies = replies.map((reply) => {
+				const answer = { text: reply.text };
+				if (reply.author !== void 0) answer.author = reply.author;
+				return answer;
+			});
+			into.set(key, {
+				row: rootEntry.row,
+				column: rootEntry.column,
+				comment
+			});
+		}
+	}
+}
+function readSheetCellComments(pkg, sheetPath) {
+	const comments = /* @__PURE__ */ new Map();
+	readLegacyComments(pkg, sheetPath, comments);
+	readThreadedComments(pkg, sheetPath, comments);
+	return comments;
+}
+//#endregion
+export { readSheetCellComments };

package/dist/typed/xlsx/content.cjs

@@ -8,6 +8,7 @@ const require_typed_xlsx_util = require("./util.cjs");
 const require_typed_xlsx_print_settings = require("./print-settings.cjs");
 const require_typed_xlsx_serial = require("./serial.cjs");
 const require_typed_xlsx_styles = require("./styles.cjs");
+const require_typed_xlsx_comments = require("./comments.cjs");
 const require_typed_xlsx_units = require("./units.cjs");
 let document_schema_js = require("document-schema.js");
 //#region src/typed/xlsx/content.ts
@@ -296,6 +297,27 @@ function readCells(worksheet, sharedStrings, context) {
 	applyMergedRanges(worksheet, cells);
 	return cells;
 }
+function applyCellComments(comments, cells) {
+	if (comments.size === 0) return;
+	const byPosition = /* @__PURE__ */ new Map();
+	for (const cell of cells) byPosition.set(`${cell.row}:${cell.column}`, cell);
+	for (const [key, { row, column, comment }] of comments) {
+		const existing = byPosition.get(key);
+		if (existing !== void 0) {
+			existing.comment = comment;
+			continue;
+		}
+		const materialised = {
+			row,
+			column,
+			value: { kind: "empty" },
+			displayText: "",
+			comment
+		};
+		cells.push(materialised);
+		byPosition.set(key, materialised);
+	}
+}
 function readSheet(pkg, entry, sheetIndex, sharedStrings, definedNamesBySheet, context) {
 	const worksheet = require_typed_util.rootElement(pkg.parts[entry.path]);
 	if (worksheet === void 0) return {
@@ -306,9 +328,11 @@ function readSheet(pkg, entry, sheetIndex, sharedStrings, definedNamesBySheet, c
 		images: [],
 		printSettings: require_typed_xlsx_print_settings.readPrintSettings(fallbackEmptyWorksheet(), sheetIndex, definedNamesBySheet)
 	};
+	const cells = readCells(worksheet, sharedStrings, context);
+	applyCellComments(require_typed_xlsx_comments.readSheetCellComments(pkg, entry.path), cells);
 	return {
 		name: entry.name,
-		cells: readCells(worksheet, sharedStrings, context),
+		cells,
 		columns: readColumns(worksheet),
 		rows: readRows(worksheet),
 		images: [],

package/dist/typed/xlsx/content.js

@@ -7,6 +7,7 @@ import { readXmlBool } from "./util.js";
 import { readPrintSettings } from "./print-settings.js";
 import { readDate1904, serialToIsoDate, serialToIsoDateTime, serialToIsoTime } from "./serial.js";
 import { readCellStyles } from "./styles.js";
+import { readSheetCellComments } from "./comments.js";
 import { columnWidthCharsToPt } from "./units.js";
 import { CONTENT_FORMAT_VERSION, parseCellReference, parseRangeReference } from "document-schema.js";
 //#region src/typed/xlsx/content.ts
@@ -295,6 +296,27 @@ function readCells(worksheet, sharedStrings, context) {
 	applyMergedRanges(worksheet, cells);
 	return cells;
 }
+function applyCellComments(comments, cells) {
+	if (comments.size === 0) return;
+	const byPosition = /* @__PURE__ */ new Map();
+	for (const cell of cells) byPosition.set(`${cell.row}:${cell.column}`, cell);
+	for (const [key, { row, column, comment }] of comments) {
+		const existing = byPosition.get(key);
+		if (existing !== void 0) {
+			existing.comment = comment;
+			continue;
+		}
+		const materialised = {
+			row,
+			column,
+			value: { kind: "empty" },
+			displayText: "",
+			comment
+		};
+		cells.push(materialised);
+		byPosition.set(key, materialised);
+	}
+}
 function readSheet(pkg, entry, sheetIndex, sharedStrings, definedNamesBySheet, context) {
 	const worksheet = rootElement(pkg.parts[entry.path]);
 	if (worksheet === void 0) return {
@@ -305,9 +327,11 @@ function readSheet(pkg, entry, sheetIndex, sharedStrings, definedNamesBySheet, c
 		images: [],
 		printSettings: readPrintSettings(fallbackEmptyWorksheet(), sheetIndex, definedNamesBySheet)
 	};
+	const cells = readCells(worksheet, sharedStrings, context);
+	applyCellComments(readSheetCellComments(pkg, entry.path), cells);
 	return {
 		name: entry.name,
-		cells: readCells(worksheet, sharedStrings, context),
+		cells,
 		columns: readColumns(worksheet),
 		rows: readRows(worksheet),
 		images: [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ooxml.js",
-  "version": "2.12.2",
+  "version": "2.13.0",
   "description": "Type-safe, lossless round-trip conversion between OOXML packages (docx, pptx, xlsx) and JSON, built on Zod 4 codecs.",
   "type": "module",
   "repository": {