UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

985 lines • 43.9 kB
/** * comments — OOXML comment insertion, threaded replies, and part bootstrapping. * * Creates comment XML parts when missing, inserts comment range markers, * and supports threaded replies via commentsExtended.xml. */ import { OOXML, W } from './namespaces.js'; import { parseXml, serializeXml } from './xml.js'; import { getParagraphRuns, getParagraphText, splitRunAtVisibleOffset } from './text.js'; import { getParagraphBookmarkId } from './bookmarks.js'; import { childElements, getLeafText, isW } from './dom-helpers.js'; import { getAttributeSafe } from './xml-helpers.js'; import { createRevisionContainer, prepareElementForDeletion, } from './track-changes-emitter.js'; // ── Relationship types ────────────────────────────────────────────────── const REL_TYPE_COMMENTS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments'; const REL_TYPE_COMMENTS_EXTENDED = 'http://schemas.microsoft.com/office/2011/relationships/commentsExtended'; const REL_TYPE_PEOPLE = 'http://schemas.microsoft.com/office/2011/relationships/people'; // ── Content types ─────────────────────────────────────────────────────── const CT_COMMENTS = 'application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml'; const CT_COMMENTS_EXTENDED = 'application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml'; const CT_PEOPLE = 'application/vnd.openxmlformats-officedocument.wordprocessingml.people+xml'; // XML Namespaces namespace — used when binding/declaring prefixes via setAttributeNS. const XMLNS_NS = 'http://www.w3.org/2000/xmlns/'; // ── Minimal XML templates ─────────────────────────────────────────────── const COMMENTS_XML_TEMPLATE = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` + `<w:comments xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"` + ` xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml"` + ` xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"/>`; const COMMENTS_EXTENDED_XML_TEMPLATE = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` + `<w15:commentsEx xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"` + ` xmlns:w14="http://schemas.microsoft.com/office/word/2010/wordml"/>`; const PEOPLE_XML_TEMPLATE = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` + `<w15:people xmlns:w15="http://schemas.microsoft.com/office/word/2012/wordml"/>`; // ── Helpers ───────────────────────────────────────────────────────────── function generateParaId() { // 8-hex-digit random ID used for w14:paraId / w15:paraId const val = Math.floor(Math.random() * 0xFFFFFFFF); return val.toString(16).toUpperCase().padStart(8, '0'); } function isoNow() { return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z'); } /** * Create missing comment XML parts when a DOCX has no comment infrastructure. * Idempotent — skips parts that already exist. */ export async function bootstrapCommentParts(zip) { const created = []; // 1. Ensure comment parts exist if (!zip.hasFile('word/comments.xml')) { zip.writeText('word/comments.xml', COMMENTS_XML_TEMPLATE); created.push('word/comments.xml'); } if (!zip.hasFile('word/commentsExtended.xml')) { zip.writeText('word/commentsExtended.xml', COMMENTS_EXTENDED_XML_TEMPLATE); created.push('word/commentsExtended.xml'); } if (!zip.hasFile('word/people.xml')) { zip.writeText('word/people.xml', PEOPLE_XML_TEMPLATE); created.push('word/people.xml'); } if (created.length === 0) return { partsCreated: [] }; // 2. Update [Content_Types].xml await ensureContentTypes(zip, created); // 3. Update word/_rels/document.xml.rels await ensureRelationships(zip, created); return { partsCreated: created }; } async function ensureContentTypes(zip, newParts) { const ctPath = '[Content_Types].xml'; let ctXml; try { ctXml = await zip.readText(ctPath); } catch { // Minimal [Content_Types].xml if missing ctXml = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` + `<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types"/>`; } const ctDoc = parseXml(ctXml); const typesEl = ctDoc.documentElement; const ctNs = 'http://schemas.openxmlformats.org/package/2006/content-types'; const partToCt = { 'word/comments.xml': CT_COMMENTS, 'word/commentsExtended.xml': CT_COMMENTS_EXTENDED, 'word/people.xml': CT_PEOPLE, }; // Check existing overrides const overrides = Array.from(typesEl.getElementsByTagNameNS(ctNs, 'Override')); const existingPartNames = new Set(overrides.map((o) => o.getAttribute('PartName'))); for (const part of newParts) { const partName = `/${part}`; const contentType = partToCt[part]; if (!contentType || existingPartNames.has(partName)) continue; const override = ctDoc.createElementNS(ctNs, 'Override'); override.setAttribute('PartName', partName); override.setAttribute('ContentType', contentType); typesEl.appendChild(override); } zip.writeText(ctPath, serializeXml(ctDoc)); } async function ensureRelationships(zip, newParts) { const relsPath = 'word/_rels/document.xml.rels'; let relsXml; try { relsXml = await zip.readText(relsPath); } catch { relsXml = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>` + `<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"/>`; } const relsDoc = parseXml(relsXml); const relsEl = relsDoc.documentElement; const relNs = OOXML.REL_NS; const partToRelType = { 'word/comments.xml': REL_TYPE_COMMENTS, 'word/commentsExtended.xml': REL_TYPE_COMMENTS_EXTENDED, 'word/people.xml': REL_TYPE_PEOPLE, }; // Check existing relationships const existingRels = Array.from(relsEl.getElementsByTagNameNS(relNs, 'Relationship')); const existingTypes = new Set(existingRels.map((r) => r.getAttribute('Type'))); // Allocate next rId let maxId = 0; for (const rel of existingRels) { const id = rel.getAttribute('Id') ?? ''; const match = /^rId(\d+)$/.exec(id); if (match) maxId = Math.max(maxId, parseInt(match[1], 10)); } for (const part of newParts) { const relType = partToRelType[part]; if (!relType || existingTypes.has(relType)) continue; maxId++; const rel = relsDoc.createElementNS(relNs, 'Relationship'); rel.setAttribute('Id', `rId${maxId}`); rel.setAttribute('Type', relType); // Target is relative to word/ rel.setAttribute('Target', part.replace('word/', '')); relsEl.appendChild(rel); } zip.writeText(relsPath, serializeXml(relsDoc)); } /** * Insert a root comment anchored to a text range within a paragraph. * * - Allocates next comment ID from existing comments.xml * - Inserts commentRangeStart/commentRangeEnd markers in document body * - Inserts commentReference run after range end * - Adds comment entry to comments.xml * - Adds author to people.xml if not present */ export async function addComment(documentXml, zip, params, ctx) { const { paragraphEl, author, text, initials } = params; const visibleLen = getParagraphText(paragraphEl).length; const start = params.start ?? 0; const end = params.end ?? visibleLen; if (start > end) { throw new Error(`Invalid comment range: start (${start}) must be <= end (${end})`); } if (start < 0 || end > visibleLen) { throw new Error(`Invalid comment range: [${start}, ${end}) is outside paragraph visible text [0, ${visibleLen})`); } // Load comments.xml const commentsXml = await zip.readText('word/comments.xml'); const commentsDoc = parseXml(commentsXml); // Allocate next comment ID const commentId = allocateNextCommentId(commentsDoc); // Insert range markers and reference in document body insertCommentMarkers(documentXml, paragraphEl, commentId, start, end, ctx); // Add comment element to comments.xml const paraId = generateParaId(); addCommentElement(commentsDoc, { id: commentId, author, initials: initials ?? author.charAt(0).toUpperCase(), text, paraId, }); zip.writeText('word/comments.xml', serializeXml(commentsDoc)); // Add author to people.xml await ensureAuthorInPeople(zip, author); return { commentId }; } /** * Add a threaded reply to an existing comment. * * Replies don't have range markers in the document body. * Thread linkage is stored in commentsExtended.xml via paraIdParent. * `ctx` is accepted for API consistency with other comment mutations, but this * primitive only updates comment side parts for replies, so no body revision * markup is emitted here. */ export async function addCommentReply(_documentXml, zip, params, _ctx) { const { parentCommentId, author, text, initials } = params; // Load comments.xml const commentsXml = await zip.readText('word/comments.xml'); const commentsDoc = parseXml(commentsXml); // Find parent comment's paraId const parentParaId = findCommentParaId(commentsDoc, parentCommentId); if (!parentParaId) { throw new Error(`Parent comment ID ${parentCommentId} not found in comments.xml`); } // Allocate ID and add reply comment const commentId = allocateNextCommentId(commentsDoc); const replyParaId = generateParaId(); addCommentElement(commentsDoc, { id: commentId, author, initials: initials ?? author.charAt(0).toUpperCase(), text, paraId: replyParaId, }); zip.writeText('word/comments.xml', serializeXml(commentsDoc)); // Link reply in commentsExtended.xml await linkReplyInCommentsExtended(zip, replyParaId, parentParaId); // Ensure parent also has an entry in commentsExtended.xml await ensureCommentExEntry(zip, parentParaId); // Add author to people.xml await ensureAuthorInPeople(zip, author); return { commentId, parentCommentId }; } // ── Internal helpers ──────────────────────────────────────────────────── function allocateNextCommentId(commentsDoc) { const commentEls = commentsDoc.getElementsByTagNameNS(OOXML.W_NS, W.comment); let maxId = -1; for (let i = 0; i < commentEls.length; i++) { const el = commentEls.item(i); const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false }); if (idStr) { const id = parseInt(idStr, 10); if (id > maxId) maxId = id; } } return maxId + 1; } function findCommentParaId(commentsDoc, commentId) { const commentEls = commentsDoc.getElementsByTagNameNS(OOXML.W_NS, W.comment); for (let i = 0; i < commentEls.length; i++) { const el = commentEls.item(i); const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false }); if (idStr && parseInt(idStr, 10) === commentId) { // paraId is on the w:p child inside the comment const paras = el.getElementsByTagNameNS(OOXML.W_NS, W.p); if (paras.length > 0) { const p = paras.item(0); return getAttributeSafe(p, OOXML.W14_NS, 'paraId', 'w14', { bareFallback: false }); } } } return null; } /** * Ensure a comment-related document root binds the w14 and w15 prefixes before any * w14:* / w15:* attribute is written into it. Real-world docx files often ship a * pre-existing comments.xml (or commentsExtended.xml / people.xml) that omits one or * both declarations; without a real namespace binding, xmldom would reject the * round-tripped XML with `NamespaceError: prefix is non-null and namespace is null`. * * Uses `setAttributeNS(XMLNS_NS, …)` so the prefix is actually bound on the live DOM * (not just serialized as a literal attribute) — that means subsequent `createElementNS` * / `setAttributeNS` / `lookupNamespaceURI` calls on the same Document resolve correctly * without depending on a serialize/reparse round trip. Idempotent — guards on the real * binding via `lookupNamespaceURI`, not on a same-named plain attribute. */ function ensureCommentPartNamespaceAliases(commentsDoc) { const root = commentsDoc.documentElement; if (root.lookupNamespaceURI('w14') !== OOXML.W14_NS) { root.setAttributeNS(XMLNS_NS, 'xmlns:w14', OOXML.W14_NS); } if (root.lookupNamespaceURI('w15') !== OOXML.W15_NS) { root.setAttributeNS(XMLNS_NS, 'xmlns:w15', OOXML.W15_NS); } } function addCommentElement(commentsDoc, params) { ensureCommentPartNamespaceAliases(commentsDoc); const root = commentsDoc.documentElement; const commentEl = commentsDoc.createElementNS(OOXML.W_NS, 'w:comment'); commentEl.setAttribute('w:id', String(params.id)); commentEl.setAttribute('w:author', params.author); commentEl.setAttribute('w:date', isoNow()); commentEl.setAttribute('w:initials', params.initials); // Comment body: <w:p w14:paraId="..."><w:pPr><w:pStyle w:val="CommentText"/></w:pPr><w:r><w:annotationRef/></w:r><w:r><w:t>text</w:t></w:r></w:p> const p = commentsDoc.createElementNS(OOXML.W_NS, 'w:p'); // Use setAttributeNS so the attribute carries a real namespace URI — otherwise xmldom // serializes a prefix it cannot resolve and reparse throws NamespaceError (#154). p.setAttributeNS(OOXML.W14_NS, 'w14:paraId', params.paraId); // Annotation reference run const refRun = commentsDoc.createElementNS(OOXML.W_NS, 'w:r'); const annotRef = commentsDoc.createElementNS(OOXML.W_NS, 'w:annotationRef'); refRun.appendChild(annotRef); p.appendChild(refRun); // Text run const textRun = commentsDoc.createElementNS(OOXML.W_NS, 'w:r'); const t = commentsDoc.createElementNS(OOXML.W_NS, 'w:t'); if (params.text.startsWith(' ') || params.text.endsWith(' ')) { t.setAttributeNS('http://www.w3.org/XML/1998/namespace', 'xml:space', 'preserve'); } t.appendChild(commentsDoc.createTextNode(params.text)); textRun.appendChild(t); p.appendChild(textRun); commentEl.appendChild(p); root.appendChild(commentEl); } function insertCommentMarkers(documentXml, paragraphEl, commentId, start, end, ctx) { const runs = getParagraphRuns(paragraphEl); const rangeStart = documentXml.createElementNS(OOXML.W_NS, 'w:commentRangeStart'); rangeStart.setAttribute('w:id', String(commentId)); const rangeEnd = documentXml.createElementNS(OOXML.W_NS, 'w:commentRangeEnd'); rangeEnd.setAttribute('w:id', String(commentId)); const refRun = documentXml.createElementNS(OOXML.W_NS, 'w:r'); const rPr = documentXml.createElementNS(OOXML.W_NS, 'w:rPr'); const rStyle = documentXml.createElementNS(OOXML.W_NS, 'w:rStyle'); rStyle.setAttribute('w:val', 'CommentReference'); rPr.appendChild(rStyle); refRun.appendChild(rPr); const commentRef = documentXml.createElementNS(OOXML.W_NS, 'w:commentReference'); commentRef.setAttribute('w:id', String(commentId)); refRun.appendChild(commentRef); const refAnchor = ctx ? createRevisionContainer(documentXml, 'ins', ctx) : refRun; if (ctx) { refAnchor.appendChild(refRun); } if (runs.length === 0) { paragraphEl.appendChild(rangeStart); paragraphEl.appendChild(rangeEnd); paragraphEl.appendChild(refAnchor); return; } const mapping = mapOffsetsToRuns(runs, start, end); const { startRunIdx, startOffset, endRunIdx, endOffset } = mapping; // Collapsed range (start === end): insert both markers at the same boundary. // Splitting again here would create an empty <w:r> inside the marker pair — // replaceParagraphTextRange() avoids this by deleting the temporary run, which // we can't do for comments. Handle the boundary directly. if (startRunIdx === endRunIdx && startOffset === endOffset) { insertCollapsedRangeMarkers(runs[startRunIdx], startOffset, rangeStart, rangeEnd, refAnchor); return; } // Split boundary runs at the exact visible-text offsets so the markers can sit // on true sub-paragraph boundaries instead of being snapped to whole-run edges. // Choreography mirrors replaceParagraphTextRange() in text.ts:404. let startRunEl = runs[startRunIdx].r; let endRunEl = runs[endRunIdx].r; if (startRunIdx === endRunIdx) { const runLen = runs[startRunIdx].text.length; if (endOffset < runLen) { const { left } = splitRunAtVisibleOffset(startRunEl, endOffset); startRunEl = left; endRunEl = left; } if (startOffset > 0) { const { right } = splitRunAtVisibleOffset(startRunEl, startOffset); startRunEl = right; endRunEl = right; } } else { if (startOffset > 0) { const { right } = splitRunAtVisibleOffset(startRunEl, startOffset); startRunEl = right; } const endLen = runs[endRunIdx].text.length; if (endOffset < endLen) { const { left } = splitRunAtVisibleOffset(endRunEl, endOffset); endRunEl = left; } } // Insert relative to each run's parent so anchors inside w:hyperlink, w:ins, // w:del, w:sdtContent, etc. keep the markers inside the wrapper. const startParent = startRunEl.parentNode; const endParent = endRunEl.parentNode; if (!startParent || !endParent) { throw new Error('Split run has no parent'); } startParent.insertBefore(rangeStart, startRunEl); endParent.insertBefore(rangeEnd, endRunEl.nextSibling); endParent.insertBefore(refAnchor, rangeEnd.nextSibling); } function mapOffsetsToRuns(runs, start, end) { // Map visible-text offsets to (runIndex, offsetInRun). Caller validates that // 0 <= start <= end <= sum(runs[i].text.length). let pos = 0; let startRunIdx = -1; let endRunIdx = -1; let startOffset = 0; let endOffset = 0; for (let i = 0; i < runs.length; i++) { const len = runs[i].text.length; if (startRunIdx === -1 && start >= pos && start <= pos + len) { startRunIdx = i; startOffset = start - pos; } if (endRunIdx === -1 && end >= pos && end <= pos + len) { endRunIdx = i; endOffset = end - pos; break; } pos += len; } if (startRunIdx === -1 || endRunIdx === -1) { throw new Error(`Could not map offsets [${start}, ${end}) to runs`); } return { startRunIdx, startOffset, endRunIdx, endOffset }; } function insertCollapsedRangeMarkers(run, offsetInRun, rangeStart, rangeEnd, refAnchor) { const runEl = run.r; const parent = runEl.parentNode; if (!parent) throw new Error('Run has no parent'); const runLen = run.text.length; if (offsetInRun === 0) { // Insert before the run. parent.insertBefore(rangeStart, runEl); parent.insertBefore(rangeEnd, runEl); parent.insertBefore(refAnchor, runEl); return; } if (offsetInRun === runLen) { // Insert after the run. Capture nextSibling once because insertBefore // shifts it (rangeStart would otherwise land last instead of first). const ref = runEl.nextSibling; parent.insertBefore(rangeStart, ref); parent.insertBefore(rangeEnd, ref); parent.insertBefore(refAnchor, ref); return; } // Mid-run: split once so the markers sit between the two halves. const { right } = splitRunAtVisibleOffset(runEl, offsetInRun); parent.insertBefore(rangeStart, right); parent.insertBefore(rangeEnd, right); parent.insertBefore(refAnchor, right); } async function linkReplyInCommentsExtended(zip, replyParaId, parentParaId) { const extXml = await zip.readText('word/commentsExtended.xml'); const extDoc = parseXml(extXml); ensureCommentPartNamespaceAliases(extDoc); const root = extDoc.documentElement; const exEl = extDoc.createElementNS(OOXML.W15_NS, 'w15:commentEx'); exEl.setAttributeNS(OOXML.W15_NS, 'w15:paraId', replyParaId); exEl.setAttributeNS(OOXML.W15_NS, 'w15:paraIdParent', parentParaId); exEl.setAttributeNS(OOXML.W15_NS, 'w15:done', '0'); root.appendChild(exEl); zip.writeText('word/commentsExtended.xml', serializeXml(extDoc)); } async function ensureCommentExEntry(zip, paraId) { const extXml = await zip.readText('word/commentsExtended.xml'); const extDoc = parseXml(extXml); ensureCommentPartNamespaceAliases(extDoc); const root = extDoc.documentElement; // Check if entry already exists const existing = root.getElementsByTagNameNS(OOXML.W15_NS, 'commentEx'); for (let i = 0; i < existing.length; i++) { const el = existing.item(i); const pid = getAttributeSafe(el, OOXML.W15_NS, 'paraId', 'w15', { bareFallback: false }); if (pid === paraId) return; // Already present } const exEl = extDoc.createElementNS(OOXML.W15_NS, 'w15:commentEx'); exEl.setAttributeNS(OOXML.W15_NS, 'w15:paraId', paraId); exEl.setAttributeNS(OOXML.W15_NS, 'w15:done', '0'); root.appendChild(exEl); zip.writeText('word/commentsExtended.xml', serializeXml(extDoc)); } async function ensureAuthorInPeople(zip, author) { const peopleXml = await zip.readText('word/people.xml'); const peopleDoc = parseXml(peopleXml); ensureCommentPartNamespaceAliases(peopleDoc); const root = peopleDoc.documentElement; // Check if author already exists const persons = root.getElementsByTagNameNS(OOXML.W15_NS, 'person'); for (let i = 0; i < persons.length; i++) { const el = persons.item(i); const name = getAttributeSafe(el, OOXML.W15_NS, 'author', 'w15', { bareFallback: false }); if (name === author) return; // Already present } const personEl = peopleDoc.createElementNS(OOXML.W15_NS, 'w15:person'); personEl.setAttributeNS(OOXML.W15_NS, 'w15:author', author); // Add a presenceInfo child (required by Word) const presenceInfo = peopleDoc.createElementNS(OOXML.W15_NS, 'w15:presenceInfo'); presenceInfo.setAttributeNS(OOXML.W15_NS, 'w15:providerId', 'None'); presenceInfo.setAttributeNS(OOXML.W15_NS, 'w15:userId', author); personEl.appendChild(presenceInfo); root.appendChild(personEl); zip.writeText('word/people.xml', serializeXml(peopleDoc)); } var FieldState; (function (FieldState) { FieldState[FieldState["OUTSIDE_FIELD"] = 0] = "OUTSIDE_FIELD"; FieldState[FieldState["IN_FIELD_CODE"] = 1] = "IN_FIELD_CODE"; FieldState[FieldState["IN_FIELD_RESULT"] = 2] = "IN_FIELD_RESULT"; })(FieldState || (FieldState = {})); /** * Read all comments from a document, building a threaded tree. * * Root comments are returned at the top level; replies are nested under * their parent's `replies` array. Thread linkage is resolved via * commentsExtended.xml paraIdParent relationships. */ export async function getComments(zip, documentXml) { const commentsText = await zip.readTextOrNull('word/comments.xml'); if (!commentsText) return []; const commentsDoc = parseXml(commentsText); const commentEls = commentsDoc.getElementsByTagNameNS(OOXML.W_NS, W.comment); if (commentEls.length === 0) return []; const rangeMetadata = resolveCommentRangeMetadata(documentXml); // Build a map of commentId → { paraId, Comment } const byParaId = new Map(); const byId = new Map(); for (let i = 0; i < commentEls.length; i++) { const el = commentEls.item(i); const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false }); const id = idStr ? parseInt(idStr, 10) : -1; if (id < 0) continue; const author = getAttributeSafe(el, OOXML.W_NS, 'author', 'w', { bareFallback: false }) ?? ''; const date = getAttributeSafe(el, OOXML.W_NS, 'date', 'w', { bareFallback: false }) ?? ''; const initials = getAttributeSafe(el, OOXML.W_NS, 'initials', 'w', { bareFallback: false }) ?? ''; // Extract text from <w:t> elements, skipping annotationRef runs const text = extractCommentText(el); // Get paraId from first <w:p> child (namespace-aware to handle non-`w` prefixes) const paras = el.getElementsByTagNameNS(OOXML.W_NS, W.p); let paragraphId = null; if (paras.length > 0) { const p = paras.item(0); paragraphId = getAttributeSafe(p, OOXML.W14_NS, 'paraId', 'w14', { bareFallback: false }); } const startPoint = rangeMetadata.startById.get(id); const endPoint = rangeMetadata.endById.get(id); const comment = { id, author, date, initials, text, paragraphId, anchoredParagraphId: startPoint?.paragraphId ?? null, endParagraphId: endPoint?.paragraphId ?? startPoint?.paragraphId ?? null, startRunIndex: startPoint?.runIndex, startCharOffset: startPoint?.charOffset, endRunIndex: endPoint?.runIndex, endCharOffset: endPoint?.charOffset, replies: [], }; byId.set(id, comment); if (paragraphId) byParaId.set(paragraphId, comment); } // Build thread tree from commentsExtended.xml const extText = await zip.readTextOrNull('word/commentsExtended.xml'); if (extText) { const extDoc = parseXml(extText); const exEls = extDoc.getElementsByTagNameNS(OOXML.W15_NS, 'commentEx'); for (let i = 0; i < exEls.length; i++) { const ex = exEls.item(i); const childParaId = getAttributeSafe(ex, OOXML.W15_NS, 'paraId', 'w15', { bareFallback: false }); const parentParaId = getAttributeSafe(ex, OOXML.W15_NS, 'paraIdParent', 'w15', { bareFallback: false }); if (!childParaId || !parentParaId) continue; const child = byParaId.get(childParaId); const parentComment = byParaId.get(parentParaId); if (child && parentComment) { parentComment.replies.push(child); } } } // Collect root-level comments (those not appearing as anyone's reply) const replyParaIds = new Set(); if (extText) { const extDoc = parseXml(extText); const exEls = extDoc.getElementsByTagNameNS(OOXML.W15_NS, 'commentEx'); for (let i = 0; i < exEls.length; i++) { const ex = exEls.item(i); const childParaId = getAttributeSafe(ex, OOXML.W15_NS, 'paraId', 'w15', { bareFallback: false }); const parentParaId = getAttributeSafe(ex, OOXML.W15_NS, 'paraIdParent', 'w15', { bareFallback: false }); if (childParaId && parentParaId) { replyParaIds.add(childParaId); } } } const roots = []; for (const comment of byId.values()) { if (!comment.paragraphId || !replyParaIds.has(comment.paragraphId)) { roots.push(comment); } } return roots; } function resolveCommentRangeMetadata(documentXml) { const startById = new Map(); const endById = new Map(); const root = documentXml.documentElement; if (!root) return { startById, endById }; const paragraphList = root.getElementsByTagNameNS(OOXML.W_NS, W.p); for (let i = 0; i < paragraphList.length; i++) { resolveCommentRangeMetadataInParagraph(paragraphList.item(i), startById, endById); } return { startById, endById }; } function resolveCommentRangeMetadataInParagraph(paragraph, startById, endById) { const walkState = { charPos: 0, fieldState: FieldState.OUTSIDE_FIELD, allRuns: [], currentRunIndex: 0, startMarkers: [], endMarkers: [], }; walkParagraphForCommentMarkers(paragraph, paragraph, walkState); const paragraphId = getParagraphBookmarkId(paragraph); for (const marker of walkState.startMarkers) { if (startById.has(marker.id)) continue; startById.set(marker.id, { paragraphId, ...resolveMarkerToRunBoundary(walkState.allRuns, marker, 'start'), }); } for (const marker of walkState.endMarkers) { if (endById.has(marker.id)) continue; endById.set(marker.id, { paragraphId, ...resolveMarkerToRunBoundary(walkState.allRuns, marker, 'end'), }); } } function walkParagraphForCommentMarkers(rootParagraph, node, state) { for (const child of childElements(node)) { if (child !== rootParagraph && isW(child, W.p)) continue; if (isW(child, W.commentRangeStart)) { recordParagraphLevelMarker(child, state.startMarkers, state); continue; } if (isW(child, W.commentRangeEnd)) { recordParagraphLevelMarker(child, state.endMarkers, state); continue; } if (isW(child, W.r)) { walkRunForCommentMarkers(child, state); continue; } walkParagraphForCommentMarkers(rootParagraph, child, state); } } function walkRunForCommentMarkers(run, state) { const runIndex = state.currentRunIndex; state.currentRunIndex += 1; const runVisibleStart = state.charPos; for (const child of childElements(run)) { if (isW(child, W.commentRangeStart)) { recordInRunMarker(child, state.startMarkers, runIndex, state.charPos - runVisibleStart); continue; } if (isW(child, W.commentRangeEnd)) { recordInRunMarker(child, state.endMarkers, runIndex, state.charPos - runVisibleStart); continue; } if (!child.namespaceURI || child.namespaceURI !== OOXML.W_NS) continue; if (child.localName === W.fldChar) { const type = getWordAttribute(child, 'fldCharType') ?? ''; if (type === 'begin') state.fieldState = FieldState.IN_FIELD_CODE; else if (type === 'separate') state.fieldState = FieldState.IN_FIELD_RESULT; else if (type === 'end') state.fieldState = FieldState.OUTSIDE_FIELD; continue; } if (state.fieldState === FieldState.IN_FIELD_CODE) continue; if (child.localName === W.t) { state.charPos += (getLeafText(child) ?? '').length; continue; } if (child.localName === W.tab || child.localName === W.br) { state.charPos += 1; } } state.allRuns.push({ visibleLength: state.charPos - runVisibleStart }); } function recordInRunMarker(markerEl, bucket, runIndex, charOffset) { const id = getCommentMarkerId(markerEl); if (id == null) return; bucket.push({ id, inside: { runIndex, charOffset } }); } function recordParagraphLevelMarker(markerEl, bucket, state) { const id = getCommentMarkerId(markerEl); if (id == null) return; bucket.push({ id, between: { afterRunIndex: state.currentRunIndex - 1 } }); } function getCommentMarkerId(markerEl) { const idStr = getAttributeSafe(markerEl, OOXML.W_NS, 'id', 'w', { bareFallback: false }); if (!idStr) return null; const id = parseInt(idStr, 10); return Number.isNaN(id) ? null : id; } function getWordAttribute(el, localName) { return getAttributeSafe(el, OOXML.W_NS, localName, 'w'); } function resolveMarkerToRunBoundary(allRuns, marker, boundary) { // Marker seen INSIDE a run already carries the exact runIndex + charOffset. if (marker.inside) { return { runIndex: marker.inside.runIndex, charOffset: marker.inside.charOffset }; } if (!marker.between) return {}; if (allRuns.length === 0) return {}; const { afterRunIndex } = marker.between; const lastIndex = allRuns.length - 1; if (boundary === 'start') { // Marker sits between run `afterRunIndex` and run `afterRunIndex + 1`. // For a `start` marker, the range opens at offset 0 of the next run if it exists. const nextIdx = afterRunIndex + 1; if (nextIdx <= lastIndex) { return { runIndex: nextIdx, charOffset: 0 }; } // Marker is past the last run — clamp to end of last run. return { runIndex: lastIndex, charOffset: allRuns[lastIndex].visibleLength }; } // boundary === 'end': range closes at the end of the previous run if one exists. if (afterRunIndex < 0) { // Marker is before the first run — empty range starting at run 0. return { runIndex: 0, charOffset: 0 }; } if (afterRunIndex <= lastIndex) { return { runIndex: afterRunIndex, charOffset: allRuns[afterRunIndex].visibleLength }; } return { runIndex: lastIndex, charOffset: allRuns[lastIndex].visibleLength }; } /** * Get a single comment by ID, searching the full tree including replies. */ export async function getComment(zip, documentXml, commentId) { const all = await getComments(zip, documentXml); return findCommentById(all, commentId); } function findCommentById(comments, id) { for (const c of comments) { if (c.id === id) return c; const found = findCommentById(c.replies, id); if (found) return found; } return null; } // ── Comment deletion ───────────────────────────────────────────────── /** * Delete a comment and all its descendants from the document. * * - Removes comment elements from comments.xml * - Removes commentEx entries from commentsExtended.xml (if present) * - For root comments: removes commentRangeStart, commentRangeEnd, and * commentReference from document.xml (element-level; run removed only if empty) * - Transitive cascade: deleting any node also deletes all descendants */ export async function deleteComment(documentXml, zip, params, ctx) { const { commentId } = params; const commentsText = await zip.readTextOrNull('word/comments.xml'); if (!commentsText) throw new Error(`Comment ID ${commentId} not found`); const commentsDoc = parseXml(commentsText); // Find the target comment element and its paraId const targetEl = findCommentElementById(commentsDoc, commentId); if (!targetEl) throw new Error(`Comment ID ${commentId} not found`); const targetParaId = getCommentElParaId(targetEl); // Collect all IDs to delete: the target + all transitive descendants const idsToDelete = new Set([commentId]); const paraIdsToDelete = new Set(); if (targetParaId) paraIdsToDelete.add(targetParaId); // Build paraId→commentId and paraId→commentEl maps for all comments const paraIdToId = new Map(); const allCommentEls = commentsDoc.getElementsByTagNameNS(OOXML.W_NS, W.comment); for (let i = 0; i < allCommentEls.length; i++) { const el = allCommentEls.item(i); const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false }); const id = idStr ? parseInt(idStr, 10) : -1; if (id < 0) continue; const pid = getCommentElParaId(el); if (pid) paraIdToId.set(pid, id); } // Read commentsExtended.xml to find descendants via paraIdParent graph const extText = await zip.readTextOrNull('word/commentsExtended.xml'); if (extText) { const extDoc = parseXml(extText); const exEls = extDoc.getElementsByTagNameNS(OOXML.W15_NS, 'commentEx'); // Build parent→children map const childrenOf = new Map(); for (let i = 0; i < exEls.length; i++) { const ex = exEls.item(i); const childPid = getAttributeSafe(ex, OOXML.W15_NS, 'paraId', 'w15', { bareFallback: false }); const parentPid = getAttributeSafe(ex, OOXML.W15_NS, 'paraIdParent', 'w15', { bareFallback: false }); if (childPid && parentPid) { const arr = childrenOf.get(parentPid); if (arr) arr.push(childPid); else childrenOf.set(parentPid, [childPid]); } } // BFS from target paraId to collect all descendant paraIds const queue = targetParaId ? [targetParaId] : []; while (queue.length > 0) { const pid = queue.shift(); const children = childrenOf.get(pid); if (!children) continue; for (const childPid of children) { if (!paraIdsToDelete.has(childPid)) { paraIdsToDelete.add(childPid); const childId = paraIdToId.get(childPid); if (childId != null) idsToDelete.add(childId); queue.push(childPid); } } } } // 1. Remove comment elements from comments.xml const elsToRemove = []; for (let i = 0; i < allCommentEls.length; i++) { const el = allCommentEls.item(i); const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false }); const id = idStr ? parseInt(idStr, 10) : -1; if (idsToDelete.has(id)) elsToRemove.push(el); } for (const el of elsToRemove) { el.parentNode?.removeChild(el); } zip.writeText('word/comments.xml', serializeXml(commentsDoc)); // 2. Remove commentEx entries from commentsExtended.xml (if present) if (extText) { const extDoc = parseXml(extText); const exEls = extDoc.getElementsByTagNameNS(OOXML.W15_NS, 'commentEx'); const exToRemove = []; for (let i = 0; i < exEls.length; i++) { const ex = exEls.item(i); const pid = getAttributeSafe(ex, OOXML.W15_NS, 'paraId', 'w15', { bareFallback: false }); if (pid && paraIdsToDelete.has(pid)) exToRemove.push(ex); } for (const ex of exToRemove) { ex.parentNode?.removeChild(ex); } zip.writeText('word/commentsExtended.xml', serializeXml(extDoc)); } // 3. Remove range markers and commentReference from document.xml (for root comments) for (const cid of idsToDelete) { removeCommentMarkersFromDocument(documentXml, cid, ctx); } } function findCommentElementById(commentsDoc, commentId) { const commentEls = commentsDoc.getElementsByTagNameNS(OOXML.W_NS, W.comment); for (let i = 0; i < commentEls.length; i++) { const el = commentEls.item(i); const idStr = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false }); if (idStr && parseInt(idStr, 10) === commentId) return el; } return null; } function getCommentElParaId(commentEl) { const paras = commentEl.getElementsByTagNameNS(OOXML.W_NS, W.p); if (paras.length === 0) return null; const p = paras.item(0); return getAttributeSafe(p, OOXML.W14_NS, 'paraId', 'w14', { bareFallback: false }); } function removeCommentMarkersFromDocument(documentXml, commentId, ctx) { const cidStr = String(commentId); // Remove commentRangeStart elements const rangeStarts = documentXml.getElementsByTagNameNS(OOXML.W_NS, W.commentRangeStart); const startsToRemove = []; for (let i = 0; i < rangeStarts.length; i++) { const el = rangeStarts.item(i); const id = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false }); if (id === cidStr) startsToRemove.push(el); } for (const el of startsToRemove) el.parentNode?.removeChild(el); // Remove commentRangeEnd elements const rangeEnds = documentXml.getElementsByTagNameNS(OOXML.W_NS, W.commentRangeEnd); const endsToRemove = []; for (let i = 0; i < rangeEnds.length; i++) { const el = rangeEnds.item(i); const id = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false }); if (id === cidStr) endsToRemove.push(el); } for (const el of endsToRemove) el.parentNode?.removeChild(el); // Remove commentReference elements, or preserve their containing run under // a deletion wrapper when tracked changes are requested. const refs = documentXml.getElementsByTagNameNS(OOXML.W_NS, W.commentReference); const refsToRemove = []; for (let i = 0; i < refs.length; i++) { const el = refs.item(i); const id = getAttributeSafe(el, OOXML.W_NS, 'id', 'w', { bareFallback: false }); if (id === cidStr) refsToRemove.push(el); } for (const ref of refsToRemove) { const run = ref.parentNode; if (!run) continue; if (ctx) { const parent = run.parentNode; if (!parent) continue; const deletion = createRevisionContainer(documentXml, 'del', ctx); parent.replaceChild(deletion, run); deletion.appendChild(prepareElementForDeletion(run)); continue; } run.removeChild(ref); // Remove run only if it has no visible content after removing the reference if (!hasVisibleRunContent(run)) { const runParent = run.parentNode; runParent?.removeChild(run); // If the run lived inside a tracked-change wrapper (e.g., the comment // was added with ctx earlier and is now being deleted without ctx), // the wrapper is left orphaned with no content. Clean it up. if (runParent && isW(runParent, 'ins')) { runParent.parentNode?.removeChild(runParent); } else if (runParent && isW(runParent, 'del')) { runParent.parentNode?.removeChild(runParent); } } } } function hasVisibleRunContent(run) { for (const child of Array.from(run.childNodes)) { if (child.nodeType !== 1) continue; const el = child; if (el.namespaceURI !== OOXML.W_NS) continue; if (el.localName === W.rPr) continue; return true; } return false; } function extractCommentText(commentEl) { const parts = []; const runs = commentEl.getElementsByTagNameNS(OOXML.W_NS, W.r); for (let i = 0; i < runs.length; i++) { const run = runs.item(i); // Skip runs that contain annotationRef (they're metadata, not user text) const annotRefs = run.getElementsByTagNameNS(OOXML.W_NS, W.annotationRef); if (annotRefs.length > 0) continue; const ts = run.getElementsByTagNameNS(OOXML.W_NS, W.t); for (let j = 0; j < ts.length; j++) { const t = ts.item(j); parts.push(t.textContent ?? ''); } } return parts.join(''); } //# sourceMappingURL=comments.js.map