/**
 * `<timeline-ui>` — Timeline and step wizard. Two modes: timeline (per-item state) and steps (parent-driven).
 *
 * @see https://ui-kit.exe.xyz/site/components/timeline
 *
 * 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 interface TimelineToggleEventDetail {
  /** New open state of the toggled item after the press. */
  expanded: boolean;
}

export type TimelineToggleEvent = CustomEvent<TimelineToggleEventDetail>;

export class UITimeline extends UIElement {
  /** Layout direction */
  orientation: 'vertical' | 'horizontal';
  /** Rail size preset — use `sm` for agent-reasoning/pipeline views; `md` is the default. */
  size: 'sm' | 'md';

  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: UITimeline, ev: HTMLElementEventMap[K]) => unknown,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener(type: 'timeline-toggle', listener: (ev: TimelineToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
}

export class UITimelineItem extends UIElement {
  /** Subtitle below the label. */
  description: string;
  /** Elapsed time (e.g. "1.2s", "340ms"). */
  duration: string;
  /** Optional leading icon name (Phosphor). */
  icon: string;
  /** Show a spinner instead of the icon while status=pending. */
  spinner: boolean;
  /** Lifecycle state (idle | pending | done | failed). */
  status: string;
  /** Primary step label. */
  text: string;
  /** Absolute timestamp (HH:MM or ISO). */
  time: string;
  /** Visual variant (default | accent | success | warning | danger). */
  variant: string;
}
