/**
 * `<tour-ui>` — Spotlight-driven product tour / guided walkthrough. Hosts a sequence
of `<tour-step>` children, each targeting an element via CSS selector.
When active, dims the page with a scrim, cuts a "hole" around the
current step's target, and renders a popover next to it with step
content + Skip / Previous / Next navigation.

Use for first-run onboarding tours, feature introductions after a
release, and inline walkthroughs the user opts into ("Take the tour").
Distinct from `<onboarding-checklist-ui>` (persistent todo-list of
setup steps the user works through at their own pace) and from
`<tooltip-ui>` (single hover hint with no orchestration).

Architecture: tour-ui is a behavioral wrapper (`display: contents`)
that reads target / title / content from `<tour-step>` children. On
start, mounts a spotlight + popover surface into `document.body`
(top-layer via Popover API). The spotlight is a transparent
position:fixed element with a huge box-shadow that produces the
dimmed scrim outside its bounds (single-element backdrop, no clip-path
or SVG mask needed). The popover is anchored to the target via the
same `core/anchor.js` pattern used by menu-ui / context-menu-ui /
popover-ui.

 *
 * @see https://ui-kit.exe.xyz/site/components/tour
 *
 * Type declarations generated by scripts/build/dts-codegen.mjs from
 * the component's `.a2ui.json` sidecar(s). Edit the source `.yaml`,
 * run `npm run build:components`, then `npm run codegen:dts` to
 * regenerate; or hand-author this file fully if rich event types are
 * needed beyond what the yaml `events:` block can express.
 */

import { UIElement } from '../../core/element.js';

export type TourFinishEvent = CustomEvent<unknown>;
export type TourSkipEvent = CustomEvent<unknown>;
export type TourStartEvent = CustomEvent<unknown>;
export type TourStepChangeEvent = CustomEvent<unknown>;

export class UITour extends UIElement {
  /** Whether the tour is currently running. Setting to `true` mounts
the spotlight + popover; setting to `false` tears down.
 */
  active: boolean;
  /** Current step index (0-based). Setting this property advances the
tour to that step (updating spotlight + popover position).
 */
  step: number;

  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: UITour, ev: HTMLElementEventMap[K]) => unknown,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener(type: 'tour-finish', listener: (ev: TourFinishEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'tour-skip', listener: (ev: TourSkipEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'tour-start', listener: (ev: TourStartEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'tour-step-change', listener: (ev: TourStepChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
}

export class UITourStep extends UIElement {
  /** Step heading rendered in the popover. */
  title: string;
  /** Preferred popover placement relative to the target. Same vocabulary
as `core/anchor.js` (`top`, `bottom`, `left`, `right`,
`bottom-start`, `bottom-end`, etc.). Auto-flips on viewport overflow
via position-try-fallbacks.
 */
  placement: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end' | 'left-start' | 'left-end' | 'right-start' | 'right-end';
  /** CSS selector for the element to spotlight when this step is
active. Resolved via `document.querySelector(target)` at step
activation time. If the selector matches nothing, the spotlight
falls back to viewport-center and the popover anchors to the
page (no halo cutout).
 */
  target: string;
}
