/** A single cell, 0-based: `row` is the data-row index, `col` the column index. */
export interface CellAddress {
    row: number;
    col: number;
}
/** A rectangular cell range (inclusive of both corners). */
export interface RangeAddress {
    start: CellAddress;
    end: CellAddress;
}
/**
 * Per-axis `$`-absoluteness of a reference (Tier 2). A bare `A1` is relative on
 * both axes; `$A$1` is absolute on both, `$A1` on the column only, `A$1` on the
 * row only. The resolved {@link CellAddress} is the same either way (relative
 * semantics manifest only when fill/copy rewrites the formula), so these flags
 * ride alongside the address and never reach the evaluator or dependency graph.
 */
export interface CellRefFlags {
    /** The column axis is fixed (`$A`): fill/copy never shifts it. */
    colAbsolute: boolean;
    /** The row axis is fixed (`$1`): fill/copy never shifts it. */
    rowAbsolute: boolean;
}
/** A parsed cell reference: its resolved address plus per-axis absoluteness. */
export interface ParsedCellRef extends CellRefFlags {
    address: CellAddress;
}
/** Maps between a column's data key and its stable A1 letter. */
export interface ColumnLetterMaps {
    /** Column key (stringified) to its A1 letter, e.g. `price` to `C`. */
    toLetter: Map<string, string>;
    /** A1 letter to column key, e.g. `C` to `price`. */
    toKey: Map<string, string>;
}
/** Type guard distinguishing a {@link RangeAddress} from a {@link CellAddress}. */
export declare function isRangeAddress(addr: CellAddress | RangeAddress): addr is RangeAddress;
/**
 * Convert A1 column letters to a 0-based column index (bijective base-26).
 * `A` to `0`, `Z` to `25`, `AA` to `26`. Case-insensitive.
 */
export declare function columnLetterToIndex(letters: string): number;
/**
 * Convert a 0-based column index to A1 column letters (the inverse of
 * {@link columnLetterToIndex}). `0` to `A`, `25` to `Z`, `26` to `AA`.
 */
export declare function indexToColumnLetter(index: number): string;
/**
 * Parse a single A1 cell token into its resolved address plus per-axis
 * `$`-absoluteness ({@link ParsedCellRef}). `$A$1`, `$A1`, `A$1`, and `A1` all
 * resolve to the same address; the `$` markers populate {@link CellRefFlags}.
 * Throws {@link ParseError} on malformed input.
 */
export declare function parseCellRef(token: string, position?: number): ParsedCellRef;
/**
 * Parse an A1 token into an address. `B2` yields a {@link CellAddress};
 * `A1:C3` yields a {@link RangeAddress}. Throws {@link ParseError} on malformed
 * input. The `position` is recorded on thrown errors so the editor can point at
 * the offending text.
 */
export declare function parseA1(token: string, position?: number): CellAddress | RangeAddress;
/**
 * Format a single cell address as A1 text, e.g. `{ row: 1, col: 2 }` to `C2`.
 * When `flags` mark an axis absolute, the corresponding `$` is emitted (`$C$2`).
 */
export declare function formatCell(addr: CellAddress, flags?: Partial<CellRefFlags>): string;
/**
 * Shift an address by (`dRow`, `dCol`), moving only the axes that `flags` leave
 * relative; absolute axes keep their value. Results are clamped at 0 so the
 * address stays well-formed; a target beyond the data surfaces as `#REF!` at
 * evaluation, exactly as an out-of-range literal reference would. Used by fill
 * and intra-grid paste to relocate a formula's references.
 */
export declare function offsetAddress(addr: CellAddress, dRow: number, dCol: number, flags?: Partial<CellRefFlags>): CellAddress;
/** Format a cell or range address as A1 text (`C2` or `A1:C3`). */
export declare function formatA1(addr: CellAddress | RangeAddress): string;
/**
 * Normalize a range so `start` is the top-left and `end` the bottom-right,
 * regardless of the order the corners were given in.
 */
export declare function normalizeRange(range: RangeAddress): RangeAddress;
/**
 * Enumerate every cell in a range in row-major order. Used by the dependency
 * graph (F3) to wire each cell of a range to the formula that reads it.
 */
export declare function rangeCells(range: RangeAddress): CellAddress[];
/**
 * Build the stable column-key to A1-letter maps from the grid's column list.
 * Letters are assigned by configuration order (`A` = first column, including
 * hidden ones), so a formula's references keep their meaning across reorder,
 * sort, and filter. The recalc layer (F3) uses {@link ColumnLetterMaps.toKey}
 * to resolve a parsed column index to the data key it reads.
 */
export declare function buildColumnLetters(columns: readonly {
    key: PropertyKey;
}[]): ColumnLetterMaps;