/**
 * Configuration options for the OfficeParser.
 */
export interface OfficeParserConfig {
    /**
     * Flag to show all the logs to console in case of an error irrespective of your own handling.
     * Default is false.
     */
    outputErrorToConsole?: boolean;
    /**
     * The delimiter used for every new line in places that allow multiline text like word.
     * Default is \n.
     */
    newlineDelimiter?: string;
    /**
     * Flag to ignore notes from parsing in files like powerpoint.
     * Default is false. It includes notes in the parsed text by default.
     */
    ignoreNotes?: boolean;
    /**
     * Flag, if set to true, will collectively put all the parsed text from notes at last in files like powerpoint.
     * Default is false. It puts each notes right after its main slide content.
     * If ignoreNotes is set to true, this flag is also ignored.
     * @note This flag currently does not affect RTF files; RTF footnotes/endnotes are always collected and appended at the end of the content.
     */
    putNotesAtLast?: boolean;
    /**
     * Flag to extract attachments like images, charts, etc.
     * Default is false.
     */
    extractAttachments?: boolean;
    /**
     * Flag to include raw content (XML for XML-based formats, RTF for RTF) in the AST.
     * Default is false.
     */
    includeRawContent?: boolean;
    /**
     * Flag to enable OCR for images.
     * Default is false.
     */
    ocr?: boolean;
    /**
     * Language for OCR.
     * Default is 'eng'.
     *
     * You can provide multiple languages separated by a `+` sign (e.g., 'eng+fra' for English and French).
     * The OCR engine will then attempt to recognize text in any of the specified languages.
     *
     * See the list of supported languages and their codes here:
     * https://tesseract-ocr.github.io/tessdoc/Data-Files#data-files-for-version-400-november-29-2016
     */
    ocrLanguage?: string;
    /**
     * The URL/path to the PDF.js worker script.
     *
     * **Mandatory** when using PDF parsing in browser environments to avoid worker configuration errors.
     * If not provided, it defaults to `https://unpkg.com/pdfjs-dist@5.4.530/build/pdf.worker.min.mjs`.
     * You can override this with your own local path or a different CDN link.
     */
    pdfWorkerSrc?: string;
    /**
     * 当输入为 Buffer / ArrayBuffer 时，magic sniff（如 file-type）可能得到 `zip` 等与 OOXML 不符的后缀；
     * 传入用户选择的文件名（含 `.docx` 等）可强制按该扩展名选解析器（与 Node 下按路径解析一致）。
     */
    suggestedFileName?: string;
    /**
     * CSV 字段分隔符。默认 `,`；欧版 Excel 导出常用 `;`。
     */
    csvDelimiter?: string;
}
/**
 * Supported file types for parsing.
 */
export type SupportedFileType = 'docx' | 'pptx' | 'xlsx' | 'csv' | 'odt' | 'odp' | 'ods' | 'pdf' | 'rtf';
/**
 * Types of content nodes in the AST.
 */
export type OfficeContentNodeType = 'paragraph' | 'heading' | 'table' | 'list' | 'text' | 'image' | 'chart' | 'drawing' | 'slide' | 'note' | 'sheet' | 'row' | 'cell' | 'page';
/**
 * Supported MIME types for attachments.
 */
export type OfficeMimeType = 'image/jpeg' | 'image/png' | 'image/gif' | 'image/bmp' | 'image/tiff' | 'image/svg+xml' | 'application/pdf' | 'application/xml' | 'application/vnd.openxmlformats-officedocument.wordprocessingml.document' | 'application/vnd.oasis.opendocument.chart' | 'application/vnd.oasis.opendocument.spreadsheet' | 'application/vnd.oasis.opendocument.text' | 'application/vnd.oasis.opendocument.presentation';
/**
 * Text formatting options available for text content.
 * Represents common formatting attributes found in office documents (DOCX, RTF, PPTX, etc.).
 * All properties are optional and only present when the formatting is explicitly applied.
 */
