/**
 * docx Phase 4 — table lenses: enumerate, read, and edit `w:tbl`
 * structures, and create new tables.
 *
 * OWNERSHIP (DESIGN-P4.md): this file + tables.test.ts belong to the
 * TABLES agent. Allowed imports: ./internal.js, ../xml, ../mce,
 * ../schema. Never import ./index.js or another feature module.
 *
 * Table/TableRow/TableCell are lenses (CONTRACTS.md §0.1): they hold
 * references into the live main-part DOM, mutate it in place, and mark
 * the main part dirty through DocumentInternal. Cell properties (w:tcPr
 * — widths, spans, shading, borders) are always preserved by edits.
 *
 * Merged cells (CONTRACTS.md §7.10, DESIGN-P4.md decision 6): `cell(r, c)`
 * indexes the row's `w:tc` elements — a cell whose w:tcPr carries a
 * `w:gridSpan` covering N grid columns counts ONCE, and the continuation
 * cells of a vertical merge (`w:vMerge`) are ordinary `w:tc` elements
 * that also count. Grid-position addressing needs a layout model and is
 * a later phase; gridSpan/vMerge markup itself is preserved untouched.
 */
import { XmlElement } from '../xml/index.js';
import { type DocumentInternal } from './internal.js';
/** Options for {@link addTable}. */
export interface TableCreateOptions {
    /**
     * Table style id (w:tblPr/w:tblStyle), e.g. 'TableGrid'. Not
     * validated. When absent, the table gets direct single-line borders
     * (w:tblBorders) so it is visible — a style-less borderless grid is
     * invisible in Word and reads as a bug to users.
     */
    style?: string;
    /**
     * Column widths in twips (w:tblGrid/w:gridCol + w:tcW). Length must
     * equal `cols` or the call throws. Default: equal columns filling the
     * printable page width (9360 twips for create()'s US-Letter page).
     */
    widthsTwips?: readonly number[];
}
/**
 * Lens over one `w:tc` (table cell). Valid while the element stays in
 * the document.
 */
export declare class TableCell {
    #private;
    /** @internal Constructed by {@link TableRow.cells} / {@link Table.cell}. */
    constructor(guard: symbol, di: DocumentInternal, el: XmlElement);
    /** The underlying `w:tc` element (direct edits require markDirty). */
    get element(): XmlElement;
    /**
     * Plain text of the cell: the text of each paragraph in the cell
     * (MCE-resolved, nested-table content excluded), joined with '\n'.
     *
     * @example
     * table.cell(0, 1).text(); // 'Q2 Revenue'
     */
    text(): string;
    /**
     * Replace the cell's CONTENT with a single paragraph containing `text`,
     * PRESERVING the cell properties (w:tcPr — width, span, shading,
     * borders) exactly. Marks the main part dirty.
     *
     * @example
     * table.cell(1, 2).setText('42');
     */
    setText(text: string): void;
    /**
     * The paragraphs inside the cell as raw `w:p` elements in document
     * order (nested tables not descended into). Wrap with the docx
     * Paragraph lens via `Document.paragraphs()` when lens methods are
     * needed.
     *
     * @example
     * table.cell(0, 0).paragraphElements().length; // 1
     */
    paragraphElements(): readonly XmlElement[];
}
/**
 * Lens over one `w:tr` (table row). Valid while the element stays in the
 * document.
 */
export declare class TableRow {
    #private;
    /** @internal Constructed by {@link Table.rows}. */
    constructor(guard: symbol, di: DocumentInternal, el: XmlElement);
    /** The underlying `w:tr` element (direct edits require markDirty). */
    get element(): XmlElement;
    /**
     * The row's cells in document order (MCE-resolved). A fresh array of
     * lenses per call. A cell spanning several grid columns (w:gridSpan)
     * appears ONCE.
     *
     * @example
     * table.rows()[1].cells().map((c) => c.text()); // ['R2C1', 'R2C2']
     */
    cells(): readonly TableCell[];
}
/**
 * Lens over one `w:tbl`. Valid while the element stays in the document.
 */
export declare class Table {
    #private;
    /** @internal Constructed by {@link listTables} / {@link addTable}. */
    constructor(guard: symbol, di: DocumentInternal, el: XmlElement, depth: number);
    /** The underlying `w:tbl` element (direct edits require markDirty). */
    get element(): XmlElement;
    /**
     * Nesting depth: 0 for a body-level table, 1 for a table inside a cell
     * of a depth-0 table, and so on.
     */
    get depth(): number;
    /**
     * The table style id (w:tblPr/w:tblStyle/@w:val), when present.
     *
     * @example
     * doc.tables()[0].styleId(); // 'TableGrid'
     */
    styleId(): string | undefined;
    /**
     * The rows (`w:tr`) in document order. A fresh array of lenses per call.
     *
     * @example
     * table.rows()[0].cells()[0].text(); // 'Region'
     */
    rows(): readonly TableRow[];
    /**
     * Number of rows (w:tr count).
     *
     * @example
     * table.rowCount(); // 4
     */
    rowCount(): number;
    /**
     * Number of grid columns (w:tblGrid/w:gridCol count; falls back to the
     * widest row's cell count when the grid is absent).
     *
     * @example
     * table.columnCount(); // 3
     */
    columnCount(): number;
    /**
     * The cell at 0-based (row, col). Throws a range error naming the
     * table's actual dimensions when out of bounds. `col` indexes the
     * row's `w:tc` elements (a cell spanning N grid columns counts once —
     * documented; grid-position addressing is a later phase).
     *
     * @example
     * table.cell(0, 0).text(); // 'Region'
     */
    cell(row: number, col: number): TableCell;
    /**
     * Append a row: a new `w:tr` whose cells copy each corresponding
     * cell's `w:tcPr` from the current last row (widths/shading survive)
     * and contain one empty paragraph. Marks the main part dirty. Returns
     * the new row's lens.
     *
     * @example
     * const row = table.addRow();
     * row.cells()[0].setText('Total');
     */
    addRow(): TableRow;
}
/**
 * Every `w:tbl` in the body in document order, DEPTH-FIRST — nested
 * tables follow their containing table, with {@link Table.depth}
 * recording the nesting level. MCE-resolved. A fresh array per call.
 *
 * @example
 * const [invoice] = listTables(di);
 * invoice.cell(2, 1).text();
 */
export declare function listTables(di: DocumentInternal): readonly Table[];
/**
 * Append a `rows` × `cols` table at the end of the body (before the
 * body-final w:sectPr, via insertInSchemaOrder): w:tbl > w:tblPr
 * (tblStyle or default single borders, tblW auto) + w:tblGrid + rows of
 * cells each holding one empty paragraph. Marks the main part dirty.
 * Throws when rows/cols < 1 or widthsTwips length ≠ cols.
 *
 * @example
 * const t = addTable(di, 3, 4, { style: 'TableGrid' });
 * t.cell(0, 0).setText('Region');
 */
export declare function addTable(di: DocumentInternal, rows: number, cols: number, options?: TableCreateOptions): Table;
//# sourceMappingURL=tables.d.ts.map