@ansonlai/docx-redline-js 0.8.4 → 0.10.0

package/core/current-properties.js

@@ -0,0 +1,136 @@
+/**
+ * Single accessor for CURRENT paragraph/run properties.
+ *
+ * Descendant lookups (`getElementsByTagNameNS`, `getWordDescendants`, ...) cross `w:pPrChange` and
+ * `w:rPrChange`, so a historical `numPr`/`pStyle`/`b` snapshot looks like a current value. Everything in
+ * this module reads direct children of `w:pPr` / `w:rPr` only. The `*PrChange` snapshot is reachable
+ * only through the explicit `getHistorical*` functions (reject simulation, restore).
+ *
+ * Depends only on `core/types.js`.
+ */
+
+import { NS_W } from './types.js';
+
+function isWordElement(node, localName) {
+    if (!node || node.nodeType !== 1) return false;
+    const name = String(node.localName || node.nodeName || '').replace(/^.*:/, '');
+    if (localName != null && name !== localName) return false;
+    return !node.namespaceURI || node.namespaceURI === NS_W;
+}
+
+/** First direct child element with the given WordprocessingML local name. */
+export function getDirectWordChild(node, localName) {
+    if (!node) return null;
+    for (const child of Array.from(node.childNodes || [])) {
+        if (isWordElement(child, localName)) return child;
+    }
+    return null;
+}
+
+/** Direct child elements with the given local name (all direct Word elements when omitted). */
+export function getDirectWordChildren(node, localName) {
+    if (!node) return [];
+    return Array.from(node.childNodes || []).filter(child => isWordElement(child, localName));
+}
+
+/** Direct child of a properties element; never descends into `*PrChange` snapshots. */
+export function getCurrentChild(propsEl, localName) {
+    return getDirectWordChild(propsEl, localName);
+}
+
+function readVal(el) {
+    if (!el) return null;
+    const value = (typeof el.getAttributeNS === 'function' && el.getAttributeNS(NS_W, 'val'))
+        || el.getAttribute?.('w:val')
+        || el.getAttribute?.('val')
+        || null;
+    return value === '' ? null : value;
+}
+
+function readNumPr(propsEl) {
+    const numPr = getDirectWordChild(propsEl, 'numPr');
+    if (!numPr) return null;
+    return {
+        element: numPr,
+        numId: readVal(getDirectWordChild(numPr, 'numId')),
+        ilvl: readVal(getDirectWordChild(numPr, 'ilvl')),
+        numIdElement: getDirectWordChild(numPr, 'numId'),
+        ilvlElement: getDirectWordChild(numPr, 'ilvl')
+    };
+}
+
+function readParagraphProps(pPr) {
+    const pStyleEl = getDirectWordChild(pPr, 'pStyle');
+    const outlineEl = getDirectWordChild(pPr, 'outlineLvl');
+    return {
+        pPr: pPr || null,
+        numPr: readNumPr(pPr),
+        pStyle: readVal(pStyleEl),
+        pStyleElement: pStyleEl,
+        outlineLvl: readVal(outlineEl),
+        outlineLvlElement: outlineEl
+    };
+}
+
+/** Current paragraph properties: the paragraph's direct `w:pPr` only. */
+export function getCurrentParagraphProperties(p) {
+    return readParagraphProps(getDirectWordChild(p, 'pPr'));
+}
+
+/** Current run properties: the run's direct `w:rPr` (null when absent). */
+export function getCurrentRunProperties(r) {
+    return getDirectWordChild(r, 'rPr');
+}
+
+/** Paragraph-mark run properties (`w:pPr/w:rPr`), distinct from any run's `rPr`. */
+export function getParagraphMarkProperties(p) {
+    return getDirectWordChild(getDirectWordChild(p, 'pPr'), 'rPr');
+}
+
+/**
+ * Historical paragraph properties: the `w:pPrChange/w:pPr` snapshot. Explicit opt-in; shape matches
+ * `getCurrentParagraphProperties`. Returns null when the paragraph has no tracked property change.
+ */
+export function getHistoricalParagraphProperties(p) {
+    const change = getDirectWordChild(getDirectWordChild(p, 'pPr'), 'pPrChange');
+    const snapshot = getDirectWordChild(change, 'pPr');
+    return snapshot ? readParagraphProps(snapshot) : null;
+}
+
+/** Historical run properties: the `w:rPrChange/w:rPr` snapshot, or null. */
+export function getHistoricalRunProperties(r) {
+    const change = getDirectWordChild(getDirectWordChild(r, 'rPr'), 'rPrChange');
+    return getDirectWordChild(change, 'rPr');
+}
+
+/** All `w:p` elements at or under `root` (the paragraph itself when `root` is one). */
+function paragraphsUnder(root) {
+    if (!root || root.nodeType !== 1) return [];
+    const out = isWordElement(root, 'p') ? [root] : [];
+    if (typeof root.getElementsByTagNameNS === 'function') {
+        out.push(...Array.from(root.getElementsByTagNameNS(NS_W, 'p')));
+    }
+    return out;
+}
+
+/**
+ * Current `w:numId` elements (direct `pPr/numPr/numId`) of every paragraph at or under `root`.
+ * Excludes `pPrChange` snapshots, so Reject still restores the snapshot numId.
+ */
+export function getCurrentNumIdElements(root) {
+    const out = [];
+    for (const p of paragraphsUnder(root)) {
+        const el = getCurrentParagraphProperties(p).numPr?.numIdElement;
+        if (el) out.push(el);
+    }
+    return out;
+}
+
+/**
+ * Every `w:numId` element referenced anywhere under `root`, INCLUDING `pPrChange` snapshots. Explicitly
+ * historical-inclusive: used when a numbering part must define every id the content can ever reference.
+ */
+export function getAllReferencedNumIdElements(root) {
+    if (!root || typeof root.getElementsByTagNameNS !== 'function') return [];
+    return Array.from(root.getElementsByTagNameNS(NS_W, 'numId'));
+}