export interface TextFormatting {
    /**
     * Whether the text is bold.
     * Corresponds to `<w:b/>` in OOXML, `\b` in RTF.
     * @example true for **bold text**, false or undefined for normal weight
     */
    bold?: boolean;
    /**
     * Whether the text is italic.
     * Corresponds to `<w:i/>` in OOXML, `\i` in RTF.
     * @example true for *italic text*, false or undefined for normal style
     */
    italic?: boolean;
    /**
     * Whether the text is underlined.
     * Corresponds to `<w:u/>` in OOXML, `\ul` in RTF.
     * @example true for underlined text, false or undefined for no underline
     */
    underline?: boolean;
    /**
     * Whether the text has a strikethrough.
     * Corresponds to `<w:strike/>` in OOXML, `\strike` in RTF.
     * @example true for ~~struck through~~ text
     */
    strikethrough?: boolean;
    /**
     * Text color in hex format (#RRGGBB).
     * Extracted from color tables in RTF or XML color attributes in OOXML.
     * @example "#ff0000" for red, "#00ff00" for green, "#0000ff" for blue
     */
    color?: string;
    /**
     * Background/highlight color in hex format (#RRGGBB).
     * Represents the background color or text highlighting.
     * @example "#ffff00" for yellow highlight, "#d3d3d3" for light gray
     */
    backgroundColor?: string;
    /**
     * Font size with units.
     * Most parsers append 'pt' (points), but ODF may use other units like 'in' (inches) or 'cm'.
     * @example "12pt" for 12pt, "14pt" for 14pt, "0.5in" for 0.5 inches
     */
    size?: string;
    /**
     * Font family/typeface name.
     * Extracted from font tables in RTF or font definitions in OOXML.
     * @example "Arial", "Times New Roman", "Calibri", "Ubuntu Mono"
     */
    font?: string;
    /**
     * Whether the text is subscript (e.g., H₂O).
     * Corresponds to `\sub` in RTF, `<w:vertAlign w:val="subscript"/>` in OOXML.
     * Mutually exclusive with superscript.
     * @example true for subscript text like H₂O
     */
    subscript?: boolean;
    /**
     * Whether the text is superscript (e.g., E=mc²).
     * Corresponds to `\super` in RTF, `<w:vertAlign w:val="superscript"/>` in OOXML.
     * Mutually exclusive with subscript.
     * @example true for superscript text like x²
     */
    superscript?: boolean;
    /**
     * The alignment of the text.
     * Common in spreadsheet cells or paragraph styles.
     * @example "center", "right"
     */
    alignment?: 'left' | 'center' | 'right' | 'justify';
}
/**
 * Metadata for a slide in PowerPoint.
 */
/**
 * PPTX shape bounding box in EMU (from `p:xfrm` / `p:spPr/a:xfrm`), 914400 EMU = 1 inch.
 */
export interface PptShapePositionEmu {
    x: number;
    y: number;
    cx: number;
    cy: number;
}
export interface SlideMetadata {
    /** The slide number (1-based). */
    slideNumber: number;
    /**
     * The unique ID of the note associated with this slide (if any).
     * @example "slide-note-1"
     */
    noteId?: string;
    /** The style of the slide. */
    style?: string;
    /**
     * PPTX: `p:cSld/p:bg/p:bgPr/a:solidFill`（或渐变首色）解析出的页面底色，六位十六进制无 `#`，与下游 `pageBackground.rgb` 一致。
     */
    pptPageBackgroundRgb?: string;
}
/**
 * Metadata for a sheet in Excel.
 */
/** One merged rectangle from `<mergeCells>` (0-based indices). */
export interface SheetMergeRange {
    start: {
        r: number;
        c: number;
    };
    end: {
        r: number;
        c: number;
    };
}
/**
 * `<cols><col min max style="xfIndex">` 一段：列区间（0-based 含端点）与对应单元格样式（已由 styles.xml 解析为 TextFormatting）。
 * 文档中靠后的 `<col>` 与靠前区间重叠时，后写覆盖（与 Excel 列宽段合并行为一致）。
 */
