/**
 * xlsx shared internals — the contract Phase-3 feature modules code against.
 *
 * OWNERSHIP (DESIGN-P3.md): this file is owned by the architect/Integrate
 * agent and is FROZEN during parallel implementation. Feature implementers
 * (styles.ts, structure.ts, formula/, streaming.ts) import from it but never
 * edit it. `index.ts` implements the `WorkbookInternal` / `SheetInternal`
 * interfaces (via `Workbook._internal()` / `Worksheet._internal()`) and
 * re-exports the public helpers below.
 *
 * Everything in this file is either:
 *  - a pure helper extracted from index.ts (behavior unchanged), or
 *  - a capability interface implemented by the lenses in index.ts.
 *
 * Nothing here mutates DOMs except through the interfaces; dirty-marking
 * discipline (CONTRACTS.md §0.1) is the caller's responsibility via
 * `markDirty`.
 */
import type { OfficeDocument } from '../document/index.js';
import type { OpcPart } from '../opc/index.js';
import type { XmlDocument, XmlElement, XmlDeclaration } from '../xml/index.js';
/** SpreadsheetML main namespace. */
export declare const SML_NAMESPACE = "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
export declare const REL_TYPE_WORKSHEET = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet";
export declare const REL_TYPE_STYLES = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
export declare const REL_TYPE_SHARED_STRINGS = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings";
export declare const REL_TYPE_CALC_CHAIN = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/calcChain";
/** Worksheet → table part relationship (structure.ts). */
export declare const REL_TYPE_TABLE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/table";
export declare const CT_WORKSHEET = "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml";
export declare const CT_STYLES = "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml";
export declare const CT_SHARED_STRINGS = "application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml";
export declare const CT_WORKBOOK_XLSX = "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml";
/** Excel table part content type (structure.ts). */
export declare const CT_TABLE = "application/vnd.openxmlformats-officedocument.spreadsheetml.table+xml";
/**
 * Sheet-family content types other than the worksheet's whose cells may
 * carry `t="s"` shared-string references. These parts stay opaque (never
 * modeled, always raw-copied), but their references are counted into the
 * sst `count` attribute (CONTRACTS.md §8.4).
 */
export declare const CT_MACROSHEET = "application/vnd.ms-excel.macrosheet+xml";
export declare const CT_INTL_MACROSHEET = "application/vnd.ms-excel.intlmacrosheet+xml";
export declare const CT_DIALOGSHEET = "application/vnd.openxmlformats-officedocument.spreadsheetml.dialogsheet+xml";
/** The XML declaration every part this module creates carries. */
export declare const STANDARD_XML_DECL: XmlDeclaration;
/** Create a module-prefixed error (CONTRACTS.md §0.3). */
export declare function xlsxError(message: string): Error;
/**
 * A cell value crossing the API boundary.
 * null reads as "empty cell"; writing null clears the cell's value.
 */
export type CellValue = string | number | boolean | Date | null;
/** A parsed A1 reference; row and col are 1-based. */
export interface CellAddress {
    readonly row: number;
    readonly col: number;
}
/** A parsed A1 range; start is the top-left, end the bottom-right corner. */
export interface RangeAddress {
    readonly start: CellAddress;
    readonly end: CellAddress;
}
/** Excel sheet limits: XFD1048576. */
export declare const MAX_COL = 16384;
export declare const MAX_ROW = 1048576;
/** Column letters → 1-based column number ('A' → 1, 'XFD' → 16384). */
export declare function lettersToCol(letters: string): number;
/** 1-based column number → letters (1 → 'A', 16384 → 'XFD'). */
export declare function colToLetters(col: number): string;
/**
 * Parse an A1-style reference ('B7', absolute markers '$B$7' accepted and
 * ignored). Throws `Error` on anything else (ranges, R1C1, out of bounds
 * — max XFD1048576).
 */
export declare function parseCellRef(ref: string): CellAddress;
/** Format a 1-based address as an A1 reference (e.g. {row:7,col:2} → 'B7'). */
export declare function formatCellRef(address: CellAddress): string;
/**
 * A single cell address from either accepted spelling: 'B7' (A1 text,
 * absolute markers ignored) or {row, col} (1-based, validated against
 * sheet bounds). The shared input normalizer behind every cell-taking
 * lens method.
 */
export declare function toCellAddress(ref: string | CellAddress): CellAddress;
/**
 * Parse an A1 range ('A1:C3'; a single cell 'B2' is the degenerate range
 * B2:B2; absolute markers accepted and ignored). The result is normalized:
 * `start` is the top-left corner even when the input was 'C3:A1'.
 * Throws `Error` on whole-column/row ranges ('A:A', '1:3') and anything
 * that is not a cell or cell:cell range.
 */
