/**
 * Keyboard navigation utilities for Stream Frames.
 *
 * Supports two navigation modes:
 * - **Flat**: ArrowRight/Left and ArrowUp/Down both advance linearly (geo, simple charts)
 * - **Graph**: ArrowRight/Left navigates within a series/group, ArrowUp/Down switches
 *   between series/groups at a similar position (XY lines, stacked bars, networks)
 *
 * Reuses the existing hover/tooltip system — keyboard focus sets the same
 * HoverData state that mouse hover does.
 */
import type { HoverData } from "../realtime/types";
import type { Datum } from "../charts/shared/datumTypes";
import type { NetworkSceneEdge, NetworkSceneNode } from "./networkTypes";
import type { SceneNode } from "./types";
import type { OrdinalSceneNode } from "./ordinalTypes";
import type { GeoSceneNode } from "./geoTypes";
export interface NavPoint {
    x: number;
    y: number;
    datum: Datum | null;
    /** Shape hint for focus ring rendering */
    shape?: "circle" | "rect" | "wedge";
    /** Width of rect-shaped elements (bars, sankey nodes) */
    w?: number;
    /** Height of rect-shaped elements */
    h?: number;
    /** Group identifier for graph navigation (series name, category, node id) */
    group?: string;
    /** Index in NavGraph.flat — set by buildNavGraph for O(1) lookup */
    _flatIndex?: number;
    /** Index within its group — set by buildNavGraph for O(1) resolvePosition */
    _groupIndex?: number;
}
/**
 * A navigation graph that organizes NavPoints into groups (series/categories)
 * and positions within each group, enabling 2D keyboard navigation.
 *
 * ArrowRight/Left = next/prev within the current group (e.g. along a line series)
 * ArrowUp/Down = switch to the nearest point in an adjacent group (e.g. switch series)
 */
export interface NavGraph {
    /** All points in flat order (for PageUp/Down, Home/End) */
    flat: NavPoint[];
    /** Group names in stable order */
    groups: string[];
    /** Points per group, in position order */
    byGroup: Map<string, NavPoint[]>;
    /** Precomputed node id → flat index lookup (for network navigation) */
    idToIdx: Map<string, number>;
}
export interface NavPosition {
    /** Index into NavGraph.flat */
    flatIndex: number;
    /** Current group name */
    group: string;
    /** Index within the current group */
    indexInGroup: number;
}
/**
 * Build a navigation graph from grouped NavPoints.
 * Points within each group are sorted by x then y.
 * Groups are sorted by their first-point y position (top to bottom).
 */
export declare function buildNavGraph(points: NavPoint[]): NavGraph;
/**
 * Resolve the current NavPosition from a flat index.
 * Clamps to valid range if the index is stale (e.g. scene changed between key presses).
 */
export declare function resolvePosition(graph: NavGraph, flatIndex: number): NavPosition;
/**
 * Compute the next navigation position given a key press and current position.
 * Returns the flat index into graph.flat, -1 to clear, or null for unhandled keys.
 */
export declare function nextGraphIndex(key: string, pos: NavPosition, graph: NavGraph): number | null;
/**
 * Extract navigable data points from XY scene nodes.
 * Lines/areas carry a `group` field identifying the series.
 * ArrowRight/Left = within series, ArrowUp/Down = switch series.
 */
export declare function extractXYNavPoints(scene: SceneNode[]): NavPoint[];
/**
 * Extract navigable points from ordinal scene nodes.
 * Bars use `node.group` (stack/group key) falling back to `datum.category`.
 * ArrowRight/Left = across categories, ArrowUp/Down = within stacked segments.
 */
export declare function extractOrdinalNavPoints(scene: OrdinalSceneNode[]): NavPoint[];
/**
 * Extract navigable points from network scene nodes.
 * Each node's group is its own id, enabling neighbor traversal via edges.
 */
export declare function extractNetworkNavPoints(scene: NetworkSceneNode[]): NavPoint[];
/**
 * Network-specific navigation: spatial arrow keys + edge following.
 *
 * ArrowRight/Left/Up/Down: move to the nearest node in that direction.
 * Enter: follow an edge to a connected neighbor of the current node.
 * PageUp/Down, Home/End, Escape: flat navigation.
 *
 * Returns the flat index of the target node, -1 to clear, or null for unhandled keys.
 */
export declare function nextNetworkIndex(key: string, pos: NavPosition, graph: NavGraph, edges: EdgeLike[], neighborIndexRef: {
    current: number;
}): number | null;
/** Collect neighbor node ids from edge list for a given node. */
type EdgeLike = NetworkSceneEdge | {
    source?: unknown;
    target?: unknown;
    datum?: Datum | null;
};
/**
 * Extract navigable points from geo scene nodes.
 * Flat navigation only (no meaningful grouping for geo).
 */
export declare function extractGeoNavPoints(scene: GeoSceneNode[]): NavPoint[];
/**
 * Compute the next focus index given a key and current index.
 * Returns -1 to clear focus. Returns null for unhandled keys.
 *
 * Used by Geo frame (flat navigation) and as fallback.
 */
export declare function nextIndex(key: string, current: number, total: number): number | null;
/**
 * Convert a NavPoint to HoverData for the tooltip system.
 */
export declare function navPointToHover(point: NavPoint): HoverData;
export {};