export interface SheetColumnStyleSegment {
    minCol: number;
    maxCol: number;
    formatting: TextFormatting;
}
export interface SheetMetadata {
    /** The name of the sheet. */
    sheetName: string;
    /** The style of the sheet. */
    style?: string;
    /**
     * Column widths from `<cols>` (OOXML `width` = character count under default font).
     * Keys are **0-based** column indices.
     */
    columnWidths?: Record<number, number>;
    /**
     * Merged regions from `<mergeCells>` / `<mergeCell ref="A1:B2"/>`.
     * Use this when cells in the covered area are empty and not emitted as `<c>` nodes.
     */
    mergeRanges?: SheetMergeRange[];
    /**
     * Row heights from `<row r="n" ht="..." customHeight="1">` — values are **points** (hpt).
     * Keys are **0-based** row indices.
     */
    rowHeights?: Record<number, number>;
    /**
     * 列级默认样式（`<col style="xfIndex">`），用于无 `<c>` 节点但仍继承列填充等样式的格子。
     */
    columnStyleSegments?: SheetColumnStyleSegment[];
}
/**
 * Metadata for a heading.
 */
/** Word `w:spacing` 数值（twips）；供 transform 映射到 Univer `paragraphStyle`。 */
export interface DocxSpacingTwips {
    before?: number;
    after?: number;
    line?: number;
    lineRule?: string | null;
}
export interface HeadingMetadata {
    /** The heading level (e.g., 1 for H1). */
    level: number;
    /** The alignment of the heading. */
    alignment?: 'left' | 'center' | 'right' | 'justify';
    /** PPTX: `a:bodyPr@anchor`（`t` / `ctr` / `b` 等），供垂直对齐。 */
    pptBodyAnchor?: string;
    /** PPTX: `a:bodyPr@anchorCtr="1"` 时与水平居中相关。 */
    pptBodyAnchorCtr?: boolean;
    /** The style of the heading. */
    style?: string;
    /** Word `w:pPr/w:spacing`。 */
    docxSpacingTwips?: DocxSpacingTwips;
    /** PPTX: shape `a:xfrm` box in EMU (slide coordinates). */
    pptPositionEmu?: PptShapePositionEmu;
    /** PPTX: first run font size in points (`a:rPr@sz` / 100). */
    pptFontSizePt?: number;
    /** PPTX: line spacing multiple from `a:lnSpc/a:spcPct@val` / 100000. */
    pptLineSpacing?: number;
    /** PPTX: first run text color `#RRGGBB`. */
    pptRunColor?: string;
}
/**
 * Metadata for a paragraph.
 */
export interface ParagraphMetadata {
    /** The alignment of the paragraph. */
    alignment?: 'left' | 'center' | 'right' | 'justify';
    /** PPTX: `a:bodyPr@anchor`。 */
    pptBodyAnchor?: string;
    /** PPTX: `a:bodyPr@anchorCtr`。 */
    pptBodyAnchorCtr?: boolean;
    /** The style of the paragraph. */
    style?: string;
    /** Word `w:pPr/w:spacing`。 */
    docxSpacingTwips?: DocxSpacingTwips;
    /** PPTX: shape `a:xfrm` box in EMU (slide coordinates). */
    pptPositionEmu?: PptShapePositionEmu;
    pptFontSizePt?: number;
    pptLineSpacing?: number;
    pptRunColor?: string;
}
/**
 * Metadata for a list item.
 */
