open-agreements
Version:
Open-source legal template filling CLI and library
238 lines • 8.35 kB
JavaScript
/**
* DOM Helper Layer
*
* Thin helpers that bridge xmldom's missing APIs and enforce the text semantics
* contract for OOXML processing. These helpers address:
*
* 1. Leaf text contract — getLeafText() returns direct text child value only,
* unlike DOM textContent which is recursive. Critical for hash/compare code.
* 2. Child element access — wraps xmldom's .children (0.9+) with static array return.
* 3. Tree manipulation — insertAfter, wrap, unwrap operations.
* 4. Namespace-safe element creation — always use createElementNS for OOXML.
*/
import { OOXML } from './namespaces.js';
// ── DOM node type constants (avoid magic numbers) ──────────────────
export const NODE_TYPE = {
ELEMENT: 1,
TEXT: 3,
PROCESSING_INSTRUCTION: 7,
COMMENT: 8,
DOCUMENT: 9,
};
// ── Leaf text contract ─────────────────────────────────────────────
/**
* Get direct text child value (leaf-only). Returns undefined if no text child.
*
* Use this instead of el.textContent in hash/compare code — DOM textContent
* is recursive and would silently break hashing on container elements.
*/
export function getLeafText(el) {
for (let i = 0; i < el.childNodes.length; i++) {
const child = el.childNodes[i];
if (child.nodeType === NODE_TYPE.TEXT)
return child.nodeValue ?? '';
}
return undefined;
}
/**
* Set the direct text content of a leaf element. Replaces or creates
* the first text child node.
*
* NOTE: We must update BOTH `data` and `nodeValue` on the text node.
* In @xmldom/xmldom, `CharacterData` stores text in two separate plain
* properties: `data` (read by XMLSerializer) and `nodeValue` (read by
* `textContent` getter). All CharacterData mutation methods keep them
* in sync, but a direct `child.nodeValue = text` assignment only updates
* `nodeValue`, leaving the stale original value in `data`. This causes
* XMLSerializer to output the old text. Using `replaceData` (which sets
* both atomically) is the correct W3C-compliant approach.
*/
export function setLeafText(el, text) {
for (let i = 0; i < el.childNodes.length; i++) {
const child = el.childNodes[i];
if (child.nodeType === NODE_TYPE.TEXT) {
child.replaceData(0, child.length, text);
return;
}
}
el.appendChild(el.ownerDocument.createTextNode(text));
}
// ── Child element access (static array from .children) ────────────
/**
* Get element-only children. Filters out text nodes, comments, PIs.
*/
export function childElements(el) {
if ('children' in el)
return Array.from(el.children);
const result = [];
for (let i = 0; i < el.childNodes.length; i++) {
const child = el.childNodes[i];
if (child.nodeType === NODE_TYPE.ELEMENT)
result.push(child);
}
return result;
}
/**
* Find the first direct child element with a specific tag name.
*/
export function findChildByTagName(el, tagName) {
const kids = el.children;
for (let i = 0; i < kids.length; i++) {
if (kids[i].tagName === tagName)
return kids[i];
}
return null;
}
// ── Tree manipulation helpers ──────────────────────────────────────
/**
* Insert newEl after refEl in parent.
*/
export function insertAfterElement(refEl, newEl) {
refEl.parentNode.insertBefore(newEl, refEl.nextSibling);
}
/**
* Wrap target in wrapper (replace target with wrapper, wrapper contains target).
*/
export function wrapElement(target, wrapper) {
target.parentNode.insertBefore(wrapper, target);
wrapper.appendChild(target);
}
/**
* Unwrap element — replace it with its children in parent.
*/
export function unwrapElement(el) {
const parent = el.parentNode;
while (el.firstChild)
parent.insertBefore(el.firstChild, el);
parent.removeChild(el);
}
/**
* Remove all descendant elements matching a tag name.
* Returns the number of elements removed.
*/
export function removeAllByTagName(root, tagName) {
const elements = Array.from(root.getElementsByTagName(tagName));
let count = 0;
for (const el of elements) {
if (el.parentNode) {
el.parentNode.removeChild(el);
count++;
}
}
return count;
}
/**
* Unwrap all elements matching a tag name throughout the tree.
* Returns the number of elements unwrapped.
*/
export function unwrapAllByTagName(root, tagName) {
// Collect deepest-first to handle nesting correctly
const elements = Array.from(root.getElementsByTagName(tagName));
elements.reverse();
let count = 0;
for (const el of elements) {
if (el.parentNode) {
unwrapElement(el);
count++;
}
}
return count;
}
/**
* Find all descendant elements with a specific tag name.
* Returns a static array (unlike the live NodeList from getElementsByTagName).
*/
export function findAllByTagName(root, tagName) {
const nodeList = root.getElementsByTagName(tagName);
const result = [];
for (let i = 0; i < nodeList.length; i++) {
result.push(nodeList[i]);
}
return result;
}
/**
* Rename an element by creating a new element with the target tag name,
* copying all attributes and children, and replacing it in the parent.
*
* Returns the new element. Callers holding a reference to the old element
* should update to use the returned value.
*/
export function renameElement(el, newTagName) {
const doc = el.ownerDocument;
const ns = el.namespaceURI;
const newEl = ns ? doc.createElementNS(ns, newTagName) : doc.createElement(newTagName);
// Copy attributes
for (let i = 0; i < el.attributes.length; i++) {
const attr = el.attributes[i];
newEl.setAttribute(attr.name, attr.value);
}
// Move children
while (el.firstChild) {
newEl.appendChild(el.firstChild);
}
// Replace in parent
if (el.parentNode) {
el.parentNode.replaceChild(newEl, el);
}
return newEl;
}
/**
* Insert a child element at a specific index position.
* If index >= child count, appends at the end.
*/
export function insertChildAt(parent, child, index) {
const children = childElements(parent);
if (index >= children.length) {
parent.appendChild(child);
}
else {
parent.insertBefore(child, children[index]);
}
}
// ── Namespace-safe OOXML element creation ──────────────────────────
/**
* Create OOXML element with correct namespace. Never use plain createElement
* for OOXML tags — it yields namespaceURI=null which breaks namespace-aware code.
*/
export function createWmlElement(doc, localTag, attrs) {
const el = doc.createElementNS(OOXML.W_NS, `w:${localTag}`);
if (attrs) {
for (const [k, v] of Object.entries(attrs)) {
el.setAttribute(k, v);
}
}
return el;
}
/**
* Create a w:t text element with the given text content.
* Automatically sets xml:space="preserve" to maintain whitespace fidelity.
*/
export function createWmlTextElement(doc, text) {
const el = doc.createElementNS(OOXML.W_NS, 'w:t');
el.setAttribute('xml:space', 'preserve');
el.appendChild(doc.createTextNode(text));
return el;
}
// ── Namespace-aware OOXML element checks ───────────────────────────
/**
* Check if an element is in the OOXML WordprocessingML namespace
* with the given local name.
*/
export function isW(el, localName) {
return !!el && el.namespaceURI === OOXML.W_NS && el.localName === localName;
}
/**
* Get direct child elements in the OOXML WordprocessingML namespace
* with a specific local name. Unlike getElementsByTagNameNS, this only
* returns direct children (not nested descendants).
*/
export function getDirectChildrenByName(parent, localName) {
const out = [];
const kids = parent.children;
for (let i = 0; i < kids.length; i++) {
if (isW(kids[i], localName))
out.push(kids[i]);
}
return out;
}
//# sourceMappingURL=dom-helpers.js.map