@ansonlai/docx-redline-js 0.1.0

package/engine/format-paragraph-targeting.js

@@ -0,0 +1,208 @@
+import { advanceOffsetForParagraphBoundary } from '../core/paragraph-offset-policy.js';
+
+const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+
+function isWordElement(node, localName) {
+    if (!node || node.nodeType !== 1) return false;
+    if (node.namespaceURI === NS_W && node.localName === localName) return true;
+    const nodeName = String(node.nodeName || '');
+    return nodeName === `w:${localName}` || nodeName === localName;
+}
+
+/**
+ * Paragraph targeting helpers for format-only operations.
+ *
+ * Encapsulates paragraph text reconstruction and matching logic used to map
+ * AI-provided text ranges to the correct paragraph/spans in OOXML.
+ */
+
+/**
+ * Builds paragraph metadata (text, spans, offsets) used for format-only changes.
+ *
+ * @param {Document} xmlDoc - XML document (unused, kept for signature compatibility)
+ * @param {Element[]} paragraphs - Paragraph elements
+ * @param {Array} textSpans - Extracted text spans
+ * @returns {Array}
+ */
+export function buildParagraphInfos(xmlDoc, paragraphs, textSpans) {
+    void xmlDoc;
+    const spansByParagraph = new Map();
+    for (const span of textSpans) {
+        if (!span || !span.paragraph) continue;
+        if (!spansByParagraph.has(span.paragraph)) {
+            spansByParagraph.set(span.paragraph, []);
+        }
+        spansByParagraph.get(span.paragraph).push(span);
+    }
+
+    const infos = [];
+    let runningOffset = 0;
+
+    paragraphs.forEach((p, index) => {
+        const spans = (spansByParagraph.get(p) || []).slice().sort((a, b) => a.charStart - b.charStart);
+        const text = buildParagraphTextFromSpans(spans);
+        const normalizedText = normalizeParagraphComparisonText(text);
+        const normalizedTrim = normalizedText.trim();
+
+        infos.push({
+            paragraph: p,
+            spans,
+            text,
+            normalizedText,
+            normalizedTrim,
+            startOffset: runningOffset
+        });
+
+        runningOffset += normalizedText.length;
+        runningOffset = advanceOffsetForParagraphBoundary(runningOffset, index, paragraphs.length);
+    });
+
+    return infos;
+}
+
+/**
+ * Finds a paragraph info entry that matches the provided text.
+ *
+ * @param {Array} paragraphInfos - Paragraph metadata
+ * @param {string} originalText - Original text
+ * @returns {Object|null}
+ */
+export function findMatchingParagraphInfo(paragraphInfos, originalText) {
+    if (!originalText) return null;
+
+    const normalizedOriginal = normalizeParagraphComparisonText(originalText);
+    const normalizedTrim = normalizedOriginal.trim();
+    if (!normalizedTrim) return null;
+
+    for (const info of paragraphInfos) {
+        if (info.normalizedText === normalizedOriginal) {
+            return info;
+        }
+    }
+
+    for (const info of paragraphInfos) {
+        if (info.normalizedTrim === normalizedTrim) {
+            return info;
+        }
+    }
+
+    return null;
+}
+
+/**
+ * Finds the best target paragraph and offset for format-only operations.
+ *
+ * @param {Array} paragraphInfos - Paragraph metadata
+ * @param {string} originalText - Original text used for matching
+ * @returns {{ targetInfo: Object|null, matchOffset: number }}
+ */
+export function findTargetParagraphInfo(paragraphInfos, originalText) {
+    const normalizedOriginalFull = normalizeParagraphComparisonText(originalText);
+    const normalizedOriginalTrim = normalizedOriginalFull.trim();
+
+    let targetInfo = null;
+    let matchOffset = 0;
+
+    for (const info of paragraphInfos) {
+        if (info.normalizedText === normalizedOriginalFull) {
+            targetInfo = info;
+            return { targetInfo, matchOffset };
+        }
+    }
+
+    if (normalizedOriginalTrim.length > 0) {
+        for (const info of paragraphInfos) {
+            if (info.normalizedTrim === normalizedOriginalTrim) {
+                targetInfo = info;
+                return { targetInfo, matchOffset };
+            }
+        }
+    }
+
+    if (normalizedOriginalTrim.length > 0) {
+        const docPlain = paragraphInfos.map(info => info.normalizedText).join('\n');
+        const idx = docPlain.indexOf(normalizedOriginalTrim);
+        if (idx !== -1) {
+            for (const info of paragraphInfos) {
+                const start = info.startOffset;
+                const length = info.normalizedText.length;
+                if (idx >= start && idx <= start + length) {
+                    targetInfo = info;
+                    matchOffset = idx - start;
+                    break;
+                }
+            }
+        }
+    }
+
+    // Fallback: single-paragraph scope where extracted span text is only a subset
+    // of original paragraph text (common when prior tracked wrappers contain text
+    // that is not represented in direct run-span extraction).
+    if (!targetInfo && paragraphInfos.length === 1 && normalizedOriginalFull.length > 0) {
+        const onlyInfo = paragraphInfos[0];
+        const paragraphTrim = onlyInfo.normalizedTrim || '';
+        if (paragraphTrim.length > 0) {
+            const subsetIndex = normalizedOriginalFull.indexOf(paragraphTrim);
+            if (subsetIndex >= 0) {
+                targetInfo = onlyInfo;
+                matchOffset = -subsetIndex;
+            }
+        }
+    }
+
+    return { targetInfo, matchOffset };
+}
+
+/**
+ * Walks up the DOM to find the containing paragraph for a run.
+ *
+ * @param {Node} node - Starting node
+ * @returns {Element|null}
+ */
+export function getContainingParagraph(node) {
+    let current = node;
+    while (current) {
+        if (isWordElement(current, 'p')) return current;
+        current = current.parentNode;
+    }
+    return null;
+}
+
+/**
+ * Reconstructs human-readable text from spans to align with Word paragraph text.
+ *
+ * @param {Array} spans - Span collection
+ * @returns {string}
+ */
+function buildParagraphTextFromSpans(spans) {
+    if (!spans || spans.length === 0) return '';
+
+    let text = '';
+    for (const span of spans) {
+        if (!span || !span.textElement) continue;
+        const textElement = span.textElement;
+        if (isWordElement(textElement, 't')) {
+            text += span.textElement.textContent || '';
+        } else if (isWordElement(textElement, 'tab')) {
+            text += '\t';
+        } else if (isWordElement(textElement, 'br') || isWordElement(textElement, 'cr')) {
+            text += '\n';
+        } else if (isWordElement(textElement, 'noBreakHyphen')) {
+            text += '\u2011';
+        }
+    }
+    return text;
+}
+
+/**
+ * Normalizes paragraph text for comparisons (handles carriage returns and NBSP).
+ *
+ * @param {string} text - Text input
+ * @returns {string}
+ */
+function normalizeParagraphComparisonText(text) {
+    if (!text) return '';
+    return text
+        .replace(/\r/g, '\n')
+        .replace(/\u00a0/g, ' ');
+}