export interface ListMetadata {
    /**
     * The type of list: 'ordered' (numbered) or 'unordered' (bulleted).
     * @example 'ordered' for numbered lists, 'unordered' for bulleted lists
     */
    listType: 'ordered' | 'unordered';
    /**
     * The nesting level (indent level) of the list item, starting from 0.
     * @example 0 for top-level items, 1 for first nested level
     */
    indentation: number;
    /**
     * Text alignment of the list item.
     * @example 'left', 'center', 'right', 'justify'
     */
    alignment: 'left' | 'center' | 'right' | 'justify';
    /**
     * The list ID from the Word document's numbering definition.
     * Used to identify which list definition this item belongs to.
     * @example '1', '2' for different list definitions
     */
    listId: string;
    /**
     * The zero-based index of this item within its list.
     * Continues incrementing even across paragraph interruptions for the same listId.
     * @example 0, 1, 2, 3 for sequential list items
     */
    itemIndex: number;
    /**
     * The style name of the list item.
     * @example "ListParagraph"
     */
    style?: string;
    /** Word `w:pPr/w:spacing`。 */
    docxSpacingTwips?: DocxSpacingTwips;
    /** PPTX: shape `a:xfrm` box in EMU (slide coordinates). */
    pptPositionEmu?: PptShapePositionEmu;
    pptFontSizePt?: number;
    pptLineSpacing?: number;
    pptRunColor?: string;
    /** PPTX: `a:bodyPr@anchor`（列表与段落共用 `txBody`）。 */
    pptBodyAnchor?: string;
    /** PPTX: `a:bodyPr@anchorCtr`。 */
    pptBodyAnchorCtr?: boolean;
}
/**
 * Metadata for a table cell (primarily used in Excel/spreadsheet parsing).
 * Contains positional information about where the cell appears in the table.
 */
export interface CellMetadata {
    /**
     * The row index of the cell (0-based).
     * @example 0 for the first row, 1 for the second row, etc.
     */
    row: number;
    /**
     * The column index of the cell (0-based).
     * @example 0 for column A, 1 for column B, etc.
     */
    col: number;
    /**
     * The number of rows this cell spans (merges).
     * @example 2 if the cell is merged with the one below it.
     */
    rowSpan?: number;
    /**
     * The number of columns this cell spans (merges).
     * @example 2 if the cell is merged with the one to its right.
     */
    colSpan?: number;
    /** The style of the cell. */
    style?: string;
    /**
     * Excel 数字格式代码（来自 styles.xml / cellXfs → numFmt），如 `0.00%`、`yyyy/m/d\\ h:mm;@`。
     */
    numberFormat?: string;
    /** 单元格批注（`xl/comments/*.xml`） */
    excelComment?: {
        author?: string;
        text: string;
    };
}
/**
 * Cell anchor corner in SpreadsheetML drawing (xlsx).
 * `col` / `row` are 0-based (same as OOXML xdr:col / xdr:row).
 * Offsets are in EMU (English Metric Units; 914400 EMU = 1 inch).
 */
export interface ExcelDrawingCellMarker {
    col: number;
    row: number;
    colOffEmu: number;
    rowOffEmu: number;
}
/** DrawingML `a:xfrm@rot`：以 1/60000 度为单位（与 PPT 一致），顺时针为正。 */
export type ExcelDrawingRotation = {
    rotationEmu?: number;
};
/**
 * Image position in an Excel worksheet from drawing part (twoCell / oneCell / absolute anchor).
 */
export type ExcelDrawingAnchor = ({
    anchorType: 'twoCell';
    from: ExcelDrawingCellMarker;
    to?: ExcelDrawingCellMarker;
} & ExcelDrawingRotation) | ({
    anchorType: 'oneCell';
    from: ExcelDrawingCellMarker;
    extentEmu: {
        cx: number;
        cy: number;
    };
    /** `a:picLocks@noChangeAspect`：为 true 时保持位图纵横比填入锚框 */
    picNoChangeAspect?: boolean;
    /** `a:blipFill` 下存在 `a:stretch`（常为拉伸填满显示区） */
    picBlipStretch?: boolean;
} & ExcelDrawingRotation) | ({
    anchorType: 'absolute';
    positionEmu: {
        x: number;
        y: number;
    };
    extentEmu: {
        cx: number;
        cy: number;
    };
} & ExcelDrawingRotation);
/**
 * Metadata for a chart node in the document.
 * Links the chart node to its corresponding attachment in the attachments array.
 */
