chart-shell headless API

export declare const CHART_SHELL_CHILD_NAMES: readonly ["tooltip", "legend", "selection", "brush", "zoom", "keyboard"];

export declare const CHART_SHELL_VISUALLY_HIDDEN_STYLE: "border: 0; clip: rect(0px, 0px, 0px, 0px); clip-path: inset(50%); height: 1px; margin: -1px; overflow: hidden; padding: 0; position: absolute; white-space: nowrap; width: 1px";

export declare const CHART_SHELL_VISUALLY_HIDDEN_STYLE_OBJECT: Record<string, string>;

type ChartActiveTargetChangeDetail = {
  readonly id: string | null;
  readonly reason: ChartTargetReason;
};

type ChartDomainChangeReason = "brush" | "wheel" | "pan" | "pinch" | "keyboard" | "programmatic";

type ChartDomainScalar = string | number;

interface ChartEventBounds {
  readonly left: number;
  readonly top: number;
  readonly width: number;
  readonly height: number;
}

interface ChartKeyboardMoveOptions {
  readonly step?: number;
  readonly shiftStep?: number;
}

declare function chartKeydownIntent(key: string): ChartShellKeyboardIntent;

type ChartLegendPosition = "top" | "right" | "bottom";

type ChartLegendViewConfig = {
  readonly ariaLabel?: string;
  readonly position?: ChartLegendPosition;
};

type ChartLegendViewModel<TItem> = {
  readonly items: readonly (TItem & {
    readonly active: boolean;
  })[];
  readonly position: ChartLegendPosition;
  readonly ariaLabel: string | undefined;
};

interface ChartPoint2D {
  readonly x: number;
  readonly y: number;
}

interface ChartPointerEventOptions {
  readonly bounds?: ChartEventBounds;
  readonly plotOffset?: ChartPoint2D;
  readonly clamp?: boolean;
}

type ChartPointerSource = "pointer" | "mouse" | "touch" | "keyboard" | "unknown";

export declare const chartShellAnatomy: {
  readonly scope: "chart-shell";
  readonly parts: readonly ["root", "plot", "live-region"];
};

interface ChartShellApi {
  rootProps(): PartProps;
  plotProps(): PartProps;
  liveRegionProps(): PartProps;
  readonly tooltipOpen: boolean;
  readonly activeId: string | null;
  readonly selectedIds: readonly string[];
  readonly brushDomain: ChartXDomain;
  readonly zoomDomain: ChartXDomain;
}

type ChartShellCommand = ChartTooltipChildCommand | ChartLegendChildCommand | SelectionCommand | ChartBrushChildCommand | ChartZoomChildCommand | ChartKeyboardChildCommand;

interface ChartShellConnectOptions {
  readonly onSelectedIdsChange?: (detail: SelectionChangeDetail) => void;
  readonly onActiveTargetChange?: (detail: ChartActiveTargetChangeDetail) => void;
  readonly onOpenChange?: (detail: ChartTooltipOpenChangeDetail) => void;
  readonly onHiddenSeriesChange?: (detail: {
    readonly ids: readonly string[];
    readonly reason: string;
  }) => void;
  readonly onBrushDomainChange?: (detail: {
    readonly domain: unknown;
    readonly reason: string;
  }) => void;
  readonly onZoomDomainChange?: (detail: {
    readonly domain: unknown;
    readonly reason: string;
  }) => void;
  readonly announce?: (key: string, args: {
    readonly [key: string]: string | number | null;
  }, politeness: "polite" | "assertive") => void;
}

type ChartShellContext = {
  readonly tooltip: ChartTooltipChildState | null;
  readonly legend: ChartLegendChildState | null;
  readonly selection: SelectionMachineState | null;
  readonly brush: ChartBrushChildState | null;
  readonly zoom: ChartZoomChildState | null;
  readonly keyboard: ChartKeyboardChildState | null;
};

interface ChartShellController {
  readonly listenerCount: () => number;
  attach(service: ChartShellService): void;
  start(): void;
  update(host: Partial<ChartShellControllerHost>): void;
  destroy(): void;
}

interface ChartShellControllerHost {
  readonly getRoot?: () => HTMLElement | null;
  readonly getPlot?: () => HTMLElement | null;
  readonly hitTest?: (event: NormalizedChartPointerEvent) => string | null;
  readonly toDomain?: (event: NormalizedChartPointerEvent) => ChartDomainScalar | null;
  readonly bounds?: () => ChartEventBounds | undefined;
  readonly plotOffset?: () => ChartPoint2D | undefined;
}