package/engine/format-span-application.js

@@ -0,0 +1,178 @@
+/**
+ * Span-level formatting helpers.
+ *
+ * Handles boundary splitting and robust format application on already-extracted
+ * text spans without owning paragraph targeting concerns.
+ */
+
+import { mergeFormats } from '../pipeline/markdown-processor.js';
+import { injectFormattingToRPr, createTextRun } from './run-builders.js';
+
+/**
+ * Splits spans at all supplied absolute boundaries.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Array} textSpans - Input spans
+ * @param {number[]} boundaries - Absolute boundaries
+ * @returns {Array}
+ */
+export function splitSpansAtBoundaries(xmlDoc, textSpans, boundaries) {
+    const sortedBoundaries = Array.from(new Set(boundaries)).sort((a, b) => a - b);
+    if (sortedBoundaries.length === 0 || textSpans.length === 0) {
+        return [...textSpans];
+    }
+
+    const orderedSpans = [...textSpans].sort((a, b) => a.charStart - b.charStart || a.charEnd - b.charEnd);
+    const splitSpans = [];
+    let boundaryIndex = 0;
+
+    for (const span of orderedSpans) {
+        while (boundaryIndex < sortedBoundaries.length && sortedBoundaries[boundaryIndex] <= span.charStart) {
+            boundaryIndex++;
+        }
+
+        let currentSpan = span;
+        while (boundaryIndex < sortedBoundaries.length && sortedBoundaries[boundaryIndex] < currentSpan.charEnd) {
+            const boundary = sortedBoundaries[boundaryIndex];
+            const splitResult = splitSpanAtOffset(xmlDoc, currentSpan, boundary);
+
+            if (!splitResult) {
+                boundaryIndex++;
+                continue;
+            }
+
+            splitSpans.push(splitResult[0]);
+            currentSpan = splitResult[1];
+            boundaryIndex++;
+        }
+
+        splitSpans.push(currentSpan);
+    }
+
+    return splitSpans;
+}
+
+/**
+ * Robust formatting application.
+ * Identifies all boundaries, splits all runs first, then applies merged formats.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Array} textSpans - Text spans
+ * @param {Array} formatHints - Format hints
+ * @param {string} author - Change author
+ * @param {boolean} generateRedlines - Track change toggle
+ * @returns {void}
+ */
+export function applyFormatHintsToSpansRobust(xmlDoc, textSpans, formatHints, author, generateRedlines) {
+    if (textSpans.length === 0) return;
+
+    const boundaries = [];
+    for (const hint of formatHints) {
+        boundaries.push(hint.start, hint.end);
+    }
+
+    const currentSpans = splitSpansAtBoundaries(xmlDoc, textSpans, boundaries)
+        .sort((a, b) => a.charStart - b.charStart || a.charEnd - b.charEnd);
+    const getOverlappingHints = createFormatHintOverlapLookup(formatHints);
+
+    for (const span of currentSpans) {
+        const applicableHints = getOverlappingHints(span.charStart, span.charEnd);
+        if (applicableHints.length > 0) {
+            const targetFormat = mergeFormats(...applicableHints.map(h => h.format));
+            addFormattingToRun(xmlDoc, span.runElement, targetFormat, author, generateRedlines);
+        }
+    }
+}
+
+function createFormatHintOverlapLookup(formatHints) {
+    const sortedHints = (formatHints || [])
+        .slice()
+        .sort((a, b) => a.start - b.start || a.end - b.end);
+
+    const activeHints = [];
+    let nextHintIndex = 0;
+
+    return (start, end) => {
+        while (nextHintIndex < sortedHints.length && sortedHints[nextHintIndex].start < end) {
+            activeHints.push(sortedHints[nextHintIndex]);
+            nextHintIndex++;
+        }
+
+        for (let i = activeHints.length - 1; i >= 0; i--) {
+            if (activeHints[i].end <= start) {
+                activeHints.splice(i, 1);
+            }
+        }
+
+        const overlaps = [];
+        for (const hint of activeHints) {
+            if (hint.start < end && hint.end > start) {
+                overlaps.push(hint);
+            }
+        }
+        return overlaps;
+    };
+}
+
+/**
+ * Splits a text span at a specific absolute character offset.
+ * Modifies the DOM and returns the two new span objects.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Object} span - Text span
+ * @param {number} absoluteOffset - Absolute split offset
+ * @returns {Array|null}
+ */
+export function splitSpanAtOffset(xmlDoc, span, absoluteOffset) {
+    const run = span.runElement;
+    const parent = run.parentNode;
+    if (!parent) return null;
+
+    const fullText = span.textElement.textContent || '';
+    const localSplitPoint = absoluteOffset - span.charStart;
+
+    const textBefore = fullText.substring(0, localSplitPoint);
+    const textAfter = fullText.substring(localSplitPoint);
+
+    if (textBefore.length === 0 || textAfter.length === 0) return null;
+
+    const runBefore = createTextRun(xmlDoc, textBefore, span.rPr, false);
+    const runAfter = createTextRun(xmlDoc, textAfter, span.rPr, false);
+
+    parent.insertBefore(runBefore, run);
+    parent.insertBefore(runAfter, run);
+    parent.removeChild(run);
+
+    const tBefore = runBefore.getElementsByTagName('w:t')[0];
+    const tAfter = runAfter.getElementsByTagName('w:t')[0];
+
+    return [
+        { ...span, charEnd: absoluteOffset, textElement: tBefore, runElement: runBefore },
+        { ...span, charStart: absoluteOffset, textElement: tAfter, runElement: runAfter }
+    ];
+}
+
+/**
+ * Adds formatting elements to a run's rPr, with track change support.
+ *
+ * @param {Document} xmlDoc - XML document
+ * @param {Element} run - Run element
+ * @param {Object} format - Format flags
+ * @param {string} author - Change author
+ * @param {boolean} generateRedlines - Track change toggle
+ * @returns {void}
+ */
+function addFormattingToRun(xmlDoc, run, format, author, generateRedlines) {
+    let rPr = run.getElementsByTagName('w:rPr')[0];
+    const baseRPr = rPr ? rPr.cloneNode(true) : null;
+
+    if (!rPr) {
+        rPr = xmlDoc.createElement('w:rPr');
+        run.insertBefore(rPr, run.firstChild);
+    }
+
+    const newRPr = injectFormattingToRPr(xmlDoc, baseRPr, format, author, generateRedlines);
+
+    while (rPr.firstChild) rPr.removeChild(rPr.firstChild);
+    Array.from(newRPr.childNodes).forEach(child => rPr.appendChild(child));
+}