/**
 * docx Phase 4 — sections (headers/footers) and list creation (the
 * WRITE side of numbering; the READ side lives in resolver.ts).
 *
 * OWNERSHIP (DESIGN-P4.md): this file + sections.test.ts belong to the
 * SECTIONS agent. Allowed imports: ./internal.js, ../xml, ../mce,
 * ../schema. Never import ./index.js or another feature module.
 *
 * Headers/footers: header/footer parts are created with correct content
 * types and main-part relationships, and wired into EVERY `w:sectPr`
 * (the body-final one plus any pPr/sectPr of earlier sections) so the
 * header/footer shows across the whole document — Word's inheritance
 * rules make anything less surprising. 'first' auto-sets w:titlePg on
 * each sectPr; 'even' auto-sets w:evenAndOddHeaders in settings.xml
 * (created on demand) — without those flags Word ignores the reference.
 *
 * Lists: addBulletList/addNumberedList create one minimal correct
 * numbering definition per call (w:abstractNum with 9 levels + a w:num
 * referencing it, ids allocated smallest-free) in numbering.xml (created
 * on demand via ensureNumbering) and reference it from new paragraphs
 * via w:pPr > w:numPr.
 */
import { type DocumentInternal } from './internal.js';
import { XmlElement } from '../xml/index.js';
/**
 * Which pages a header/footer applies to: 'default' = all pages (odd
 * pages once 'even' exists), 'first' = first page of the section,
 * 'even' = even pages.
 */
export type HeaderFooterType = 'default' | 'first' | 'even';
/** One existing header or footer (returned by {@link headers} / {@link footers}). */
export interface HeaderFooterInfo {
    /** 'header' or 'footer'. */
    readonly kind: 'header' | 'footer';
    /** Which pages it applies to. */
    readonly type: HeaderFooterType;
    /** The part holding it, e.g. '/word/header1.xml'. */
    readonly partName: string;
    /**
     * Plain text of the part: every paragraph's text joined with '\n'
     * (same rules as Document.text(), MCE-resolved).
     *
     * @example
     * headers(di)[0].text(); // 'ACME Corp — Confidential'
     */
    text(): string;
}
/** Options for {@link setHeader} / {@link setFooter}. */
export interface SetHeaderFooterOptions {
    /** Which pages the header/footer applies to. Default 'default'. */
    type?: HeaderFooterType;
}
/**
 * One list item: a plain string is a level-0 item; the object form
 * nests it (`level` is 0-based, max 8).
 */
export type ListItem = string | {
    readonly text: string;
    readonly level: number;
};
/** Options for {@link addNumberedList}. */
export interface NumberedListOptions {
    /**
     * Number format of every level (w:numFmt): 'decimal' → 1. 2. 3.,
     * 'lowerLetter' → a. b. c., 'lowerRoman'/'upperLetter'/'upperRoman'
     * likewise. Default: Word's standard alternation
     * decimal/lowerLetter/lowerRoman repeating across levels 0–8.
     */
    format?: 'decimal' | 'lowerLetter' | 'upperLetter' | 'lowerRoman' | 'upperRoman';
}
/**
 * Every header referenced by any `w:sectPr` (body-final or mid-document),
 * de-duplicated by part, in first-reference document order.
 *
 * @example
 * headers(di).map((h) => `${h.type}: ${h.text()}`);
 */
export declare function headers(di: DocumentInternal): readonly HeaderFooterInfo[];
/** Every footer referenced by any `w:sectPr` — see {@link headers}. */
export declare function footers(di: DocumentInternal): readonly HeaderFooterInfo[];
/**
 * Set the document's header of the given type: creates a header part
 * (smallest-free /word/headerN.xml) containing one paragraph with
 * `text`, adds the content-type override + main-part relationship, and
 * writes a `w:headerReference` of that type into EVERY w:sectPr
 * (schema-ordered). An existing reference of the same type is replaced;
 * a replaced part no longer referenced from any sectPr is removed
 * (part, rels entry, override). type 'first' also sets w:titlePg;
 * 'even' also sets w:evenAndOddHeaders in settings.xml. Marks every
 * touched part dirty.
 *
 * @example
 * setHeader(di, 'ACME Corp — Confidential');
 * setHeader(di, 'Chapter one only', { type: 'first' });
 */
export declare function setHeader(di: DocumentInternal, text: string, options?: SetHeaderFooterOptions): void;
/** Set the document's footer of the given type — see {@link setHeader}. */
export declare function setFooter(di: DocumentInternal, text: string, options?: SetHeaderFooterOptions): void;
/**
 * Append one paragraph per item, all sharing ONE new bullet numbering
 * definition (abstractNum with the standard Word bullet characters for
 * levels 0–8 + num, created in numbering.xml on demand). Items are
 * level-0 unless given as `{ text, level }` (0–8; out of range throws).
 * Returns the new `w:p` elements in order (the Document lens wraps them
 * into Paragraph objects at integration). Marks main + numbering dirty.
 * An empty items array is a no-op returning [].
 *
 * @example
 * addBulletList(di, ['Alpha', { text: 'Nested', level: 1 }, 'Beta']);
 */
export declare function addBulletList(di: DocumentInternal, items: readonly ListItem[]): readonly XmlElement[];
/**
 * Append one paragraph per item as a numbered list — one new numbering
 * definition per call, so consecutive calls restart at 1. Level formats
 * follow {@link NumberedListOptions.format}; lvlText is '%N.' style
 * with Word's standard per-level indents.
 *
 * @example
 * addNumberedList(di, ['Prepare', 'Execute', 'Verify']); // 1. 2. 3.
 */
export declare function addNumberedList(di: DocumentInternal, items: readonly ListItem[], options?: NumberedListOptions): readonly XmlElement[];
//# sourceMappingURL=sections.d.ts.map