import type { FormulaAstNode, FormulaCellRefNode, FormulaColumnValuesNode, FormulaFieldRefNode, FormulaRangeRefNode } from "./formulaAst.mjs";
import type { FormulaPositionContext, FormulaSourceSpan } from "./formulaTypes.mjs";
/**
 * The reference-bearing AST node kinds the editor colors and the grid outlines.
 * A `rangeRef`/`cellRef`/`columnValues`/`fieldRef` is one reference: the whole
 * node is one colored chunk, never its inner axes.
 */
export type FormulaReferenceNode = FormulaFieldRefNode | FormulaCellRefNode | FormulaRangeRefNode | FormulaColumnValuesNode;
/**
 * A reference scanned from formula source, dialect-agnostic. `spans` are
 * offsets into the EXPRESSION (without the leading `=`), in the shown dialect's
 * coordinates. `node` carries the selectors the grid adapter resolves against a
 * position context to a concrete cell/range/column target. Spans are a list to
 * leave room for the canonical inner-identity refinement (one node, several
 * colored chunks); the producers below emit exactly one span per reference.
 */
export interface FormulaRawReference {
  spans: FormulaSourceSpan[];
  node: FormulaReferenceNode;
}
/**
 * Collects references from a parsed canonical AST. A `rangeRef` is taken whole
 * so the editor colors the entire `RANGE_REF(...)` chunk and the grid draws one
 * rectangle. References are returned in source order (by span start) so palette
 * colors cycle stably.
 */
export declare function collectCanonicalReferences(ast: FormulaAstNode): FormulaRawReference[];
/**
 * Scans references straight out of A1 source. Forked from the `toCanonicalFormula`
 * scan loop and sharing its tokenization primitives, so the highlighted tokens
 * are exactly the ones the commit transform rewrites — they can never disagree.
 * Unlike the canonical walk, this is textual and robust to a half-typed formula:
 * it colors `B5` even when the rest of the expression does not yet parse.
 *
 * Records A1-source spans directly (the canonical AST built from A1 input has no
 * usable spans — `toCanonicalFormula` stamps `ZERO_SPAN` on every rewritten
 * node). The selector nodes are built with the same `buildCellRefNode` /
 * `buildColumnValuesNode` the commit uses, so resolution is dialect-uniform.
 */
export declare function scanA1References(expression: string, positionContext: FormulaPositionContext): FormulaRawReference[];
/**
 * Produces the dialect-appropriate reference list for an expression (without the
 * leading `=`). A1 mode scans the A1 text directly; canonical mode walks the
 * parsed AST. Both yield `FormulaRawReference[]` with expression-relative spans
 * and selector nodes the grid adapter resolves and colors.
 */
export declare function buildFormulaReferences(expression: string, options: {
  a1Notation: boolean;
  positionContext: FormulaPositionContext;
}): FormulaRawReference[];