@ansonlai/docx-redline-js 0.8.2 → 0.8.4

package/pipeline/serialization.js

@@ -4,14 +4,14 @@
  * Converts patched run model back to OOXML with track changes.
  */
 
-import { RunKind, escapeXml, createRevisionMetadata } from '../core/types.js';
-import { getApplicableFormatHints } from './markdown-processor.js';
-import { serializeXml } from '../adapters/xml-adapter.js';
-import { warn } from '../adapters/logger.js';
-import { buildDocumentFragmentPackage } from '../services/package-builder.js';
-import { getDefaultAuthor } from '../adapters/config.js';
-
-const XMLNS_ATTR_REGEX = /\s+xmlns:[^=]+="[^"]*"/g;
+import { RunKind, escapeXml, createRevisionMetadata } from '../core/types.js';
+import { getApplicableFormatHints } from './markdown-processor.js';
+import { serializeXml } from '../adapters/xml-adapter.js';
+import { warn } from '../adapters/logger.js';
+import { buildDocumentFragmentPackage } from '../services/package-builder.js';
+import { getDefaultAuthor } from '../adapters/config.js';
+
+const XMLNS_ATTR_REGEX = /\s+xmlns:[^=]+="[^"]*"/g;
 
 /**
  * Serializes a patched run model to OOXML.
@@ -22,48 +22,48 @@ const XMLNS_ATTR_REGEX = /\s+xmlns:[^=]+="[^"]*"/g;
  * @param {import('../core/types.js').SerializationOptions} [options={}] - Serialization options
  * @returns {string} OOXML paragraph string (WITHOUT namespace - added by wrapper)
  */
