import type { NavTreeNode } from "./navigationTree";
import type { Datum } from "../charts/shared/datumTypes";
/**
 * useNavigationSync — keep an `AccessibleNavTree` and a chart in sync, both ways:
 *
 *   tree → canvas : landing on a datum node highlights the matching mark (via
 *                   the selection store — pass `selection` to the chart).
 *   canvas → tree : hovering/clicking a mark moves the tree's active node (via
 *                   the observation store — give the chart a `chartId`).
 *
 * Both directions ride the existing module-global stores, so **no provider is
 * required** — the chart just needs `chartId` and `selection={sync.selection}`,
 * and the tree needs `activeId`/`onActiveChange`. Headless: BYO layout.
 *
 * @example
 * const sync = useNavigationSync({ tree, chartId: "sales", matchFields: ["month"] })
 * <LineChart chartId="sales" selection={sync.selection} {...props} />
 * <AccessibleNavTree tree={tree} activeId={sync.activeId} onActiveChange={sync.onActiveChange} />
 */
export interface UseNavigationSyncOptions {
    /** The navigation tree (from `buildNavigationTree`). */
    tree: NavTreeNode;
    /** `chartId` set on the chart, so its hover/click can be matched back to a leaf. */
    chartId?: string;
    /**
     * Fields that identify a datum for highlighting + matching. Defaults to the
     * primitive-valued keys of the first leaf's datum.
     */
    matchFields?: string[];
    /** Selection name shared with the chart's `selection={{ name }}`. Default "__semiotic-nav-sync". */
    selectionName?: string;
    /** Which canvas observations move the tree. Default ["hover", "click"]. */
    observe?: Array<"hover" | "click">;
    /**
     * The chart's annotations. An annotation anchored to a datum carries that
     * datum's identifying fields (the same `matchFields` used for hover sync), so
     * each one resolves to a nav-tree leaf. Lets a non-visual reader *reach* an
     * anchored point — e.g. an AI's "anchored conversation" note — via
     * `focusAnnotation`, and lets the tree mark annotated nodes via `annotatedIds`.
     */
    annotations?: ReadonlyArray<Datum>;
}
export interface UseNavigationSyncResult {
    /** Controlled active node id — pass to `AccessibleNavTree`. */
    activeId: string;
    /** Change handler — pass to `AccessibleNavTree` (drives the canvas highlight). */
    onActiveChange: (node: NavTreeNode) => void;
    /** Pass to the chart as `selection={sync.selection}`. */
    selection: {
        name: string;
    };
    /** Nav-tree leaf ids that an annotation anchors to — mark these as "has a note". */
    annotatedIds: Set<string>;
    /**
     * Move the tree (and canvas highlight) to an annotation's anchored node.
     * Accepts an annotation object or its index in `annotations`. Returns `true`
     * if the anchor resolved to a leaf. The reader lands on the anchored datum.
     */
    focusAnnotation: (annotation: Datum | number) => boolean;
}
export declare function useNavigationSync(options: UseNavigationSyncOptions): UseNavigationSyncResult;