type ChartShellEvent = ChartTooltipChildEvent | ChartLegendChildEvent | SelectionEvent | ChartBrushChildEvent | ChartZoomChildEvent | ChartKeyboardChildEvent;

declare function chartShellEventsFromKey(key: string): readonly ChartShellEvent[];

type ChartShellInput = {
  readonly children?: readonly string[];
  readonly tooltip?: ChartTooltipChildInput;
  readonly selection?: SelectionInput;
  readonly legend?: ChartLegendChildInput;
  readonly brush?: ChartBrushChildInput;
  readonly zoom?: ChartZoomChildInput;
  /** Route a valid brush commit through the existing zoom child. @default false */
  readonly zoomOnBrush?: boolean;
  readonly keyboard?: ChartKeyboardChildInput;
};

declare function chartShellInputFromChildren(options: {
  readonly children: readonly string[];
  readonly orderedIds?: readonly string[];
  readonly selectionMode?: SelectionMode;
  readonly selectedIds?: SelectionValue;
  readonly defaultSelectedIds?: SelectionValue;
  readonly disabledIds?: readonly string[];
  readonly hiddenSeries?: readonly string[];
  readonly defaultHiddenSeries?: readonly string[];
  readonly brushDomain?: ChartXDomain;
  readonly defaultBrushDomain?: ChartXDomain;
  readonly zoomDomain?: ChartXDomain;
  readonly defaultZoomDomain?: ChartXDomain;
  /** Full caller x-domain used to clamp brush and zoom requests. */
  readonly bounds?: ChartXDomain;
  readonly zoomOnBrush?: boolean;
}): ChartShellInput;

interface ChartShellKeyboardController {
  readonly listenerCount: () => number;
  attach(service: ChartShellService): void;
  start(): void;
  destroy(): void;
}

interface ChartShellKeyboardControllerHost {
  readonly getTarget: () => EventTarget | null;
}

type ChartShellKeyboardIntent = "escape" | 1 | -1 | null;

declare function chartShellKeyEffect(key: string): ChartShellKeyEffect;

type ChartShellKeyEffect = {
  readonly intent: "escape" | 1 | -1;
  readonly preventDefault: boolean;
} | null;

export declare const chartShellMachine: ChartShellMachine;

interface ChartShellMount {
  readonly service: ChartShellService;
  readonly connector: ChartShellApi;
  readonly controller: ChartShellController;
  readonly root: HTMLElement;
  destroy(): void;
}

type ChartShellPart = (typeof chartShellAnatomy.parts)[number];

export declare const chartShellSelectors: {
  tooltip: (snapshot: ChartShellSnapshot) => ChartTooltipChildState | null;
  legend: (snapshot: ChartShellSnapshot) => ChartLegendChildState | null;
  selection: (snapshot: ChartShellSnapshot) => SelectionMachineState | null;
  brush: (snapshot: ChartShellSnapshot) => ChartBrushChildState | null;
  zoom: (snapshot: ChartShellSnapshot) => ChartZoomChildState | null;
  keyboard: (snapshot: ChartShellSnapshot) => ChartKeyboardChildState | null;
  tooltipOpen: (snapshot: ChartShellSnapshot) => boolean;
  candidateId: (snapshot: ChartShellSnapshot) => string | null;
  activeId: (snapshot: ChartShellSnapshot) => string | null;
  selectedIds: (snapshot: ChartShellSnapshot) => SelectionValue;
  hiddenSeries: (snapshot: ChartShellSnapshot) => readonly string[];
  brushDomain: (snapshot: ChartShellSnapshot) => {
    readonly start: ChartDomainScalar;
    readonly end: ChartDomainScalar;
  } | null;
  brushDraft: (snapshot: ChartShellSnapshot) => {
    readonly start: ChartDomainScalar;
    readonly end: ChartDomainScalar;
  } | null;
  zoomDomain: (snapshot: ChartShellSnapshot) => {
    readonly start: ChartDomainScalar;
    readonly end: ChartDomainScalar;
  } | null;
  keyboardActiveIndex: (snapshot: ChartShellSnapshot) => number | null;
  keyboardActiveId: (snapshot: ChartShellSnapshot) => string | null;
  enabledChildren: (snapshot: ChartShellSnapshot) => readonly ChartShellChildName[];
};

type ChartShellService = Service<ChartShellInput, ChartShellStateValue, ChartShellContext, ChartShellEvent, ChartShellCommand>;

type ChartShellSnapshot = Snapshot<ChartShellStateValue, ChartShellContext>;

type ChartShellStateValue = "ready";

