import type { Datum } from "../charts/shared/datumTypes";
import type { ChartCapability, ChartFamily } from "./chartCapabilityTypes";
import type { IntentId } from "./intents";
import type { AudienceProfile } from "./audienceProfile";
/**
 * describeChart — generate a layered natural-language description of a chart
 * from its `(component, props)` config, following Lundgard & Satyanarayan's
 * four-level model of semantic content (IEEE VIS 2021):
 *
 *   L1 (encoding)   — chart type and what's mapped to which channel.
 *   L2 (statistics) — ranges, mean, extrema (the level blind/low-vision
 *                     readers rank *most* useful, alongside L3).
 *   L3 (trends)     — overall direction and notable shape over an ordered axis.
 *   L4 (intent)     — the *illocutionary* sentence: what communicative act the
 *                     chart performs and which feature it asks the reader to act
 *                     on ("This is an alerting chart; the May spike warrants a
 *                     closer look."). Opt-in — only emitted when the caller
 *                     supplies the chart's capability descriptor (or an explicit
 *                     communicative act). Without that intent metadata, the
 *                     domain meaning stays the author's `summary` or an LLM's
 *                     job, as before.
 *
 * Pure, SSR-safe, dependency-light (the new capability/audience inputs are
 * type-only — no runtime registry pull). Wired into ChartContainer as an opt-in
 * full-accessibility affordance (see ChartContainer's `describe` prop); also
 * usable directly, surfaced by the accessibility audit, and composed by
 * `buildReaderGrounding` into the agent-reader payload.
 */
export type DescribeLevel = "l1" | "l2" | "l3" | "l4";
/**
 * The communicative act a chart performs — its illocutionary force, the verb
 * behind "what is this chart *doing*?". Derived from the dominant intent (or
 * the chart family as a fallback) and used to phrase the L4 sentence.
 */
export type CommunicativeAct = "alerting" | "tracking" | "comparing" | "ranking" | "apportioning" | "characterizing" | "relating" | "tracing" | "nesting" | "locating" | "presenting";
/**
 * Lightweight intent context for the L4 sentence. Either hand `describeChart`
 * a full {@link ChartCapability} (its static `intentScores` are read; function
 * scorers are skipped since no data profile is in scope here) or this resolved
 * shape — e.g. a `Suggestion`'s already-resolved `{ family, intentScores }`,
 * which is the most precise source.
 */
export interface DescribeCapabilityContext {
    /** Chart family — anchors the communicative act when intent scores are absent. */
    family?: ChartFamily;
    /** Per-intent scores (0..5), already resolved. The top-scoring intent picks the act. */
    intentScores?: Partial<Record<IntentId, number>>;
    /** Explicit override — skips intent/family inference entirely. */
    act?: CommunicativeAct;
}
export interface DescribeChartResult {
    /** The selected levels joined into one description (what you'd feed a summary). */
    text: string;
    /** Each level on its own, so callers can pick verbosity. */
    levels: {
        l1?: string;
        l2?: string;
        l3?: string;
        l4?: string;
    };
    /**
     * The author's marked features, as a sentence — present only when the chart
     * carries `annotations`. An annotation is author intent in its purest form,
     * so it leads `text` ahead of the auto-derived L1–L3: a non-visual or agent
     * reader hears what the author chose to call out first. Provenance-aware —
     * an AI- or watcher-authored note is qualified as such.
     */
    annotations?: string;
}
export interface DescribeChartOptions {
    /**
     * Which semantic levels to include. Default ["l1","l2","l3"]. L4 is appended
     * automatically when `capability` (or `capability.act`) is provided and
     * `levels` is left at the default; pass `levels` explicitly to override.
     */
    levels?: DescribeLevel[];
    /** Locale for number formatting. Default "en". */
    locale?: string;
    /**
     * Intent context that powers the L4 illocutionary sentence — a chart's
     * capability descriptor or a resolved {@link DescribeCapabilityContext}.
     * Closes the L1–L3 → L4 gap by joining the *production*-side intent metadata
     * (which already lives in each `*.capability.ts`) to the *reception*-side
     * description.
     */
    capability?: ChartCapability | DescribeCapabilityContext;
    /**
     * Audience profile — tunes the L4 sentence for reception. When the chart's
     * familiarity for this audience is low, L4 appends a brief orienting nudge so
     * an unfamiliar reader leans on the description.
     */
    audience?: AudienceProfile;
}
/** The communicative act a built-in intent implies, or undefined if unknown. */
export declare function communicativeActForIntent(intent: IntentId): CommunicativeAct | undefined;
/**
 * Resolve the communicative act for a chart from (in priority order) an explicit
 * act, the dominant resolved intent, the declared family, or the component's own
 * family classification. Returns undefined only when nothing identifies it.
 */
export declare function resolveCommunicativeAct(component: string, context: ChartCapability | DescribeCapabilityContext | undefined): CommunicativeAct | undefined;
/** Build a number formatter — compact (6.5M) for large magnitudes, plain
 *  otherwise. Exported so the navigation tree formats values identically. */
export declare function chartValueFormatter(locale?: string): (n: number) => string;
/**
 * One human phrase for a single annotation — its kind (provenance-qualified),
 * plus its label if it has one: `an AI-suggested callout labeled "Peak"`.
 * Exported so the navigation tree (`buildNavigationTree`) labels its annotation
 * nodes with the same vocabulary the prose description uses — tree and prose
 * speak the same language. Editorial status is *not* included here (it would
 * change the prose sentence); callers that want it append it themselves.
 */
export declare function annotationPhrase(ann: Datum): string;
export declare function describeChart(component: string, props: Datum, options?: DescribeChartOptions): DescribeChartResult;
