/**
 * `<datetime-picker-ui>` — Single-control date + time selection. Trigger button opens a popover with a `<calendar-picker-ui>` on the left + a `<time-picker-ui>` on the right; commit emits a full ISO 8601 datetime string ("YYYY-MM-DDTHH:mm" or with seconds). Composes the two underlying primitives — never wraps a native `<input type="datetime-local">` (per ADR-0025). Form-associated under one `name`. SPEC-038.
 *
 * @see https://ui-kit.exe.xyz/site/components/datetime-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 DatetimePickerChangeEventDetail {
  source: string;
  value: string;
}

export type DatetimePickerChangeEvent = CustomEvent<DatetimePickerChangeEventDetail>;
export interface DatetimePickerCloseEventDetail {
  reason: string;
}

export type DatetimePickerCloseEvent = CustomEvent<DatetimePickerCloseEventDetail>;
export interface DatetimePickerInputEventDetail {
  value: string;
}

export type DatetimePickerInputEvent = CustomEvent<DatetimePickerInputEventDetail>;
export interface DatetimePickerInvalidEventDetail {
  reason: string;
  value: string;
}

export type DatetimePickerInvalidEvent = CustomEvent<DatetimePickerInvalidEventDetail>;
export interface DatetimePickerOpenEventDetail {
  trigger: string;
}

export type DatetimePickerOpenEvent = CustomEvent<DatetimePickerOpenEventDetail>;

export class UIDatetimePicker extends UIElement {
  /** Required for validation when inside a `<form>`. */
  required: boolean;
  /** Block all interaction. Trigger remains rendered but does not open the popover. */
  disabled: boolean;
  /** Trigger button date format. `short`: `Jan 1, 2026 14:30`; `long`: `January 1, 2026 14:30`; `iso`: full ISO string. */
  format: 'short' | 'long' | 'iso';
  /** Hour cycle for the time pane. Empty (default) derives from the
document locale. `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 ISO 8601 datetime (inclusive). Days after are disabled in the calendar pane; times after are rejected by the time pane on the same day. */
  max: string;
  /** Earliest selectable ISO 8601 datetime (inclusive). Days before are disabled in the calendar pane; times before are rejected by the time pane on the same day. */
  min: string;
  /** Form field name. The ISO 8601 datetime is submitted under this key when the picker is inside a `<form>`. */
  name: string;
  /** Whether the popover is currently open. */
  open: boolean;
  /** Text shown in the trigger when the value is empty. */
  placeholder: string;
  /** Popover placement relative to the trigger. Default `bottom` centers the calendar+time panel under the trigger (ADR-0034 Rule 2 — ~600px panel >> trigger). */
  placement: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
  /** Time-pane precision. `minute` (default) emits `HH:mm`; `second` exposes the seconds segment and emits `HH:mm:ss`. */
  precision: 'minute' | 'second';
  /** Block edits; allow keyboard navigation for screen-reader inspection. */
  readonly: boolean;
  /** Per-Arrow-keypress increment in seconds for the time pane. 60 = minute precision (default), 900 = 15-minute, 1 = second precision. */
  step: number;
  /** Current value as ISO 8601 datetime ("YYYY-MM-DDTHH:mm" or "YYYY-MM-DDTHH:mm:ss"). Empty when no value selected. */
  value: string;

  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: UIDatetimePicker, ev: HTMLElementEventMap[K]) => unknown,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener(type: 'change', listener: (ev: DatetimePickerChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'close', listener: (ev: DatetimePickerCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'input', listener: (ev: DatetimePickerInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'invalid', listener: (ev: DatetimePickerInvalidEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'open', listener: (ev: DatetimePickerOpenEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
}
