@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/query/form-fields.js

@@ -0,0 +1,268 @@
+/**
+ * Form Field Data API
+ *
+ * Extract and fill form field values in a document.
+ */
+import { isHyperlink, isRun } from "../core/text-utils.js";
+import { walkDocument } from "../core/walker.js";
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Extract all form field values from a document.
+ *
+ * Traverses the document body (paragraphs, tables, headers, footers)
+ * and collects all legacy form field data.
+ *
+ * @param doc - The document to extract from.
+ * @returns Array of form field entries with their current values.
+ */
+export function extractFormFields(doc) {
+    const results = [];
+    const visitor = {
+        enterRun(run) {
+            if (!run.content) {
+                return "continue";
+            }
+            for (const rc of run.content) {
+                if (rc.type === "field" && rc.formField) {
+                    const ff = rc.formField;
+                    let value;
+                    if (ff.type === "text") {
+                        value = ff.default ?? "";
+                    }
+                    else if (ff.type === "checkBox") {
+                        value = ff.checked ?? ff.default ?? false;
+                    }
+                    else {
+                        // dropdown
+                        value = ff.default ?? 0;
+                    }
+                    results.push({
+                        name: ff.name ?? "",
+                        type: ff.type,
+                        value,
+                        entries: ff.type === "dropDown" ? ff.entries : undefined
+                    });
+                }
+            }
+            return "continue";
+        }
+    };
+    walkDocument(doc, visitor, {
+        includeHeaders: true,
+        includeFooters: true,
+        includeFootnotes: false,
+        includeEndnotes: false,
+        includeComments: false
+    });
+    return results;
+}
+/**
+ * Fill form field values throughout a document.
+ *
+ * The body, headers, footers, footnotes, endnotes and comments are all
+ * processed so a form field placed inside a header (a common case) still
+ * gets filled. Inside paragraphs the visitor descends into hyperlinks and
+ * track-change wrappers so a form field referenced from a tracked
+ * insertion is also reachable.
+ *
+ * @param doc - The document to fill (returns a new copy with filled values).
+ * @param values - Map of field name → new value.
+ * @returns A new document with form fields populated.
+ */
+export function fillFormFields(doc, values) {
+    const newBody = doc.body.map(block => fillFieldsInBlock(block, values));
+    const newHeaders = doc.headers
+        ? new Map(Array.from(doc.headers, ([k, h]) => [
+            k,
+            {
+                ...h,
+                content: {
+                    ...h.content,
+                    children: h.content.children.map(c => fillFieldsInBlock(c, values))
+                }
+            }
+        ]))
+        : undefined;
+    const newFooters = doc.footers
+        ? new Map(Array.from(doc.footers, ([k, f]) => [
+            k,
+            {
+                ...f,
+                content: {
+                    ...f.content,
+                    children: f.content.children.map(c => fillFieldsInBlock(c, values))
+                }
+            }
+        ]))
+        : undefined;
+    const newFootnotes = doc.footnotes
+        ? doc.footnotes.map(fn => ({
+            ...fn,
+            content: fn.content.map(p => fillFieldsInParagraph(p, values))
+        }))
+        : undefined;
+    const newEndnotes = doc.endnotes
+        ? doc.endnotes.map(en => ({
+            ...en,
+            content: en.content.map(p => fillFieldsInParagraph(p, values))
+        }))
+        : undefined;
+    const newComments = doc.comments
+        ? doc.comments.map(cm => ({
+            ...cm,
+            content: cm.content.map(p => fillFieldsInParagraph(p, values))
+        }))
+        : undefined;
+    return {
+        ...doc,
+        body: newBody,
+        ...(newHeaders ? { headers: newHeaders } : {}),
+        ...(newFooters ? { footers: newFooters } : {}),
+        ...(newFootnotes ? { footnotes: newFootnotes } : {}),
+        ...(newEndnotes ? { endnotes: newEndnotes } : {}),
+        ...(newComments ? { comments: newComments } : {})
+    };
+}
+// =============================================================================
+// Internal helpers
+// =============================================================================
+function fillFieldsInBlock(block, values) {
+    if (block.type === "paragraph") {
+        return fillFieldsInParagraph(block, values);
+    }
+    if (block.type === "table") {
+        return {
+            ...block,
+            rows: block.rows.map(r => ({
+                ...r,
+                cells: r.cells.map(c => ({
+                    ...c,
+                    content: c.content.map(inner => fillFieldsInBlock(inner, values))
+                }))
+            }))
+        };
+    }
+    if (block.type === "sdt") {
+        return {
+            ...block,
+            content: block.content.map(c => {
+                if ("type" in c && (c.type === "paragraph" || c.type === "table")) {
+                    return fillFieldsInBlock(c, values);
+                }
+                if (c &&
+                    typeof c === "object" &&
+                    !("type" in c) &&
+                    "content" in c &&
+                    Array.isArray(c.content)) {
+                    // Inline (run-only) SDT child — fill any field run-content nodes
+                    // it carries directly.
+                    return fillFieldsInRun(c, values);
+                }
+                return c;
+            })
+        };
+    }
+    if (block.type === "textBox") {
+        return {
+            ...block,
+            content: block.content.map(p => fillFieldsInParagraph(p, values))
+        };
+    }
+    if (block.type === "drawingShape") {
+        if (!block.textContent || block.textContent.length === 0) {
+            return block;
+        }
+        return {
+            ...block,
+            textContent: block.textContent.map(p => fillFieldsInParagraph(p, values))
+        };
+    }
+    if (block.type === "tableOfContents") {
+        if (!block.cachedParagraphs || block.cachedParagraphs.length === 0) {
+            return block;
+        }
+        return {
+            ...block,
+            cachedParagraphs: block.cachedParagraphs.map(p => fillFieldsInParagraph(p, values))
+        };
+    }
+    return block;
+}
+function fillFieldsInParagraph(para, values) {
+    let modified = false;
+    const newChildren = para.children.map(child => {
+        // Hyperlink: descend into its run children.
+        if (isHyperlink(child)) {
+            let hlModified = false;
+            const newRuns = child.children.map(r => {
+                const filled = fillFieldsInRun(r, values);
+                if (filled !== r) {
+                    hlModified = true;
+                }
+                return filled;
+            });
+            if (hlModified) {
+                modified = true;
+                return { ...child, children: newRuns };
+            }
+            return child;
+        }
+        // Track-change wrappers around a run.
+        if ("type" in child &&
+            (child.type === "insertedRun" ||
+                child.type === "movedToRun")) {
+            const wrapper = child;
+            const filled = fillFieldsInRun(wrapper.run, values);
+            if (filled !== wrapper.run) {
+                modified = true;
+                return { ...wrapper, run: filled };
+            }
+            return child;
+        }
+        if (!isRun(child)) {
+            return child;
+        }
+        const filled = fillFieldsInRun(child, values);
+        if (filled !== child) {
+            modified = true;
+        }
+        return filled;
+    });
+    return modified ? { ...para, children: newChildren } : para;
+}
+function fillFieldsInRun(run, values) {
+    if (!run.content) {
+        return run;
+    }
+    let runModified = false;
+    const newContent = run.content.map(rc => {
+        if (rc.type !== "field" || !rc.formField) {
+            return rc;
+        }
+        const ff = rc.formField;
+        const name = ff.name ?? "";
+        if (!values.has(name)) {
+            return rc;
+        }
+        const newVal = values.get(name);
+        runModified = true;
+        let newFF;
+        if (ff.type === "text") {
+            newFF = { ...ff, default: String(newVal) };
+        }
+        else if (ff.type === "checkBox") {
+            newFF = { ...ff, checked: Boolean(newVal) };
+        }
+        else {
+            // dropdown: value is the selected index
+            newFF = {
+                ...ff,
+                default: typeof newVal === "number" ? newVal : parseInt(String(newVal), 10) || 0
+            };
+        }
+        return { ...rc, formField: newFF };
+    });
+    return runModified ? { ...run, content: newContent } : run;
+}