-export function serializeToOoxml(patchedModel, pPr, formatHints = [], options = {}) {
-    const serializationOptions = normalizeSerializationOptions(options);
-    const { generateRedlines } = serializationOptions;
-    const paragraphs = [];
-    let currentPPrXml = '';
-    let currentPPrElement = null;
-    let currentRuns = [];
+export function serializeToOoxml(patchedModel, pPr, formatHints = [], options = {}) {
+    const serializationOptions = normalizeSerializationOptions(options);
+    const { generateRedlines } = serializationOptions;
+    const paragraphs = [];
+    let currentPPrXml = '';
+    let currentPPrElement = null;
+    let currentRuns = [];
 
     // Helper to flush accumulated runs into a paragraph
     function flushParagraph() {
         if (currentRuns.length > 0 || paragraphs.length === 0) {
             // Build paragraph properties - handle both string and DOM element
-            let pPrContent = '';
-            if (currentPPrXml) {
-                pPrContent = stripNamespaceDeclarations(currentPPrXml);
-            } else if (currentPPrElement) {
-                currentPPrXml = stripNamespaceDeclarations(serializeXml(currentPPrElement));
-                pPrContent = currentPPrXml;
-            } else if (pPr) {
-                // Fallback to legacy pPr if no PARAGRAPH_START was seen
-                if (typeof pPr === 'string') {
-                    pPrContent = pPr;
-                } else {
-                    pPrContent = serializeXml(pPr);
-                }
-                pPrContent = stripNamespaceDeclarations(pPrContent);
-            }
-            paragraphs.push(`<w:p>${pPrContent}${currentRuns.join('')}</w:p>`);
-            currentRuns = [];
-        }
+            let pPrContent = '';
+            if (currentPPrXml) {
+                pPrContent = stripNamespaceDeclarations(currentPPrXml);
+            } else if (currentPPrElement) {
+                currentPPrXml = stripNamespaceDeclarations(serializeXml(currentPPrElement));
+                pPrContent = currentPPrXml;
+            } else if (pPr) {
+                // Fallback to legacy pPr if no PARAGRAPH_START was seen
+                if (typeof pPr === 'string') {
+                    pPrContent = pPr;
+                } else {
+                    pPrContent = serializeXml(pPr);
+                }
+                pPrContent = stripNamespaceDeclarations(pPrContent);
+            }
+            paragraphs.push(`<w:p>${pPrContent}${currentRuns.join('')}</w:p>`);
+            currentRuns = [];
+        }
     }
 
     for (const item of patchedModel) {
         switch (item.kind) {
             case RunKind.PARAGRAPH_START:
                 // Flush previous paragraph before starting a new one
-                if (currentRuns.length > 0 || paragraphs.length > 0) {
-                    flushParagraph();
-                }
-                currentPPrXml = item.pPrXml || '';
-                currentPPrElement = item.pPrElement || null;
-                break;
+                if (currentRuns.length > 0 || paragraphs.length > 0) {
+                    flushParagraph();
+                }
+                currentPPrXml = item.pPrXml || '';
+                currentPPrElement = item.pPrElement || null;
+                break;
 
             case RunKind.TEXT:
                 currentRuns.push(buildRunXmlWithHints(item, formatHints, serializationOptions));
@@ -87,11 +87,11 @@ export function serializeToOoxml(patchedModel, pPr, formatHints = [], options =
 
             case RunKind.BOOKMARK:
             case RunKind.HYPERLINK:
-                // Pass through original XML - but strip any namespace declarations
-                if (item.nodeXml) {
-                    currentRuns.push(stripNamespaceDeclarations(item.nodeXml));
-                }
-                break;
+                // Pass through original XML - but strip any namespace declarations
+                if (item.nodeXml) {
+                    currentRuns.push(stripNamespaceDeclarations(item.nodeXml));
+                }
+                break;
 
             case RunKind.CONTAINER_START:
                 if (item.containerKind === 'sdt') {
@@ -134,29 +134,29 @@ export function serializeToOoxml(patchedModel, pPr, formatHints = [], options =
  * @param {import('../core/types.js').SerializationOptions|string|undefined|null} options - Raw options
  * @returns {import('../core/types.js').SerializationOptions}
  */
-function normalizeSerializationOptions(options) {
-    // Backward compatibility: accept legacy `font` string signature.
-    if (typeof options === 'string') {
-        return {
-            author: getDefaultAuthor(),
-            generateRedlines: true,
-            font: options,
-            revisionIdAllocator: null
-        };
-    }
-
-    const normalized = options && typeof options === 'object' ? options : {};
-    const resolvedAuthor = typeof normalized.author === 'string' && normalized.author.trim()
-        ? normalized.author.trim()
-        : getDefaultAuthor();
-
-    return {
-        author: resolvedAuthor,
-        generateRedlines: normalized.generateRedlines ?? true,
-        font: normalized.font ?? null,
-        revisionIdAllocator: normalized.revisionIdAllocator ?? null
-    };
-}
+function normalizeSerializationOptions(options) {
+    // Backward compatibility: accept legacy `font` string signature.
+    if (typeof options === 'string') {
+        return {
+            author: getDefaultAuthor(),
+            generateRedlines: true,
+            font: options,
+            revisionIdAllocator: null
+        };
+    }
+
+    const normalized = options && typeof options === 'object' ? options : {};
+    const resolvedAuthor = typeof normalized.author === 'string' && normalized.author.trim()
+        ? normalized.author.trim()
+        : getDefaultAuthor();
+
+    return {
+        author: resolvedAuthor,
+        generateRedlines: normalized.generateRedlines ?? true,
+        font: normalized.font ?? null,
+        revisionIdAllocator: normalized.revisionIdAllocator ?? null
+    };
+}
 
 /**
  * Builds a run XML element, applying format hints if applicable.
@@ -166,10 +166,10 @@ function normalizeSerializationOptions(options) {
  * @param {import('../core/types.js').SerializationOptions} options - Serialization options
  * @returns {string}
  */
-function buildRunXmlWithHints(item, formatHints, options = {}) {
-    const applicableHints = getApplicableFormatHints(formatHints, item.startOffset, item.endOffset);
-    const font = options?.font ?? null;
-    let cleanRPr = item.rPrXml ? stripNamespaceDeclarations(item.rPrXml) : '';
+function buildRunXmlWithHints(item, formatHints, options = {}) {
+    const applicableHints = getApplicableFormatHints(formatHints, item.startOffset, item.endOffset);
+    const font = options?.font ?? null;
+    let cleanRPr = item.rPrXml ? stripNamespaceDeclarations(item.rPrXml) : '';
 
     if (font) {
         cleanRPr = applyFont(cleanRPr, font);
@@ -219,7 +219,24 @@ function buildRunXmlWithHints(item, formatHints, options = {}) {
 function buildSimpleRun(text, rPrXml) {
     if (!text) return '';
     const rPr = rPrXml || '';
-    return `<w:r>${rPr}<w:t xml:space="preserve">${escapeXml(text)}</w:t></w:r>`;
+    return `<w:r>${rPr}${buildRunContent(text, 'w:t')}</w:r>`;
+}
+
+/**
+ * Builds run content, restoring in-run line breaks and tabs (ingested from
+ * w:br/w:cr/w:tab as "\n"/"\t") as elements; raw control characters inside
+ * w:t or w:delText render as spaces in Word.
+ *
+ * @param {string} text - Run text
+ * @param {'w:t'|'w:delText'} textTag - Text element name
+ * @returns {string}
+ */
+function buildRunContent(text, textTag) {
+    return String(text).split(/(\r\n|[\n\r\v\t])/).map(part => {
+        if (part === '\t') return '<w:tab/>';
+        if (part === '\n' || part === '\r' || part === '\r\n' || part === '\v') return '<w:br/>';
+        return part ? `<${textTag} xml:space="preserve">${escapeXml(part)}</${textTag}>` : '';
+    }).join('');
 }
 
 /**
@@ -229,21 +246,21 @@ function buildSimpleRun(text, rPrXml) {
  * @param {import('../core/types.js').SerializationOptions} options - Serialization options
  * @returns {string}
  */
-function buildDeletionXml(item, options = {}) {
-    const metadata = createRevisionMetadata(
-        options.author ?? getDefaultAuthor(),
-        options.revisionIdAllocator,
-        'del'
-    );
-    const font = options.font ?? null;
-    let rPr = item.rPrXml ? stripNamespaceDeclarations(item.rPrXml) : '';
+function buildDeletionXml(item, options = {}) {
+    const metadata = createRevisionMetadata(
+        options.author ?? getDefaultAuthor(),
+        options.revisionIdAllocator,
+        'del'
+    );
+    const font = options.font ?? null;
+    let rPr = item.rPrXml ? stripNamespaceDeclarations(item.rPrXml) : '';
 
     if (font) {
         rPr = applyFont(rPr, font);
     }
 
     return `<w:del w:id="${metadata.id}" w:author="${escapeXml(metadata.author)}" w:date="${metadata.date}">` +
-        `<w:r>${rPr}<w:delText xml:space="preserve">${escapeXml(item.text)}</w:delText></w:r>` +
+        `<w:r>${rPr}${buildRunContent(item.text, 'w:delText')}</w:r>` +
         `</w:del>`;
 }
 
@@ -255,18 +272,18 @@ function buildDeletionXml(item, options = {}) {
  * @param {import('../core/types.js').SerializationOptions} options - Serialization options
  * @returns {string}
  */
-function buildInsertionXml(item, formatHints, options = {}) {
-    const metadata = createRevisionMetadata(
-        options.author ?? getDefaultAuthor(),
-        options.revisionIdAllocator,
-        'ins'
-    );
+function buildInsertionXml(item, formatHints, options = {}) {
+    const metadata = createRevisionMetadata(
+        options.author ?? getDefaultAuthor(),
+        options.revisionIdAllocator,
+        'ins'
+    );
     const font = options.font ?? null;
 
     // Build the inner run content with format hints
     const applicableHints = getApplicableFormatHints(formatHints, item.startOffset, item.endOffset);
     let innerContent = '';
-    let cleanRPr = item.rPrXml ? stripNamespaceDeclarations(item.rPrXml) : '';
+    let cleanRPr = item.rPrXml ? stripNamespaceDeclarations(item.rPrXml) : '';
 
     if (font) {
         cleanRPr = applyFont(cleanRPr, font);
@@ -383,7 +400,7 @@ export function wrapInDocumentFragment(paragraphXml, options = {}) {
  * @param {import('../core/types.js').DocumentFragmentOptions|boolean|undefined|null} options - Raw options
  * @returns {import('../core/types.js').DocumentFragmentOptions}
  */
-function normalizeFragmentOptions(options) {
+function normalizeFragmentOptions(options) {
     if (typeof options === 'boolean') {
         return { includeNumbering: options };
     }
@@ -397,9 +414,9 @@ function normalizeFragmentOptions(options) {
         numberingXml: options.numberingXml ?? null,
         appendTrailingParagraph: options.appendTrailingParagraph ?? true
     };
-}
-
-function stripNamespaceDeclarations(xml) {
-    return xml ? xml.replace(XMLNS_ATTR_REGEX, '') : '';
-}
+}
+
+function stripNamespaceDeclarations(xml) {
+    return xml ? xml.replace(XMLNS_ATTR_REGEX, '') : '';
+}
 

package/services/batch-operation-orchestrator.js

@@ -24,6 +24,7 @@ import {
     reconcileReceiptsAgainstOutput
 } from './receipt-collector.js';
 import { compileOperationBatch } from './operation-batch-compiler.js';
+import { createDynamicNumberingIdState } from './numbering-helpers.js';
 import { createRetryPlan } from './error-recovery.js';
 
 const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
@@ -368,6 +369,11 @@ export async function applyOperationsToDocumentXml(documentXml, operations, auth
 
     const atomic = options.atomic === true;
     const continueOnError = options.continueOnError !== false;
+    // Generated list definitions must not collide with the supplied source numbering part.
+    if (runtimeContext && typeof runtimeContext === 'object' && !runtimeContext.numberingIdState
+        && typeof runtimeContext.numberingXml === 'string' && runtimeContext.numberingXml.trim()) {
+        runtimeContext.numberingIdState = createDynamicNumberingIdState(runtimeContext.numberingXml);
+    }
     const context = cloneBatchRuntimeContext(runtimeContext);
     if (!(context.targetRefSnapshot instanceof Map)) {
         context.targetRefSnapshot = session.initialTargetReferenceSnapshot;

package/services/document-inspection.js

@@ -8,6 +8,9 @@ import { extractDocumentPartsEntries, computeRevisionTokenSync } from './revisio
 const attr = (node, name) => node?.getAttribute?.(`w:${name}`) || node?.getAttribute?.(name) || '';
 const descendants = (node, name) => Array.from(node?.getElementsByTagNameNS?.(NS_W, name) || []);
 const first = (node, name) => descendants(node, name)[0] || null;
+const directChild = (node, name) => Array.from(node?.childNodes || []).find(child => child?.nodeType === 1 && child.localName === name && (!child.namespaceURI || child.namespaceURI === NS_W)) || null;
+/** Current paragraph properties: the paragraph's direct w:pPr only (never the historical w:pPrChange/w:pPr). */
+const currentPPr = paragraph => directChild(paragraph, 'pPr');
 function hasAncestor(node, localName) { let cursor = node?.parentNode; while (cursor) { if (cursor.localName === localName && (!cursor.namespaceURI || cursor.namespaceURI === NS_W)) return true; cursor = cursor.parentNode; } return false; }
 
 function parseXml(xml, partName, required = false) {
@@ -18,11 +21,11 @@ function parseXml(xml, partName, required = false) {
 }
 
 function paragraphListProperties(paragraph) {
-    const numPr = first(first(paragraph, 'pPr'), 'numPr');
+    const numPr = directChild(currentPPr(paragraph), 'numPr');
     if (!numPr) return null;
-    const numId = attr(first(numPr, 'numId'), 'val');
+    const numId = attr(directChild(numPr, 'numId'), 'val');
     if (!numId || numId === '0') return null;
-    return { numId, level: Number.parseInt(attr(first(numPr, 'ilvl'), 'val') || '0', 10) || 0 };
+    return { numId, level: Number.parseInt(attr(directChild(numPr, 'ilvl'), 'val') || '0', 10) || 0 };
 }
 
 function parseNumbering(numberingDoc) {
@@ -100,11 +103,11 @@ function createNumberingResolver(numberingDoc) {
 }
 
 function headingLevel(paragraph) {
-    const pPr = first(paragraph, 'pPr');
-    const style = attr(first(pPr, 'pStyle'), 'val');
+    const pPr = currentPPr(paragraph);
+    const style = attr(directChild(pPr, 'pStyle'), 'val');
     const match = style.match(/^heading\s*([1-9])$/i);
     if (match) return Math.min(Number(match[1]), 6);
-    const outline = Number.parseInt(attr(first(pPr, 'outlineLvl'), 'val'), 10);
+    const outline = Number.parseInt(attr(directChild(pPr, 'outlineLvl'), 'val'), 10);
     return Number.isInteger(outline) ? Math.min(outline + 1, 6) : null;
 }
 
@@ -283,7 +286,7 @@ export function inspectDocumentParts(parts, options = {}) {
         const ids = [...new Set([...descendants(paragraph, 'commentRangeStart'), ...descendants(paragraph, 'commentReference')].map(node => attr(node, 'id')).filter(Boolean))];
         const authors = revisionAuthors(paragraph);
         const list = resolveNumbering(paragraphListProperties(paragraph));
-        const styleId = attr(first(first(paragraph, 'pPr'), 'pStyle'), 'val') || null;
+        const styleId = attr(directChild(currentPPr(paragraph), 'pStyle'), 'val') || null;
         const structure = structuralContext(paragraph, text);
         const index = zeroIndex + 1;
         const provision = list?.label && list.format !== 'bullet' ? list.label : null;

package/services/document-operation-applier.js

@@ -216,9 +216,11 @@ export async function applyOperationToDocumentXml(documentXml, op, author, runti
         ...(operation.existingRevisions ? { existingRevisions: operation.existingRevisions } : {}),
         structuredContent: typeof operation.structuredContent === 'boolean' ? operation.structuredContent : (options.structuredContent !== false),
         explicitStructuredContent: operation.structuredContent === true,
+        ...(operation._localizedReplacementCompilation && operation.structuredContent !== true ? { literalTextEdit: true } : {}),
         pairReplacements: typeof operation.pairReplacements === 'boolean' ? operation.pairReplacements : (options.pairReplacements !== false),
         ...(operation.insertionAffinity ? { insertionAffinity: operation.insertionAffinity } : {}),
         ...(operation.formattingRevisionPolicy ? { formattingRevisionPolicy: operation.formattingRevisionPolicy } : {}),
+        ...(operation.operationKind === 'format' && Number.isInteger(operation.textOccurrence) ? { textOccurrence: operation.textOccurrence } : {}),
         targetDescriptor: operation.targetDescriptor,
         targetEndDescriptor: operation.targetEndDescriptor,
         _compiledSourceId: operation._compiledSourceId || null,