open-agreements
Version:
Open-source legal template filling CLI and library
291 lines • 11.9 kB
JavaScript
import { parseXml, serializeXml } from './xml.js';
import { childElements, createWmlElement, renameElement } from './dom-helpers.js';
import { OOXML } from './namespaces.js';
const SYNTHETIC_DOC = parseXml('<root xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main"/>');
const EXCLUDED_PPR_CHANGE_CHILDREN = new Set(['w:rPr', 'w:rPrChange', 'w:pPrChange', 'w:sectPr']);
const EXCLUDED_TRPR_CHANGE_CHILDREN = new Set(['w:trPrChange', 'w:ins', 'w:del']);
// CT_TcPrInner (the inner pPr under <w:tcPrChange>) preserves cell-topology
// revision children (w:cellIns, w:cellDel, w:cellMerge). Only the
// change-of-a-change marker w:tcPrChange itself is excluded. See:
// https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.wordprocessing.previoustablecellproperties
const EXCLUDED_TCPR_CHANGE_CHILDREN = new Set(['w:tcPrChange']);
const EXCLUDED_RPR_CHANGE_CHILDREN = new Set(['w:rPrChange']);
/**
* Create a revision ID allocator.
*
* @param startId - First ID to allocate. Defaults to `1`.
*/
export function createRevisionIdState(startId = 1) {
return {
nextId: startId,
moveRangeIds: new Map(),
};
}
/**
* Allocate the next revision ID from a shared state object.
*/
export function allocateRevisionId(state) {
return state.nextId++;
}
/**
* Format a revision timestamp as OOXML-friendly ISO 8601.
*/
export function formatDate(date) {
return date.toISOString().replace(/\.\d{3}Z$/, 'Z');
}
/**
* Escape XML attribute text used in serialized revision markup.
*/
export function escapeXmlAttr(text) {
return text
.replace(/&/g, '&')
.replace(/</g, '<')
.replace(/>/g, '>')
.replace(/"/g, '"');
}
/**
* Create a reusable revision context for tracked-change emission.
*/
export function createRevisionContext(options) {
const { author, date, idState = createRevisionIdState() } = options;
return {
author,
date: typeof date === 'string' ? date : formatDate(date ?? new Date()),
idState,
};
}
/**
* Create a fresh tracked-change container (`<w:ins>` or `<w:del>`) into which
* the caller appends owned child nodes.
*
* Use this when wrapping multiple sibling elements under one revision marker.
* For single-element wrapping, prefer `wrapElementWithIns` / `wrapElementWithDel`.
*/
export function createRevisionContainer(doc, kind, ctx) {
return createRevisionWrapperElement(doc, kind, ctx);
}
/**
* Rewrite `<w:t>` → `<w:delText>` and `<w:instrText>` → `<w:delInstrText>`
* on the given element and all its descendants, for use inside a `<w:del>`
* container.
*
* **CALLERS MUST USE THE RETURN VALUE.** When the input element itself is a
* root `<w:t>` or `<w:instrText>`, this helper creates a renamed replacement
* node (you cannot rename a DOM element in place); the input element is
* detached from the tree and the new node is returned. Pattern:
*
* const ready = prepareElementForDeletion(detachedElement);
* wrapper.appendChild(ready);
*
* The element MUST already be detached from any parent. Calling on an
* attached element will leave the original tree in an inconsistent state.
*/
export function prepareElementForDeletion(element) {
return normalizeDeletionElement(element);
}
/**
* Wrap an xmldom element in `<w:ins>`.
*
* The source element is cloned; the original DOM node is left untouched.
*/
export function wrapElementWithIns(element, ctx) {
const wrapper = createRevisionContainer(getOwnerDocument(element), 'ins', ctx);
wrapper.appendChild(element.cloneNode(true));
return wrapper;
}
/**
* Wrap an xmldom element in `<w:del>`.
*
* Any descendant `<w:t>` and `<w:instrText>` nodes are converted to the OOXML
* deletion equivalents before the cloned element is appended.
*/
export function wrapElementWithDel(element, ctx) {
const wrapper = createRevisionContainer(getOwnerDocument(element), 'del', ctx);
const cloned = prepareElementForDeletion(element.cloneNode(true));
wrapper.appendChild(cloned);
return wrapper;
}
/**
* Build a `<w:pPrChange>` wrapper containing the previous paragraph properties.
*
* The nested snapshot excludes children that are not valid in `CT_PPrBase`.
*/
export function buildPPrChangeElement(oldPPr, ctx) {
const pPrChange = createWmlElement(getOwnerDocument(oldPPr), 'pPrChange', revisionAttributes(ctx));
const previousPPr = createWmlElement(getOwnerDocument(oldPPr), 'pPr');
if (oldPPr) {
for (const child of childElements(oldPPr)) {
if (!EXCLUDED_PPR_CHANGE_CHILDREN.has(child.tagName)) {
previousPPr.appendChild(child.cloneNode(true));
}
}
}
pPrChange.appendChild(previousPPr);
return pPrChange;
}
/**
* Build a `<w:trPrChange>` wrapper containing the previous row properties.
*
* The nested snapshot excludes children that are not valid in `CT_TrPrBase`.
*/
export function buildTrPrChangeElement(oldTrPr, ctx) {
const trPrChange = createWmlElement(getOwnerDocument(oldTrPr), 'trPrChange', revisionAttributes(ctx));
const previousTrPr = createWmlElement(getOwnerDocument(oldTrPr), 'trPr');
if (oldTrPr) {
for (const child of childElements(oldTrPr)) {
if (!EXCLUDED_TRPR_CHANGE_CHILDREN.has(child.tagName)) {
previousTrPr.appendChild(child.cloneNode(true));
}
}
}
trPrChange.appendChild(previousTrPr);
return trPrChange;
}
/**
* Build a `<w:tcPrChange>` wrapper containing the previous cell properties.
*
* The nested snapshot excludes children that are not valid in `CT_TcPrBase`.
*/
export function buildTcPrChangeElement(oldTcPr, ctx) {
const tcPrChange = createWmlElement(getOwnerDocument(oldTcPr), 'tcPrChange', revisionAttributes(ctx));
const previousTcPr = createWmlElement(getOwnerDocument(oldTcPr), 'tcPr');
if (oldTcPr) {
for (const child of childElements(oldTcPr)) {
if (!EXCLUDED_TCPR_CHANGE_CHILDREN.has(child.tagName)) {
previousTcPr.appendChild(child.cloneNode(true));
}
}
}
tcPrChange.appendChild(previousTcPr);
return tcPrChange;
}
/**
* Build a `<w:rPrChange>` wrapper containing the previous run properties.
*
* The nested snapshot excludes any existing `w:rPrChange` child. This filtering
* is intentional: OOXML does not permit recursively nested `w:rPrChange` (a
* change-of-a-change is undefined), so the helper drops it. Note this is a
* stricter contract than the legacy reconstructor's per-child loop, which
* would have passed a nested `w:rPrChange` through verbatim. The reconstructor
* still uses its own per-child path; this helper is for new primitive code
* (#136 onward).
*/
export function buildRPrChangeElement(oldRPr, ctx) {
const rPrChange = createWmlElement(getOwnerDocument(oldRPr), 'rPrChange', revisionAttributes(ctx));
const previousRPr = createWmlElement(getOwnerDocument(oldRPr), 'rPr');
if (oldRPr) {
for (const child of childElements(oldRPr)) {
if (!EXCLUDED_RPR_CHANGE_CHILDREN.has(child.tagName)) {
previousRPr.appendChild(child.cloneNode(true));
}
}
}
rPrChange.appendChild(previousRPr);
return rPrChange;
}
/**
* Wrap serialized OOXML content in a `<w:ins>` element.
*
* This keeps the reconstructor on its string-based emission path while sharing
* revision metadata handling with the DOM-aware helpers above.
*/
export function wrapSerializedContentWithIns(content, ctx) {
return `${createSerializedRevisionOpenTag('w:ins', ctx)}${content}</w:ins>`;
}
/**
* Wrap serialized OOXML content in a `<w:del>` element.
*
* Visible text nodes are rewritten to their deletion-tag equivalents before
* the wrapper is serialized.
*/
export function wrapSerializedContentWithDel(content, ctx) {
return `${createSerializedRevisionOpenTag('w:del', ctx)}${convertSerializedDeletionContent(content)}</w:del>`;
}
/**
* Matches a `<w:t>` or `<w:instrText>` open tag (including the self-closing
* form). Used as a fast path: content with no convertible tags is returned
* byte-for-byte unchanged, skipping the parse/serialize round-trip.
*/
const CONVERTIBLE_TEXT_TAG = /<w:(?:t|instrText)[\s/>]/;
/**
* Convert serialized run content from insertion-style text tags to deletion
* equivalents (`w:t` -> `w:delText`, `w:instrText` -> `w:delInstrText`).
*
* The fragment is parsed into a DOM and renamed via the same traversal as
* `prepareElementForDeletion`, so attribute order is preserved and shapes a
* regex sweep mishandles (self-closing `<w:t/>`, attribute values containing
* `>`) convert correctly. Namespace prefixes the fragment uses without an
* inline declaration are bound on a temporary wrapper root that is stripped
* from the returned serialization.
*
* @see https://github.com/UseJunior/safe-docx/issues/102
*/
export function convertSerializedDeletionContent(content) {
if (!CONVERTIBLE_TEXT_TAG.test(content)) {
return content;
}
const doc = parseXml(`<root${declareContentPrefixes(content)}>${content}</root>`);
for (const child of childElements(doc.documentElement)) {
normalizeDeletionElement(child);
}
// Strip the wrapper root: everything between the end of its open tag and
// the start of its close tag. Safe because the declared URIs contain no '>'.
const serialized = serializeXml(doc);
return serialized.slice(serialized.indexOf('>') + 1, serialized.lastIndexOf('<'));
}
/**
* Matches a `prefix:` occurrence in markup context — after `<`, `</`, or
* whitespace (attribute position). May over-match inside text content, which
* is harmless: it only yields an unused declaration on the wrapper root.
*/
const PREFIX_SCAN = /[<\s]\/?([A-Za-z_][A-Za-z0-9_.-]*):/g;
/**
* Build `xmlns` declarations for every namespace prefix a serialized fragment
* uses, so the fragment parses under a wrapper root (xmldom rejects
* undeclared prefixes). `w` binds to the real WordprocessingML namespace —
* the deletion rename produces elements in that namespace — while unknown
* prefixes get placeholder URIs. The wrapper root carrying these declarations
* is stripped after serialization, so placeholders never reach the output;
* fragments serialized from a real document carry their own inline
* declarations, which take precedence over the wrapper's.
*/
function declareContentPrefixes(content) {
const declarations = new Map([['w', OOXML.W_NS]]);
for (const match of content.matchAll(PREFIX_SCAN)) {
const prefix = match[1];
if (prefix !== 'xml' && prefix !== 'xmlns' && !declarations.has(prefix)) {
declarations.set(prefix, `urn:safe-docx:undeclared-prefix:${prefix}`);
}
}
return [...declarations].map(([prefix, uri]) => ` xmlns:${prefix}="${uri}"`).join('');
}
function getOwnerDocument(element) {
return element?.ownerDocument ?? SYNTHETIC_DOC;
}
function revisionAttributes(ctx) {
return {
'w:id': String(allocateRevisionId(ctx.idState)),
'w:author': ctx.author,
'w:date': ctx.date,
};
}
function createRevisionWrapperElement(doc, tag, ctx) {
return createWmlElement(doc, tag, revisionAttributes(ctx));
}
function createSerializedRevisionOpenTag(tagName, ctx) {
const id = allocateRevisionId(ctx.idState);
return `<${tagName} w:id="${id}" w:author="${escapeXmlAttr(ctx.author)}" w:date="${ctx.date}">`;
}
function normalizeDeletionElement(element) {
for (const child of childElements(element)) {
normalizeDeletionElement(child);
}
if (element.tagName === 'w:t') {
return renameElement(element, 'w:delText');
}
if (element.tagName === 'w:instrText') {
return renameElement(element, 'w:delInstrText');
}
return element;
}
//# sourceMappingURL=track-changes-emitter.js.map