package/core/paragraph-text.js

@@ -1,209 +1,211 @@
-import { NS_W } from './types.js';
-
-function localName(node) {
-    return String(node?.localName || node?.nodeName || '').replace(/^.*:/, '');
-}
-
-/** Returns whether a node contributes to the selected revision view. */
-export function isNodeVisibleInRevisionView(node, boundary = null, revisionView = 'accepted') {
-    const view = revisionView === 'current' ? 'accepted' : revisionView;
-    let cursor = node;
-    while (cursor && cursor !== boundary) {
-        const name = localName(cursor);
-        if (view === 'accepted' && (name === 'del' || name === 'moveFrom')) return false;
-        if (view === 'rejected' && (name === 'ins' || name === 'moveTo')) return false;
-        cursor = cursor.parentNode;
-    }
-    return true;
-}
-
-/** Reads exact visible text from a run, including tabs, breaks and non-breaking hyphens. */
-export function readCanonicalRunText(run, options = {}) {
-    const revisionView = options.revisionView === 'current' ? 'accepted' : (options.revisionView || 'accepted');
-    const boundary = options.boundary || null;
-    if (!isNodeVisibleInRevisionView(run, boundary, revisionView)) return '';
-    let text = '';
-    const visit = node => {
-        for (const child of Array.from(node?.childNodes || [])) {
-            if (child?.nodeType !== 1 || (child.namespaceURI && child.namespaceURI !== NS_W)) continue;
-            if (!isNodeVisibleInRevisionView(child, boundary, revisionView)) continue;
-            const name = localName(child);
-            if (name === 't' || (name === 'delText' && revisionView === 'rejected')) text += child.textContent || '';
-            else if (name === 'tab') text += '\t';
-            else if (name === 'br' || name === 'cr') text += '\n';
-            else if (name === 'noBreakHyphen') text += '\u2011';
-            else if (name === 'softHyphen') text += '\u00ad';
-            else visit(child);
-        }
-    };
-    visit(run);
-    return text;
-}
-
-const attr = (node, name) => node?.getAttribute?.(`w:${name}`) || node?.getAttribute?.(name) || '';
-
-/**
- * Extracts revision-view text segments from a paragraph or container node.
- *
- * Emits structural text pieces tracking revision ancestry (ins, del, moveFrom, moveTo),
- * computes independent accepted and rejected UTF-16 cursor offsets, and merges
- * adjacent pieces with compatible carrier containers and revision metadata.
- *
- * @param {Element | null | undefined} paragraph - Paragraph or container element
- * @param {Object} [options={}] - Extraction options
- * @param {boolean} [options.mergeRuns=true] - Merge adjacent runs sharing compatible container and revision metadata
- * @returns {Array<{ text: string, kind: 'baseline' | 'insertion' | 'deletion' | 'move_from' | 'move_to', author?: string, revisionId?: string, acceptedStart: number | null, rejectedStart: number | null }>}
- */
-export function extractParagraphRevisionSegments(paragraph, options = {}) {
-    if (!paragraph) return [];
-
-    const rawPieces = [];
-
-    function walk(node, currentRevision, currentCarrier) {
-        for (const child of Array.from(node?.childNodes || [])) {
-            if (child?.nodeType !== 1) continue;
-            if (child.namespaceURI && child.namespaceURI !== NS_W) continue;
-
-            const name = localName(child);
-            if (name === 'pPr' || name === 'rPr') continue;
-
-            let nextRevision = currentRevision;
-            if (name === 'ins') {
-                nextRevision = {
-                    kind: 'insertion',
-                    author: attr(child, 'author') || undefined,
-                    revisionId: attr(child, 'id') || undefined
-                };
-            } else if (name === 'del') {
-                nextRevision = {
-                    kind: 'deletion',
-                    author: attr(child, 'author') || undefined,
-                    revisionId: attr(child, 'id') || undefined
-                };
-            } else if (name === 'moveFrom') {
-                nextRevision = {
-                    kind: 'move_from',
-                    author: attr(child, 'author') || undefined,
-                    revisionId: attr(child, 'id') || undefined
-                };
-            } else if (name === 'moveTo') {
-                nextRevision = {
-                    kind: 'move_to',
-                    author: attr(child, 'author') || undefined,
-                    revisionId: attr(child, 'id') || undefined
-                };
-            }
-
-            let nextCarrier = currentCarrier;
-            if (name === 'r') {
-                nextCarrier = child;
-            }
-
-            let text = null;
-            let kind = nextRevision ? nextRevision.kind : 'baseline';
-            let author = nextRevision?.author;
-            let revisionId = nextRevision?.revisionId;
-
-            if (name === 't') {
-                text = child.textContent || '';
-            } else if (name === 'delText') {
-                text = child.textContent || '';
-                if (!nextRevision) {
-                    kind = 'deletion';
-                }
-            } else if (name === 'tab') {
-                text = '\t';
-            } else if (name === 'br' || name === 'cr') {
-                text = '\n';
-            } else if (name === 'noBreakHyphen') {
-                text = '\u2011';
-            } else if (name === 'softHyphen') {
-                text = '\u00ad';
-            }
-
-            if (text !== null) {
-                if (text.length > 0) {
-                    rawPieces.push({
-                        text,
-                        kind,
-                        author,
-                        revisionId,
-                        carrier: nextCarrier || child,
-                        carrierContainer: (nextCarrier || child)?.parentNode || null
-                    });
-                }
-            } else {
-                walk(child, nextRevision, nextCarrier);
-            }
-        }
-    }
-
-    const initialCarrier = localName(paragraph) === 'r' ? paragraph : null;
-    walk(paragraph, null, initialCarrier);
-
-    if (rawPieces.length === 0) return [];
-
-    const mergeRuns = options.mergeRuns !== false;
-    const merged = [];
-    let current = null;
-
-    for (const piece of rawPieces) {
-        if (!current) {
-            current = { ...piece };
-            continue;
-        }
-
-        const sameKind = current.kind === piece.kind;
-        const sameAuthor = current.author === piece.author;
-        const sameRevisionId = current.revisionId === piece.revisionId;
-        const sameCarrier = current.carrier === piece.carrier;
-        const compatibleContainer = mergeRuns && current.carrierContainer === piece.carrierContainer;
-
-        if (sameKind && sameAuthor && sameRevisionId && (sameCarrier || compatibleContainer)) {
-            current.text += piece.text;
-        } else {
-            merged.push(current);
-            current = { ...piece };
-        }
-    }
-    if (current) merged.push(current);
-
-    let acceptedCursor = 0;
-    let rejectedCursor = 0;
-    const segments = [];
-
-    for (const item of merged) {
-        const isAccepted = item.kind !== 'deletion' && item.kind !== 'move_from';
-        const isRejected = item.kind !== 'insertion' && item.kind !== 'move_to';
-
-        const acceptedStart = isAccepted ? acceptedCursor : null;
-        const rejectedStart = isRejected ? rejectedCursor : null;
-
-        if (isAccepted) acceptedCursor += item.text.length;
-        if (isRejected) rejectedCursor += item.text.length;
-
-        const segment = {
-            text: item.text,
-            kind: item.kind,
-            acceptedStart,
-            rejectedStart
-        };
-        if (item.author !== undefined) segment.author = item.author;
-        if (item.revisionId !== undefined) segment.revisionId = item.revisionId;
-
-        segments.push(segment);
-    }
-
-    return segments;
-}
-
-/** Canonical exact paragraph text used by inspection, targeting and ingestion. */
-export function extractCanonicalParagraphText(paragraph, options = {}) {
-    if (!paragraph) return '';
-    const view = options.revisionView === 'current' ? 'accepted' : (options.revisionView || 'accepted');
-    const segments = extractParagraphRevisionSegments(paragraph, options);
-    if (view === 'rejected') {
-        return segments.filter(s => s.rejectedStart !== null).map(s => s.text).join('');
-    }
-    return segments.filter(s => s.acceptedStart !== null).map(s => s.text).join('');
-}
+import { NS_W } from './types.js';
+
+function localName(node) {
+    const local = node?.localName;
+    if (local) return local.indexOf(':') < 0 ? local : local.replace(/^.*:/, '');
+    return String(node?.nodeName || '').replace(/^.*:/, '');
+}
+
+/** Returns whether a node contributes to the selected revision view. */
+export function isNodeVisibleInRevisionView(node, boundary = null, revisionView = 'accepted') {
+    const view = revisionView === 'current' ? 'accepted' : revisionView;
+    let cursor = node;
+    while (cursor && cursor !== boundary) {
+        const name = localName(cursor);
+        if (view === 'accepted' && (name === 'del' || name === 'moveFrom')) return false;
+        if (view === 'rejected' && (name === 'ins' || name === 'moveTo')) return false;
+        cursor = cursor.parentNode;
+    }
+    return true;
+}
+
+/** Reads exact visible text from a run, including tabs, breaks and non-breaking hyphens. */
+export function readCanonicalRunText(run, options = {}) {
+    const revisionView = options.revisionView === 'current' ? 'accepted' : (options.revisionView || 'accepted');
+    const boundary = options.boundary || null;
+    if (!isNodeVisibleInRevisionView(run, boundary, revisionView)) return '';
+    let text = '';
+    const visit = node => {
+        for (let child = node?.firstChild; child; child = child.nextSibling) {
+            if (child?.nodeType !== 1 || (child.namespaceURI && child.namespaceURI !== NS_W)) continue;
+            if (!isNodeVisibleInRevisionView(child, boundary, revisionView)) continue;
+            const name = localName(child);
+            if (name === 't' || (name === 'delText' && revisionView === 'rejected')) text += child.textContent || '';
+            else if (name === 'tab') text += '\t';
+            else if (name === 'br' || name === 'cr') text += '\n';
+            else if (name === 'noBreakHyphen') text += '\u2011';
+            else if (name === 'softHyphen') text += '\u00ad';
+            else visit(child);
+        }
+    };
+    visit(run);
+    return text;
+}
+
+const attr = (node, name) => node?.getAttribute?.(`w:${name}`) || node?.getAttribute?.(name) || '';
+
+/**
+ * Extracts revision-view text segments from a paragraph or container node.
+ *
+ * Emits structural text pieces tracking revision ancestry (ins, del, moveFrom, moveTo),
+ * computes independent accepted and rejected UTF-16 cursor offsets, and merges
+ * adjacent pieces with compatible carrier containers and revision metadata.
+ *
+ * @param {Element | null | undefined} paragraph - Paragraph or container element
+ * @param {Object} [options={}] - Extraction options
+ * @param {boolean} [options.mergeRuns=true] - Merge adjacent runs sharing compatible container and revision metadata
+ * @returns {Array<{ text: string, kind: 'baseline' | 'insertion' | 'deletion' | 'move_from' | 'move_to', author?: string, revisionId?: string, acceptedStart: number | null, rejectedStart: number | null }>}
+ */
+export function extractParagraphRevisionSegments(paragraph, options = {}) {
+    if (!paragraph) return [];
+
+    const rawPieces = [];
+
+    function walk(node, currentRevision, currentCarrier) {
+        for (const child of Array.from(node?.childNodes || [])) {
+            if (child?.nodeType !== 1) continue;
+            if (child.namespaceURI && child.namespaceURI !== NS_W) continue;
+
+            const name = localName(child);
+            if (name === 'pPr' || name === 'rPr') continue;
+
+            let nextRevision = currentRevision;
+            if (name === 'ins') {
+                nextRevision = {
+                    kind: 'insertion',
+                    author: attr(child, 'author') || undefined,
+                    revisionId: attr(child, 'id') || undefined
+                };
+            } else if (name === 'del') {
+                nextRevision = {
+                    kind: 'deletion',
+                    author: attr(child, 'author') || undefined,
+                    revisionId: attr(child, 'id') || undefined
+                };
+            } else if (name === 'moveFrom') {
+                nextRevision = {
+                    kind: 'move_from',
+                    author: attr(child, 'author') || undefined,
+                    revisionId: attr(child, 'id') || undefined
+                };
+            } else if (name === 'moveTo') {
+                nextRevision = {
+                    kind: 'move_to',
+                    author: attr(child, 'author') || undefined,
+                    revisionId: attr(child, 'id') || undefined
+                };
+            }
+
+            let nextCarrier = currentCarrier;
+            if (name === 'r') {
+                nextCarrier = child;
+            }
+
+            let text = null;
+            let kind = nextRevision ? nextRevision.kind : 'baseline';
+            let author = nextRevision?.author;
+            let revisionId = nextRevision?.revisionId;
+
+            if (name === 't') {
+                text = child.textContent || '';
+            } else if (name === 'delText') {
+                text = child.textContent || '';
+                if (!nextRevision) {
+                    kind = 'deletion';
+                }
+            } else if (name === 'tab') {
+                text = '\t';
+            } else if (name === 'br' || name === 'cr') {
+                text = '\n';
+            } else if (name === 'noBreakHyphen') {
+                text = '\u2011';
+            } else if (name === 'softHyphen') {
+                text = '\u00ad';
+            }
+
+            if (text !== null) {
+                if (text.length > 0) {
+                    rawPieces.push({
+                        text,
+                        kind,
+                        author,
+                        revisionId,
+                        carrier: nextCarrier || child,
+                        carrierContainer: (nextCarrier || child)?.parentNode || null
+                    });
+                }
+            } else {
+                walk(child, nextRevision, nextCarrier);
+            }
+        }
+    }
+
+    const initialCarrier = localName(paragraph) === 'r' ? paragraph : null;
+    walk(paragraph, null, initialCarrier);
+
+    if (rawPieces.length === 0) return [];
+
+    const mergeRuns = options.mergeRuns !== false;
+    const merged = [];
+    let current = null;
+
+    for (const piece of rawPieces) {
+        if (!current) {
+            current = { ...piece };
+            continue;
+        }
+
+        const sameKind = current.kind === piece.kind;
+        const sameAuthor = current.author === piece.author;
+        const sameRevisionId = current.revisionId === piece.revisionId;
+        const sameCarrier = current.carrier === piece.carrier;
+        const compatibleContainer = mergeRuns && current.carrierContainer === piece.carrierContainer;
+
+        if (sameKind && sameAuthor && sameRevisionId && (sameCarrier || compatibleContainer)) {
+            current.text += piece.text;
+        } else {
+            merged.push(current);
+            current = { ...piece };
+        }
+    }
+    if (current) merged.push(current);
+
+    let acceptedCursor = 0;
+    let rejectedCursor = 0;
+    const segments = [];
+
+    for (const item of merged) {
+        const isAccepted = item.kind !== 'deletion' && item.kind !== 'move_from';
+        const isRejected = item.kind !== 'insertion' && item.kind !== 'move_to';
+
+        const acceptedStart = isAccepted ? acceptedCursor : null;
+        const rejectedStart = isRejected ? rejectedCursor : null;
+
+        if (isAccepted) acceptedCursor += item.text.length;
+        if (isRejected) rejectedCursor += item.text.length;
+
+        const segment = {
+            text: item.text,
+            kind: item.kind,
+            acceptedStart,
+            rejectedStart
+        };
+        if (item.author !== undefined) segment.author = item.author;
+        if (item.revisionId !== undefined) segment.revisionId = item.revisionId;
+
+        segments.push(segment);
+    }
+
+    return segments;
+}
+
+/** Canonical exact paragraph text used by inspection, targeting and ingestion. */
+export function extractCanonicalParagraphText(paragraph, options = {}) {
+    if (!paragraph) return '';
+    const view = options.revisionView === 'current' ? 'accepted' : (options.revisionView || 'accepted');
+    const segments = extractParagraphRevisionSegments(paragraph, options);
+    if (view === 'rejected') {
+        return segments.filter(s => s.rejectedStart !== null).map(s => s.text).join('');
+    }
+    return segments.filter(s => s.acceptedStart !== null).map(s => s.text).join('');
+}