export declare function parseRangeRef(ref: string): RangeAddress;
/**
 * Format a range as canonical A1 text: 'A1:C3', or the single-cell 'B2'
 * form when the range is degenerate (start === end). Excel range XML
 * attributes (`mergeCell/@ref`, `table/@ref`) require the two-corner form
 * even for one cell — use {@link formatRangeRefFull} for those.
 */
export declare function formatRangeRef(range: RangeAddress): string;
/** Format a range always in the two-corner 'A1:C3' form (XML attributes). */
export declare function formatRangeRefFull(range: RangeAddress): string;
export declare const MS_PER_DAY = 86400000;
/** 1900 system epoch: 1899-12-30 (compensates Excel's 1900 leap-year bug). */
export declare const EPOCH_1900: number;
/** 1904 system epoch. */
export declare const EPOCH_1904: number;
/** Built-in date/time number format ids (ECMA-376 §18.8.30). */
export declare const BUILTIN_DATE_NUMFMT: ReadonlySet<number>;
/**
 * Built-in number format codes (ECMA-376 §18.8.30). Ids 0–49 that have a
 * defined code; implied formats (5–8, 23–36, 41–44) vary by locale and are
 * omitted — resolve them as `undefined` (callers report the id alone).
 */
export declare const BUILTIN_NUMFMT_CODES: ReadonlyMap<number, string>;
/**
 * First numFmtId available for custom formats. Excel reserves 0–163;
 * custom `numFmt` entries are allocated from 164 up (styles.ts).
 */
export declare const FIRST_CUSTOM_NUMFMT_ID = 164;
/**
 * Heuristic for custom number formats: a format is a date/time format when
 * it contains any of the tokens y/m/d/h/s outside quoted literals,
 * backslash escapes, and [bracketed] sections (colors, conditions,
 * locale/currency markers). "AM/PM" is caught via its 'M'.
 */
export declare function isDateFormatCode(code: string): boolean;
/** Serial number → Date (UTC), rounded to the nearest millisecond. */
export declare function serialToDate(serial: number, date1904: boolean): Date;
/** Date → serial number in the workbook's date system. */
export declare function dateToSerial(date: Date, date1904: boolean): number;
/** Parse an ISO 8601 cell value (t="d") as UTC when no zone is given. */
export declare function parseIsoDate(text: string): Date;
/** The logical type of a cell as classified by `Worksheet.getCellInfo`. */
export type CellType = 'empty' | 'string' | 'number' | 'boolean' | 'date' | 'error';
/** Rich read result: type, decoded value, and the formula text if any. */
export interface CellInfo {
    readonly type: CellType;
    readonly value: CellValue;
    /** Formula text (`f` element), when the cell has one. May be '' for
     * dependent cells of a shared formula. */
    readonly formula?: string;
}
/**
 * Flatten an `si` (or inline `is`) element to plain text: a direct `t`
 * child plus every rich run's `r > t`, in document order. Phonetic runs
 * (`rPh`) and `phoneticPr` are excluded — Excel does not display them as
 * cell text.
 */
export declare function flattenStringItem(item: XmlElement): string;
/** True for an si with exactly one direct `t` child and no rich runs. */
export declare function isPlainStringItem(item: XmlElement): boolean;
/**
 * Leading/trailing whitespace needs xml:space="preserve" on `t`.
 * The class is \s plus NEL (U+0085, not matched by \s in JS) and NBSP
 * (explicit for clarity; \s already matches it).
 */
export declare function needsSpacePreserve(text: string): boolean;
/**
 * Count `t="s"` cells (`c` elements referencing the shared string table)
 * anywhere under `el`. Namespace-insensitive on purpose: macrosheet parts
 * carry cell markup whose namespace varies by producer while sharing the
 * worksheet cell shape.
 */
export declare function countSharedStringCells(el: XmlElement): number;
/**
 * Structural equality of two style-sheet elements: same local name, same
 * attribute set (qualified name → value, order-insensitive so equivalent
 * xfs written in different attribute orders still dedup), and pairwise-
 * equal child elements in order (alignment/protection under an xf).
 *
 * This is THE dedup oracle for fonts, fills, borders, numFmts and xfs:
 * styles.ts (and index.ts's derived date/General xfs) find-or-append
 * against the relevant collection using this comparison, so repeated
 * styling never bloats styles.xml (CONTRACTS.md §8.11).
 */
