/**
 * `<time-picker-ui>` — Time-of-day picker with discrete segments (hour, minute, optional second, optional AM/PM). Each segment follows the WAI-ARIA Spinbutton pattern with Arrow-key increment/decrement, Page Up/Down for larger jumps, Home/End for segment min/max, and Tab to move between segments. Form-associated input emitting ISO 8601 time string ("HH:mm" or "HH:mm:ss") via change events. Per ADR-0025 no native form controls — segments are contenteditable spans inside a custom host. SPEC-043.
 *
 * @see https://ui-kit.exe.xyz/site/components/time-picker
 *
 * 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 TimePickerChangeEventDetail {
  /** Which segment commit fired the event (`hour` | `minute` | `second` | `meridiem`). */
  segment: string;
  /** Current value as ISO 8601 ("HH:mm" or "HH:mm:ss"). */
  value: string;
}

export type TimePickerChangeEvent = CustomEvent<TimePickerChangeEventDetail>;
export interface TimePickerInputEventDetail {
  /** In-flight value as ISO 8601. */
  value: string;
}

export type TimePickerInputEvent = CustomEvent<TimePickerInputEventDetail>;
export interface TimePickerInvalidEventDetail {
  /** Why it failed (`min` | `max` | `parse`). */
  reason: 'min' | 'max' | 'parse';
  /** Value that failed validation. */
  value: string;
}

export type TimePickerInvalidEvent = CustomEvent<TimePickerInvalidEventDetail>;

export class UITimePicker extends UIElement {
  /** Marks the field as required for form validation. Sets aria-required. */
  required: boolean;
  /** Disables interaction; dims the control */
  disabled: boolean;
  /** Hour cycle. Empty (default) derives from the document locale — most
en-* locales resolve to `h23`. `h12` forces a 12-hour cycle with an
AM/PM (meridiem) segment; `h23` forces 24-hour cycle.
 */
  hourcycle: '' | 'h12' | 'h23';
  /** BCP-47 locale tag used to derive hour-cycle when `hour-cycle` is empty. Falls back to `<html lang>` then to browser default. */
  locale: string;
  /** Latest selectable time as ISO 8601. Empty disables the constraint. */
  max: string;
  /** Earliest selectable time as ISO 8601. Empty disables the constraint. */
  min: string;
  /** Form field name for FormData submission */
  name: string;
  /** Per-segment placeholder text shown when a segment is empty. Defaults to "--". */
  placeholder: string;
  /** Whether the seconds segment is exposed. `minute` (default) hides seconds; `second` adds the seconds segment + separator. */
  precision: 'minute' | 'second';
  /** Prevents editing while keeping the field focusable. Segments stay focusable for inspection. */
  readonly: boolean;
  /** Per-Arrow-keypress increment in seconds. 60 = minute precision (default), 900 = 15-minute, 1 = second precision. */
  step: number;
  /** Current time value as ISO 8601 ("HH:mm" or "HH:mm:ss"). Empty when no value selected. */
  value: string;

  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: UITimePicker, ev: HTMLElementEventMap[K]) => unknown,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener(type: 'change', listener: (ev: TimePickerChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'input', listener: (ev: TimePickerInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'invalid', listener: (ev: TimePickerInvalidEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
}
