import type { AnnotationContext } from "../realtime/types";
import type { Datum } from "../charts/shared/datumTypes";
import { type AnnotationDensityConfig } from "./annotationDensity";
export interface AnnotationLayoutConfig {
    /** Distance from the anchor for the first candidate ring. */
    defaultOffset?: number;
    /** Gap around note boxes when testing note-note collisions. */
    notePadding?: number;
    /** Gap around point marks when testing note-mark collisions. */
    markPadding?: number;
    /** Gap from the plot edge, used as a cheap axis-occlusion proxy. */
    edgePadding?: number;
    /** Preserve annotations that already declare either dx or dy. Default true. */
    preserveManualOffsets?: boolean;
    /** Use a curved connector when auto-placement has to route far from the target. */
    routeLongConnectors?: boolean;
    /** Distance threshold for routeLongConnectors. */
    connectorThreshold?: number;
    /**
     * M3 — amount & density management. When set, after placement the lowest-
     * priority note-like annotations are shed so the plot is not over-crowded
     * (`true` uses the area-derived default budget; an object tunes it). Reference
     * lines, bands and overlays are never shed. Off by default.
     */
    density?: boolean | AnnotationDensityConfig;
    /**
     * M3 — progressive disclosure. When `true`, notes shed by `density` (M3) or
     * the `responsive` breakpoint (M5) are kept in the output tagged
     * `_annotationDeferred` (hidden by default, revealed on chart hover/focus)
     * instead of dropped. The persistent set is always rendered, so a non-hover
     * reader still sees the core notes. No effect unless a shedding pass is on.
     */
    progressiveDisclosure?: boolean;
    /**
     * M4 — redundant-cue default (Rahman et al.'s "Association"). A colored
     * `text` note is the one note type that never draws a connector, so it ties
     * to its target by color alone — invisible to a color-blind or non-visual
     * reader. When `true`, an offset colored `text` note is flagged
     * `_redundantConnector` so the renderer adds a faint leader line from the
     * anchor to the text: a spatial cue, not another color. Off by default.
     */
    redundantCues?: boolean;
    /**
     * M5 — responsive annotation behavior. As the plot narrows past `minWidth`
     * (default 480px), `secondary`-emphasis notes are shed by *importance* — a
     * complement to `density`'s count budget. Pass `true` for the default
     * breakpoint or `{ minWidth }` to tune it. With `progressiveDisclosure`,
     * shed notes are deferred (revealable) rather than dropped. Primary and
     * unmarked notes are always kept. Off by default.
     */
    responsive?: boolean | {
        minWidth?: number;
    };
    /**
     * M5 — cohesion mode (Rahman et al.'s "Cohesion"). `"blended"` lets notes
     * adopt the chart's visual language (mark colors / chart typography — the
     * default look); `"layer"` presents them as a distinct editorial layer
     * (annotation-color, italic editorial type). Stamped onto note-like
     * annotations that don't set their own `cohesion`; a per-annotation
     * `cohesion` always wins. Off (inherit) by default.
     */
    cohesion?: AnnotationCohesion;
    /**
     * M6 — audience adaptation. An `AudienceProfile` (structurally, anything with
     * a `familiarity` map) biases annotation *amount*: a low-familiarity audience
     * keeps more notes (orienting context), an expert audience fewer. It scales
     * the `density` budget, so it only takes effect when `density` is engaged.
     */
    audience?: AnnotationAudience;
}
export type AnnotationCohesion = "blended" | "layer";
/** Structural subset of `AudienceProfile` the annotation layer reads — anything
 *  with a per-chart `familiarity` map satisfies it, so a real `AudienceProfile`
 *  can be passed directly without coupling `recipes` to the `ai` module. */
export interface AnnotationAudience {
    name?: string;
    familiarity?: Partial<Record<string, number>>;
}
export type AutoPlaceAnnotationsConfig = AnnotationLayoutConfig;
export type AutoPlaceAnnotations = boolean | AutoPlaceAnnotationsConfig;
export interface AnnotationLayoutOptions extends AnnotationLayoutConfig {
    annotations: ReadonlyArray<Datum>;
    context: AnnotationContext;
}
/**
 * Pure annotation placement recipe.
 *
 * It clones note-like annotations that do not already declare `dx`/`dy`, picks
 * an adjacent candidate offset, and leaves every other annotation untouched.
 * The pass is deterministic and geometry-only; renderers still own the actual
 * SVG/HTML annotation drawing.
 */
export declare function annotationLayout(options: AnnotationLayoutOptions): Datum[];
