@cj-tech-master/excelts 9.5.4 → 9.5.5

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

@@ -0,0 +1,129 @@
+/**
+ * Document Search & Query API (read-only helpers)
+ *
+ * Functions for searching, counting, and extracting text from a DocxDocument.
+ */
+import type { DocxDocument, Paragraph, Table, Hyperlink, BookmarkStart, CommentDef, ImageDef, SectionProperties } from "../types.js";
+/** Result of a text search in a document. */
+export interface SearchResult {
+    /**
+     * The paragraph's visit order across the entire document, counting
+     * paragraphs reachable from the body (including those nested in tables,
+     * SDTs, text boxes, headers, footers, footnotes, endnotes and TOC
+     * caches) in walk order.
+     *
+     * This is **not** an index into `doc.body`: nested paragraphs are
+     * counted too. Use it as a stable ordinal for ordering results, not
+     * for direct array access.
+     */
+    readonly paragraphIndex: number;
+    /** The matched text. */
+    readonly match: string;
+    /** Character offset within the paragraph's concatenated text. */
+    readonly offset: number;
+}
+/** A heading extracted from a document. */
+export interface DocumentHeading {
+    /** Heading level (1-9). */
+    readonly level: number;
+    /** Plain text of the heading. */
+    readonly text: string;
+    /** Index into doc.body where the paragraph resides. */
+    readonly paragraphIndex: number;
+    /** Style ID used (e.g. "Heading1"). */
+    readonly style?: string;
+}
+/** A section definition found in the document. */
+export interface DocumentSection {
+    /** The section properties. */
+    readonly properties: SectionProperties;
+    /** Index of the paragraph containing this section break (or -1 for the final section). */
+    readonly paragraphIndex: number;
+    /** Whether this is the final section (from doc.sectionProperties). */
+    readonly isFinal: boolean;
+}
+/** Extract concatenated plain text from a paragraph's runs. */
+export declare function paragraphText(para: Paragraph): string;
+/**
+ * Count all top-level paragraphs in the document body.
+ */
+export declare function paragraphCount(doc: DocxDocument): number;
+/**
+ * Count words across all paragraphs in the document body.
+ * Uses simple whitespace splitting; for East Asian text, each CJK character
+ * is counted as one "word" to approximate meaningful unit count.
+ */
+export declare function countWords(doc: DocxDocument): number;
+/**
+ * Extract the heading outline from a document.
+ *
+ * Matches paragraphs whose style is `Heading1` through `Heading9` (case-insensitive),
+ * or whose `outlineLevel` property is set (0-8).
+ */
+export declare function getHeadings(doc: DocxDocument): DocumentHeading[];
+/**
+ * Find a bookmark by name.
+ *
+ * @returns The bookmark start marker + its location, or `undefined` if not found.
+ */
+export declare function findBookmark(doc: DocxDocument, name: string): {
+    bookmark: BookmarkStart;
+    paragraphIndex: number;
+    childIndex: number;
+} | undefined;
+/**
+ * Find a comment by its ID.
+ */
+export declare function findComment(doc: DocxDocument, id: number): CommentDef | undefined;
+/**
+ * List all images registered in the document.
+ */
+export declare function listImages(doc: DocxDocument): readonly ImageDef[];
+/**
+ * List all tables in the document.
+ *
+ * By default this returns **all** tables in the document body (including
+ * tables nested inside other tables, SDTs, text boxes, and TOC cached
+ * paragraphs). For top-level only behavior pass `{ topLevelOnly: true }`.
+ *
+ * @example
+ * listTables(doc)                          // all tables (consistent with tableCount)
+ * listTables(doc, { topLevelOnly: true })  // direct children of body only
+ */
+export declare function listTables(doc: DocxDocument, options?: {
+    readonly topLevelOnly?: boolean;
+}): readonly Table[];
+/**
+ * Collect all hyperlinks in the document body.
+ */
+export declare function listHyperlinks(doc: DocxDocument): readonly Hyperlink[];
+/**
+ * Get the total number of tables (top-level) and nested tables.
+ */
+export declare function tableCount(doc: DocxDocument): number;
+/**
+ * List all sections in a document.
+ *
+ * Sections are defined by section breaks within paragraph properties
+ * and the final section at the document level.
+ *
+ * @param doc - The document to inspect.
+ * @returns Array of section definitions in document order.
+ */
+export declare function listSections(doc: DocxDocument): DocumentSection[];
+/**
+ * Extract plain text from the entire document: body, headers, footers,
+ * footnotes, and endnotes.
+ *
+ * Paragraphs are separated by `\n`. Tables render as tab-separated cell text.
+ */
+export declare function extractText(doc: DocxDocument): string;
+/**
+ * Search for text occurrences across the entire document: body, tables, SDTs,
+ * headers, footers, footnotes, and endnotes.
+ *
+ * @param doc - The document model to search.
+ * @param query - String or RegExp to search for.
+ * @returns Array of search results.
+ */
+export declare function searchText(doc: DocxDocument, query: string | RegExp): SearchResult[];

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

