@ansonlai/docx-redline-js 0.4.0 → 0.5.1

package/engine/surgical-mode.js

@@ -15,6 +15,78 @@ import {
     reconcileFormattingForTextSpan
 } from './surgical-diff-application.js';
 import { withOoxmlSourceType } from '../core/word-xml.js';
+import { createReplacementRevisionEvent } from '../core/types.js';
+
+function checkSafeAdjacencyForPairing(spanIndex, startPos, endPos, allowInsertionCarrier = false) {
+    const spans = [];
+    forEachOverlappingSpan(spanIndex, startPos, endPos, span => spans.push(span));
+    if (spans.length === 0) return { safe: false };
+
+    const firstRun = spans[0].runElement;
+    const parent = firstRun?.parentNode;
+    if (!parent) return { safe: false };
+
+    // All overlapping runs must share the exact same parent element
+    const sameParent = spans.every(s => s.runElement?.parentNode === parent);
+    if (!sameParent) return { safe: false, structuralBoundary: true };
+
+    // Parent container itself cannot be an existing revision or unsupported container
+    const parentLocal = (parent.localName || parent.nodeName.replace(/^.*:/, ''));
+    if (
+        ['hyperlink', 'sdt', 'del', 'moveFrom', 'moveTo'].includes(parentLocal)
+        || (parentLocal === 'ins' && !allowInsertionCarrier)
+    ) {
+        return { safe: false, structuralBoundary: true };
+    }
+
+    const structuralTags = new Set([
+        'hyperlink', 'fldSimple', 'sdt',
+        'commentRangeStart', 'commentRangeEnd', 'commentReference',
+        'bookmarkStart', 'bookmarkEnd',
+        'moveFrom', 'moveTo', 'ins', 'del'
+    ]);
+
+    for (const span of spans) {
+        const run = span.runElement;
+        for (const child of Array.from(run.childNodes || [])) {
+            if (child.nodeType === 1) {
+                const tag = child.localName || child.nodeName.replace(/^.*:/, '');
+                if (structuralTags.has(tag) || tag === 'fldChar') {
+                    return { safe: false, structuralBoundary: true };
+                }
+            }
+        }
+    }
+
+    const lastRun = spans[spans.length - 1].runElement;
+    let curr = firstRun;
+    while (curr && curr !== lastRun) {
+        if (curr !== firstRun) {
+            const tag = curr.localName || curr.nodeName.replace(/^.*:/, '');
+            if (structuralTags.has(tag)) {
+                return { safe: false, structuralBoundary: true };
+            }
+        }
+        curr = curr.nextSibling;
+    }
+
+    function hasStructuralDescendant(node) {
+        if (!node || node.nodeType !== 1) return false;
+        const tag = node.localName || node.nodeName.replace(/^.*:/, '');
+        if (structuralTags.has(tag) || tag === 'fldChar') return true;
+        for (const child of Array.from(node.childNodes || [])) {
+            if (child.nodeType === 1 && hasStructuralDescendant(child)) return true;
+        }
+        return false;
+    }
+
+    // Inspect immediate adjacent siblings of the deleted range
+    if (hasStructuralDescendant(firstRun.previousSibling) || hasStructuralDescendant(lastRun.nextSibling)) {
+        return { safe: false, structuralBoundary: true };
+    }
+
+    return { safe: true };
+}
 
 /**
  * Applies surgical mode reconciliation.
@@ -28,9 +100,10 @@ import { withOoxmlSourceType } from '../core/word-xml.js';
  * @param {boolean} [generateRedlines=true] - Track change toggle
  * @param {Element|null} [targetParagraph=null] - Optional scope paragraph
  * @param {{ diffTimeoutSeconds?: number }} [diffOptions={}] - Diff configuration
- * @returns {{ oxml: string, hasChanges: boolean, sourceType?: 'package'|'document'|'fragment' }}
+ * @param {Object} [options={}] - Additional reconciliation options (e.g. pairReplacements)
+ * @returns {{ oxml: string, hasChanges: boolean, warnings?: string[], sourceType?: 'package'|'document'|'fragment' }}
  */