export interface ChartMetadata {
    /**
     * The name of the attachment that contains the actual chart data.
     * Use this to look up the full chart data from the attachments array.
     * @example "chart1.xml"
     */
    attachmentName: string;
    /**
     * Excel worksheet: drawing anchor for this chart (`xdr:graphicFrame` inside twoCell/oneCell/absolute anchor).
     */
    excelDrawing?: ExcelDrawingAnchor;
    /**
     * Excel: name of the chart object on the drawing canvas (`xdr:cNvPr` / selection pane).
     * @example "图表 6"
     */
    title?: string;
    /**
     * Title text from the chart definition (`c:chart` / `c:title`), when present in the chart part.
     * @example "图表标题"
     */
    chartTitle?: string;
    /** PPTX: graphic frame `p:xfrm` box in EMU (slide coordinates). */
    pptPositionEmu?: PptShapePositionEmu;
}
/**
 * Excel worksheet floating shape with text: text box (浮动文字) or WordArt-style shape (艺术字).
 */
export interface ExcelShapeMetadata {
    /**
     * `textBox`: shape with `txBox="1"` (文本框). `wordArt`: other text shapes (e.g. 艺术字).
     */
    excelShapeKind: 'textBox' | 'wordArt';
    excelDrawing: ExcelDrawingAnchor;
    /** `xdr:cNvPr` name (e.g. "文本框 4") */
    shapeName?: string;
}
/**
 * Metadata for an image node in the document.
 * Links the image node to its corresponding attachment in the attachments array.
 */
export interface ImageMetadata {
    /**
     * The name of the attachment that contains the actual image data.
     * Use this to look up the full image data from the attachments array.
     * @example "image1.png"
     */
    attachmentName: string;
    /**
     * Alt text (alternative text) describing the image.
     * Extracted from image properties in the document.
     * @example "Company logo"
     */
    altText?: string;
    /**
     * When the image comes from an Excel worksheet drawing, anchor geometry (cell + offsets / size).
     */
    excelDrawing?: ExcelDrawingAnchor;
    /** PPTX: picture `p:spPr/a:xfrm` box in EMU (slide coordinates). */
    pptPositionEmu?: PptShapePositionEmu;
    /** PPTX: 来自 `p:cSld/p:bg` 的全幅背景图，置于子节点最前以匹配图层顺序。 */
    pptIsSlideBackground?: boolean;
    /** PPTX: `p:pic/p:spPr/a:prstGeom@prst`（如 `ellipse` 圆裁剪）。 */
    pptImagePrstGeom?: string;
    /**
     * DOCX: `wp:extent` / `extent` (`cx`/`cy`) in EMU (DrawingML),用于导出时还原显示尺寸。
     */
    docxExtentEmu?: {
        cx: number;
        cy: number;
    };
}
/**
 * Metadata for PDF page nodes.
 * Indicates which page of the PDF this content came from.
 */
export interface PageMetadata {
    /**
     * The page number (1-based) from the PDF document.
     * @example 1 for the first page, 2 for the second page, etc.
     */
    pageNumber: number;
}
/**
 * Metadata for text nodes that contain hyperlinks.
 * Used to track hyperlinks in text runs.
 */
export interface TextMetadata {
    /** Style name of the text */
    style?: string;
    /**
     * The hyperlink URL (for external links) or anchor reference (for internal links).
     * @example "https://example.com" or "#_Toc123456"
     */
    link?: string;
    /**
     * Type of hyperlink.
     * - 'internal': Link to a bookmark/anchor within the same document
     * - 'external': Link to an external URL
     */
    linkType?: 'internal' | 'external';
}
/**
 * Metadata for note nodes (footnotes/endnotes).
 * Used in ODT and DOCX files to track notes.
 */
export interface NoteMetadata {
    /**
     * Type of note: 'footnote' or 'endnote'.
     */
    noteType?: 'footnote' | 'endnote';
    /**
     * The unique ID of the note from the source document.
     * @example "1", "2"
     */
    noteId?: string;
}
/**
 * Union type for content metadata.
 */