type ChartShellTargetReason = "pointer" | "focus" | "keyboard";

type ChartTooltipOpenChangeDetail = {
  readonly open: boolean;
  readonly reason: string;
};

type ChartXDomain = {
  readonly start: ChartDomainScalar;
  readonly end: ChartDomainScalar;
} | null;

type ChartXDomainChangeDetail = {
  readonly domain: ChartXDomain;
  readonly reason: ChartDomainChangeReason;
};

declare function clampPointToBounds(point: ChartPoint2D, bounds: Pick<ChartEventBounds, "width" | "height">): ChartPoint2D;

declare function connectChartShell(service: ChartShellService, scope: PartScope, _options?: ChartShellConnectOptions): ChartShellApi;

declare function createChartShellController(host: ChartShellControllerHost): ChartShellController;

declare function createChartShellKeyboardController(host: ChartShellKeyboardControllerHost): ChartShellKeyboardController;

declare function createDragController(options?: DragControllerOptions): DragController;

type CrosshairBehaviorConfig = {
  readonly x?: boolean;
  readonly y?: boolean;
};

interface DragController {
  getState(): DragControllerState;
  start(event: unknown): DragControllerState;
  move(event: unknown): DragControllerState;
  end(event?: unknown): DragControllerState;
  cancel(): DragControllerState;
  keyboardMove(event: unknown): DragControllerState;
}

interface DragControllerOptions {
  readonly bounds?: ChartEventBounds;
  readonly plotOffset?: ChartPoint2D;
  readonly clamp?: boolean;
  readonly capturePointer?: boolean;
  readonly keyboardStep?: number;
  readonly keyboardShiftStep?: number;
  readonly constrain?: (point: DragPoint, state: DragControllerState) => DragPoint;
  readonly onStart?: (point: DragPoint, state: DragControllerState) => void;
  readonly onMove?: (point: DragPoint, state: DragControllerState) => void;
  readonly onEnd?: (point: DragPoint, state: DragControllerState) => void;
  readonly onCancel?: (state: DragControllerState) => void;
}

interface DragControllerState {
  readonly phase: DragPhase;
  readonly dragging: boolean;
  readonly origin: DragPoint | null;
  readonly point: DragPoint | null;
}

type DragPhase = "idle" | "start" | "move" | "end" | "cancel";

interface DragPoint extends ChartPoint2D {
  readonly clientX: number;
  readonly clientY: number;
  readonly dx: number;
  readonly dy: number;
  readonly originX: number;
  readonly originY: number;
  readonly plotX: number;
  readonly plotY: number;
  readonly pointerId?: number;
  readonly pointerType?: string;
  readonly source: NormalizedChartPointerEvent["source"] | "keyboard";
}

declare function focusFirstChartTarget(service: ChartShellService, prepared: PreparedChartNavigator): string | null;

declare function keyboardDeltaFromEvent(event: unknown, options?: ChartKeyboardMoveOptions): ChartPoint2D | null;

type LegendConfig = ChartLegendViewConfig & {
  readonly interactive?: boolean;
  readonly swatchSize?: number;
};

type LegendPosition = ChartLegendPosition;

declare function legendViewModel<TItem extends {
  id: string;
}>(items: readonly TItem[], hiddenSeries: readonly string[], config: ChartLegendViewConfig | undefined): ChartLegendViewModel<TItem>;

declare function localChartPoint(event: unknown, options?: ChartPointerEventOptions): ChartPoint2D | null;

declare function mountChartShell(container: HTMLElement, options?: MountChartShellOptions): ChartShellMount;

interface MountChartShellOptions extends ChartShellInput, ChartShellConnectOptions {
  readonly scheduler?: Scheduler;
  readonly host?: Partial<ChartShellControllerHost>;
}

declare function navigateChartTarget(service: ChartShellService, prepared: PreparedChartNavigator, activeId: string | null, intent: "escape" | 1 | -1): string | null;

declare function normalizeChartPointerEvent(event: unknown, options?: ChartPointerEventOptions): NormalizedChartPointerEvent | null;

interface NormalizedChartPointerEvent extends ChartPoint2D {
  readonly source: ChartPointerSource;
  readonly clientX: number;
  readonly clientY: number;
  readonly plotX: number;
  readonly plotY: number;
  readonly inside: boolean;
  readonly bounds: ChartEventBounds;
  readonly pointerId?: number;
  readonly pointerType?: string;
  readonly buttons?: number;
  readonly altKey: boolean;
  readonly ctrlKey: boolean;
  readonly metaKey: boolean;
  readonly shiftKey: boolean;
}