-export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer, author, formatHints, generateRedlines = true, targetParagraph = null, diffOptions = {}) {
+export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer, author, formatHints, generateRedlines = true, targetParagraph = null, diffOptions = {}, options = {}) {
     void originalText;
 
     const allParagraphs = targetParagraph
@@ -40,12 +113,15 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
     const { fullText, textSpans } = buildSurgicalTextSpans(allParagraphs);
     const diffs = computeWordDiffs(fullText, modifiedText, diffOptions);
     const spanIndex = buildSpanIndex(textSpans);
+    const pairReplacements = options.pairReplacements === true;
+    const warnings = [];
 
     let originalPos = 0;
     let newPos = 0;
     let hasChanges = false;
 
-    for (const [op, text] of diffs) {
+    for (let i = 0; i < diffs.length; i++) {
+        const [op, text] = diffs[i];
         if (op === 0) {
             const len = text.length;
             const startPos = originalPos;
@@ -67,14 +143,70 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
             originalPos += len;
             newPos += len;
         } else if (op === -1) {
-            if (processDelete(xmlDoc, spanIndex, originalPos, originalPos + text.length, author, generateRedlines)) {
+            const hasNextInsert = (i + 1 < diffs.length) && (diffs[i + 1][0] === 1);
+            let paired = false;
+            let delMetadata = null;
+            let insMetadata = null;
+
+            if (pairReplacements && generateRedlines && hasNextInsert) {
+                const nextText = diffs[i + 1][1];
+                const textWithoutNewlines = nextText.replace(/\n/g, ' ');
+                if (textWithoutNewlines.trim().length > 0) {
+                    const checkResult = checkSafeAdjacencyForPairing(
+                        spanIndex,
+                        originalPos,
+                        originalPos + text.length,
+                        options?.existingRevisions === 'slice-cross-author'
+                    );
+                    if (checkResult.safe) {
+                        const event = createReplacementRevisionEvent(author, xmlDoc);
+                        delMetadata = { id: event.deletionId, author: event.author, date: event.date };
+                        insMetadata = { id: event.insertionId, author: event.author, date: event.date };
+                        paired = true;
+                    } else if (checkResult.structuralBoundary) {
+                        warnings.push('PAIRING_SKIPPED_STRUCTURAL_BOUNDARY');
+                    }
+                }
+            }
+
+            if (processDelete(xmlDoc, spanIndex, originalPos, originalPos + text.length, author, generateRedlines, delMetadata)) {
                 hasChanges = true;
             }
             originalPos += text.length;
+
+            if (paired) {
+                i++;
+                const [, nextText] = diffs[i];
+                const textWithoutNewlines = nextText.replace(/\n/g, ' ');
+                if (textWithoutNewlines.trim().length > 0) {
+                    const insertResult = processInsert(xmlDoc, spanIndex, originalPos, textWithoutNewlines, author, formatHints, newPos, generateRedlines, allParagraphs[0] || null, insMetadata, options?.insertionAffinity || null, options?.existingRevisions || 'merge-same-author');
+                    if (insertResult && typeof insertResult === 'object' && insertResult.error) {
+                        return withOoxmlSourceType({
+                            oxml: serializer.serializeToString(xmlDoc),
+                            hasChanges: false,
+                            status: 'error',
+                            error: insertResult.error
+                        });
+                    }
+                    if (insertResult === true) {
+                        hasChanges = true;
+                    }
+                }
+                newPos += nextText.length;
+            }
         } else if (op === 1) {
             const textWithoutNewlines = text.replace(/\n/g, ' ');
             if (textWithoutNewlines.trim().length > 0) {
-                if (processInsert(xmlDoc, spanIndex, originalPos, textWithoutNewlines, author, formatHints, newPos, generateRedlines, allParagraphs[0] || null)) {
+                const insertResult = processInsert(xmlDoc, spanIndex, originalPos, textWithoutNewlines, author, formatHints, newPos, generateRedlines, allParagraphs[0] || null, null, options?.insertionAffinity || null, options?.existingRevisions || 'merge-same-author');
+                if (insertResult && typeof insertResult === 'object' && insertResult.error) {
+                    return withOoxmlSourceType({
+                        oxml: serializer.serializeToString(xmlDoc),
+                        hasChanges: false,
+                        status: 'error',
+                        error: insertResult.error
+                    });
+                }
+                if (insertResult === true) {
                     hasChanges = true;
                 }
             }
@@ -82,5 +214,9 @@ export function applySurgicalMode(xmlDoc, originalText, modifiedText, serializer
         }
     }
 
-    return withOoxmlSourceType({ oxml: serializer.serializeToString(xmlDoc), hasChanges });
+    return withOoxmlSourceType({
+        oxml: serializer.serializeToString(xmlDoc),
+        hasChanges,
+        ...(warnings.length > 0 ? { warnings: [...new Set(warnings)] } : {})
+    });
 }

package/engine/surgical-run-splitting.js

@@ -1,6 +1,15 @@
 import { createWordElement, isWordElement } from '../core/word-xml.js';
+import {
+    NS_W,
+    RevisionIdAllocator,
+    createRevisionIdAllocator,
+    getRevisionIdAllocatorForDocument
+} from '../core/types.js';
+import { refreshRunPropertyChangeIds } from '../core/revision-cloning.js';
 import { getRunChildText, isTextLikeRunChild } from './surgical-spans.js';
 
+const TRACK_CHANGE_CARRIERS = new Set(['ins']);
+
 export function getRunContentPieces(runElement) {
     const pieces = [];
     let offset = 0;
@@ -62,6 +71,100 @@ export function insertRunPiecesBefore(xmlDoc, parent, referenceNode, pieces, rPr
     return run;
 }
 
+/**
+ * Splits a run-level tracked-change carrier at an accepted-view character
+ * offset without mutating the source carrier. The original revision ID stays
+ * with the leading fragment; an interior trailing fragment receives a fresh,
+ * document-scoped ID while all other carrier metadata remains unchanged.
+ *
+ * @param {Document} xmlDoc
+ * @param {Element} carrierElement
+ * @param {number} splitOffset
+ * @param {RevisionIdAllocator|null} [allocator=null]
+ * @returns {{ leftCarrier: Element|null, rightCarrier: Element|null }}
+ */
+export function splitTrackChangeCarrier(xmlDoc, carrierElement, splitOffset, allocator = null) {
+    const carrierName = getLocalName(carrierElement);
+    if (!TRACK_CHANGE_CARRIERS.has(carrierName)) {
+        throw new TypeError('splitTrackChangeCarrier requires a w:ins carrier.');
+    }
+    if (!Number.isInteger(splitOffset) || splitOffset < 0) {
+        throw new RangeError('splitOffset must be a non-negative integer.');
+    }
+
+    const children = Array.from(carrierElement.childNodes || []);
+    const totalLength = children.reduce((length, child) => {
+        return length + (isWordElement(child, 'r') ? getRunTextLength(getRunContentPieces(child)) : 0);
+    }, 0);
+    if (splitOffset > totalLength) {
+        throw new RangeError(`splitOffset ${splitOffset} exceeds carrier text length ${totalLength}.`);
+    }
+
+    if (splitOffset === 0) {
+        return { leftCarrier: null, rightCarrier: carrierElement.cloneNode(true) };
+    }
+    if (splitOffset === totalLength) {
+        return { leftCarrier: carrierElement.cloneNode(true), rightCarrier: null };
+    }
+
+    const leftCarrier = carrierElement.cloneNode(false);
+    const rightCarrier = carrierElement.cloneNode(false);
+    let offset = 0;
+
+    for (const child of children) {
+        if (!isWordElement(child, 'r')) {
+            const destination = offset <= splitOffset ? leftCarrier : rightCarrier;
+            destination.appendChild(child.cloneNode(true));
+            continue;
+        }
+
+        const pieces = getRunContentPieces(child);
+        const runLength = getRunTextLength(pieces);
+        const runEnd = offset + runLength;
+
+        if (runEnd <= splitOffset) {
+            leftCarrier.appendChild(child.cloneNode(true));
+        } else if (offset >= splitOffset) {
+            rightCarrier.appendChild(child.cloneNode(true));
+        } else {
+            const localOffset = splitOffset - offset;
+            const rPr = Array.from(child.childNodes || []).find(node => isWordElement(node, 'rPr')) || null;
+            const leftPieces = sliceRunPieces(xmlDoc, pieces, 0, localOffset, false);
+            const rightPieces = sliceRunPieces(xmlDoc, pieces, localOffset, runLength, false);
+            leftCarrier.appendChild(createRunFromPieces(xmlDoc, leftPieces, rPr));
+            const rightRun = createRunFromPieces(xmlDoc, rightPieces, rPr);
+            refreshRunPropertyChangeIds(rightRun, resolveAllocator(xmlDoc, allocator));
+            rightCarrier.appendChild(rightRun);
+        }
+        offset = runEnd;
+    }
+
+    const resolvedAllocator = resolveAllocator(xmlDoc, allocator);
+    const nextId = resolvedAllocator.next();
+    setWordAttribute(rightCarrier, 'id', String(nextId));
+    resolvedAllocator._receiptCollector?.recordRevision(nextId, carrierName);
+
+    return { leftCarrier, rightCarrier };
+}
+
+function resolveAllocator(xmlDoc, allocator) {
+    return allocator instanceof RevisionIdAllocator
+        ? allocator
+        : (getRevisionIdAllocatorForDocument(xmlDoc) || createRevisionIdAllocator(xmlDoc));
+}
+
+function setWordAttribute(element, localName, value) {
+    if (typeof element.setAttributeNS === 'function') {
+        element.setAttributeNS(NS_W, `w:${localName}`, value);
+    } else {
+        element.setAttribute(`w:${localName}`, value);
+    }
+}
+
+function getLocalName(element) {
+    return String(element?.localName || element?.nodeName || '').replace(/^.*:/, '');
+}
+
 function cloneRunPiece(xmlDoc, sourceNode, text, asDeletedText) {
     if (asDeletedText) {
         const delText = createWordElement(xmlDoc, 'w:delText');

package/engine/surgical-spans.js

@@ -7,6 +7,7 @@ export function getRunChildText(child) {
     if (isWordElement(child, 'br') || isWordElement(child, 'cr')) return '\n';
     if (isWordElement(child, 'tab')) return '\t';
     if (isWordElement(child, 'noBreakHyphen')) return '\u2011';
+    if (isWordElement(child, 'softHyphen')) return '\u00ad';
     return '';
 }
 
@@ -15,7 +16,8 @@ export function isTextLikeRunChild(child) {
         || isWordElement(child, 'br')
         || isWordElement(child, 'cr')
         || isWordElement(child, 'tab')
-        || isWordElement(child, 'noBreakHyphen');
+        || isWordElement(child, 'noBreakHyphen')
+        || isWordElement(child, 'softHyphen');
 }
 
 export function buildSurgicalTextSpans(paragraphs) {
@@ -34,6 +36,27 @@ export function buildSurgicalTextSpans(paragraphs) {
                         fullText += processRunElement(hc, paragraph, container, fullText.length, textSpans).text;
                     }
                 }
+            } else if (isWordElement(child, 'ins')) {
+                for (let ic = child.firstChild; ic; ic = ic.nextSibling) {
+                    if (isWordElement(ic, 'r')) {
+                        fullText += processRunElement(ic, paragraph, container, fullText.length, textSpans).text;
+                    }
+                }
+            } else if (isWordElement(child, 'sdt')) {
+                const sdtContent = Array.from(child.childNodes || []).find(n => isWordElement(n, 'sdtContent'));
+                if (sdtContent) {
+                    for (let sc = sdtContent.firstChild; sc; sc = sc.nextSibling) {
+                        if (isWordElement(sc, 'r')) {
+                            fullText += processRunElement(sc, paragraph, container, fullText.length, textSpans).text;
+                        }
+                    }
+                }
+            } else if (isWordElement(child, 'smartTag')) {
+                for (let st = child.firstChild; st; st = st.nextSibling) {
+                    if (isWordElement(st, 'r')) {
+                        fullText += processRunElement(st, paragraph, container, fullText.length, textSpans).text;
+                    }
+                }
             }
         }
 
@@ -167,3 +190,31 @@ function lowerBound(values, target) {
 
     return left;
 }
+
+export function describeInsertionBoundary(spanIndex, pos, fallbackParagraph = null) {
+    if (!spanIndex || !spanIndex.spans || spanIndex.spans.length === 0) {
+        return {
+            leftSpan: null,
+            rightSpan: null,
+            containingSpan: null,
+            isInterior: false,
+            fallbackParagraph
+        };
+    }
+
+    const containingSpan = findContainingSpan(spanIndex, pos);
+    const isInterior = containingSpan !== null && pos > containingSpan.charStart && pos < containingSpan.charEnd;
+
+    // leftSpan ends at or before pos
+    const leftSpan = findFirstSpanEndingAt(spanIndex, pos) || (pos > 0 ? findLastSpanEndingBeforeOrAt(spanIndex, pos) : null);
+    // rightSpan starts at or after pos
+    const rightSpan = spanIndex.spans.find(s => s.charStart === pos) || (pos === 0 ? spanIndex.spans[0] : null);
+
+    return {
+        leftSpan,
+        rightSpan,
+        containingSpan,
+        isInterior,
+        fallbackParagraph
+    };
+}

package/engine/table-cell-context.js

@@ -11,6 +11,7 @@ import { buildParagraphOnlyPackage } from '../services/package-builder.js';
 import { getElementsByTagNSOrTag } from '../core/xml-query.js';
 import { NS_W } from '../core/types.js';
 import { isWordElement } from '../core/word-xml.js';
+import { extractCanonicalParagraphText } from '../core/paragraph-text.js';
 
 const W14_NS = 'http://schemas.microsoft.com/office/word/2010/wordml';
 
@@ -69,12 +70,8 @@ export function detectTableCellContext(xmlDoc, originalText, options = {}) {
     if (originalText && originalText.trim()) {
         const normalizedTarget = originalText.trim();
         if (!targetParagraph) {
-            for (const p of paragraphsInCells) {
-                const textNodes = getElementsByTagNSOrTag(p, NS_W, 't');
-                let paragraphText = '';
-                for (const t of textNodes) {
-                    paragraphText += t.textContent || '';
-                }
+            for (const p of paragraphsInCells) {
+                const paragraphText = extractCanonicalParagraphText(p);
 
                 if (paragraphText.trim() === normalizedTarget) {
                     targetParagraph = p;

package/engine/table-mode.js

@@ -165,7 +165,7 @@ export function applyTextToTableTransformation(xmlDoc, modifiedText, serializer,
                 });
 
                 const del = createWordElement(workingDoc, 'w:del');
-                const metadata = createRevisionMetadata(author, workingDoc);
+                const metadata = createRevisionMetadata(author, workingDoc, 'del');
                 del.setAttribute('w:id', String(metadata.id));
                 del.setAttribute('w:author', metadata.author);
                 del.setAttribute('w:date', metadata.date);