@ansonlai/docx-redline-js 0.1.0

package/core/table-targeting.js

@@ -0,0 +1,233 @@
+/**
+ * Shared table-targeting helpers for per-paragraph redline callers.
+ */
+
+import {
+    WORD_MAIN_NS,
+    getParagraphText,
+    isMarkdownTableText,
+    findContainingWordElement,
+    normalizeWhitespaceForTargeting
+} from './paragraph-targeting.js';
+
+function getDirectWordChildren(element, localName) {
+    if (!element) return [];
+    return Array.from(element.childNodes || []).filter(
+        node =>
+            node &&
+            node.nodeType === 1 &&
+            node.namespaceURI === WORD_MAIN_NS &&
+            node.localName === localName
+    );
+}
+
+function escapeMarkdownCell(text) {
+    return String(text || '')
+        .replace(/\|/g, '\\|')
+        .replace(/\r?\n/g, '<br>');
+}
+
+function extractTableMatrix(tableElement) {
+    const rowElements = getDirectWordChildren(tableElement, 'tr');
+    const matrix = rowElements.map(row => {
+        const cellElements = getDirectWordChildren(row, 'tc');
+        return cellElements.map(cell => {
+            const paragraphs = getDirectWordChildren(cell, 'p');
+            if (paragraphs.length === 0) return normalizeWhitespaceForTargeting(getParagraphText(cell));
+            const lines = paragraphs
+                .map(p => normalizeWhitespaceForTargeting(getParagraphText(p)))
+                .filter(Boolean);
+            return lines.join('\n');
+        });
+    });
+
+    const columnCount = matrix.reduce((max, row) => Math.max(max, row.length), 0);
+    matrix.forEach(row => {
+        while (row.length < columnCount) row.push('');
+    });
+
+    return { matrix, rowElements, columnCount };
+}
+
+function tableMatrixToMarkdown(matrix, columnCount) {
+    if (!Array.isArray(matrix) || matrix.length === 0 || columnCount <= 0) return null;
+    const normalized = matrix.map(row => {
+        const copy = Array.isArray(row) ? row.slice(0, columnCount) : [];
+        while (copy.length < columnCount) copy.push('');
+        return copy;
+    });
+
+    const header = normalized[0];
+    const separator = new Array(columnCount).fill('---');
+    const bodyRows = normalized.slice(1);
+    const toLine = row => `| ${row.map(cell => escapeMarkdownCell(cell)).join(' | ')} |`;
+
+    return [toLine(header), toLine(separator), ...bodyRows.map(toLine)].join('\n');
+}
+
+function isSymmetricLabelRow(rowValues) {
+    if (!Array.isArray(rowValues) || rowValues.length < 2) return false;
+    const normalized = rowValues.map(value => normalizeWhitespaceForTargeting(value)).filter(Boolean);
+    if (normalized.length < 2) return false;
+    return normalized.every(value => value === normalized[0]);
+}
+
+/**
+ * Heuristic detector for paragraphs likely belonging to a table-source block.
+ *
+ * @param {string} text - Paragraph text
+ * @returns {boolean}
+ */
+export function isLikelyStructuredTableSourceParagraph(text) {
+    const normalized = String(text || '').trim();
+    if (!normalized) return false;
+    if (/^and$/i.test(normalized)) return true;
+    if (/^\[.*\]$/.test(normalized)) return true;
+    if (/^\(.*\)$/.test(normalized)) return true;
+    if (/:\s*$/.test(normalized)) return true;
+    if (normalized.length <= 90 && !/[.!?]$/.test(normalized) && /[:\[\]()]/.test(normalized)) return true;
+    if (/^[\[(]/.test(normalized)) return true;
+    return false;
+}
+
+/**
+ * Infers a contiguous paragraph block for table conversion starting from a paragraph.
+ *
+ * @param {Element|null} startParagraph - Starting w:p node
+ * @param {Object} [options={}] - Inference options
+ * @param {number} [options.maxScan=10] - Max sibling paragraphs to inspect
+ * @param {(paragraph: Element) => string} [options.getParagraphText] - Optional text getter
+ * @returns {Element[]|null}
+ */
+export function inferTableReplacementParagraphBlock(startParagraph, options = {}) {
+    const maxScan = Number.isInteger(options?.maxScan) && options.maxScan > 0 ? options.maxScan : 10;
+    const paragraphTextGetter = typeof options?.getParagraphText === 'function'
+        ? options.getParagraphText
+        : getParagraphText;
+
+    if (!startParagraph || !startParagraph.parentNode) return null;
+
+    const block = [startParagraph];
+    let cursor = startParagraph.nextSibling;
+    let scanned = 0;
+
+    while (cursor && scanned < maxScan) {
+        scanned += 1;
+        const nextCursor = cursor.nextSibling;
+        if (cursor.nodeType !== 1 || cursor.namespaceURI !== WORD_MAIN_NS || cursor.localName !== 'p') {
+            cursor = nextCursor;
+            continue;
+        }
+
+        const text = String(paragraphTextGetter(cursor) || '').trim();
+        if (!text) {
+            if (block.length > 1) break;
+            cursor = nextCursor;
+            continue;
+        }
+
+        if (!isLikelyStructuredTableSourceParagraph(text)) break;
+        block.push(cursor);
+        cursor = nextCursor;
+    }
+
+    return block.length > 1 ? block : null;
+}
+
+/**
+ * Builds full-table markdown when a table-cell redline uses multiline text.
+ *
+ * Heuristic:
+ * - If target paragraph is inside a table cell
+ * - and `modifiedText` is multiline but not markdown-table syntax
+ * - and first line matches current paragraph text
+ * Then treat extra lines as row insertions in the target column.
+ * For symmetric label rows (for example `Title:` in both signature columns),
+ * inserted values are mirrored across columns.
+ *
+ * @param {Element} targetParagraph - Resolved target paragraph
+ * @param {string} modifiedText - User/model modified text
+ * @param {{
+ *   tableElement?: Element|null,
+ *   currentParagraphText?: string,
+ *   onInfo?: (msg:string)=>void,
+ *   onWarn?: (msg:string)=>void
+ * }} [options] - Optional context/log callbacks
+ * @returns {string|null}
+ */
+export function synthesizeTableMarkdownFromMultilineCellEdit(targetParagraph, modifiedText, options = {}) {
+    const onInfo = typeof options.onInfo === 'function' ? options.onInfo : () => {};
+    const onWarn = typeof options.onWarn === 'function' ? options.onWarn : () => {};
+
+    const rawModified = String(modifiedText || '');
+    if (!rawModified.includes('\n')) return null;
+    if (isMarkdownTableText(rawModified)) return null;
+
+    const lines = rawModified
+        .split(/\r?\n/g)
+        .map(line => line.trim())
+        .filter(Boolean);
+    if (lines.length < 2) return null;
+
+    const tableElement = options.tableElement || findContainingWordElement(targetParagraph, 'tbl');
+    const rowElement = findContainingWordElement(targetParagraph, 'tr');
+    const cellElement = findContainingWordElement(targetParagraph, 'tc');
+    if (!tableElement || !rowElement || !cellElement) return null;
+
+    const currentParagraphText = normalizeWhitespaceForTargeting(
+        options.currentParagraphText || getParagraphText(targetParagraph)
+    );
+    const firstLine = normalizeWhitespaceForTargeting(lines[0]);
+    if (currentParagraphText && firstLine && firstLine !== currentParagraphText) {
+        // Avoid rewriting full tables from ambiguous multiline content.
+        onWarn('[Table] Multiline cell text did not anchor to original cell text; skipping table-row synthesis heuristic.');
+        return null;
+    }
+
+    const { matrix, rowElements, columnCount } = extractTableMatrix(tableElement);
+    if (matrix.length === 0 || columnCount === 0) return null;
+
+    const rowIndex = rowElements.indexOf(rowElement);
+    const cellElements = getDirectWordChildren(rowElement, 'tc');
+    const colIndex = cellElements.indexOf(cellElement);
+    if (rowIndex < 0 || colIndex < 0 || colIndex >= columnCount) return null;
+
+    matrix[rowIndex][colIndex] = lines[0];
+    const mirrorAcrossColumns = isSymmetricLabelRow(matrix[rowIndex]);
+    if (mirrorAcrossColumns) {
+        onInfo('[Table] Symmetric row detected; mirroring inserted row values across columns.');
+    }
+
+    for (let i = 1; i < lines.length; i++) {
+        const insertIndex = rowIndex + i;
+        const extraValue = lines[i];
+        if (
+            insertIndex < matrix.length &&
+            !normalizeWhitespaceForTargeting(matrix[insertIndex][colIndex])
+        ) {
+            if (mirrorAcrossColumns) {
+                for (let col = 0; col < columnCount; col++) {
+                    if (!normalizeWhitespaceForTargeting(matrix[insertIndex][col])) {
+                        matrix[insertIndex][col] = extraValue;
+                    }
+                }
+            } else {
+                matrix[insertIndex][colIndex] = extraValue;
+            }
+        } else {
+            const newRow = new Array(columnCount).fill('');
+            if (mirrorAcrossColumns) {
+                for (let col = 0; col < columnCount; col++) newRow[col] = extraValue;
+            } else {
+                newRow[colIndex] = extraValue;
+            }
+            matrix.splice(Math.min(insertIndex, matrix.length), 0, newRow);
+        }
+    }
+
+    const markdown = tableMatrixToMarkdown(matrix, columnCount);
+    if (!markdown) return null;
+
+    onInfo('[Table] Synthesized full markdown table from multiline cell edit for table-scope reconciliation.');
+    return markdown;
+}

package/core/types.js

@@ -0,0 +1,204 @@
+/**
+ * OOXML Reconciliation Pipeline - Core Types
+ * 
+ * Data types and enums for the reconciliation system.
+ */
+
+import { getDefaultAuthor } from '../adapters/config.js';
+
+// WordprocessingML namespace
+export const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+export const NS_R = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+
+/**
+ * Diff operation types from word-level diffing
+ */
+export const DiffOp = Object.freeze({
+    EQUAL: 'equal',
+    DELETE: 'delete',
+    INSERT: 'insert'
+});
+
+/**
+ * Run types in the run model
+ */
+export const RunKind = Object.freeze({
+    TEXT: 'run',
+    DELETION: 'deletion',
+    INSERTION: 'insertion',
+    HYPERLINK: 'hyperlink',
+    BOOKMARK: 'bookmark',
+    FIELD: 'field',
+    // Container delimiters for preserving hierarchy
+    CONTAINER_START: 'container_start',
+    CONTAINER_END: 'container_end',
+    // Multi-paragraph support
+    PARAGRAPH_START: 'paragraph_start'
+});
+
+/**
+ * Container types that wrap runs
+ */
+export const ContainerKind = Object.freeze({
+    SDT: 'sdt',                 // Content Control
+    SMART_TAG: 'smartTag',      // Smart Tag
+    CUSTOM_XML: 'customXml',    // Custom XML
+    FIELD_COMPLEX: 'fldComplex' // Complex field (fldChar-based)
+});
+
+/**
+ * Content types for block-level detection
+ */
+export const ContentType = Object.freeze({
+    PARAGRAPH: 'paragraph',
+    BULLET_LIST: 'bullet_list',
+    NUMBERED_LIST: 'numbered_list',
+    TABLE: 'table'
+});
+
+/**
+ * Supported numbering formats
+ */
+export const NumberFormat = Object.freeze({
+    DECIMAL: 'decimal',           // 1, 2, 3
+    LOWER_ALPHA: 'lowerLetter',   // a, b, c
+    UPPER_ALPHA: 'upperLetter',   // A, B, C
+    LOWER_ROMAN: 'lowerRoman',    // i, ii, iii
+    UPPER_ROMAN: 'upperRoman',    // I, II, III
+    BULLET: 'bullet',             // •
+    OUTLINE: 'outline'            // 1.1.2.3
+});
+
+/**
+ * Numbering suffixes/formats
+ */
+export const NumberSuffix = Object.freeze({
+    PERIOD: 'period',             // 1.
+    PAREN_RIGHT: 'parenRight',    // 1)
+    PAREN_BOTH: 'parenBoth',      // (1)
+    NONE: 'none'
+});
+
+/**
+ * @typedef {Object} RunEntry
+ * @property {string} kind - RunKind value
+ * @property {string} text - Text content of the run
+ * @property {string} [rPrXml] - Serialized run properties (formatting)
+ * @property {Element|null} [pPrElement] - Lazy paragraph properties element for PARAGRAPH_START entries
+ * @property {string} [pPrXml] - Serialized paragraph properties for PARAGRAPH_START entries
+ * @property {number} startOffset - Start offset in accepted text
+ * @property {number} endOffset - End offset in accepted text
+ * @property {string} [author] - Author for track changes
+ * @property {string} [nodeXml] - Original XML for special elements
+ */
+
+/**
+ * @typedef {Object} DiffOperation
+ * @property {string} type - DiffOp value
+ * @property {number} startOffset - Start offset in original text
+ * @property {number} endOffset - End offset in original text
+ * @property {string} text - Text content of the operation
+ */
+
+/**
+ * @typedef {Object} FormatHint
+ * @property {number} start - Start offset in clean text
+ * @property {number} end - End offset in clean text
+ * @property {Object} format - Format flags (bold, italic, etc.)
+ */
+
+/**
+ * @typedef {Object} IngestionResult
+ * @property {RunEntry[]} runModel - Array of run entries
+ * @property {string} acceptedText - Reconstructed text from runs
+ * @property {Element|null} pPr - Paragraph properties element
+ */
+
+/**
+ * @typedef {Object} PreprocessResult
+ * @property {string} cleanText - Text with markdown stripped
+ * @property {FormatHint[]} formatHints - Position-based format information
+ */
+
+/**
+ * @typedef {Object} ReconciliationResult
+ * @property {string} ooxml - The reconciled OOXML output
+ * @property {boolean} isValid - Whether validation passed
+ * @property {string[]} warnings - Any warnings during processing
+ */
+
+/**
+ * @typedef {Object} SerializationOptions
+ * @property {string} [author] - Author for generated track changes (defaults to configured default author)
+ * @property {boolean} [generateRedlines=true] - Toggle track-change wrappers
+ * @property {string|null} [font=null] - Optional font override for generated runs
+ */
+
+/**
+ * @typedef {Object} DocumentFragmentOptions
+ * @property {boolean} [includeNumbering=false] - Include numbering relationship/part
+ * @property {string|null} [numberingXml=null] - Custom numbering part payload
+ * @property {boolean} [appendTrailingParagraph=true] - Append trailing blank paragraph
+ */
+
+/**
+ * Escapes XML special characters
+ * @param {string} str - String to escape
+ * @returns {string} Escaped string
+ */
+export function escapeXml(str) {
+    if (!str) return '';
+    return str
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&apos;');
+}
+
+// Global revision ID counter for track changes
+let revisionIdCounter = 1000;
+
+/**
+ * Gets the next unique revision ID for track changes
+ * @returns {number} Unique revision ID
+ */
+export function getNextRevisionId() {
+    return revisionIdCounter++;
+}
+
+/**
+ * Returns the canonical ISO timestamp used for track-change metadata.
+ *
+ * @param {Date} [date] - Optional date source (for tests)
+ * @returns {string}
+ */
+export function getRevisionTimestamp(date = new Date()) {
+    return date.toISOString();
+}
+
+/**
+ * Creates shared revision metadata for OOXML track-change tags.
+ *
+ * @param {string} [author] - Track-change author (defaults to configured default author)
+ * @returns {{ id: number, author: string, date: string }}
+ */
+export function createRevisionMetadata(author) {
+    const resolvedAuthor = typeof author === 'string' && author.trim()
+        ? author.trim()
+        : getDefaultAuthor();
+
+    return {
+        id: getNextRevisionId(),
+        author: resolvedAuthor,
+        date: getRevisionTimestamp()
+    };
+}
+
+/**
+ * Resets the revision ID counter (for testing)
+ * @param {number} [startValue=1000] - Value to reset to
+ */
+export function resetRevisionIdCounter(startValue = 1000) {
+    revisionIdCounter = startValue;
+}

package/core/xml-query.js

@@ -0,0 +1,99 @@
+/**
+ * Shared XML query helpers for OOXML documents.
+ *
+ * These wrappers provide consistent first/all element access across:
+ * - Namespace-aware lookups (`getElementsByTagNameNS`)
+ * - Prefix-based fallbacks (`getElementsByTagName('w:...')`)
+ */
+
+/**
+ * Returns all descendant elements matching a qualified tag name.
+ *
+ * @param {Node|Document|Element|null|undefined} node - Query root
+ * @param {string} tagName - Qualified element name (for example, `w:p`)
+ * @returns {Element[]}
+ */
+export function getElementsByTag(node, tagName) {
+    if (!node || typeof node.getElementsByTagName !== 'function') return [];
+    return Array.from(node.getElementsByTagName(tagName));
+}
+
+/**
+ * Returns the first descendant element matching a qualified tag name.
+ *
+ * @param {Node|Document|Element|null|undefined} node - Query root
+ * @param {string} tagName - Qualified element name (for example, `w:p`)
+ * @returns {Element|null}
+ */
+export function getFirstElementByTag(node, tagName) {
+    if (!node || typeof node.getElementsByTagName !== 'function') return null;
+    const elements = node.getElementsByTagName(tagName);
+    return elements.length > 0 ? elements[0] : null;
+}
+
+/**
+ * Returns all descendant elements matching namespace + local name.
+ *
+ * @param {Node|Document|Element|null|undefined} node - Query root
+ * @param {string} namespaceUri - Namespace URI (or `*`)
+ * @param {string} localName - Local tag name (for example, `p`)
+ * @returns {Element[]}
+ */
+export function getElementsByTagNS(node, namespaceUri, localName) {
+    if (!node || typeof node.getElementsByTagNameNS !== 'function') return [];
+    return Array.from(node.getElementsByTagNameNS(namespaceUri, localName));
+}
+
+/**
+ * Returns the first descendant element matching namespace + local name.
+ *
+ * @param {Node|Document|Element|null|undefined} node - Query root
+ * @param {string} namespaceUri - Namespace URI (or `*`)
+ * @param {string} localName - Local tag name (for example, `p`)
+ * @returns {Element|null}
+ */
+export function getFirstElementByTagNS(node, namespaceUri, localName) {
+    if (!node || typeof node.getElementsByTagNameNS !== 'function') return null;
+    const elements = node.getElementsByTagNameNS(namespaceUri, localName);
+    return elements.length > 0 ? elements[0] : null;
+}
+
+/**
+ * Returns all elements using namespace-aware lookup with prefixed fallback.
+ *
+ * @param {Node|Document|Element|null|undefined} node - Query root
+ * @param {string} namespaceUri - Namespace URI
+ * @param {string} localName - Local name
+ * @param {string} [fallbackTagName] - Optional prefixed fallback (default: `w:${localName}`)
+ * @returns {Element[]}
+ */
+export function getElementsByTagNSOrTag(node, namespaceUri, localName, fallbackTagName = `w:${localName}`) {
+    const namespacedElements = getElementsByTagNS(node, namespaceUri, localName);
+    if (namespacedElements.length > 0) return namespacedElements;
+    return getElementsByTag(node, fallbackTagName);
+}
+
+/**
+ * Returns the first element using namespace-aware lookup with prefixed fallback.
+ *
+ * @param {Node|Document|Element|null|undefined} node - Query root
+ * @param {string} namespaceUri - Namespace URI
+ * @param {string} localName - Local name
+ * @param {string} [fallbackTagName] - Optional prefixed fallback (default: `w:${localName}`)
+ * @returns {Element|null}
+ */
+export function getFirstElementByTagNSOrTag(node, namespaceUri, localName, fallbackTagName = `w:${localName}`) {
+    const namespacedElement = getFirstElementByTagNS(node, namespaceUri, localName);
+    if (namespacedElement) return namespacedElement;
+    return getFirstElementByTag(node, fallbackTagName);
+}
+
+/**
+ * Returns XML parser error element if present.
+ *
+ * @param {Document|Element|null|undefined} xmlDoc - Parsed XML document
+ * @returns {Element|null}
+ */
+export function getXmlParseError(xmlDoc) {
+    return getFirstElementByTag(xmlDoc, 'parsererror');
+}