/** PPTX: table in `p:graphicFrame` — optional slide bounds from `p:xfrm`. */
export interface TableMetadata {
    pptPositionEmu?: PptShapePositionEmu;
}
/** PPTX: non-text primitive shape (e.g. rectangle) from `p:sp` without `p:txBody`. */
export interface PptDrawingShapeMetadata {
    pptPositionEmu: PptShapePositionEmu;
    pptShapeKind: 'rect' | 'roundRect' | 'ellipse' | 'custGeom';
    /** OOXML `a:prstGeom@prst`（ST_ShapeType），与 `pptShapeKind` 一并保留供导出/二次映射。 */
    pptPrst?: string;
    pptFillColor?: string;
    /** `a:gradFill` → CSS `linear-gradient(...)`，供渲染层叠 DOM 还原渐变填充。 */
    pptFillGradientCss?: string;
    /** `a:ln/a:solidFill` 边框色 `#RRGGBB` */
    pptLineColor?: string;
    /** 边框宽度（pt），由 `a:ln@w` EMU / 12700 近似 */
    pptLineWidthPt?: number;
    /** PPTX: `a:prstGeom` 为 `roundRect` 时 `a:avLst/a:gd@name=adj` 的 `fmla="val N"`（0–50000）。 */
    pptRoundRectAdj?: number;
}
export type ContentMetadata = SlideMetadata | SheetMetadata | HeadingMetadata | ListMetadata | CellMetadata | ImageMetadata | ChartMetadata | ExcelShapeMetadata | PageMetadata | ParagraphMetadata | TextMetadata | NoteMetadata | TableMetadata | PptDrawingShapeMetadata | undefined;
/**
 * Represents a node in the document content tree.
 * This is the core building block of the parsed document structure.
 * Content nodes can be nested to represent hierarchical document structures
 * (e.g., paragraphs containing text runs, tables containing rows, rows containing cells).
 *
 * @example
 * // A simple paragraph with formatted text
 * {
 *   type: 'paragraph',
 *   text: 'Hello world',
 *   children: [
 *     { type: 'text', text: 'Hello ', formatting: { bold: true } },
 *     { type: 'text', text: 'world', formatting: { italic: true } }
 *   ]
 * }
 *
 * @example
 * // A heading with metadata
 * {
 *   type: 'heading',
 *   text: 'Chapter 1',
 *   metadata: { level: 1 },
 *   children: [...]
 * }
 */
export interface OfficeContentNode {
    /**
     * The type of the node.
     * Determines how the node should be interpreted and rendered.
     * Common types: 'paragraph', 'heading', 'table', 'list', 'text', 'image', etc.
     */
    type: OfficeContentNodeType;
    /**
     * The complete text content of the node and all its children combined.
     * For container nodes (paragraph, heading), this is the concatenation of all child text.
     * For leaf nodes (text), this is the actual text content.
     * @example "Hello world" for a paragraph containing "Hello " and "world"
     */
    text?: string;
    /**
     * Child nodes that make up this node's content.
     * Used for hierarchical structures:
     * - Paragraphs contain text runs with different formatting
     * - Tables contain rows
     * - Rows contain cells
     * - Cells contain paragraphs
     * @example [{ type: 'text', text: 'Hello', formatting: { bold: true } }]
     */
    children?: OfficeContentNode[];
    /**
     * Text formatting applied to this node.
     * Only applicable to text-containing nodes.
     * For container nodes like paragraphs, formatting typically appears on child text nodes.
     * @example { bold: true, size: "12", font: "Arial" }
     */
    formatting?: TextFormatting;
    /**
     * Type-specific metadata providing additional context about the node.
     * The metadata structure depends on the node type:
     * - Headings: { level: 1 }
     * - Lists: { listType: 'ordered', indentation: 0 }
     * - Cells: { row: 0, col: 0 }
     * - Slides: { slideNumber: 1 }
     * @example { level: 1 } for a heading
     */
    metadata?: ContentMetadata;
    /**
     * The raw source content for this node.
     * - For XML-based formats (DOCX, XLSX, PPTX): contains the raw XML
     * - For RTF: contains the raw RTF markup
     * - For PDF: typically not available
     * Only populated when `config.includeRawContent` is true.
     * Useful for debugging or when you need access to format-specific features.
     * @example "<w:p><w:r><w:t>Hello</w:t></w:r></w:p>" for DOCX
     */
    rawContent?: string;
}
/**
 * Structured information extracted from a chart.
 */
