@ansonlai/docx-redline-js 0.1.0

package/engine/rpr-helpers.js

@@ -0,0 +1,194 @@
+/**
+ * Run property (w:rPr) helper utilities.
+ *
+ * This module owns low-level formatting element operations, including
+ * schema-order insertion, format extraction, and format add/remove transforms.
+ */
+
+/**
+ * Canonical OOXML run-property schema ordering.
+ * Shared by all rPr synchronizers.
+ */
+export const RPR_SCHEMA_ORDER = [
+    'w:rStyle', 'w:rFonts', 'w:b', 'w:bCs', 'w:i', 'w:iCs', 'w:caps', 'w:smallCaps',
+    'w:strike', 'w:dstrike', 'w:outline', 'w:shadow', 'w:emboss', 'w:imprint', 'w:noProof',
+    'w:snapToGrid', 'w:vanish', 'w:webHidden', 'w:color', 'w:spacing', 'w:w', 'w:kern',
+    'w:position', 'w:sz', 'w:szCs', 'w:highlight', 'w:u', 'w:effect', 'w:bdr', 'w:shd',
+    'w:fitText', 'w:vertAlign', 'w:rtl', 'w:cs', 'w:em', 'w:lang', 'w:eastAsianLayout',
+    'w:specVanish', 'w:oMath'
+];
+
+/**
+ * Inserts an rPr child node in schema order.
+ *
+ * @param {Element} rPr - Run properties element
+ * @param {Element} el - Child element to insert
+ */
+export function insertRPrChildInOrder(rPr, el) {
+    const myIndex = RPR_SCHEMA_ORDER.indexOf(el.nodeName);
+    const myPriority = myIndex === -1 ? 999 : myIndex;
+
+    let inserted = false;
+    for (const child of Array.from(rPr.childNodes)) {
+        if (child.nodeType !== 1) continue;
+        const childIndex = RPR_SCHEMA_ORDER.indexOf(child.nodeName);
+        const childPriority = childIndex === -1 ? 999 : childIndex;
+        if (childPriority > myPriority) {
+            rPr.insertBefore(el, child);
+            inserted = true;
+            break;
+        }
+    }
+    if (!inserted) rPr.appendChild(el);
+}
+
+/**
+ * Shared override routine used by add/remove format transforms.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Element} rPr - Run properties target
+ * @param {{bold?: boolean, italic?: boolean, underline?: boolean, strikethrough?: boolean}} formatFlags - Flags to apply
+ * @param {'remove'|'add'} mode - Override mode
+ */
+function _applyOverrides(xmlDoc, rPr, formatFlags, mode) {
+    if (!rPr || !formatFlags) return;
+
+    const applyBold = !!formatFlags.bold;
+    const applyItalic = !!formatFlags.italic;
+    const applyUnderline = !!formatFlags.underline;
+    const applyStrike = !!formatFlags.strikethrough;
+
+    const removalSet = new Set();
+    if (applyBold) {
+        removalSet.add('w:b');
+        removalSet.add('w:bCs');
+    }
+    if (applyItalic) {
+        removalSet.add('w:i');
+        removalSet.add('w:iCs');
+    }
+    if (applyUnderline) removalSet.add('w:u');
+    if (applyStrike) removalSet.add('w:strike');
+
+    if (removalSet.size > 0) {
+        const toRemove = [];
+        for (const child of Array.from(rPr.childNodes)) {
+            if (removalSet.has(child.nodeName)) {
+                toRemove.push(child);
+            }
+        }
+        for (const el of toRemove) {
+            rPr.removeChild(el);
+        }
+    }
+
+    if (applyBold) {
+        const b = xmlDoc.createElement('w:b');
+        b.setAttribute('w:val', mode === 'add' ? '1' : '0');
+        insertRPrChildInOrder(rPr, b);
+
+        const bCs = xmlDoc.createElement('w:bCs');
+        bCs.setAttribute('w:val', mode === 'add' ? '1' : '0');
+        insertRPrChildInOrder(rPr, bCs);
+    }
+    if (applyItalic) {
+        const i = xmlDoc.createElement('w:i');
+        i.setAttribute('w:val', mode === 'add' ? '1' : '0');
+        insertRPrChildInOrder(rPr, i);
+
+        const iCs = xmlDoc.createElement('w:iCs');
+        iCs.setAttribute('w:val', mode === 'add' ? '1' : '0');
+        insertRPrChildInOrder(rPr, iCs);
+    }
+    if (applyUnderline) {
+        const u = xmlDoc.createElement('w:u');
+        u.setAttribute('w:val', mode === 'add' ? 'single' : 'none');
+        insertRPrChildInOrder(rPr, u);
+    }
+    if (applyStrike) {
+        const strike = xmlDoc.createElement('w:strike');
+        strike.setAttribute('w:val', mode === 'add' ? '1' : '0');
+        insertRPrChildInOrder(rPr, strike);
+    }
+}
+
+/**
+ * Builds an rPr XML snippet that explicitly removes formatting while preserving other properties.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Element} originalRun - Source run
+ * @param {Object} formatToRemove - Format flags to remove
+ * @param {XMLSerializer} serializer - Serializer instance
+ * @returns {string}
+ */
+export function buildOverrideRPrXml(xmlDoc, originalRun, formatToRemove, serializer) {
+    const baseRPr = originalRun.getElementsByTagName('w:rPr')[0] || null;
+    const rPr = baseRPr ? baseRPr.cloneNode(true) : xmlDoc.createElement('w:rPr');
+    _applyOverrides(xmlDoc, rPr, formatToRemove, 'remove');
+
+    let rPrXml = serializer.serializeToString(rPr);
+    rPrXml = rPrXml.replace(/\s+xmlns:[^=]+="[^"]*"/g, '');
+    return rPrXml === '<w:rPr/>' ? '' : rPrXml;
+}
+
+/**
+ * Removes formatting tags and adds explicit off overrides for the specified flags.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Element} rPr - Run properties
+ * @param {Object} formatToRemove - Format flags to remove
+ */
+export function applyFormatOverridesToRPr(xmlDoc, rPr, formatToRemove) {
+    _applyOverrides(xmlDoc, rPr, formatToRemove, 'remove');
+}
+
+/**
+ * Extracts format flags from a run properties element.
+ *
+ * @param {Element|null} rPr - Run properties element
+ * @returns {{ bold: boolean, italic: boolean, underline: boolean, strikethrough: boolean, hasFormatting: boolean }}
+ */
+export function extractFormatFromRPr(rPr) {
+    const format = { bold: false, italic: false, underline: false, strikethrough: false, hasFormatting: false };
+    if (!rPr) return format;
+
+    for (const child of Array.from(rPr.childNodes)) {
+        if (child.nodeName === 'w:b') format.bold = isFormattingElementEnabled(child, false);
+        if (child.nodeName === 'w:i') format.italic = isFormattingElementEnabled(child, false);
+        if (child.nodeName === 'w:u') format.underline = isFormattingElementEnabled(child, true);
+        if (child.nodeName === 'w:strike') format.strikethrough = isFormattingElementEnabled(child, false);
+
+        if (child.nodeName === 'w:rStyle') {
+            const styleRef = child.getAttribute('w:val');
+            if (styleRef) {
+                const lowerStyle = styleRef.toLowerCase();
+                if (lowerStyle.includes('bold') || lowerStyle.includes('strong')) format.bold = true;
+                if (lowerStyle.includes('italic') || lowerStyle.includes('emphasis')) format.italic = true;
+                if (lowerStyle.includes('underline')) format.underline = true;
+            }
+        }
+    }
+
+    format.hasFormatting = format.bold || format.italic || format.underline || format.strikethrough;
+    return format;
+}
+
+/**
+ * Determines whether a formatting element is effectively "on".
+ *
+ * @param {Element} element - Formatting element
+ * @param {boolean} isUnderline - Underline semantic handling
+ * @returns {boolean}
+ */
+function isFormattingElementEnabled(element, isUnderline) {
+    const rawValue = element.getAttribute('w:val') || element.getAttribute('val') || '';
+    const value = rawValue.toLowerCase();
+
+    if (!value) return true;
+
+    if (isUnderline) {
+        return value !== 'none' && value !== '0' && value !== 'false' && value !== 'off';
+    }
+
+    return value !== '0' && value !== 'false' && value !== 'off';
+}