export declare function styleElementEquals(a: XmlElement, b: XmlElement): boolean;
/** The 1-based row index of a `row` element (explicit r, else implied). */
export declare function rowIndex(row: XmlElement, implied: number): number;
/** The 1-based column of a `c` element (explicit r, else implied). */
export declare function cellColumn(cell: XmlElement, implied: number): number;
/**
 * One modeled part and its live DOM. The DOM is always the document
 * layer's cached instance — dirty flagging and save-time serialization
 * are its job.
 */
export interface PartDom {
    readonly part: OpcPart;
    readonly doc: XmlDocument;
}
/**
 * Capabilities of a `Workbook` exposed to feature modules.
 * Obtained via `Workbook._internal()`; implemented in index.ts.
 *
 * All mutating operations follow the lens rules: they mutate the live DOM
 * and mark the owning part dirty (or the feature module does, via
 * {@link WorkbookInternal.markDirty}).
 */
export interface WorkbookInternal {
    /** The underlying office document (package, parts, DOM cache). */
    readonly office: OfficeDocument;
    /** workbook.xml part + live DOM. */
    readonly workbook: PartDom;
    /** styles.xml, or null when the workbook has none (yet). */
    styles(): PartDom | null;
    /**
     * styles.xml, creating the minimal repair-free stylesheet part,
     * content-type override and workbook relationship on first use.
     */
    ensureStyles(): PartDom;
    /** sharedStrings.xml, or null when the workbook has none (yet). */
    sharedStrings(): PartDom | null;
    /** Flag a modeled part dirty (delegates to the document-layer cache). */
    markDirty(pd: PartDom): void;
    /** True when workbookPr declares the 1904 date system. */
    date1904(): boolean;
    /** Resolve shared string `index` to flattened text. Throws when out of range. */
    sharedString(index: number): string;
    /**
     * Intern `text` in the shared string table (creating the part on first
     * use), deduplicating by exact text. Returns the si index. Marks the
     * table dirty. Callers that add/remove `t="s"` cells must call
     * {@link updateSharedStringCounts} afterwards.
     */
    internString(text: string): number;
    /**
     * Bring the sst count/uniqueCount attributes up to date; marks the
     * table dirty. Pass `delta` — the net change in `t="s"` cells (across
     * loaded worksheets) caused by the mutation just performed — to keep
     * the update O(1); omit it to force a full recount from the DOM.
     */
    updateSharedStringCounts(delta?: number): void;
    /**
     * True when the cell style index `s` resolves to a date/time number
     * format (built-in 14–22/45–47 or a custom date-token format).
     */
    isDateStyle(s: string | undefined): boolean;
    /**
     * Remove the calculation chain part + workbook relationship. Call after
     * any formula add/remove — a stale calcChain makes Excel repair the
     * file; Excel rebuilds the chain on demand.
     */
    dropCalcChain(): void;
    /**
     * The name attribute of EVERY workbook `<sheet>` entry in document
     * order — including chartsheets/macrosheets/dialogsheets that have no
     * worksheet lens. This is the index space of `definedName/@localSheetId`
     * (structure.ts must map sheet-scoped names through THIS list, not
     * through {@link sheets}).
     */
    sheetNames(): readonly string[];
    /** Internals of every modeled worksheet, in workbook order. */
    sheets(): readonly SheetInternal[];
}
/**
 * Capabilities of a `Worksheet` exposed to feature modules.
 * Obtained via `Worksheet._internal()`; implemented in index.ts.
 */
export interface SheetInternal {
    /** The owning workbook's internals. */
    readonly workbook: WorkbookInternal;
    /** The `<sheet>` entry element in workbook.xml. */
    readonly sheetEl: XmlElement;
    /** The worksheet part + live DOM. */
    readonly pd: PartDom;
    /** Sheet name as shown on the tab. */
    readonly name: string;
    /**
     * The `sheetData` element. With `create: true` it is created (in schema
     * order) when missing and the return type is non-optional.
     */
    sheetData(create: true): XmlElement;
    sheetData(create: boolean): XmlElement | undefined;
    /** The `row` element for 1-based `row`, or undefined. */
    findRow(row: number): XmlElement | undefined;
    /** Find or create the `row` element, inserted in ascending r order. */
    ensureRow(row: number): XmlElement;
    /** The `c` element at `addr`, or undefined. */
    findCell(addr: CellAddress): XmlElement | undefined;
    /**
     * Find or create the `c` element at `addr` (row created too), inserted
     * in ascending column order within its row.
     */
    ensureCell(addr: CellAddress): XmlElement;
    /** Flag this worksheet part dirty. */
    markDirty(): void;
}
//# sourceMappingURL=internal.d.ts.map