/**
 * DOCX Module - Document Walker (Visitor Pattern)
 *
 * Unified traversal engine for the DocxDocument model. Provides a single,
 * tested implementation of document tree walking that all consumers
 * (renderers, validators, field engines, template engines, etc.) can use
 * instead of each implementing their own recursive traversal.
 *
 * Design principles:
 * - Visitor receives enter/leave callbacks for structural elements
 * - Return "skip" to prune subtrees, "stop" to abort early
 * - WalkPath provides full context (location, nesting depth, container)
 * - Options control which parts of the document are visited
 */
import type { DocxDocument, BodyContent, Paragraph, Run, RunContent, Table, TableRow, TableCell, MathBlock, MathContent, StructuredDocumentTag, Hyperlink, InsertedRun, DeletedRun, MovedFromRun, MovedToRun, FloatingImage, BookmarkStart, CommentRangeStart, CommentRangeEnd, TextBox, TableOfContents, AltChunk, ChartContent, ChartExContent, CheckBox, DrawingShape, OpaqueDrawing } from "../types.js";
/** Action returned by visitor callbacks to control traversal. */
export type VisitAction = "continue" | "skip" | "stop";
/** Location context passed to visitor callbacks. */
export interface WalkPath {
    /** Current section index (0-based). */
    readonly section: number;
    /** Nesting depth (0 = top-level body content). */
    readonly depth: number;
    /** Whether currently inside a header. */
    readonly inHeader: boolean;
    /** Whether currently inside a footer. */
    readonly inFooter: boolean;
    /** Whether currently inside a footnote. */
    readonly inFootnote: boolean;
    /** Whether currently inside an endnote. */
    readonly inEndnote: boolean;
    /** Whether currently inside a comment. */
    readonly inComment: boolean;
    /** Index within the parent container. */
    readonly index: number;
}
/** Options controlling which parts of the document to walk. */
export interface WalkOptions {
    /** Walk header content. Default: true. */
    readonly includeHeaders?: boolean;
    /** Walk footer content. Default: true. */
    readonly includeFooters?: boolean;
    /** Walk footnote content. Default: true. */
    readonly includeFootnotes?: boolean;
    /** Walk endnote content. Default: true. */
    readonly includeEndnotes?: boolean;
    /** Walk comment content. Default: false. */
    readonly includeComments?: boolean;
}
/**
 * Visitor interface for document traversal.
 * All methods are optional — implement only what you need.
 */
export interface DocxVisitor {
    enterParagraph?(para: Paragraph, path: WalkPath): VisitAction | void;
    leaveParagraph?(para: Paragraph, path: WalkPath): void;
    enterTable?(table: Table, path: WalkPath): VisitAction | void;
    leaveTable?(table: Table, path: WalkPath): void;
    enterTableRow?(row: TableRow, path: WalkPath): VisitAction | void;
    leaveTableRow?(row: TableRow, path: WalkPath): void;
    enterTableCell?(cell: TableCell, path: WalkPath): VisitAction | void;
    leaveTableCell?(cell: TableCell, path: WalkPath): void;
    enterSdt?(sdt: StructuredDocumentTag, path: WalkPath): VisitAction | void;
    leaveSdt?(sdt: StructuredDocumentTag, path: WalkPath): void;
    enterMathBlock?(math: MathBlock, path: WalkPath): VisitAction | void;
    leaveMathBlock?(math: MathBlock, path: WalkPath): void;
    visitFloatingImage?(image: FloatingImage, path: WalkPath): void;
    visitTextBox?(textBox: TextBox, path: WalkPath): VisitAction | void;
    visitTableOfContents?(toc: TableOfContents, path: WalkPath): void;
    visitAltChunk?(chunk: AltChunk, path: WalkPath): void;
    visitChart?(chart: ChartContent, path: WalkPath): void;
    visitChartEx?(chart: ChartExContent, path: WalkPath): void;
    visitCheckBox?(checkBox: CheckBox, path: WalkPath): void;
    visitDrawingShape?(shape: DrawingShape, path: WalkPath): void;
    visitOpaqueDrawing?(drawing: OpaqueDrawing, path: WalkPath): void;
    enterRun?(run: Run, path: WalkPath): VisitAction | void;
    leaveRun?(run: Run, path: WalkPath): void;
    enterHyperlink?(hyperlink: Hyperlink, path: WalkPath): VisitAction | void;
    leaveHyperlink?(hyperlink: Hyperlink, path: WalkPath): void;
    visitInsertedRun?(inserted: InsertedRun, path: WalkPath): VisitAction | void;
    visitDeletedRun?(deleted: DeletedRun, path: WalkPath): void;
    visitMovedFromRun?(moved: MovedFromRun, path: WalkPath): void;
    visitMovedToRun?(moved: MovedToRun, path: WalkPath): VisitAction | void;
    visitBookmarkStart?(bookmark: BookmarkStart, path: WalkPath): void;
    visitBookmarkEnd?(id: number, path: WalkPath): void;
    visitCommentRangeStart?(comment: CommentRangeStart, path: WalkPath): void;
    visitCommentRangeEnd?(comment: CommentRangeEnd, path: WalkPath): void;
    visitRunContent?(content: RunContent, run: Run, path: WalkPath): void;
    visitMathContent?(content: MathContent, path: WalkPath): void;
}
/**
 * Walk an entire DocxDocument, calling visitor methods for each element.
 *
 * @param doc - The document to walk.
 * @param visitor - Visitor with callbacks for elements of interest.
 * @param options - Controls which document parts to include.
 */
export declare function walkDocument(doc: DocxDocument, visitor: DocxVisitor, options?: WalkOptions): void;
/**
 * Walk a list of body content blocks (useful for walking sub-documents).
 *
 * @param blocks - Body content array to walk.
 * @param visitor - Visitor with callbacks.
 * @param basePath - Optional initial path context.
 * @returns "stop" if traversal was aborted, "continue" otherwise.
 */
export declare function walkBlocks(blocks: readonly BodyContent[], visitor: DocxVisitor, basePath?: WalkPath): "stop" | "continue";
/**
 * Collect all paragraphs from a document (including nested in tables/SDTs).
 */
export declare function collectParagraphs(doc: DocxDocument, options?: WalkOptions): Paragraph[];
/**
 * Collect all runs from a document (including nested).
 */
export declare function collectRuns(doc: DocxDocument, options?: WalkOptions): Run[];
/**
 * Collect all tables from a document (including nested).
 */
export declare function collectTables(doc: DocxDocument, options?: WalkOptions): Table[];