@gmickel/gno 1.46.0 → 2.1.0

package/vendor/converters/officeparser/dist/parsers/WordParser.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Word Document (DOCX) Parser
+ *
+ * **DOCX Format Overview:**
+ * DOCX is the default format for Microsoft Word documents since Office 2007.
+ * It's based on the Office Open XML (OOXML) standard (ECMA-376, ISO/IEC 29500).
+ *
+ * **File Structure:**
+ * DOCX files are ZIP archives containing:
+ * - `word/document.xml` - Main document content
+ * - `word/styles.xml` - Style definitions
+ * - `word/numbering.xml` - List numbering definitions
+ * - `word/footnotes.xml` - Footnotes content
+ * - `word/media/*` - Embedded images and media
+ * - `docProps/core.xml` - Document metadata
+ * - `[Content_Types].xml` - MIME type mappings
+ *
+ * **XML Structure (word/document.xml):**
+ * ```xml
+ * <w:document>
+ *   <w:body>
+ *     <w:p>                    <!-- Paragraph -->
+ *       <w:pPr>                <!-- Paragraph properties -->
+ *         <w:pStyle w:val="Heading1"/>
+ *       </w:pPr>
+ *       <w:r>                  <!-- Run (text with same formatting) -->
+ *         <w:rPr>              <!-- Run properties -->
+ *           <w:b/>             <!-- Bold -->
+ *           <w:sz w:val="24"/> <!-- Font size (half-points) -->
+ *         </w:rPr>
+ *         <w:t>Hello</w:t>     <!-- Text -->
+ *       </w:r>
+ *     </w:p>
+ *   </w:body>
+ * </w:document>
+ * ```
+ *
+ * **Key OOXML Elements:**
+ * - `<w:p>` - Paragraph
+ * - `<w:r>` - Run (contiguous text with same formatting)
+ * - `<w:t>` - Text content
+ * - `<w:br>` - Line or page break
+ * - `<w:b>`, `<w:i>`, `<w:u>` - Bold, italic, underline
+ * - `<w:pStyle>` - Paragraph style (for headings)
+ * - `<w:numPr>` - List numbering properties
+ * - `<w:tbl>` - Table
+ * - `<w:drawing>` - Drawing/image
+ *
+ * **Parsing Approach:**
+ * 1. Extract ZIP contents
+ * 2. Parse word/document.xml for structure and text
+ * 3. Extract formatting from run properties (rPr)
+ * 4. Identify headings via paragraph styles
+ * 5. Extract footnotes from word/footnotes.xml
+ * 6. Process embedded images from word/media/*
+ * 7. Parse metadata from docProps/core.xml
+ *
+ * @module WordParser
+ * @see https://www.ecma-international.org/publications-and-standards/standards/ecma-376/ OOXML Standard
+ * @see https://learn.microsoft.com/en-us/openspecs/office_standards/ms-docx/ [MS-DOCX] Specification
+ */
+import { FullOfficeParserConfig, OfficeParserAST } from '../types.js';
+/**
+ * Parses a Word document (.docx) and extracts content, formatting, and metadata.
+ *
+ * The parsing process:
+ * 1. Unzip the DOCX file
+ * 2. Parse word/document.xml to extract paragraphs and runs
+ * 3. Extract text formatting from run properties
+ * 4. Identify headings from paragraph styles
+ * 5. Process lists from numbering properties
+ * 6. Extract images and optionally perform OCR
+ * 7. Parse document metadata
+ *
+ * @param buffer - The DOCX file as a Buffer
+ * @param config - Parser configuration options
+ * @returns A promise resolving to the parsed AST
+ */
+export declare const parseWord: (buffer: Buffer, config: FullOfficeParserConfig) => Promise<OfficeParserAST>;