import type { FormulaCellRefNode, FormulaColumnValuesNode, FormulaRangeRefNode } from "./formulaAst.js";
import type { ParsedRef } from "./formulaA1Tokens.js";
import type { FormulaCellRef, FormulaPositionContext } from "./formulaTypes.js";
/**
 * 1-based column index to bijective base-26 letters: `1` → `"A"`, `26` → `"Z"`,
 * `27` → `"AA"`. Returns `""` for non-positive or non-integer input.
 */
export declare function columnIndexToLetters(index: number): string;
/**
 * Inverse of `columnIndexToLetters` (case-insensitive). `"A"` → `1`, `"AA"` → `27`.
 * Returns `0` when any character is not a Latin letter.
 */
export declare function columnLettersToIndex(letters: string): number;
/**
 * `true` when a field name is lexically an A1 cell address (`q1`, `AB12`): the
 * A1 scanners would read the bare name as a cell reference, so the A1 dialect
 * must write such a field through the `FIELD("…")` escape.
 */
export declare function isA1AmbiguousFieldName(field: string): boolean;
export interface A1TransformContext {
  positionContext: FormulaPositionContext;
  /**
   * The cell the formula is being committed to / displayed for. Plain range
   * endpoints freeze to `ANCHOR(delta)` offsets from this cell when it sits in
   * the data band, and anchor axes render as `anchorPosition + delta` at
   * display time. Without it (or with a pinned/positionless cell), plain range
   * endpoints freeze to absolute positions and anchor axes display in
   * canonical form inline.
   */
  anchorCell?: FormulaCellRef;
}
export interface ToCanonicalOptions {
  /**
   * Added to relative (no-`$`) column positions — the Excel-style fill
   * adjustment applied when an A1 formula is pasted away from its origin.
   * Single-cell refs freeze the offset position to an identity; range window
   * axes freeze the offset position (as an anchor delta for in-band anchors).
   * @default 0
   */
  columnOffset?: number;
  /**
   * Added to relative (no-`$`) row positions.
   * @default 0
   */
  rowOffset?: number;
}
/**
 * The freeze target for plain range axes: the committing cell's view position,
 * or `null` when plain axes must freeze to absolute positions instead — no
 * anchor cell supplied, its row filtered out or pinned (outside the data
 * band), or its column hidden. The band test is on the ROW: a pinned summary's
 * window must not follow anything, its column axes included, so band
 * membership decides the whole endpoint at once.
 */
export declare function getRangeFreezeAnchor(context: FormulaPositionContext, anchorCell: FormulaCellRef | undefined): {
  rowIndex: number;
  columnIndex: number;
} | null;
export interface A1TransformResult {
  /**
   * The expression in canonical syntax (without the leading `=`). Unrecognized
   * text is copied through unchanged, so a malformed A1 expression yields a
   * malformed canonical expression that fails as `#ERROR!` at evaluation —
   * consistent with the permissive-commit rule.
   */
  source: string;
  /**
   * `true` when at least one A1 reference token was rewritten — lets the adapter
   * skip the canonical store when nothing changed.
   */
  changed: boolean;
}
export declare function buildCellRefNode(ref: ParsedRef, context: FormulaPositionContext, columnOffset: number, rowOffset: number): FormulaCellRefNode;
/**
 * Builds the window for an A1 range (`A1:B5`). A `$` axis stores its absolute
 * view position; a plain axis stores an `ANCHOR` offset from `anchor` (the
 * committing in-band cell) or, without an anchor, the absolute position in
 * today's non-fixed form. Out-of-view positions are stored as written and clip
 * (positional) or error (anchor) at resolve time.
 */
export declare function buildRangeRefNode(startRef: ParsedRef, endRef: ParsedRef, columnOffset: number, rowOffset: number, anchor?: {
  rowIndex: number;
  columnIndex: number;
} | null): FormulaRangeRefNode;
export declare function buildColumnValuesNode(range: {
  letters: string;
  absolute: boolean;
}, context: FormulaPositionContext, columnOffset: number): FormulaColumnValuesNode | null;
/**
 * Rewrites an A1-dialect expression (without the leading `=`) into the canonical
 * dialect. Never throws.
 */
export declare function toCanonicalFormula(expression: string, context: A1TransformContext, options?: ToCanonicalOptions): A1TransformResult;
/**
 * Renders a canonical expression (without the leading `=`) into A1 notation for
 * editing. References whose identity has no current position (hidden column,
 * filtered-out row) and anchor-relative range axes without a renderable
 * position fall back to canonical form inline. Never throws; returns the input
 * unchanged when it is not parseable as canonical.
 */
export declare function toDisplayFormula(expression: string, context: A1TransformContext): string;