@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/types/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/types/modules/word/query/mail-merge.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Mail Merge API
+ *
+ * Replace MERGEFIELD fields in a document with values from a data map.
+ * Uses the unified walker from core/walker.ts for consistent traversal
+ * across body, headers, footers, footnotes, endnotes, tables, and SDTs.
+ *
+ * Note: This API mutates the document in place for backward compatibility.
+ */
+import type { DocxDocument } from "../types.js";
+/**
+ * Execute a mail merge: replace all MERGEFIELD fields in the document with values from the data map.
+ *
+ * Fields not found in the data map are left unchanged (or optionally cleared).
+ * Traverses body, headers, footers, footnotes, endnotes, tables, SDTs, and comments.
+ *
+ * @param doc - The document to modify (mutated in place).
+ * @param data - Map of field names to replacement values.
+ * @param options - Optional settings.
+ * @returns The number of fields replaced.
+ */
+export declare function mailMerge(doc: DocxDocument, data: Record<string, string>, options?: {
+    /** If true, remove fields not found in data. Default: false (leave unchanged). */
+    removeUnmatched?: boolean;
+}): number;

package/dist/types/modules/word/query/merge.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Document Merge API
+ *
+ * Merge multiple DocxDocument bodies into a single document.
+ *
+ * The first document is taken as the base (its styles, settings, page layout,
+ * etc. become the foundation). Each subsequent document is appended after a
+ * section break. Numbering definitions, instances and the body references
+ * that point to them are rewritten when the appended document collides with
+ * IDs already present in the base. Image rIds, footnote/endnote ids and
+ * comment ids are also remapped, and the corresponding parts (footnotes,
+ * endnotes, comments) are merged so that references emitted in the body
+ * still resolve.
+ *
+ * What is *not* merged today (callers needing these should compose at a
+ * higher level):
+ *   - headers / footers (only the base document's are kept; appended
+ *     documents' header/footer parts are dropped)
+ *   - customXmlParts, embeddedFonts, settings, coreProperties, app
+ *     metadata, theme, document protection, signatures, vbaProject
+ *
+ * Body content from appended documents is deep-cloned so that callers'
+ * models are never mutated.
+ */
+import type { DocxDocument } from "../types.js";
+/** Options for merging documents. */
+export interface MergeOptions {
+    /** Break type between merged documents. Default: "nextPage". */
+    readonly sectionBreak?: "continuous" | "nextPage" | "evenPage" | "oddPage";
+}
+/**
+ * Merge multiple DocxDocument bodies into a single document.
+ *
+ * The first document is used as the base (preserving its styles, numbering,
+ * settings, etc.). Subsequent documents' body content is appended with
+ * section breaks between them. IDs that collide with the base are remapped
+ * during the deep-clone of each appended body:
+ *   - paragraph numbering refs (numId)
+ *   - inline / floating image rIds
+ *   - footnote, endnote and comment references (and their range markers)
+ *
+ * The corresponding `footnotes`, `endnotes`, `comments` and `images`
+ * collections are merged in tandem so references emitted into the body
+ * still resolve in the output package.
+ *
+ * @param documents - Array of documents to merge (at least 1).
+ * @param options - Optional merge settings.
+ * @returns A new merged DocxDocument.
+ */
+export declare function mergeDocuments(documents: readonly DocxDocument[], options?: MergeOptions): DocxDocument;

package/dist/types/modules/word/query/replace.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Document Replace API
+ *
+ * Uses the unified walker from core/walker.ts for consistent traversal
+ * across body, headers, footers, footnotes, endnotes, comments, and SDTs.
+ *
+ * Note: This API mutates the document in place for backward compatibility.
+ *
+ * Implementation notes:
+ *   We always operate on the paragraph's concatenated plain text and the
+ *   ordered list of text-bearing run-content nodes ("text segments").
+ *   This guarantees consistent semantics regardless of whether matches sit
+ *   inside a single run or straddle multiple runs:
+ *     1. Build segment table [seg0, seg1, ...] with absolute offsets.
+ *     2. Compute every match using a global regex (string searches are
+ *        promoted to a global regex with the literal escaped).
+ *     3. Walk segments and matches together. For each segment we emit:
+ *        - the literal (un-matched) prefix/middle/suffix slices, and
+ *        - the replacement string the first time we see each match.
+ *      Subsequent segments overlapping the same match contribute the empty
+ *      string (so the replacement is not duplicated) but otherwise keep
+ *      their original formatting (RunProperties remain on the parent run).
+ *   The returned count equals the number of matches actually replaced.
+ */
+import type { DocxDocument } from "../types.js";
+/**
+ * Replace text in a document (mutates in place).
+ *
+ * Performs document-wide text replacement within run content. Matches are
+ * applied uniformly whether they fall inside a single run or span several
+ * runs; the formatting of each run that survives the replacement is preserved.
+ *
+ * Traverses body, headers, footers, footnotes, endnotes, comments, tables, and
+ * SDTs using the unified document walker. SDTs may carry inline runs without
+ * an enclosing paragraph (content controls wrapping a single Run); those
+ * inline runs are treated as a single virtual paragraph for replacement.
+ *
+ * @param doc - The document model to modify (mutated in place).
+ * @param search - String or RegExp to find. Both are treated as global
+ *                 (every occurrence is replaced); the `g` flag on a RegExp
+ *                 is therefore optional.
+ * @param replacement - Replacement string. When `search` is a RegExp the
+ *                      replacement supports the standard `$1`/`$&`/`$$` etc.
+ *                      backreferences.
+ * @returns The exact number of replacements made.
+ */
+export declare function replaceText(doc: DocxDocument, search: string | RegExp, replacement: string): number;

package/dist/types/modules/word/query/revisions.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Track Changes — Accept / Reject API
+ *
+ * Functions for accepting or rejecting tracked changes in a DocxDocument.
+ */
+import type { DocxDocument } from "../types.js";
+/**
+ * Accept all tracked changes in a document (mutates in place).
+ *
+ * - Inserted runs: their content is kept, the `InsertedRun` wrapper is removed.
+ * - Deleted runs: their content is removed entirely.
+ * - Moved content: moved-to content is kept, moved-from is removed.
+ * - Property changes: the new properties are kept, change info is removed.
+ *
+ * @param doc - The document to modify (mutated in place).
+ * @returns Number of revisions accepted.
+ */
+export declare function acceptAllRevisions(doc: DocxDocument): number;
+/**
+ * Reject all tracked changes in a document (mutates in place).
+ *
+ * - Inserted runs: removed entirely (content was not in original).
+ * - Deleted runs: their content is kept (restoring original text).
+ * - Moved content: moved-from content is kept, moved-to is removed.
+ *
+ * @param doc - The document to modify (mutated in place).
+ * @returns Number of revisions rejected.
+ */
+export declare function rejectAllRevisions(doc: DocxDocument): number;
+/** A revision found in the document, with its location and metadata. */
+export interface RevisionEntry {
+    /** Unique revision id (from w:ins/w:del/w:moveFrom/w:moveTo @id). */
+    readonly id: number;
+    /** Revision type. */
+    readonly type: "insert" | "delete" | "moveFrom" | "moveTo" | "rowInsert" | "rowDelete" | "cellMerge" | "tablePropertyChange" | "rowPropertyChange" | "cellPropertyChange" | "paragraphPropertyChange" | "runPropertyChange";
+    /** Author of the revision. */
+    readonly author?: string;
+    /** Date of the revision (ISO 8601 string). */
+    readonly date?: string;
+}
+/**
+ * List all tracked changes in a document.
+ *
+ * Walks the document body, headers, footers, footnotes, endnotes, and comments
+ * collecting all `RevisionInfo`-bearing nodes (insertions, deletions, moves,
+ * property changes).
+ *
+ * @param doc - The document to scan.
+ * @returns Array of revision entries.
+ */
+export declare function listRevisions(doc: DocxDocument): RevisionEntry[];
+/**
+ * Accept a single revision by id (mutates in place).
+ *
+ * @param doc - The document to modify.
+ * @param revisionId - The revision id to accept.
+ * @returns true if the revision was found and accepted, false otherwise.
+ */
+export declare function acceptRevision(doc: DocxDocument, revisionId: number): boolean;
+/**
+ * Reject a single revision by id (mutates in place).
+ *
+ * @param doc - The document to modify.
+ * @param revisionId - The revision id to reject.
+ * @returns true if the revision was found and rejected, false otherwise.
+ */
+export declare function rejectRevision(doc: DocxDocument, revisionId: number): boolean;

package/dist/types/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/types/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/types/modules/word/query/style-resolve.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Style Resolution (Effective/Computed Style)
+ *
+ * Resolve the effective style for a paragraph by walking the style inheritance chain.
+ */
+import type { DocxDocument, Paragraph, ParagraphProperties, Run, RunProperties, TableLook, TableProperties } from "../types.js";
+/** Context for style resolution when a paragraph is inside a table. */
+export interface StyleResolveContext {
+    /** If the paragraph is inside a table, provide table context. */
+    readonly tableContext?: {
+        readonly tableStyleId?: string;
+        readonly tblLook?: TableLook;
+        readonly rowIndex: number;
+        readonly colIndex: number;
+        readonly totalRows: number;
+        readonly totalCols: number;
+    };
+}
+/** Resolved paragraph properties with all inherited values merged. */
+export interface ResolvedParagraphStyle {
+    /** The style chain (from most specific to base). */
+    readonly chain: readonly string[];
+    /** Merged paragraph properties (inherited + own). */
+    readonly paragraphProperties: ParagraphProperties;
+    /** Merged run properties (inherited + own). */
+    readonly runProperties: RunProperties;
+}
+/**
+ * Resolve the effective (computed) style for a paragraph by walking the style inheritance chain.
+ *
+ * Merges properties from the document defaults → base style chain → table conditional formats → paragraph's own properties.
+ *
+ * @param doc - The document containing styles and defaults.
+ * @param para - The paragraph to resolve styles for.
+ * @param context - Optional context providing table position for conditional format overlay.
+ * @returns The fully resolved paragraph style with all inherited properties merged.
+ */
+export declare function resolveStyle(doc: DocxDocument, para: Paragraph, context?: StyleResolveContext): ResolvedParagraphStyle;
+/** Resolved run style with full inheritance chain. */
+export interface ResolvedRunStyle {
+    /** Style chain (most specific → base). */
+    readonly chain: readonly string[];
+    /** Merged run properties. */
+    readonly runProperties: RunProperties;
+}
+/**
+ * Resolve the effective style for a single Run by walking the character
+ * style inheritance chain.
+ *
+ * Resolution order (low → high specificity):
+ * 1. Document defaults
+ * 2. Paragraph's resolved style (if `paragraphRunProperties` provided)
+ * 3. Run's character style chain (if `run.properties.style` is set)
+ * 4. Run's own direct properties
+ *
+ * @param doc - The document containing styles.
+ * @param run - The run to resolve.
+ * @param paragraphRunProperties - Optional inherited run properties from the
+ *   parent paragraph's resolved style. Pass `resolveStyle(doc, para).runProperties`
+ *   to layer the paragraph style on top of doc defaults.
+ * @returns The fully resolved run style.
+ */
+export declare function resolveRunStyle(doc: DocxDocument, run: Run, paragraphRunProperties?: RunProperties): ResolvedRunStyle;
+/** Resolved numbering level information. */
+export interface ResolvedNumberingLevel {
+    /** The level index (0-8). */
+    readonly level: number;
+    /** Number format. */
+    readonly format?: string;
+    /** Level text template (e.g. `"%1."`). */
+    readonly text?: string;
+    /** Justification. */
+    readonly justification?: string;
+    /** Run properties for the numbering text itself (bullet/number marker). */
+    readonly runProperties?: RunProperties;
+    /** Paragraph properties from the level (indent, alignment, etc.). */
+    readonly paragraphProperties?: ParagraphProperties;
+}
+/**
+ * Resolve the numbering level for a paragraph that has a numbering reference.
+ *
+ * Walks: paragraph.numbering → numberingInstances → abstractNumberings → level definition.
+ * Also applies `LevelOverride` if present.
+ *
+ * @param doc - The document.
+ * @param para - The paragraph (must have `numbering` set).
+ * @returns The resolved level, or undefined if no numbering or level not found.
+ */
+export declare function resolveNumberingLevel(doc: DocxDocument, para: Paragraph): ResolvedNumberingLevel | undefined;
+/**
+ * Resolve table-level styles for a given table.
+ *
+ * Walks the table style inheritance chain (basedOn) to merge table properties.
+ *
+ * @param doc - The document.
+ * @param tableStyleId - The starting table style ID.
+ * @returns The merged table-level style chain.
+ */
+export declare function resolveTableStyle(doc: DocxDocument, tableStyleId: string): {
+    chain: string[];
+    paragraphProperties: ParagraphProperties;
+    runProperties: RunProperties;
+    tableProperties?: TableProperties;
+};

package/dist/types/modules/word/reader/chart-parser.d.ts

@@ -0,0 +1,20 @@
+/**
+ * DOCX Reader - Chart Parser (c: and cx: namespaces)
+ *
+ * Parses traditional and ChartEx (Microsoft 365) chart XML into Chart model
+ * objects. Also resolves chart references in the document body, replacing
+ * opaque chart drawings with parsed Chart instances.
+ */
+import type { BodyContent, Chart, ChartExContent, ChartExData } from "../types.js";
+/** Replace OpaqueDrawing items referencing chart rIds with ChartContent. */
+declare function replaceOpaqueCharts(body: BodyContent[], chartRIdToChart: Map<string, Chart>): void;
+/** Replace OpaqueDrawing items referencing ChartEx rIds with ChartExContent. */
+declare function replaceOpaqueChartExDrawings(body: BodyContent[], chartExRIdToContent: Map<string, ChartExContent>): void;
+/** Parse a chart part XML string into a Chart object. */
+declare function parseChartXml(xmlStr: string): Chart | undefined;
+/**
+ * Parse a ChartEx XML string (cx:chartSpace) into structured ChartExData.
+ * Returns undefined if parsing fails or the structure is unrecognizable.
+ */
+declare function parseChartExXml(xmlStr: string): ChartExData | undefined;
+export { replaceOpaqueCharts, replaceOpaqueChartExDrawings, parseChartXml, parseChartExXml };

package/dist/types/modules/word/reader/comments-parser.d.ts

@@ -0,0 +1,26 @@
+/**
+ * DOCX reader — comments parsers.
+ *
+ * Split out from `docx-reader.ts` to keep that file's part-orchestration
+ * scope manageable. We accept `parseParagraph` as an injected dependency
+ * because the body paragraph parser still lives in `docx-reader.ts` (it
+ * has many cross-references that would not be cheap to disentangle); a
+ * direct import would form a cycle.
+ */
+import type { XmlElement } from "../../xml/types.js";
+import type { CommentDef, Paragraph } from "../types.js";
+import { type ReaderContext } from "./reader-context.js";
+/** Parse `word/comments.xml` into a list of CommentDef. */
+export declare function parseCommentsXml(xmlStr: string, ctx: ReaderContext, parseParagraph: (el: XmlElement, ctx: ReaderContext) => Paragraph): CommentDef[];
+/**
+ * Parse `word/commentsExtended.xml` into a paraId → metadata map.
+ *
+ * Modern Word stores comment "resolved" state and reply threading in a
+ * sidecar part keyed by the paragraph id of each comment's first
+ * paragraph. The reader merges this map into `CommentDef.done` /
+ * `CommentDef.parentId` once both parts have been parsed.
+ */
+export declare function parseCommentsExtendedXml(xmlStr: string): Map<string, {
+    done?: boolean;
+    parentId?: string;
+}>;

package/dist/types/modules/word/reader/doc-props-parsers.d.ts

@@ -0,0 +1,15 @@
+/**
+ * DOCX Reader - Document Properties Parsers
+ *
+ * Parses standard OPC document properties XML files:
+ * - docProps/core.xml (CoreProperties — title, author, dc:* fields)
+ * - docProps/app.xml (AppProperties — application info)
+ * - docProps/custom.xml (CustomProperty[] — user-defined name/value pairs)
+ * - word/fontTable.xml (FontDef[] — embedded font references)
+ */
+import type { AppProperties, CoreProperties, CustomProperty, FontDef } from "../types.js";
+declare function parseCoreProps(xmlStr: string): CoreProperties;
+declare function parseAppProps(xmlStr: string): AppProperties;
+declare function parseCustomPropsXml(xmlStr: string): CustomProperty[];
+declare function parseFontTableXml(xmlStr: string): FontDef[];
+export { parseCoreProps, parseAppProps, parseCustomPropsXml, parseFontTableXml };

package/dist/types/modules/word/reader/docx-reader.d.ts

@@ -0,0 +1,27 @@
+/**
+ * DOCX Module - Reader / Parser
+ *
+ * Reads a DOCX ZIP file and parses it into a DocxDocument model.
+ * Uses the archive module for ZIP reading and XML module for parsing.
+ */
+import { type WordSecurityPolicy } from "../security/policy.js";
+import type { DocxDocument } from "../types.js";
+/** Options for reading a DOCX file. */
+export interface ReadDocxOptions {
+    /** Password for decrypting an encrypted DOCX file. */
+    readonly password?: string;
+    /**
+     * Optional security policy that controls hard limits enforced while reading
+     * the package (max total size, max single-part size, max part count). Falls
+     * back to {@link DEFAULT_SECURITY_POLICY} when omitted. Helpful as a
+     * defense-in-depth control against ZIP bombs / pathological inputs.
+     */
+    readonly securityPolicy?: WordSecurityPolicy;
+}
+/**
+ * Read a DOCX file from a Uint8Array buffer and parse it into a DocxDocument model.
+ *
+ * If the file is encrypted (CFB format), provide a password via the options parameter
+ * to decrypt it automatically.
+ */
+export declare function readDocx(buffer: Uint8Array, options?: ReadDocxOptions): Promise<DocxDocument>;