package/core/types.js

@@ -329,9 +329,10 @@ export function createRevisionMetadata(author, allocatorOrNode = null, kind = nu
  *
  * @param {string} [author]
  * @param {RevisionIdAllocator|Document|Element|null} [allocatorOrNode=null]
+ * @param {{ deferReceipt?: boolean }} [options] - Defer receipt recording to `event.recordUsed(kind)`.
  * @returns {ReplacementRevisionEvent}
  */
-export function createReplacementRevisionEvent(author, allocatorOrNode = null) {
+export function createReplacementRevisionEvent(author, allocatorOrNode = null, { deferReceipt = false } = {}) {
     const resolvedAuthor = typeof author === 'string' && author.trim()
         ? author.trim()
         : getDefaultAuthor();
@@ -342,7 +343,7 @@ export function createReplacementRevisionEvent(author, allocatorOrNode = null) {
     const deletionId = allocator.next();
     const insertionId = allocator.next();
 
-    if (allocator._receiptCollector) {
+    if (allocator._receiptCollector && !deferReceipt) {
         allocator._receiptCollector.recordRevision(deletionId, 'del');
         allocator._receiptCollector.recordRevision(insertionId, 'ins');
     }
@@ -351,7 +352,12 @@ export function createReplacementRevisionEvent(author, allocatorOrNode = null) {
         deletionId,
         insertionId,
         author: resolvedAuthor,
-        date
+        date,
+        // With deferReceipt the caller records an id only once it is actually written to the document, so an id
+        // the diff never emits (a deletion of paragraph breaks only has no run to carry it) never reaches a receipt.
+        recordUsed: deferReceipt
+            ? kind => allocator._receiptCollector?.recordRevision(kind === 'del' ? deletionId : insertionId, kind)
+            : null
     };
 }