import { ColorSearchEngine } from './search';
import { ColorContrastDetail, ContextSurface, ContrastResult, FixabilityRecord, TokenCheckConfig } from './token-checks';
/**
 * Minimum shape the checker assumes about the override-color input. The checker
 * encapsulates everything actionColor-related (validation, suggestion search,
 * patching) — consumers don't need to wire those callbacks themselves.
 */
export interface ActionColorInput {
  actionColor?: string;
}
/**
 * Shape returned by the consumer's `generateOverrideThemes` callback.
 *
 * Compatible with vega-stencil's `OverrideColor` (`{ name: string; value: Nullable<string> }`).
 * `value` may be `undefined`/`null` when a token has no override for the supplied input —
 * such entries are dropped from the resulting token map.
 */
export interface OverrideTokenEntry {
  name: string;
  value?: string | null;
}
/**
 * Dependencies required by {@link VegaColorTokenContrastChecker}.
 *
 * Both inputs come from the consumer's design-system layer and stay outside this
 * package because they reference theme-system internals (vega-design's
 * `LightModeColorTokens` and vega-stencil's `VegaColorSchemaOverridingController`).
 *
 * @template TInput Shape of the override-color input. Must extend
 *   {@link ActionColorInput} so the checker can operate on `actionColor`.
 */
export interface CheckerDeps<TInput extends ActionColorInput> {
  /**
   * Source-of-truth design-token values for the static (non-actionColor-derived)
   * tokens the checker compares against. Format: `Record<tokenName, "r, g, b, a">`.
   * In vega-stencil this is `LightModeColorTokens`, generated by vega-design.
   */
  fixedSurfaceTokens: Record<string, string>;
  /**
   * Produce the override-token list for an input. Each entry's `value` is a CSS
   * `r g b / a` string (or `null`/`undefined` for "no override"). The checker
   * collapses this list into the resolved token map internally.
   *
   * In vega-stencil this is bound to `VegaColorSchemaOverridingController.generateOverrideThemes`.
   */
  generateOverrideThemes: (input: TInput) => readonly OverrideTokenEntry[];
}
/** Result of {@link VegaColorTokenContrastChecker.validate}. */
export interface ContrastCheckResult {
  /** `true` when every fixable-by-actionColor token passes WCAG. */
  isAccessible: boolean;
  /** Failing tokens that can be resolved by changing `actionColor`. */
  details: ColorContrastDetail[];
  /**
   * Closest accessible actionColor (by OKLab ΔE) for the suggestion search. Present
   * only when the input had an `actionColor`; equals the input value when the input
   * is already accessible.
   */
  suggestedActionColor?: string;
  /** `true` when the input's `actionColor` is not a valid hex string. */
  invalidInput?: boolean;
  /**
   * Token-level patches for tokens whose formula hard-caps contrast below the WCAG
   * threshold. Pass back to the override pipeline to apply repairs. Empty when none
   * are needed.
   */
  contrastCapPatches: Record<string, string>;
}
/**
 * WCAG 2.1 AA contrast checker for `actionColor`-driven theme overrides. Combines
 * the static token-pair catalogue (generated at build time) with consumer-supplied
 * design-token values and an override-themes generator, and exposes a single
 * pre-bound instance ready for `validate(input)` / `computeContrastCapPatches(input)`.
 *
 * Stateless against per-call inputs; holds a process-lifetime fixability cache keyed
 * by `(tokenName, pairedWith, compositedOn)` — that property depends only on the
 * catalogue and the override formulas, not on the user's input, so it can be probed
 * once.
 *
 * @template TInput Shape of the override-color input. In vega-stencil this is
 *   `VegaThemeOverrideColors`; tests can use a stricter or looser shape.
 */