package/dist/browser/modules/word/query/format-search.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Format-based Search for DOCX Documents
+ *
+ * Provides the ability to search for text runs that match specific formatting
+ * criteria (bold, italic, font, color, style, etc.) and optionally match text patterns.
+ *
+ * @stability experimental
+ *
+ * @example
+ * ```ts
+ * import { searchByFormat, type FormatCriteria } from "excelts/word";
+ *
+ * // Find all bold red text
+ * const results = searchByFormat(doc, { bold: true, color: "FF0000" });
+ *
+ * // Find all text in "Heading1" style
+ * const headings = searchByFormat(doc, { paragraphStyle: "Heading1" });
+ *
+ * // Find specific text with specific formatting
+ * const results = searchByFormat(doc, { bold: true, textMatch: /TODO/i });
+ * ```
+ */
+import type { DocxDocument, RunProperties } from "../types.js";
+/** Criteria for matching text formatting. All fields are optional — they act as AND filters. */
+export interface FormatCriteria {
+    /** Match bold text. */
+    readonly bold?: boolean;
+    /** Match italic text. */
+    readonly italic?: boolean;
+    /** Match underlined text (any style). */
+    readonly underline?: boolean;
+    /** Match strikethrough text. */
+    readonly strike?: boolean;
+    /** Match text with this font (case-insensitive). */
+    readonly font?: string;
+    /** Match text with this font size in half-points. */
+    readonly size?: number;
+    /** Match text with this color (hex, case-insensitive, without '#'). */
+    readonly color?: string;
+    /** Match text with this highlight color. */
+    readonly highlight?: string;
+    /** Match text with superscript. */
+    readonly superscript?: boolean;
+    /** Match text with subscript. */
+    readonly subscript?: boolean;
+    /** Match text with all-caps. */
+    readonly caps?: boolean;
+    /** Match text with small-caps. */
+    readonly smallCaps?: boolean;
+    /** Match text with hidden attribute. */
+    readonly hidden?: boolean;
+    /** Match runs whose paragraph has this style name/id. */
+    readonly paragraphStyle?: string;
+    /** Match runs with this character style name/id. */
+    readonly characterStyle?: string;
+    /** Optional text pattern (string or regex) to additionally filter by content. */
+    readonly textMatch?: string | RegExp;
+}
+/** A single format search result. */
+export interface FormatSearchResult {
+    /** Index in the document body (for BodyContent). */
+    readonly bodyIndex: number;
+    /** Paragraph index within the body content (for tables, the cell paragraph). */
+    readonly paragraphIndex: number;
+    /** Index of the matching run within the paragraph's children. */
+    readonly runIndex: number;
+    /** The matched text. */
+    readonly text: string;
+    /** The run's properties (formatting). */
+    readonly properties: RunProperties | undefined;
+    /** The paragraph style (if any). */
+    readonly paragraphStyle: string | undefined;
+    /** Location context for display. */
+    readonly location: "body" | "header" | "footer" | "footnote" | "endnote";
+}
+/**
+ * Search a document for text runs matching specific formatting criteria.
+ *
+ * @param doc - The document to search.
+ * @param criteria - Formatting criteria (all specified fields must match).
+ * @returns Array of matching results.
+ */
+export declare function searchByFormat(doc: DocxDocument, criteria: FormatCriteria): FormatSearchResult[];
+/**
+ * Count the number of runs matching specific formatting criteria.
+ *
+ * @param doc - The document to search.
+ * @param criteria - Formatting criteria.
+ * @returns The count of matching runs.
+ */
+export declare function countByFormat(doc: DocxDocument, criteria: FormatCriteria): number;
+/**
+ * Get all unique formatting styles used in the document.
+ * Useful for understanding what formats exist before searching.
+ *
+ * @param doc - The document to analyze.
+ * @returns Array of unique RunProperties objects found.
+ */
+export declare function getUsedFormats(doc: DocxDocument): RunProperties[];

