UNPKG

open-agreements

Version:

Open-source legal template filling CLI and library

837 lines • 37.1 kB
/** * Shared fill pipeline used by all three fill paths (template, external, fieldSelector). * Centralizes: defaults, boolean coercion, display fields, currency sanitization, * drafting note removal, and the docx-templates createReport() call. */ import AdmZip from 'adm-zip'; import { DOMParser, XMLSerializer } from '@xmldom/xmldom'; import { createReport } from 'docx-templates'; import { sanitizeCurrencyValuesFromDocx, sanitizePercentValuesFromDocx, BLANK_PLACEHOLDER, } from './fill-utils.js'; import { copyEntriesSkippingDirs, enumerateTextParts, getGeneralTextPartNames, rezipWithoutDirEntries, } from './field-selector/ooxml-parts.js'; import { assertConditionalRequiredInputs } from './conditional-inputs.js'; import { preparedFieldDefault } from './field-defaults.js'; const W_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'; /** Default patterns for paragraphs stripped before filling. */ const DEFAULT_STRIP_PATTERNS = [/\bDrafting note\b/i]; /** Fixed month-name table for deterministic date formatting (index 0 = January). */ const MONTH_NAMES = [ 'January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December', ]; /** * Format an ISO `YYYY-MM-DD` string as a document date ("2026-07-15" → * "July 15, 2026"). * * Deterministic and timezone-independent by construction: the string is split * into year/month/day components and rendered from {@link MONTH_NAMES}. It * NEVER constructs a `Date` — `new Date('2026-07-15')` parses as UTC midnight * and `toLocaleDateString` can render the previous calendar day in * negative-offset timezones — and never calls any locale/`Intl` API. * * Non-ISO values are returned unchanged so callers may continue supplying a * display-ready date string (e.g. "March 20, 2026"). A strict ISO-shaped value * is a machine-readable assertion, however, so an impossible calendar date is * rejected rather than copied into a legal document unchanged. */ export function formatDocumentDate(value) { const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value); if (!match) return value; const yearStr = match[1]; const month = Number(match[2]); const day = Number(match[3]); if (month < 1 || month > 12 || day < 1) { throw new Error(`Invalid ISO date "${value}": expected a real calendar date in YYYY-MM-DD format`); } // Reject impossible calendar dates (Feb 30/31, Apr 31, Feb 29 in a non-leap // year, …). Deterministic arithmetic only — no Date/locale. const year = Number(yearStr); const isLeapYear = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0; const daysInMonth = [31, isLeapYear ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]; if (day > daysInMonth[month - 1]) { throw new Error(`Invalid ISO date "${value}": expected a real calendar date in YYYY-MM-DD format`); } // Number(match[3]) drops the leading zero: "05" → 5. yearStr keeps any leading // zeros the (unrealistic) 4-digit year might carry. return `${MONTH_NAMES[month - 1]} ${day}, ${yearStr}`; } /** * Return a shallow copy with metadata-declared date fields normalized for * document display. This is intentionally safe to call at more than one * pipeline boundary: {@link formatDocumentDate} leaves display-ready and * non-date strings unchanged. */ export function formatDocumentDateFields(values, fields, pathPrefix = '') { const formatted = { ...values }; for (const field of fields) { const fieldPath = pathPrefix ? `${pathPrefix}.${field.name}` : field.name; const value = formatted[field.name]; if (field.type === 'date' && typeof value === 'string') { try { formatted[field.name] = formatDocumentDate(value); } catch { throw new Error(`Invalid ISO date for field "${fieldPath}": "${value}"; expected a real calendar date in YYYY-MM-DD format`); } continue; } if (field.type === 'array' && field.items && Array.isArray(value)) { formatted[field.name] = value.map((entry, index) => { if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) return entry; return formatDocumentDateFields(entry, field.items, `${fieldPath}[${index}]`); }); } } return formatted; } /** * Prepare fill data with all normalization steps: * 1. Apply defaults for optional fields not provided * 2. Normalize multiselect fields and derive booleans (optional) * 3. Warn about unfilled priority fields * 4. Coerce boolean fields (optional) * 5. Compute display fields (optional, template-specific) */ export function prepareFillData(options) { const { values, fields, priorityFieldNames = [], useBlankPlaceholder = false, coerceBooleans = false, computeDisplayFields, confirmClauses, } = options; assertConditionalRequiredInputs(values, fields); // Apply defaults for fields not provided const defaultValue = useBlankPlaceholder ? BLANK_PLACEHOLDER : ''; let data = { ...values }; for (const field of fields) { if (!(field.name in data)) { data[field.name] = preparedFieldDefault(field, defaultValue); } } // Format ISO `YYYY-MM-DD` values on `type: date` fields as document dates // ("2026-07-15" → "July 15, 2026"). Scoped to date fields ONLY — never a // blanket transform of all values. Non-ISO strings (already display-ready) and // empty-but-non-null placeholders pass through unchanged, so fixtures that // supply "March 20, 2026" are unaffected. Deterministic and // timezone-independent — see formatDocumentDate. data = formatDocumentDateFields(data, fields); for (const field of fields) { if (field.type !== 'enum') continue; const value = data[field.name]; // Optional enum fields may be omitted. In document fills, omission is // represented by the visible blank placeholder rather than an empty // string; neither sentinel is a user-supplied enum choice. if (value == null || value === '' || value === BLANK_PLACEHOLDER) continue; if (typeof value !== 'string') { throw new Error(`Enum field "${field.name}" must be a string; got ${typeof value}`); } const allowed = new Set(field.options ?? []); if (!allowed.has(value)) { throw new Error(`Enum field "${field.name}" received unknown option "${value}"; allowed: ${[...allowed].join(', ')}`); } } for (const field of fields) { if (field.type !== 'multiselect') continue; let raw = data[field.name]; if (typeof raw === 'string') { try { raw = JSON.parse(raw); } catch (err) { throw new Error(`Multiselect field "${field.name}" received malformed JSON input: ${err.message}`); } } if (!Array.isArray(raw)) { throw new Error(`Multiselect field "${field.name}" must be a JSON array of strings; got ${typeof raw}`); } const allowed = new Set(field.options ?? []); const normalized = []; for (const [index, value] of raw.entries()) { if (typeof value !== 'string') { throw new Error(`Multiselect field "${field.name}" entry at index ${index} must be a string; got ${typeof value}`); } if (!allowed.has(value)) { throw new Error(`Multiselect field "${field.name}" received unknown option "${value}"; allowed: ${[...allowed].join(', ')}`); } normalized.push(value); } data[field.name] = normalized; if (field.derive_booleans === true) { const selected = new Set(normalized); for (const option of field.options ?? []) { data[`${option}_enabled`] = selected.has(option); } } } // Reject empty priority collection fields outright. A consent template that // loops over an empty signer array would silently render a Signatures // heading with zero signatures — that's a correctness bug, not a soft warning. const prioritySet = new Set(priorityFieldNames); const emptyPriorityArrays = fields .filter((f) => prioritySet.has(f.name) && (f.type === 'array' || f.type === 'multiselect')) .filter((f) => !Array.isArray(data[f.name]) || data[f.name].length === 0) .map((f) => f.name); if (emptyPriorityArrays.length > 0) { throw new Error(`Required collection fields are empty: ${emptyPriorityArrays.join(', ')}. Provide at least one entry.`); } // Warn about priority fields that are still unfilled (no value, no default) const missing = fields .filter((f) => prioritySet.has(f.name)) .filter((f) => { const value = data[f.name]; if (Array.isArray(value)) { return value.length === 0; } return value === '' || value === BLANK_PLACEHOLDER; }) .map((f) => f.name); if (missing.length > 0) { console.warn(`Note: ${missing.length} priority fields are unfilled: ${missing.join(', ')}`); } // Coerce boolean fields to actual JS booleans. // docx-templates evaluates {IF field} in JS context where "false" is truthy. if (coerceBooleans) { for (const field of fields) { if (field.type === 'boolean' && field.name in data) { const v = data[field.name]; data[field.name] = v === true || v === 'true'; } } } // Derive `any_confirmation_pending` for the cover-page confirmation notice. // True when any APPLICABLE confirm clause (its `when=` gate is true, or it has // none) is still unconfirmed. The per-bullet visibility is handled in the DOCX // by nesting `{IF condition}{IF !confirm}…`; only the banner wrapper needs this // OR-of-applicable-clauses boolean (the {IF} grammar is single-field). Computed // after coercion so gate/confirm values are real booleans. if (confirmClauses && confirmClauses.length > 0) { const truthy = (v) => v === true || v === 'true'; data.any_confirmation_pending = confirmClauses.some((clause) => { const applicable = clause.condition ? truthy(data[clause.condition]) : true; // Use the same truthy() coercion for the confirm field as for the gate, so // a string "true" counts as confirmed even when coerceBooleans is off. return applicable && !truthy(data[clause.confirm]); }); } // Compute display fields (template-specific: radio/checkbox groups) if (computeDisplayFields) { computeDisplayFields(data); } return data; } /** * Extract paragraph text by concatenating all <w:t> elements. */ function extractParagraphText(para) { if (!para.getElementsByTagNameNS) return ''; const tElements = para.getElementsByTagNameNS(W_NS, 't'); const parts = []; for (let i = 0; i < tElements.length; i++) { parts.push(tElements[i].textContent ?? ''); } return parts.join('').trim(); } /** * Check if a table row contains ONLY paragraphs that match the strip patterns * (or are empty). If so, the entire row can be safely removed. */ function isRowOnlyDraftingNotes(tr, patterns) { const paras = tr.getElementsByTagNameNS(W_NS, 'p'); if (paras.length === 0) return false; for (let i = 0; i < paras.length; i++) { const text = extractParagraphText(paras[i]); if (text === '') continue; // empty paragraphs are fine to remove if (!patterns.some((r) => r.test(text))) return false; // non-matching content } return true; } /** * Remove paragraphs matching the given patterns from a DOCX buffer. * If a matched paragraph is the sole content of a table row, the entire * row is removed (avoids empty highlighted rows in Common Paper docs). * * Returns a new DOCX buffer with the paragraphs removed. */ function stripParagraphs(docxBuffer, patterns) { if (patterns.length === 0) return docxBuffer; const zip = new AdmZip(docxBuffer); const parser = new DOMParser(); const serializer = new XMLSerializer(); const parts = enumerateTextParts(zip); const partNames = getGeneralTextPartNames(parts); let modified = false; for (const partName of partNames) { const entry = zip.getEntry(partName); if (!entry) continue; const xml = entry.getData().toString('utf-8'); const doc = parser.parseFromString(xml, 'text/xml'); // Collect table rows to remove (whole row when only drafting notes) const rowsToRemove = new Set(); // Collect standalone paragraphs to remove const parasToRemove = []; const allParagraphs = doc.getElementsByTagNameNS(W_NS, 'p'); for (let i = 0; i < allParagraphs.length; i++) { const para = allParagraphs[i]; const text = extractParagraphText(para); if (!text || !patterns.some((r) => r.test(text))) continue; // Walk up to find if this is inside a table cell let node = para.parentNode; let inTableCell = false; let tableRow = null; while (node) { if (node.nodeType === 1) { const element = node; if (element.localName === 'tc' && element.namespaceURI === W_NS) { inTableCell = true; } if (element.localName === 'tr' && element.namespaceURI === W_NS) { tableRow = element; break; } } node = node.parentNode; } if (inTableCell && tableRow && isRowOnlyDraftingNotes(tableRow, patterns)) { rowsToRemove.add(tableRow); } else { parasToRemove.push(para); } } if (rowsToRemove.size > 0 || parasToRemove.length > 0) { modified = true; for (const row of rowsToRemove) { row.parentNode?.removeChild(row); } for (const para of parasToRemove) { para.parentNode?.removeChild(para); } // Update the zip entry const outXml = serializer.serializeToString(doc); zip.updateFile(partName, Buffer.from(outXml, 'utf-8')); } } if (!modified) return docxBuffer; // Rebuild the zip from scratch (adm-zip data descriptor workaround) const outZip = new AdmZip(); copyEntriesSkippingDirs(zip, outZip); return outZip.toBuffer(); } /** * Extract all text from a run (<w:r>) by concatenating its <w:t> elements. */ function extractRunText(run) { const tElements = run.getElementsByTagNameNS(W_NS, 't'); const parts = []; for (let i = 0; i < tElements.length; i++) { parts.push(tElements[i].textContent ?? ''); } return parts.join(''); } /** * Remove <w:highlight> elements only from runs whose template tags * are being filled with non-empty values. Unfilled fields keep their * yellow highlighting so users can see what still needs attention. * * Works by finding runs containing {field_name} tags, checking whether * the corresponding field has a non-empty value in the data, and only * stripping the highlight if it does. */ function stripFilledHighlighting(docxBuffer, filledFields) { if (filledFields.size === 0) return docxBuffer; const zip = new AdmZip(docxBuffer); const parser = new DOMParser(); const serializer = new XMLSerializer(); const parts = enumerateTextParts(zip); const partNames = getGeneralTextPartNames(parts); // Match {field_name} but not {IF ...} or {END-IF ...} etc. const tagPattern = /\{(\w+)\}/g; let modified = false; for (const partName of partNames) { const entry = zip.getEntry(partName); if (!entry) continue; const xml = entry.getData().toString('utf-8'); const doc = parser.parseFromString(xml, 'text/xml'); const allRuns = doc.getElementsByTagNameNS(W_NS, 'r'); const toRemove = []; for (let i = 0; i < allRuns.length; i++) { const run = allRuns[i]; const rPr = run.getElementsByTagNameNS(W_NS, 'rPr'); if (rPr.length === 0) continue; const highlights = rPr[0].getElementsByTagNameNS(W_NS, 'highlight'); if (highlights.length === 0) continue; // Check if this run's text contains a tag for a filled field const runText = extractRunText(run); let hasFilled = false; let match = null; tagPattern.lastIndex = 0; while ((match = tagPattern.exec(runText)) !== null) { if (filledFields.has(match[1])) { hasFilled = true; break; } } if (hasFilled) { for (let j = 0; j < highlights.length; j++) { toRemove.push(highlights[j]); } } } if (toRemove.length > 0) { modified = true; for (const el of toRemove) { el.parentNode?.removeChild(el); } const outXml = serializer.serializeToString(doc); zip.updateFile(partName, Buffer.from(outXml, 'utf-8')); } } if (!modified) return docxBuffer; const outZip = new AdmZip(); copyEntriesSkippingDirs(zip, outZip); return outZip.toBuffer(); } /** * Remove malformed/empty table rows that can be produced by conditional tags * (for example false {IF ...} blocks wrapped around full row content). * * Some viewers (notably Apple Pages) may render entire tables incorrectly when * a <w:tr> remains with <w:trPr> but no <w:tc> cells. */ function stripEmptyTableRows(docxBuffer) { const zip = new AdmZip(docxBuffer); const parser = new DOMParser(); const serializer = new XMLSerializer(); const parts = enumerateTextParts(zip); const partNames = getGeneralTextPartNames(parts); let modified = false; for (const partName of partNames) { const entry = zip.getEntry(partName); if (!entry) continue; const xml = entry.getData().toString('utf-8'); const doc = parser.parseFromString(xml, 'text/xml'); const rows = doc.getElementsByTagNameNS(W_NS, 'tr'); const rowsToRemove = []; for (let i = 0; i < rows.length; i++) { const row = rows[i]; let hasCell = false; let allCellsEmpty = true; for (let c = 0; c < row.childNodes.length; c++) { const child = row.childNodes[c]; if (child?.nodeType === 1) { const childElement = child; if (childElement.localName === 'tc' && childElement.namespaceURI === W_NS) { hasCell = true; const cellText = (childElement.textContent || '').trim(); if (cellText.length > 0) { allCellsEmpty = false; } } } } if (!hasCell || (hasCell && allCellsEmpty)) { rowsToRemove.push(row); } } // Deduplicate tcPr elements within table cells (docx-templates {IF} processing // can create duplicate <w:tcPr> blocks where the first has default properties // that override the intended ones in the second) const allCells = doc.getElementsByTagNameNS(W_NS, 'tc'); for (let i = 0; i < allCells.length; i++) { const cell = allCells[i]; const tcPrs = []; for (let c = 0; c < cell.childNodes.length; c++) { const child = cell.childNodes[c]; if (child.nodeType === 1 && child.localName === 'tcPr' && child.namespaceURI === W_NS) { tcPrs.push(child); } } if (tcPrs.length > 1) { modified = true; // Keep only the last tcPr (has the correct properties from our renderer) for (let t = 0; t < tcPrs.length - 1; t++) { cell.removeChild(tcPrs[t]); } } } // Also strip empty paragraphs within table cells (artifacts from {IF} tag processing) const cells = doc.getElementsByTagNameNS(W_NS, 'tc'); const parasToRemove = []; for (let i = 0; i < cells.length; i++) { const cell = cells[i]; const paras = cell.getElementsByTagNameNS(W_NS, 'p'); // Only strip empty paras if the cell has at least 2 paragraphs // (keep the last one — Word requires at least one <w:p> per cell) if (paras.length < 2) continue; let nonEmptyCount = 0; for (let p = 0; p < paras.length; p++) { if ((paras[p].textContent || '').trim().length > 0) nonEmptyCount++; } if (nonEmptyCount === 0) continue; // Don't strip if all are empty for (let p = 0; p < paras.length; p++) { if ((paras[p].textContent || '').trim().length === 0 && paras[p].parentNode === cell) { parasToRemove.push(paras[p]); } } } for (const para of parasToRemove) { para.parentNode?.removeChild(para); } if (rowsToRemove.length > 0 || parasToRemove.length > 0) { modified = true; for (const row of rowsToRemove) { row.parentNode?.removeChild(row); } const outXml = serializer.serializeToString(doc); zip.updateFile(partName, Buffer.from(outXml, 'utf-8')); } } if (!modified) return docxBuffer; const outZip = new AdmZip(); copyEntriesSkippingDirs(zip, outZip); return outZip.toBuffer(); } /** * True if `borders` (a `<w:tcBorders>` or `<w:pBdr>` element) declares a visible * bottom border — i.e. the line is already "ruled". A `<w:bottom>` with val * `none`/`nil` (or absent) is not a rule. */ function hasVisibleBottomBorder(borders) { if (!borders) return false; const bottoms = borders.getElementsByTagNameNS(W_NS, 'bottom'); for (let i = 0; i < bottoms.length; i++) { if (bottoms[i].parentNode !== borders) continue; // direct child only const val = bottoms[i].getAttribute('w:val'); if (val && val !== 'none' && val !== 'nil') return true; } return false; } /** First matching `<w:NAME>` element that is a direct child of `parent`, or null. */ function directChild(parent, name) { if (!parent) return null; for (let i = 0; i < parent.childNodes.length; i++) { const child = parent.childNodes[i]; if (child?.nodeType === 1 && child.localName === name && child.namespaceURI === W_NS) { return child; } } return null; } /** Last `<w:p>` that is a direct child of `cell` — the line its bottom border underlines. */ function lastDirectParagraph(cell) { let last = null; for (let i = 0; i < cell.childNodes.length; i++) { const child = cell.childNodes[i]; if (child?.nodeType === 1 && child.localName === 'p' && child.namespaceURI === W_NS) { last = child; } } return last; } /** * True when `run` sits on a line that already carries a bottom-border rule: * - its paragraph has its own bottom border (`<w:p>/<w:pPr>/<w:pBdr>/<w:bottom>`), or * - it is in the LAST paragraph of a table cell whose bottom border is visible * (`<w:tc>/<w:tcPr>/<w:tcBorders>/<w:bottom>`). * * The last-paragraph guard matters: a cell's bottom border only underlines the * cell's final line, so a placeholder in an earlier paragraph of a multi-line * cell is NOT on the rule and must be left alone. Purely structural — it asks * what the OOXML draws, never what the field means. */ function sitsOnRuledLine(run) { let cell = null; let para = null; let node = run.parentNode; while (node) { if (node.nodeType === 1) { const el = node; if (el.namespaceURI === W_NS) { if (!para && el.localName === 'p') para = el; if (!cell && el.localName === 'tc') cell = el; } } node = node.parentNode; } const paraBorders = directChild(directChild(para, 'pPr'), 'pBdr'); if (hasVisibleBottomBorder(paraBorders)) return true; const cellBorders = directChild(directChild(cell, 'tcPr'), 'tcBorders'); if (hasVisibleBottomBorder(cellBorders) && cell && para === lastDirectParagraph(cell)) { return true; } return false; } /** * Suppress the blank-fill placeholder ('_______') on runs that already sit on a * ruled line. The placeholder exists to draw a "write a value here" line where * the template provides none; on a line that is already ruled (a signature * block, an underlined field) it just stacks a second underline on top of the * existing rule. This clears the redundant underscores — leaving the rule as the * clean blank line — and drops any authoring highlight left on the run. * * Structural by design: it keys off the OOXML border, not off field names, so it * needs no knowledge of which fields are "signatures". A blank placeholder on an * un-ruled line is left untouched (its underscores are the intended cue). */ function stripBlankPlaceholderOnRuledLines(docxBuffer) { const zip = new AdmZip(docxBuffer); const parser = new DOMParser(); const serializer = new XMLSerializer(); const parts = enumerateTextParts(zip); const partNames = getGeneralTextPartNames(parts); let modified = false; for (const partName of partNames) { const entry = zip.getEntry(partName); if (!entry) continue; const doc = parser.parseFromString(entry.getData().toString('utf-8'), 'text/xml'); const runs = doc.getElementsByTagNameNS(W_NS, 'r'); let changed = false; for (let i = 0; i < runs.length; i++) { const run = runs[i]; // Only a run whose entire text IS the blank placeholder — not underscores // embedded in real prose. if (extractRunText(run).trim() !== BLANK_PLACEHOLDER) continue; if (!sitsOnRuledLine(run)) continue; // Remove only the placeholder underscores, preserving any surrounding // whitespace — a trailing space can be a signing-anchor callers rely on // (#109) — and keeping the run/paragraph so the rule itself survives. const tEls = run.getElementsByTagNameNS(W_NS, 't'); for (let t = 0; t < tEls.length; t++) { tEls[t].textContent = (tEls[t].textContent ?? '').replace(BLANK_PLACEHOLDER, ''); } // Drop any leftover authoring highlight on the now-empty run. const rPr = run.getElementsByTagNameNS(W_NS, 'rPr'); if (rPr.length > 0) { const highlights = rPr[0].getElementsByTagNameNS(W_NS, 'highlight'); for (let h = highlights.length - 1; h >= 0; h--) { highlights[h].parentNode?.removeChild(highlights[h]); } } changed = true; } if (changed) { modified = true; zip.updateFile(partName, Buffer.from(serializer.serializeToString(doc), 'utf-8')); } } if (!modified) return docxBuffer; const outZip = new AdmZip(); copyEntriesSkippingDirs(zip, outZip); return outZip.toBuffer(); } /** * Fill a DOCX template with prepared data: * 1. Strip drafting note paragraphs (configurable, on by default) * 2. Strip highlighting from runs with filled fields (unfilled keep their highlight) * 3. Sanitize currency and percentage values by scanning the template buffer for * ${field} and {field}% patterns * 4. Call docx-templates createReport() with standard delimiters * 5. Remove structurally empty table rows left by conditional rendering * 6. Suppress the blank-fill placeholder on lines that already carry a rule * 7. Return the filled buffer */ export async function fillDocx(options) { const { data, fixSmartQuotes = false, stripParagraphPatterns = DEFAULT_STRIP_PATTERNS, } = options; let { templateBuffer } = options; // Step 1: Strip drafting notes (and other configured patterns) if (stripParagraphPatterns.length > 0) { templateBuffer = stripParagraphs(templateBuffer, stripParagraphPatterns); } // Step 2: Strip highlighting only from fields that have non-empty values. // Unfilled fields keep their yellow highlight as a visual cue. const filledFields = new Set(); for (const [key, val] of Object.entries(data)) { if (typeof val === 'string' && val !== '' && val !== BLANK_PLACEHOLDER) { filledFields.add(key); } else if (typeof val === 'boolean') { filledFields.add(key); // booleans are always "filled" } } templateBuffer = stripFilledHighlighting(templateBuffer, filledFields); // Step 3: Strip the redundant sigil from values where the template already // carries it — a leading $ where the template has ${ before the tag, and a // trailing % where the template has a % after the tag. const sanitizedData = sanitizePercentValuesFromDocx(sanitizeCurrencyValuesFromDocx(data, templateBuffer), templateBuffer); // Step 4: Fill template const filled = await createReport({ template: templateBuffer, data: sanitizedData, cmdDelimiter: ['{', '}'], fixSmartQuotes, // Emit line breaks as separate text runs for viewer compatibility. processLineBreaks: true, processLineBreaksAsNewText: true, }); const filledBuffer = rezipWithoutDirEntries(new AdmZip(Buffer.from(filled))).toBuffer(); // Step 5: Remove malformed empty table rows from conditional rendering const cleaned = stripEmptyTableRows(filledBuffer); // Step 6: Drop the blank placeholder where the line is already ruled, so an // unfilled field on a signature/underlined line shows a single clean rule // instead of stacking underscores on top of the existing border. const deruled = stripBlankPlaceholderOnRuledLines(cleaned); // Step 7: Renumber clause headings so fully-omitted clauses leave no gap return renumberClauseHeadings(deruled); } /** The OAClauseHeading style marks the numbered standard-terms clause headings. */ const CLAUSE_HEADING_STYLE = 'OAClauseHeading'; /** Read a paragraph's direct pStyle value (or null). */ function paragraphStyle(p) { for (let i = 0; i < p.childNodes.length; i++) { const child = p.childNodes[i]; if (child?.nodeType === 1 && child.localName === 'pPr' && child.namespaceURI === W_NS) { const styles = child.getElementsByTagNameNS(W_NS, 'pStyle'); return styles.length > 0 ? styles[0].getAttribute('w:val') : null; } } return null; } /** * Replace the characters in [start, end) across an ordered list of <w:t> text * nodes with `replacement` (inserted at `start`). Preserves run formatting by * editing only the affected runs' text. Used to swap a clause heading's leading * number even if it is split across runs. */ function rewriteTextRange(segments, start, end, replacement) { let offset = 0; let inserted = false; for (const seg of segments) { const segStart = offset; const segEnd = offset + seg.text.length; offset = segEnd; if (segEnd <= start || segStart >= end) continue; // untouched run const localStart = Math.max(0, start - segStart); const localEnd = Math.min(seg.text.length, end - segStart); const before = seg.text.slice(0, localStart); const after = seg.text.slice(localEnd); seg.text = before + (inserted ? '' : replacement) + after; seg.node.textContent = seg.text; inserted = true; } } /** Read the `<w:t>` text nodes of a paragraph as an ordered, editable segment list. */ function paragraphTextSegments(p) { const tEls = p.getElementsByTagNameNS(W_NS, 't'); const segments = []; for (let j = 0; j < tEls.length; j++) { segments.push({ node: tEls[j], text: tEls[j].textContent ?? '' }); } return segments; } /** Matches a cover-notice cross-reference sentinel "<<xref:oa_xref_…>>". */ const XREF_SENTINEL_RE = /<<xref:(oa_xref_[0-9a-f]+)>>/; /** * Renumber standard-terms clause headings (style OAClauseHeading) sequentially * (1..N) in `word/document.xml` after {IF} resolution, so a fully-omitted clause * leaves no gap. Clause numbers are literal text (not Word list numbering), so a * dropped clause would otherwise skip a number. Idempotent: a heading already * carrying its sequential number is untouched. * * Same pass resolves the cover confirmation notice's cross-reference sentinels: * each `<<xref:<bookmark>>>` is rewritten to the live, post-renumber "Section N" * of the clause whose heading carries that bookmark (the renderer wraps the * sentinel in an internal hyperlink to the same bookmark, so the visible number * also becomes the clickable jump target). Name-based `[[clause:id]]` references * resolve to heading text upstream, so renumbering breaks no references. */ function renumberClauseHeadings(docxBuffer) { const zip = new AdmZip(docxBuffer); const docEntry = zip.getEntry('word/document.xml'); if (!docEntry) return docxBuffer; const parser = new DOMParser(); const serializer = new XMLSerializer(); const doc = parser.parseFromString(docEntry.getData().toString('utf-8'), 'text/xml'); const paragraphs = doc.getElementsByTagNameNS(W_NS, 'p'); let counter = 0; let changed = false; // First pass: assign sequential numbers and map each heading's xref bookmark // (if any) to its resolved number, so the cover-notice sentinels can link to it. const numberByBookmark = new Map(); for (let i = 0; i < paragraphs.length; i++) { const p = paragraphs[i]; if (paragraphStyle(p) !== CLAUSE_HEADING_STYLE) continue; const segments = paragraphTextSegments(p); const full = segments.map((s) => s.text).join(''); const m = full.match(/^(\s*)(\d+)\./); if (!m) continue; // a heading without a leading "N." — leave it alone counter += 1; const bookmarkStarts = p.getElementsByTagNameNS(W_NS, 'bookmarkStart'); for (let k = 0; k < bookmarkStarts.length; k++) { const name = bookmarkStarts[k].getAttribute('w:name'); if (name && name.startsWith('oa_xref_')) numberByBookmark.set(name, counter); } const newDigits = String(counter); if (m[2] === newDigits) continue; // already correct (idempotent) const start = m[1].length; rewriteTextRange(segments, start, start + m[2].length, newDigits); changed = true; } // Second pass: resolve cover-notice cross-reference sentinels to "Section N". // A present bullet always has a present (un-omitted) target heading, so the // bookmark is in the map; the empty-string fallback is purely defensive. for (let i = 0; i < paragraphs.length; i++) { const p = paragraphs[i]; const segments = paragraphTextSegments(p); if (segments.length === 0) continue; let match = segments.map((s) => s.text).join('').match(XREF_SENTINEL_RE); while (match && match.index !== undefined) { const num = numberByBookmark.get(match[1]); const replacement = num !== undefined ? `Section ${num}` : ''; rewriteTextRange(segments, match.index, match.index + match[0].length, replacement); changed = true; match = segments.map((s) => s.text).join('').match(XREF_SENTINEL_RE); } } if (!changed) return docxBuffer; zip.updateFile('word/document.xml', Buffer.from(serializer.serializeToString(doc), 'utf-8')); const outZip = new AdmZip(); copyEntriesSkippingDirs(zip, outZip); return outZip.toBuffer(); } //# sourceMappingURL=fill-pipeline.js.map