export interface ChartData {
    /** Chart title (if any) */
    title?: string;
    /** X-axis title (for continuous or categorical axes) */
    xAxisTitle?: string;
    /** Y-axis title (for value or continuous axes) */
    yAxisTitle?: string;
    /**
     * Collections of data points.
     * For bar/line charts, each dataset is one 'line' or group of bars.
     * For pie charts, there is typically only one dataset.
     */
    dataSets: {
        /** Name of this data group (e.g., 'Sales 2023') */
        name?: string;
        /** Actual numeric or string values for this group */
        values: string[];
        /** Specific labels for each point in this dataset (if defined per point) */
        pointLabels: string[];
    }[];
    /**
     * Labels for the chart facets (e.g., 'Jan', 'Feb', 'Mar' on X-axis).
     * These typically correspond to the data points in each dataSet.
     */
    labels: string[];
    /** Every text node discovered in the chart XML (for keyword search/raw extraction) */
    rawTexts: string[];
}
/**
 * Represents an attachment extracted from the document (image, chart, etc.).
 * Attachments are binary resources embedded in the document.
 * Only populated when `config.extractAttachments` is true.
 *
 * @example
 * ```typescript
 * {
 *   type: 'image',
 *   mimeType: 'image/png',
 *   data: 'iVBORw0KGgoAAAANSUhEUgAA...',  // Base64
 *   name: 'chart1.png',
 *   extension: 'png',
 *   ocrText: 'Sales Chart Q4 2024'  // If OCR was enabled
 * }
 * ```
 */
export interface OfficeAttachment {
    /**
     * The category of the attachment.
     * Helps identify what kind of content this represents.
     * @example 'image' for photos and diagrams, 'chart' for embedded charts
     */
    type: 'image' | 'chart' | 'packagePart';
    /**
     * The MIME type of the attachment data.
     * Indicates the file format and how the data should be interpreted.
     * @example 'image/png', 'image/jpeg', 'image/svg+xml'
     */
    mimeType: OfficeMimeType;
    /**
     * The attachment content encoded as Base64.
     * This is the actual binary data of the image/chart/etc. encoded for text transmission.
     * Can be used directly in HTML img tags with data URIs or decoded to binary.
     * @example "iVBORw0KGgoAAAANSUhEUgAA..." (truncated)
     */
    data: string;
    /**
     * A unique name for this attachment file.
     * May be derived from the source file or auto-generated.
     * Used to link `ImageMetadata` nodes to their corresponding attachments.
     * @example "image1.png", "chart2.emf", "picture3.jpg"
     */
    name: string;
    /**
     * The file extension (without the dot).
     * Derived from the MIME type or original filename.
     * @example "png", "jpg", "svg"
     */
    extension: string;
    /**
     * Text extracted from the image using Optical Character Recognition (OCR).
     * Only present when:
     * - `config.ocr` is true
     * - `config.extractAttachments` is true
     * - The attachment is an image containing text
     * Uses Tesseract.js with the language specified in `config.ocrLanguage`.
     * @example "Annual Revenue: $1.2M"
     */
    ocrText?: string;
    /**
     * Alt text or description associated with the image in the document.
     * Extracted from the document markup (e.g., wp:docPr descr attribute in DOCX).
     * @example "A chart showing sales growth"
     */
    altText?: string;
    /**
     * Structured data extracted from a chart attachment.
     * Only present if the attachment is a chart and data extraction was successful.
     * Contains series names, values, labels, and titles.
     * @example { title: "Sales Chart", series: [...], categories: [...] }
     */
    chartData?: ChartData;
    /**
     * When `type` is `packagePart`, full path inside the xlsx package (e.g. `xl/drawings/drawing1.xml`).
     */
    packagePath?: string;
    /** Optional sibling rels file path (e.g. `xl/drawings/_rels/drawing1.xml.rels`). */
    relsPackagePath?: string;
    /** Base64 content for `relsPackagePath`. */
    relsData?: string;
    /**
     * Worksheet part that references this drawing (e.g. `xl/worksheets/sheet1.xml`), for export merge.
     */
    targetWorksheetXml?: string;
}
/**
 * Metadata for the parsed file.
 */