package/engine/run-builders.js

@@ -0,0 +1,235 @@
+/**
+ * OOXML run/track-change builders.
+ *
+ * This module centralizes creation of `w:r`, `w:ins`, `w:del`, `w:rPrChange`,
+ * and `w:pPrChange` elements used by surgical and reconstruction modes.
+ */
+
+import { RPR_SCHEMA_ORDER } from './rpr-helpers.js';
+import { createRevisionMetadata, getRevisionTimestamp } from '../core/types.js';
+import { getFirstElementByTag } from '../core/xml-query.js';
+
+/**
+ * Creates an insertion/deletion wrapper.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {'ins'|'del'} type - Wrapper type
+ * @param {Element|null} run - Optional run to append
+ * @param {string} author - Change author
+ * @returns {Element}
+ */
+export function createTrackChange(xmlDoc, type, run, author) {
+    const wrapper = xmlDoc.createElement(type === 'ins' ? 'w:ins' : 'w:del');
+    const metadata = createRevisionMetadata(author);
+    wrapper.setAttribute('w:id', String(metadata.id));
+    wrapper.setAttribute('w:author', metadata.author);
+    wrapper.setAttribute('w:date', metadata.date);
+    if (run) {
+        wrapper.appendChild(run);
+    }
+    return wrapper;
+}
+
+/**
+ * Creates a text run with optional formatting.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {string} text - Text content
+ * @param {Element|null} rPr - Run properties
+ * @param {boolean} isDelete - Use `w:delText` instead of `w:t`
+ * @returns {Element}
+ */
+export function createTextRun(xmlDoc, text, rPr, isDelete) {
+    const run = xmlDoc.createElement('w:r');
+    if (rPr) run.appendChild(rPr.cloneNode(true));
+
+    const textEl = xmlDoc.createElement(isDelete ? 'w:delText' : 'w:t');
+    textEl.setAttribute('xml:space', 'preserve');
+    textEl.textContent = text;
+    run.appendChild(textEl);
+
+    return run;
+}
+
+/**
+ * Creates an array of runs with formatting applied from hints.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {string} text - Text to split and format
+ * @param {Element|null} baseRPr - Base run properties
+ * @param {Array} formatHints - Formatting hints
+ * @param {number} baseOffset - Absolute base offset
+ * @param {string} [author] - Change author
+ * @param {boolean} [generateRedlines] - Whether to create rPrChange
+ * @returns {Element[]}
+ */
+export function createFormattedRuns(xmlDoc, text, baseRPr, formatHints, baseOffset, author, generateRedlines) {
+    if (!text) return [];
+
+    const breaks = new Set([0, text.length]);
+    for (const hint of formatHints) {
+        const localStart = Math.max(0, hint.start - baseOffset);
+        const localEnd = Math.min(text.length, hint.end - baseOffset);
+        if (localStart >= 0 && localStart < text.length) breaks.add(localStart);
+        if (localEnd > 0 && localEnd <= text.length) breaks.add(localEnd);
+    }
+
+    const sortedBreaks = Array.from(breaks).sort((a, b) => a - b);
+    const runs = [];
+
+    for (let i = 0; i < sortedBreaks.length - 1; i++) {
+        const start = sortedBreaks[i];
+        const end = sortedBreaks[i + 1];
+        const segment = text.slice(start, end);
+        if (!segment) continue;
+
+        const segmentBaseOffset = baseOffset + start;
+        const segmentEndOffset = baseOffset + end;
+
+        const applicableHints = formatHints.filter(h =>
+            h.start <= segmentBaseOffset && h.end >= segmentEndOffset
+        );
+
+        const combinedFormat = {};
+        applicableHints.forEach(h => {
+            if (h.format) Object.assign(combinedFormat, h.format);
+        });
+
+        const formattedRPr = injectFormattingToRPr(xmlDoc, baseRPr, combinedFormat, author, generateRedlines);
+        runs.push(createTextRunWithRPrElement(xmlDoc, segment, formattedRPr, false));
+    }
+
+    return runs;
+}
+
+/**
+ * Creates a text run with an existing rPr element (no clone).
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {string} text - Text content
+ * @param {Element|null} rPrElement - Run properties element
+ * @param {boolean} isDelete - Use `w:delText` instead of `w:t`
+ * @returns {Element}
+ */
+export function createTextRunWithRPrElement(xmlDoc, text, rPrElement, isDelete) {
+    const run = xmlDoc.createElement('w:r');
+    if (rPrElement) run.appendChild(rPrElement);
+
+    const textEl = xmlDoc.createElement(isDelete ? 'w:delText' : 'w:t');
+    textEl.setAttribute('xml:space', 'preserve');
+    textEl.textContent = text;
+    run.appendChild(textEl);
+
+    return run;
+}
+
+/**
+ * Creates a new rPr synchronized to the requested core formatting flags.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Element|null} baseRPr - Base run properties
+ * @param {Object|null} format - Format flags
+ * @param {string} [author] - Change author
+ * @param {boolean} [generateRedlines] - Whether to create rPrChange
+ * @returns {Element}
+ */
+export function injectFormattingToRPr(xmlDoc, baseRPr, format, author, generateRedlines) {
+    const rPr = xmlDoc.createElement('w:rPr');
+
+    if (baseRPr) {
+        Array.from(baseRPr.childNodes).forEach(child => {
+            if (!['w:b', 'w:bCs', 'w:i', 'w:iCs', 'w:u', 'w:strike', 'w:rPrChange'].includes(child.nodeName)) {
+                rPr.appendChild(child.cloneNode(true));
+            }
+        });
+    }
+
+    const activeFormat = format || { bold: false, italic: false, underline: false, strikethrough: false };
+
+    if (author && generateRedlines) {
+        createRPrChange(xmlDoc, rPr, author, baseRPr);
+    }
+
+    const syncElement = (tagName, isOn, valOn = null, valOff = '0') => {
+        const el = xmlDoc.createElement(tagName);
+        if (isOn) {
+            if (valOn) el.setAttribute('w:val', valOn);
+        } else if (valOff) {
+            el.setAttribute('w:val', valOff);
+        }
+
+        const myIndex = RPR_SCHEMA_ORDER.indexOf(tagName);
+        const myPriority = myIndex === -1 ? 999 : myIndex;
+
+        let inserted = false;
+        for (const child of Array.from(rPr.childNodes)) {
+            if (child.nodeType !== 1) continue;
+            const childIndex = RPR_SCHEMA_ORDER.indexOf(child.nodeName);
+            const childPriority = childIndex === -1 ? 999 : childIndex;
+            if (childPriority > myPriority) {
+                rPr.insertBefore(el, child);
+                inserted = true;
+                break;
+            }
+        }
+        if (!inserted) rPr.appendChild(el);
+    };
+
+    syncElement('w:b', !!activeFormat.bold, '1', '0');
+    syncElement('w:bCs', !!activeFormat.bold, '1', '0');
+    syncElement('w:i', !!activeFormat.italic, '1', '0');
+    syncElement('w:iCs', !!activeFormat.italic, '1', '0');
+    syncElement('w:u', !!activeFormat.underline, 'single', 'none');
+    syncElement('w:strike', !!activeFormat.strikethrough, '1', '0');
+
+    return rPr;
+}
+
+/**
+ * Creates and attaches a `w:rPrChange` snapshot.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Element} rPr - Target run properties
+ * @param {string} author - Change author
+ * @param {string} dateStr - ISO date string
+ * @param {Element} [sourceNode] - Optional source for previous state snapshot
+ * @returns {Element}
+ */
+export function snapshotAndAttachRPrChange(xmlDoc, rPr, author, dateStr, sourceNode) {
+    const rPrChange = xmlDoc.createElement('w:rPrChange');
+    rPrChange.setAttribute('w:id', String(createRevisionMetadata(author).id));
+    rPrChange.setAttribute('w:author', author);
+    rPrChange.setAttribute('w:date', dateStr);
+
+    const previousRPr = xmlDoc.createElement('w:rPr');
+    const source = sourceNode || rPr;
+
+    Array.from(source.childNodes).forEach(child => {
+        if (child.nodeName !== 'w:rPrChange') {
+            previousRPr.appendChild(child.cloneNode(true));
+        }
+    });
+
+    rPrChange.appendChild(previousRPr);
+
+    const existing = getFirstElementByTag(rPr, 'w:rPrChange');
+    if (existing) {
+        rPr.removeChild(existing);
+    }
+
+    rPr.appendChild(rPrChange);
+    return rPrChange;
+}
+
+/**
+ * Creates `w:rPrChange` for track formatting changes.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Element} rPr - Run properties target
+ * @param {string} author - Change author
+ * @param {Element} [previousRPrArg] - Optional explicit previous-state source
+ * @returns {void}
+ */
+function createRPrChange(xmlDoc, rPr, author, previousRPrArg) {
+    snapshotAndAttachRPrChange(xmlDoc, rPr, author, getRevisionTimestamp(), previousRPrArg || rPr);
+}