import type { ChartPluginSignature } from "../../models/index.mjs";
import type { UseChartInteractionSignature } from "../useChartInteraction/index.mjs";
import type { UseChartCartesianAxisSignature } from "../useChartCartesianAxis/index.mjs";
import type { UseChartHighlightSignature } from "../useChartHighlight/index.mjs";
import type { FocusedItemIdentifier, SeriesId } from "../../../../models/seriesType/index.mjs";
import type { ChartSeriesType } from "../../../../models/seriesType/config.mjs";
export interface FocusItemOptions {
  /**
   * Whether the focus indicator should be rendered.
   * Defaults to `focusItemOnClick || <the focus is already visible>`.
   */
  visible?: boolean;
}
/**
 * Called when the focused item is activated with the keyboard.
 * @param {KeyboardEvent} event The keyboard event that triggered the activation.
 * @param {FocusedItemIdentifier<ChartSeriesType>} item The activated item.
 */
export type ItemActivationHandler = (event: KeyboardEvent, item: FocusedItemIdentifier<ChartSeriesType>) => void;
/**
 * The items a handler covers. An empty scope covers every item.
 */
export interface ItemActivationScope {
  type?: ChartSeriesType;
  seriesId?: SeriesId;
  /**
   * Breaks ties between handlers covering the same items, highest first.
   * Mirrors pointer hit-testing, where marks sit above lines, and lines above areas.
   * @default 0
   */
  priority?: number;
  /**
   * When set, the handler is a candidate only for items it returns `true` for. Lets a plot decline
   * an item a pointer could not reach — e.g. a line mark that is not rendered — so activation falls
   * through to the next handler.
   * @param {FocusedItemIdentifier<ChartSeriesType>} item The focused item.
   * @returns {boolean} Whether the handler can activate this item.
   */
  canActivate?: (item: FocusedItemIdentifier<ChartSeriesType>) => boolean;
}
export interface UseChartKeyboardNavigationInstance {
  /**
   * Makes an item the one keyboard navigation starts from, moving the DOM focus into the chart
   * when it is not already there.
   * Does nothing when keyboard navigation is disabled, when the series type does not support it,
   * or when the identifier is not complete enough to be focused.
   * @param {FocusedItemIdentifier} item The item to focus.
   * @param {FocusItemOptions} options Options to override the focus visibility.
   * @returns {boolean} `true` when the focus state was updated.
   */
  focusItem: (item: FocusedItemIdentifier<ChartSeriesType>, options?: FocusItemOptions) => boolean;
  /**
   * Registers a handler triggered when the focused item is activated with the keyboard.
   * Only the handler with the most specific matching scope runs, so plots sharing a series
   * do not fire the callback twice.
   * @param {ItemActivationScope} scope The items the handler covers.
   * @param {ItemActivationHandler} handler The handler to call on activation.
   * @returns {() => void} A cleanup function unregistering the handler.
   */
  registerItemActivationHandler: (scope: ItemActivationScope, handler: ItemActivationHandler) => () => void;
  /**
   * Asks for the visible zoom range to be announced to screen readers.
   * Called by the plugin owning keyboard zoom and pan, on each change the user makes with the keys.
   * @returns {void}
   */
  announceZoomChange: () => void;
}
export interface UseChartKeyboardNavigationState {
  keyboardNavigation: {
    /**
     * The item with keyboard focus. It is `null` when no item is focused.
     */
    item: null | FocusedItemIdentifier<ChartSeriesType>;
    /**
     * If `false` the focus is ignored, but we keep the item in the state to be able to restore it when focus is active again.
     */
    isFocused: boolean;
    /**
     * If `false` the focused item is not rendered as focused, and does not drive the highlight and tooltip.
     * Set when the focus was moved by a pointer instead of the keyboard. Implies `isFocused`.
     */
    isFocusVisible: boolean;
    /**
     * Indicates whether keyboard navigation is enabled or not.
     */
    enabled: boolean;
    /**
     * Incremented on each zoom change the user makes with the keyboard, and reset when the chart
     * loses focus. The live region reads the visible range when it changes, so a zoom coming from
     * the pointer or from the application is not announced.
     */
    zoomAnnouncement: number;
  };
}
type UseChartKeyboardNavigationParameters = {
  /**
   * If `true`, disables keyboard navigation for the chart.
   */
  disableKeyboardNavigation?: boolean;
  /**
   * If `true`, clicking an item immediately shows the keyboard focus indicator on it.
   * By default, clicking sets the item that keyboard navigation starts from, but the focus
   * indicator stays hidden until the user presses a key.
   * @default false
   */
  focusItemOnClick?: boolean;
};
export type UseChartKeyboardNavigationSignature = ChartPluginSignature<{
  params: UseChartKeyboardNavigationParameters;
  defaultizedParams: UseChartKeyboardNavigationParameters;
  instance: UseChartKeyboardNavigationInstance;
  state: UseChartKeyboardNavigationState;
  optionalDependencies: [UseChartInteractionSignature, UseChartHighlightSignature<ChartSeriesType>, UseChartCartesianAxisSignature];
}>;
export {};