@@ -0,0 +1,346 @@
+/**
+ * Document Search & Query API (read-only helpers)
+ *
+ * Functions for searching, counting, and extracting text from a DocxDocument.
+ */
+import { extractParagraphText } from "../core/text-utils.js";
+import { walkDocument } from "../core/walker.js";
+// =============================================================================
+// Helpers
+// =============================================================================
+/** Extract concatenated plain text from a paragraph's runs. */
+export function paragraphText(para) {
+    return extractParagraphText(para);
+}
+// =============================================================================
+// Public API
+// =============================================================================
+/**
+ * Count all top-level paragraphs in the document body.
+ */
+export function paragraphCount(doc) {
+    let count = 0;
+    for (const block of doc.body) {
+        if (block.type === "paragraph") {
+            count++;
+        }
+    }
+    return count;
+}
+/**
+ * Count words across all paragraphs in the document body.
+ * Uses simple whitespace splitting; for East Asian text, each CJK character
+ * is counted as one "word" to approximate meaningful unit count.
+ */
+export function countWords(doc) {
+    let count = 0;
+    const cjkRe = /[\u4e00-\u9fff\u3040-\u30ff\uac00-\ud7af]/g;
+    const visitor = {
+        enterParagraph(para) {
+            const text = paragraphText(para);
+            const cjkCount = (text.match(cjkRe) ?? []).length;
+            const latin = text.replace(cjkRe, " ").trim();
+            const latinCount = latin ? latin.split(/\s+/).length : 0;
+            count += cjkCount + latinCount;
+            return "skip";
+        }
+    };
+    walkDocument(doc, visitor, {
+        includeHeaders: false,
+        includeFooters: false,
+        includeFootnotes: false,
+        includeEndnotes: false,
+        includeComments: false
+    });
+    return count;
+}
+/**
+ * Extract the heading outline from a document.
+ *
+ * Matches paragraphs whose style is `Heading1` through `Heading9` (case-insensitive),
+ * or whose `outlineLevel` property is set (0-8).
+ */
+export function getHeadings(doc) {
+    const out = [];
+    doc.body.forEach((block, i) => {
+        if (block.type !== "paragraph") {
+            return;
+        }
+        const style = block.properties?.style;
+        const styleMatch = style ? /^Heading\s*(\d)$/i.exec(style) : null;
+        let level;
+        if (styleMatch) {
+            level = parseInt(styleMatch[1], 10);
+        }
+        else if (block.properties?.outlineLevel !== undefined && block.properties.outlineLevel < 9) {
+            level = block.properties.outlineLevel + 1;
+        }
+        if (level !== undefined && level >= 1 && level <= 9) {
+            out.push({
+                level,
+                text: paragraphText(block),
+                paragraphIndex: i,
+                style
+            });
+        }
+    });
+    return out;
+}
+/**
+ * Find a bookmark by name.
+ *
+ * @returns The bookmark start marker + its location, or `undefined` if not found.
+ */
+export function findBookmark(doc, name) {
+    for (let i = 0; i < doc.body.length; i++) {
+        const block = doc.body[i];
+        if (block.type !== "paragraph") {
+            continue;
+        }
+        for (let j = 0; j < block.children.length; j++) {
+            const ch = block.children[j];
+            if ("type" in ch && ch.type === "bookmarkStart" && ch.name === name) {
+                return { bookmark: ch, paragraphIndex: i, childIndex: j };
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Find a comment by its ID.
+ */
+export function findComment(doc, id) {
+    return doc.comments?.find(c => c.id === id);
+}
+/**
+ * List all images registered in the document.
+ */
+export function listImages(doc) {
+    return doc.images ?? [];
+}
+/**
+ * List all tables in the document.
+ *
+ * By default this returns **all** tables in the document body (including
+ * tables nested inside other tables, SDTs, text boxes, and TOC cached
+ * paragraphs). For top-level only behavior pass `{ topLevelOnly: true }`.
+ *
+ * @example
+ * listTables(doc)                          // all tables (consistent with tableCount)
+ * listTables(doc, { topLevelOnly: true })  // direct children of body only
+ */
+export function listTables(doc, options) {
+    if (options?.topLevelOnly) {
+        return doc.body.filter((b) => b.type === "table");
+    }
+    const out = [];
+    walkDocument(doc, {
+        enterTable(t) {
+            out.push(t);
+            return "continue";
+        }
+    }, {
+        includeHeaders: false,
+        includeFooters: false,
+        includeFootnotes: false,
+        includeEndnotes: false
+    });
+    return out;
+}
+/**
+ * Collect all hyperlinks in the document body.
+ */
+export function listHyperlinks(doc) {
+    const out = [];
+    walkDocument(doc, {
+        enterHyperlink(hl) {
+            out.push(hl);
+            return "continue";
+        }
+    }, {
+        includeHeaders: false,
+        includeFooters: false,
+        includeFootnotes: false,
+        includeEndnotes: false
+    });
+    return out;
+}
+/**
+ * Get the total number of tables (top-level) and nested tables.
+ */
+export function tableCount(doc) {
+    let count = 0;
+    const visitor = {
+        enterTable() {
+            count++;
+            return "continue";
+        }
+    };
+    walkDocument(doc, visitor, {
+        includeHeaders: false,
+        includeFooters: false,
+        includeFootnotes: false,
+        includeEndnotes: false,
+        includeComments: false
+    });
+    return count;
+}
+/**
+ * List all sections in a document.
+ *
+ * Sections are defined by section breaks within paragraph properties
+ * and the final section at the document level.
+ *
+ * @param doc - The document to inspect.
+ * @returns Array of section definitions in document order.
+ */
+export function listSections(doc) {
+    const sections = [];
+    for (let i = 0; i < doc.body.length; i++) {
+        const block = doc.body[i];
+        if (block.type === "paragraph" && block.properties?.sectionProperties) {
+            sections.push({
+                properties: block.properties.sectionProperties,
+                paragraphIndex: i,
+                isFinal: false
+            });
+        }
+    }
+    // Add final section
+    if (doc.sectionProperties) {
+        sections.push({
+            properties: doc.sectionProperties,
+            paragraphIndex: -1,
+            isFinal: true
+        });
+    }
+    return sections;
+}
+/**
+ * Extract plain text from the entire document: body, headers, footers,
+ * footnotes, and endnotes.
+ *
+ * Paragraphs are separated by `\n`. Tables render as tab-separated cell text.
+ */
+export function extractText(doc) {
+    const lines = [];
+    const stack = [];
+    const visitor = {
+        enterTable() {
+            stack.push({ rowCellTexts: [], cellLines: [], tableLines: [] });
+            return "continue";
+        },
+        leaveTable() {
+            const frame = stack.pop();
+            // Contribute this table's collected lines to parent context
+            if (stack.length > 0) {
+                // Inside an outer cell — add table lines to the outer cell
+                const parent = stack[stack.length - 1];
+                for (const line of frame.tableLines) {
+                    parent.cellLines.push(line);
+                }
+            }
+            else {
+                // Top-level: add directly to output lines
+                for (const line of frame.tableLines) {
+                    lines.push(line);
+                }
+            }
+        },
+        enterTableRow() {
+            if (stack.length > 0) {
+                stack[stack.length - 1].rowCellTexts = [];
+            }
+            return "continue";
+        },
+        leaveTableRow() {
+            if (stack.length > 0) {
+                const frame = stack[stack.length - 1];
+                frame.tableLines.push(frame.rowCellTexts.join("\t"));
+            }
+        },
+        enterTableCell() {
+            if (stack.length > 0) {
+                stack[stack.length - 1].cellLines = [];
+            }
+            return "continue";
+        },
+        leaveTableCell() {
+            if (stack.length > 0) {
+                const frame = stack[stack.length - 1];
+                frame.rowCellTexts.push(frame.cellLines.join(" "));
+            }
+        },
+        enterParagraph(para) {
+            const text = paragraphText(para);
+            if (stack.length > 0) {
+                stack[stack.length - 1].cellLines.push(text);
+            }
+            else {
+                lines.push(text);
+            }
+            return "skip";
+        }
+    };
+    walkDocument(doc, visitor, {
+        includeHeaders: true,
+        includeFooters: true,
+        includeFootnotes: true,
+        includeEndnotes: true,
+        includeComments: false
+    });
+    return lines.join("\n");
+}
+/**
+ * Search for text occurrences across the entire document: body, tables, SDTs,
+ * headers, footers, footnotes, and endnotes.
+ *
+ * @param doc - The document model to search.
+ * @param query - String or RegExp to search for.
+ * @returns Array of search results.
+ */
+export function searchText(doc, query) {
+    const results = [];
+    let idx = 0;
+    const visitor = {
+        enterParagraph(para) {
+            const text = paragraphText(para);
+            if (typeof query === "string") {
+                // Empty query would loop forever; treat it as "no match".
+                if (query.length === 0) {
+                    idx++;
+                    return "skip";
+                }
+                let pos = text.indexOf(query);
+                while (pos !== -1) {
+                    results.push({ paragraphIndex: idx, match: query, offset: pos });
+                    pos = text.indexOf(query, pos + query.length);
+                }
+            }
+            else {
+                // Strip the sticky flag — it would constrain matching to lastIndex
+                // and silently miss occurrences elsewhere in the paragraph text.
+                const baseFlags = query.flags.replace(/y/g, "");
+                const re = new RegExp(query.source, baseFlags.includes("g") ? baseFlags : baseFlags + "g");
+                let m;
+                while ((m = re.exec(text)) !== null) {
+                    results.push({ paragraphIndex: idx, match: m[0], offset: m.index });
+                    // Advance past zero-width matches to prevent infinite loops.
+                    if (m[0].length === 0) {
+                        re.lastIndex++;
+                    }
+                }
+            }
+            idx++;
+            return "skip";
+        }
+    };
+    walkDocument(doc, visitor, {
+        includeHeaders: true,
+        includeFooters: true,
+        includeFootnotes: true,
+        includeEndnotes: true,
+        includeComments: false
+    });
+    return results;
+}

package/dist/browser/modules/word/query/split.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Document Split API
+ *
+ * Split a single DocxDocument into multiple documents based on
+ * sections, page breaks, or heading levels.
+ */
+import type { DocxDocument } from "../types.js";
+/** Options for splitting a document. */
+export interface SplitOptions {
+    /**
+     * Split criteria.
+     *
+     * - `"section"` — split at every section break (paragraph with `sectionProperties`).
+     * - `"pageBreak"` — split at every explicit page break (run with `breakType: "page"`).
+     * - `"heading"` — split at every Heading 1 paragraph (or `headingLevel`).
+     *
+     * Default: `"section"`.
+     */
+    readonly by?: "section" | "pageBreak" | "heading";
+    /**
+     * Heading level to split on (only used when `by: "heading"`).
+     * Default: 1 (Heading 1).
+     */
+    readonly headingLevel?: number;
+    /**
+     * Whether each split document keeps the original document's
+     * styles, numbering, settings, fonts, etc.
+     * Default: true.
+     */
+    readonly preserveSharedParts?: boolean;
+}
+/**
+ * Split a DocxDocument into multiple documents.
+ *
+ * Each resulting document is a complete, valid DocxDocument with body content
+ * from one segment of the original. Headers, footers, footnotes, endnotes,
+ * comments, styles, numbering, and settings are preserved in each split unless
+ * `preserveSharedParts: false` is specified.
+ *
+ * @param doc - The document to split.
+ * @param options - Split criteria.
+ * @returns Array of split documents (at least 1).
+ */
+export declare function splitDocument(doc: DocxDocument, options?: SplitOptions): DocxDocument[];

package/dist/browser/modules/word/query/split.js

@@ -0,0 +1,135 @@
+/**
+ * Document Split API
+ *
+ * Split a single DocxDocument into multiple documents based on
+ * sections, page breaks, or heading levels.
+ */
+import { isRun } from "../core/text-utils.js";
+/**
+ * Split a DocxDocument into multiple documents.
+ *
+ * Each resulting document is a complete, valid DocxDocument with body content
+ * from one segment of the original. Headers, footers, footnotes, endnotes,
+ * comments, styles, numbering, and settings are preserved in each split unless
+ * `preserveSharedParts: false` is specified.
+ *
+ * @param doc - The document to split.
+ * @param options - Split criteria.
+ * @returns Array of split documents (at least 1).
+ */
+export function splitDocument(doc, options) {
+    const opts = {
+        by: options?.by ?? "section",
+        headingLevel: options?.headingLevel ?? 1,
+        preserveSharedParts: options?.preserveSharedParts ?? true
+    };
+    const segments = splitBody(doc.body, opts);
+    if (segments.length === 0) {
+        return [doc];
+    }
+    return segments.map(segment => buildSplitDoc(doc, segment, opts));
+}
+// =============================================================================
+// Internal
+// =============================================================================
+/**
+ * Split the body into segments based on the split criteria.
+ * Returns an array of segments; each segment is an array of body content blocks.
+ */
+function splitBody(body, opts) {
+    const segments = [];
+    let current = [];
+    for (const block of body) {
+        if (shouldSplitBefore(block, opts)) {
+            // Heading-based split or pageBreakBefore: start a new segment BEFORE this block
+            if (current.length > 0) {
+                segments.push(current);
+            }
+            current = [block];
+        }
+        else {
+            current.push(block);
+            if (shouldSplitAfter(block, opts)) {
+                segments.push(current);
+                current = [];
+            }
+        }
+    }
+    if (current.length > 0) {
+        segments.push(current);
+    }
+    return segments;
+}
+function shouldSplitBefore(block, opts) {
+    if (block.type !== "paragraph") {
+        return false;
+    }
+    if (opts.by === "heading") {
+        return isHeadingLevel(block, opts.headingLevel);
+    }
+    if (opts.by === "pageBreak") {
+        // pageBreakBefore semantically means "this paragraph starts on a new page".
+        // Only the explicit run page break stays as an "after" split.
+        return block.properties?.pageBreakBefore === true;
+    }
+    return false;
+}
+function shouldSplitAfter(block, opts) {
+    if (block.type !== "paragraph") {
+        return false;
+    }
+    if (opts.by === "section") {
+        return block.properties?.sectionProperties !== undefined;
+    }
+    if (opts.by === "pageBreak") {
+        return paragraphHasExplicitPageBreakRun(block);
+    }
+    return false;
+}
+function isHeadingLevel(para, level) {
+    const props = para.properties;
+    // outlineLevel mirrors getHeadings()'s detection: outlineLevel 0 == H1,
+    // outlineLevel 1 == H2, etc. Levels >= 9 mean "body text" and should not
+    // qualify as headings.
+    if (props?.outlineLevel !== undefined && props.outlineLevel < 9) {
+        if (props.outlineLevel + 1 === level) {
+            return true;
+        }
+    }
+    const style = props?.style;
+    if (!style) {
+        return false;
+    }
+    // Common heading style IDs: "Heading1", "heading 1", "Heading%i", etc.
+    const target = String(level);
+    const normalized = style.replace(/\s+/g, "").toLowerCase();
+    return (normalized === `heading${target}` ||
+        normalized === `h${target}` ||
+        normalized === `title${target}`);
+}
+function paragraphHasExplicitPageBreakRun(para) {
+    for (const child of para.children) {
+        if (isRun(child)) {
+            for (const c of child.content) {
+                if (c.type === "break" && c.breakType === "page") {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+function buildSplitDoc(source, segment, opts) {
+    if (!opts.preserveSharedParts) {
+        // Minimal split: just body + docType
+        return {
+            docType: source.docType,
+            body: segment
+        };
+    }
+    // Full split: preserve all shared parts
+    return {
+        ...source,
+        body: segment
+    };
+}