import type { FormulaFunctionRegistry } from "./formulaFunctions.mjs";
/**
 * The category a completion token belongs to. Drives the ranking tier and lets
 * the editor group/icon suggestions. `field` and `columnLetter` are produced by
 * the grid adapter (the engine never sees columns) but live here so the pure
 * ranker can tier them consistently with the static vocabulary.
 */
export type FormulaCompletionKind = 'function' | 'specialForm' | 'constant' | 'operator' | 'field' | 'columnLetter';
export interface FormulaCompletionToken {
  /**
   * Text shown in the dropdown.
   */
  label: string;
  /**
   * Text spliced at the caret. For `callable` tokens the editor appends `(`
   * with the caret placed inside.
   */
  insertText: string;
  kind: FormulaCompletionKind;
  /**
   * Functions and special forms take arguments — inserting one opens a `(`.
   */
  callable?: boolean;
  /**
   * One-line call signature, e.g. `SUM(value1, value2, …)`. Shown as signature
   * help when the caret is inside the call and as a secondary line in the list.
   */
  signature?: string;
  description?: string;
  category?: string;
  /**
   * Optional secondary text (a field's header name, or a column letter's field).
   */
  detail?: string;
}
export interface FormulaCompletionContext {
  /**
   * The partial identifier the caret sits in or right after — the prefix used
   * for matching (`''` when the caret is not on an identifier).
   */
  token: string;
  /**
   * Replace span in EXPRESSION coordinates (the source WITHOUT its leading `=`).
   * Accepting a suggestion replaces `expression.slice(replaceStart, replaceEnd)`.
   */
  replaceStart: number;
  replaceEnd: number;
  /**
   * The caret is in a value position: the start of the expression, or right
   * after `(`, `,` or a binary operator. Functions, fields and constants are
   * offered; operators are suppressed.
   */
  expectValue: boolean;
  /**
   * The caret follows a complete operand (`)`, a number, a string, an
   * identifier): a binary operator is expected next, so value tokens are
   * suppressed.
   */
  expectOperator: boolean;
  /**
   * The caret is inside a string literal (terminated or not) — suggestions are
   * suppressed entirely.
   */
  insideString: boolean;
  /**
   * The caret follows the A1 range operator (`A1:|`, `A1:D|`): a cell reference
   * is the only thing that can come next, so only column letters are offered.
   * Always `false` outside A1 notation, which has no range operator.
   */
  expectReference: boolean;
  /**
   * The caret sits strictly inside a complete reference token (`A1:D|5`) rather
   * than at either end of it. There is nothing to complete — the reference is
   * whole — so suggestions are suppressed.
   */
  insideReference: boolean;
  /**
   * The innermost enclosing function/special-form call, for signature help.
   * `argIndex` is the zero-based argument the caret is in.
   */
  functionContext: {
    name: string;
    argIndex: number;
  } | null;
}
/**
 * Builds the static completion vocabulary: registry functions (with whatever
 * optional metadata they declare — custom functions included), the canonical
 * special forms, the boolean constants and the binary operators. When no
 * registry is passed the built-in function set is used.
 */
export declare function getFormulaCompletionTokens(functions?: FormulaFunctionRegistry): FormulaCompletionToken[];
export interface FormulaCompletionContextOptions {
  /**
   * `true` when the expression is written in the A1 editor dialect, so that
   * `$A$1`, `A1:B2` and `A:A` are read as single references. The editor shows
   * whichever dialect the grid is configured for and completion must analyze
   * the same one — a canonical tokenization of A1 text stops dead at the first
   * `:` or `$` and reports a stale enclosing call for everything after it.
   * @default false
   */
  a1Notation?: boolean;
}
/**
 * Analyzes the caret in a formula expression (the source WITHOUT its leading
 * `=`) and returns the partial token, replace span, coarse value/operator
 * context, string-literal guard and enclosing call for signature help. Built on
 * a tolerant tokenization, so partial and malformed input is safe.
 */
export declare function getFormulaCompletionContext(expression: string, caret: number, options?: FormulaCompletionContextOptions): FormulaCompletionContext;
export interface RankFormulaCompletionsOptions {
  /**
   * Maximum number of ranked suggestions to return.
   * @default 8
   */
  limit?: number;
}
/**
 * Pure ranking: filters the token list by the caret context's partial token and
 * orders by `prefix-match strength × category tier`. Suppresses operators in a
 * value position, value tokens in an operator position, everything but column
 * letters after the range operator, and everything inside a string literal,
 * inside a complete reference, or in an operator position with no typed prefix.
 */
export declare function rankFormulaCompletions(tokens: readonly FormulaCompletionToken[], context: FormulaCompletionContext, options?: RankFormulaCompletionsOptions): FormulaCompletionToken[];