export declare class VegaColorTokenContrastChecker<TInput extends ActionColorInput> {
  /** Static surfaces table, derived from {@link CheckerDeps.fixedSurfaceTokens}. */
  readonly fixedSurfaces: Readonly<Record<string, ContextSurface>>;
  /** Per-instance search engine, pre-bound to {@link fixedSurfaces}. */
  readonly search: ColorSearchEngine;
  private readonly deps;
  private fixabilityCache;
  private static readonly FIXABILITY_PROBE_COLORS;
  constructor(deps: CheckerDeps<TInput>);
  /**
   * Build the resolved token map for an input by collapsing
   * {@link CheckerDeps.generateOverrideThemes} into a `Map<tokenName, value>`,
   * dropping entries with empty values.
   *
   * Public so tests can assert on the materialized map and so the wrapper can
   * re-export it as a convenience helper.
   *
   * @param {TInput} input - Override-color payload.
   * @returns {Map<string, string>} Token name → CSS `r g b / a` value.
   */
  buildTokenMap(input: TInput): Map<string, string>;
  /**
   * Validate overrides against WCAG 2.1 AA (light mode).
   *
   * @param {TInput} input - Override-color payload to validate.
   * @returns {ContrastCheckResult} Accessibility result, including failing details and optional patches.
   */
  validate(input: TInput): ContrastCheckResult;
  /**
   * Produce contrast-cap patches for tokens whose formula caps contrast below threshold.
   *
   * Two-tier strategy (minimal impact first):
   *   1. α-ascent: raise alpha to meet contrast (preserves brand hue).
   *   2. RGB shift: closest opaque color satisfying ALL surfaces (linear scan).
   *
   * @param {TInput} input - Override-color payload (must include `actionColor`).
   * @returns {Record<string, string>} Map of tokenName → patched CSS value; empty if no repair needed.
   */
  computeContrastCapPatches(input: TInput): Record<string, string>;
  /**
   * Compute contrast for a single check using the supplied token map.
   *
   * @param {TokenCheckConfig} check - Check configuration.
   * @param {Map<string, string>} tokenMap - Resolved token map.
   * @returns {ContrastResult | null} Contrast result or null when token/surface can't be resolved.
   */
  computeTokenContrast(check: TokenCheckConfig, tokenMap: Map<string, string>): ContrastResult | null;
  /**
   * Resolve a `pairedWith` name to a {@link ContextSurface} using this checker's
   * static surface table.
   *
   * @param {string} pairedWith - Token name to resolve.
   * @param {Map<string, string>} tokenMap - Resolved token map (dynamic lookup wins).
   * @returns {ContextSurface | undefined} Resolved surface, or undefined.
   */
  resolvePairedSurface(pairedWith: string, tokenMap: Map<string, string>): ContextSurface | undefined;
  /**
   * Get the per-check fixability record (cached over the process lifetime).
   *
   * @param {TokenCheckConfig} config - Check configuration.
   * @returns {FixabilityRecord} `{ fixable, maxContrast }`.
   */
  getFixabilityRecord(config: TokenCheckConfig): FixabilityRecord;
  /**
   * Collect failing fixable tokens under the supplied token map.
   *
   * @param {Map<string, string>} tokenMap - Resolved token map.
   * @param {boolean} earlyExit - If true, return after first failure.
   * @returns {ColorContrastDetail[]} Array of failing token detail entries.
   */
  collectFailures(tokenMap: Map<string, string>, earlyExit?: boolean): ColorContrastDetail[];
  /**
   * Fast check: all fixable tokens pass contrast under the supplied token map.
   *
   * @param {Map<string, string>} tokenMap - Resolved token map.
   * @returns {boolean} True if all fixable tokens pass.
   */
  isAccessible(tokenMap: Map<string, string>): boolean;
  /** Empty `actionColor` is allowed (means "no override"); when present it must be a valid hex. */
  private static isValidActionColor;
  /** Produce a new input with a different `actionColor`, preserving every other field. */
  private withActionColor;
  private static fixabilityCacheKey;
  private buildFixabilityCache;
  /**
   * Find the closest accessible actionColor (by OKLab ΔE) within ±5° hue tolerance.
   *
   * @param {TInput} input - Current override input.
   * @param {string} actionColor - Current action color hex (already extracted by validate()).
   * @returns {string | undefined} Suggested hex, or undefined if none feasible.
   */
  private findSuggestedActionColor;
  /** Verify a candidate value passes all checks for a token. */
  private verifyCandidateSatisfiesAll;
}