package/dist/browser/modules/word/query/format-search.js

@@ -0,0 +1,329 @@
+/**
+ * Format-based Search for DOCX Documents
+ *
+ * Provides the ability to search for text runs that match specific formatting
+ * criteria (bold, italic, font, color, style, etc.) and optionally match text patterns.
+ *
+ * @stability experimental
+ *
+ * @example
+ * ```ts
+ * import { searchByFormat, type FormatCriteria } from "excelts/word";
+ *
+ * // Find all bold red text
+ * const results = searchByFormat(doc, { bold: true, color: "FF0000" });
+ *
+ * // Find all text in "Heading1" style
+ * const headings = searchByFormat(doc, { paragraphStyle: "Heading1" });
+ *
+ * // Find specific text with specific formatting
+ * const results = searchByFormat(doc, { bold: true, textMatch: /TODO/i });
+ * ```
+ */
+import { extractRunText } from "../core/text-utils.js";
+import { walkDocument } from "../core/walker.js";
+/**
+ * Search a document for text runs matching specific formatting criteria.
+ *
+ * @param doc - The document to search.
+ * @param criteria - Formatting criteria (all specified fields must match).
+ * @returns Array of matching results.
+ */
+export function searchByFormat(doc, criteria) {
+    const results = [];
+    let currentBodyIndex = 0;
+    let currentParaIndex = 0;
+    let currentParagraph = null;
+    let currentLocation = "body";
+    let tableDepth = 0;
+    const visitor = {
+        enterTable(_table, path) {
+            if (tableDepth === 0) {
+                currentBodyIndex = path.index;
+            }
+            tableDepth++;
+            currentParaIndex = 0;
+            return "continue";
+        },
+        leaveTable() {
+            tableDepth--;
+        },
+        enterParagraph(para, path) {
+            currentParagraph = para;
+            if (tableDepth === 0) {
+                currentBodyIndex = path.index;
+                currentParaIndex = 0;
+            }
+            if (path.inHeader) {
+                currentLocation = "header";
+            }
+            else if (path.inFooter) {
+                currentLocation = "footer";
+            }
+            else if (path.inFootnote) {
+                currentLocation = "footnote";
+            }
+            else if (path.inEndnote) {
+                currentLocation = "endnote";
+            }
+            else {
+                currentLocation = "body";
+            }
+            // If criteria specifies paragraphStyle, check it first
+            const paraStyle = para.properties?.style;
+            if (criteria.paragraphStyle && paraStyle !== criteria.paragraphStyle) {
+                return "skip";
+            }
+            return "continue";
+        },
+        leaveParagraph() {
+            if (tableDepth > 0) {
+                currentParaIndex++;
+            }
+        },
+        enterRun(run, path) {
+            if (matchesFormat(run, criteria)) {
+                const text = extractRunText(run);
+                if (matchesTextPattern(text, criteria.textMatch)) {
+                    results.push({
+                        bodyIndex: currentBodyIndex,
+                        paragraphIndex: currentParaIndex,
+                        runIndex: path.index,
+                        text,
+                        properties: run.properties,
+                        paragraphStyle: currentParagraph?.properties?.style,
+                        location: currentLocation
+                    });
+                }
+            }
+            return "skip";
+        },
+        enterHyperlink(hyperlink, path) {
+            // Search child runs of hyperlink
+            for (let li = 0; li < hyperlink.children.length; li++) {
+                const run = hyperlink.children[li];
+                if (matchesFormat(run, criteria)) {
+                    const text = extractRunText(run);
+                    if (matchesTextPattern(text, criteria.textMatch)) {
+                        results.push({
+                            bodyIndex: currentBodyIndex,
+                            paragraphIndex: currentParaIndex,
+                            runIndex: path.index,
+                            text,
+                            properties: run.properties,
+                            paragraphStyle: currentParagraph?.properties?.style,
+                            location: currentLocation
+                        });
+                    }
+                }
+            }
+            return "skip";
+        }
+    };
+    walkDocument(doc, visitor, {
+        includeHeaders: true,
+        includeFooters: true,
+        includeFootnotes: true,
+        includeEndnotes: true,
+        includeComments: false
+    });
+    return results;
+}
+/**
+ * Count the number of runs matching specific formatting criteria.
+ *
+ * @param doc - The document to search.
+ * @param criteria - Formatting criteria.
+ * @returns The count of matching runs.
+ */
+export function countByFormat(doc, criteria) {
+    return searchByFormat(doc, criteria).length;
+}
+/**
+ * Get all unique formatting styles used in the document.
+ * Useful for understanding what formats exist before searching.
+ *
+ * @param doc - The document to analyze.
+ * @returns Array of unique RunProperties objects found.
+ */
+export function getUsedFormats(doc) {
+    const formatSet = new Map();
+    const visitor = {
+        enterRun(run) {
+            if (run.properties) {
+                const key = formatKey(run.properties);
+                if (!formatSet.has(key)) {
+                    formatSet.set(key, run.properties);
+                }
+            }
+            return "skip";
+        },
+        enterHyperlink(hyperlink) {
+            for (const run of hyperlink.children) {
+                if (run.properties) {
+                    const key = formatKey(run.properties);
+                    if (!formatSet.has(key)) {
+                        formatSet.set(key, run.properties);
+                    }
+                }
+            }
+            return "skip";
+        }
+    };
+    walkDocument(doc, visitor, {
+        includeHeaders: false,
+        includeFooters: false,
+        includeFootnotes: false,
+        includeEndnotes: false,
+        includeComments: false
+    });
+    return Array.from(formatSet.values());
+}
+// =============================================================================
+// Internal Implementation
+// =============================================================================
+function matchesFormat(run, criteria) {
+    const props = run.properties;
+    // Character style check
+    if (criteria.characterStyle) {
+        if (props?.style !== criteria.characterStyle) {
+            return false;
+        }
+    }
+    // Bold
+    if (criteria.bold !== undefined) {
+        if ((props?.bold ?? false) !== criteria.bold) {
+            return false;
+        }
+    }
+    // Italic
+    if (criteria.italic !== undefined) {
+        if ((props?.italic ?? false) !== criteria.italic) {
+            return false;
+        }
+    }
+    // Underline. Word emits an explicit `"none"` underline style when the
+    // user clears underlining on a run (rather than removing the property
+    // entirely), so treat that the same as "no underline".
+    if (criteria.underline !== undefined) {
+        const u = props?.underline;
+        const hasUnderline = u !== undefined && u !== false && u !== "none";
+        if (hasUnderline !== criteria.underline) {
+            return false;
+        }
+    }
+    // Strikethrough
+    if (criteria.strike !== undefined) {
+        if ((props?.strike ?? false) !== criteria.strike) {
+            return false;
+        }
+    }
+    // Font
+    if (criteria.font) {
+        const runFont = getRunFontString(props);
+        if (!runFont || runFont.toLowerCase() !== criteria.font.toLowerCase()) {
+            return false;
+        }
+    }
+    // Size
+    if (criteria.size !== undefined) {
+        if (props?.size !== criteria.size) {
+            return false;
+        }
+    }
+    // Color
+    if (criteria.color) {
+        const runColor = getRunColor(props);
+        if (!runColor || runColor.toLowerCase() !== criteria.color.toLowerCase()) {
+            return false;
+        }
+    }
+    // Highlight
+    if (criteria.highlight) {
+        if (props?.highlight !== criteria.highlight) {
+            return false;
+        }
+    }
+    // Superscript
+    if (criteria.superscript !== undefined) {
+        const isSuperscript = props?.vertAlign === "superscript";
+        if (isSuperscript !== criteria.superscript) {
+            return false;
+        }
+    }
+    // Subscript
+    if (criteria.subscript !== undefined) {
+        const isSubscript = props?.vertAlign === "subscript";
+        if (isSubscript !== criteria.subscript) {
+            return false;
+        }
+    }
+    // Caps
+    if (criteria.caps !== undefined) {
+        if ((props?.caps ?? false) !== criteria.caps) {
+            return false;
+        }
+    }
+    // Small caps
+    if (criteria.smallCaps !== undefined) {
+        if ((props?.smallCaps ?? false) !== criteria.smallCaps) {
+            return false;
+        }
+    }
+    // Hidden
+    if (criteria.hidden !== undefined) {
+        if ((props?.vanish ?? false) !== criteria.hidden) {
+            return false;
+        }
+    }
+    return true;
+}
+function matchesTextPattern(text, pattern) {
+    if (!pattern) {
+        return true;
+    }
+    if (typeof pattern === "string") {
+        return text.includes(pattern);
+    }
+    // RegExp.test() advances `lastIndex` for /g and /y flags. Mutating the
+    // caller's regex would surprise code that re-uses the same instance
+    // afterwards, so we test against a fresh clone instead. The clone is
+    // cheap (V8 caches the parsed source) and sidesteps the global-state
+    // hazard entirely.
+    const cloned = new RegExp(pattern.source, pattern.flags);
+    return cloned.test(text);
+}
+function getRunFontString(props) {
+    if (!props?.font) {
+        return undefined;
+    }
+    if (typeof props.font === "string") {
+        return props.font;
+    }
+    return props.font.ascii ?? props.font.hAnsi;
+}
+function getRunColor(props) {
+    if (!props?.color) {
+        return undefined;
+    }
+    if (typeof props.color === "string") {
+        return props.color;
+    }
+    return props.color.val;
+}
+function formatKey(props) {
+    return JSON.stringify({
+        bold: props.bold,
+        italic: props.italic,
+        underline: props.underline ? true : undefined,
+        strike: props.strike,
+        font: typeof props.font === "string" ? props.font : props.font?.ascii,
+        size: props.size,
+        color: typeof props.color === "string" ? props.color : props.color?.val,
+        highlight: props.highlight,
+        vertAlign: props.vertAlign,
+        caps: props.caps,
+        smallCaps: props.smallCaps,
+        style: props.style
+    });
+}