import type { Datum } from "../charts/shared/datumTypes";
import type { ChartDataProfile, Suggestion } from "./chartCapabilityTypes";
import type { IntentId } from "./intents";
import { type AudienceProfile } from "./audienceProfile";
/**
 * A "stretch pick" — an unfamiliar-but-fitting chart paired with the
 * familiar chart it could substitute for. Pairing makes the literacy
 * suggestion concrete: "instead of BarChart, try BoxPlot here, because…"
 */
export interface StretchSuggestion {
    /** The unfamiliar chart we're suggesting as growth. */
    suggestion: Suggestion;
    /**
     * The familiar chart this stretch could replace for the same intent.
     * Undefined when the stretch is recommended on its own merits (e.g. a
     * direct "increase" target with no obvious familiar counterpart).
     */
    replacing?: string;
    /** Human-readable rationale, suitable for verbatim display. */
    rationale: string;
    /** Audience familiarity for this chart — the number that made it qualify as a stretch. */
    familiarity: number;
}
export interface SuggestStretchChartsOptions {
    /** Intent(s) to rank by. When omitted, charts are picked by data fit alone. */
    intent?: IntentId | IntentId[];
    /** Required — without an audience profile, the concept of "stretch" doesn't apply. */
    audience?: AudienceProfile;
    /** Restrict to these component names. */
    allow?: ReadonlyArray<string>;
    /** Exclude these component names. */
    deny?: ReadonlyArray<string>;
    /** Max stretch picks to return (default 5). */
    maxResults?: number;
    /** Pre-built profile. */
    profile?: ChartDataProfile;
    /** Non-tabular payload — forwarded to profileData. */
    rawInput?: unknown;
    /**
     * Only return stretches within this score distance of the top familiar pick
     * (default 1.5). Tighter values keep the suggestions plausible; wider values
     * expose more variety.
     */
    scoreTolerance?: number;
}
/**
 * Find pairs (familiar, stretch) where the stretch chart fits the data,
 * has audience familiarity at or below the stretch ceiling, and either:
 *   • is an `increase` target for this audience, OR
 *   • scores within `scoreTolerance` of a familiar alternative for the
 *     same intent.
 *
 * Each pair is returned as a StretchSuggestion with `replacing` (the
 * familiar chart it could substitute for) and a rationale string.
 *
 * Heuristic only. Use `audience` with care — without target signals, every
 * audience-unfamiliar chart becomes a candidate, which can drown the
 * surface in dubious recommendations.
 */
export declare function suggestStretchCharts(data: ReadonlyArray<Datum> | null | undefined, options?: SuggestStretchChartsOptions): StretchSuggestion[];