export interface OfficeMetadata {
    /** The title of the document. */
    title?: string;
    /** The author of the document. */
    author?: string;
    /** User who last modified the document. */
    lastModifiedBy?: string;
    /** Creation date. */
    created?: Date;
    /** Last modification date. */
    modified?: Date;
    /** Description/Comments. */
    description?: string;
    /** Subject/Topic. */
    subject?: string;
    /** Number of pages (if available). */
    pages?: number;
    /** Document-wide default formatting settings (font, size, color). */
    formatting?: Partial<TextFormatting>;
    /** Style map for styles in the document. */
    styleMap?: Record<string, Partial<TextFormatting>>;
    /**
     * PPTX: `ppt/presentation.xml` 中 `p:sldSz`（EMU），用于与 `p:sp` 坐标同尺度换算画布大小。
     */
    pptSlideSizeEmu?: {
        cx: number;
        cy: number;
    };
}
/**
 * The Abstract Syntax Tree (AST) returned by the parser.
 * This is the root data structure representing the entire parsed document.
 *
 * The AST provides a format-agnostic representation of the document that can be easily
 * processed, transformed, or converted to other formats. It preserves the document's
 * structure, content, formatting, and metadata while abstracting away format-specific details.
 *
 * @example
 * ```typescript
 * const ast = await OfficeParser.parseOffice('document.docx', {
 *   extractAttachments: true,
 *   includeRawContent: false
 * });
 *
 * console.log(ast.type); // 'docx'
 * console.log(ast.metadata.author); // 'John Doe'
 * console.log(ast.content.length); // Number of top-level content nodes
 * console.log(ast.toText()); // Plain text representation
 * ```
 */
export interface OfficeParserAST {
    /**
     * The type of the parsed file.
     * Indicates which parser was used and what format the input was in.
     * @example 'docx', 'xlsx', 'csv', 'pptx', 'rtf', 'pdf', 'odt', 'odp', 'ods'
     */
    type: SupportedFileType;
    /**
     * Document metadata extracted from the file properties.
     * Includes information like author, title, creation date, etc.
     * Availability depends on the file format and whether metadata was present in the source.
     * @example { author: 'John Smith', title: 'Annual Report', created: new Date('2024-01-01') }
     */
    metadata: OfficeMetadata;
    /**
     * The hierarchical content structure of the document.
     * This is an array of top-level content nodes. Each node can have children, creating a tree.
     * For different file types:
     * - DOCX: Array of paragraphs, headings, tables, etc.
     * - XLSX: Array of sheets, each containing rows
     * - PPTX: Array of slides, each containing content nodes
     * - PDF: Array of pages, each containing paragraphs
     * @example [{ type: 'paragraph', text: 'Hello' }, { type: 'heading', text: 'Chapter 1' }]
     */
    content: OfficeContentNode[];
    /**
     * Attachments extracted from the document (images, charts, embedded files).
     * Only populated when `config.extractAttachments` is true.
     * Each attachment includes:
     * - Base64-encoded data
     * - MIME type
     * - Optional OCR text (if `config.ocr` is true)
     * @example [{ type: 'image', mimeType: 'image/png', data: 'base64...', name: 'image1.png' }]
     */
    attachments: OfficeAttachment[];
    /**
     * Converts the entire AST to plain text.
     * This method flattens the document structure and returns just the text content,
     * stripping out all formatting, metadata, and structure.
     *
     * The text is concatenated using the delimiter specified in `config.newlineDelimiter` (default: '\n').
     *
     * @returns A plain text representation of the document
     * @example
     * ```typescript
     * const text = ast.toText();
     * console.log(text); // "Hello world\nChapter 1\n..."
     * ```
     */
    toText(): string;
}
