/**
 * `<color-input-ui>` — compact form-bearing color input.
 *
 * §302 (v0.5.12, FEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the
 * USAGE.md §221f recipe (popover + button + color-picker) into a single
 * form-associated tag for inline form contexts (settings drawer "source
 * color" field, swatch-row inline-edit). Light-DOM composition; the
 * inner picker fires `change` + `input` which this element re-emits
 * with a flattened detail payload that always carries both hex + oklch
 * string forms regardless of `[format]`.
 *
 * Hand-authored (FORM_BEARING in dts-codegen) because the rich event
 * detail (parallel hex+oklch views) can't be expressed by the
 * yaml `events:` shape alone.
 *
 * @see https://ui-kit.exe.xyz/site/components/color-input
 */

import { UIFormElement } from '../../core/form.js';

/**
 * Output format selected by the `[format]` attribute. Drives the shape of
 * `value` (and the matching `detail.value` field). Both `hex` and `oklch`
 * forms are always present on the event detail regardless of `[format]`.
 */
export type ColorInputFormat = 'hex' | 'oklch';

/**
 * Detail payload for both `change` (commit) and `input` (continuous drag)
 * events. `value` mirrors the current `[format]`; `hex` and `oklch` are
 * always populated parallel views, so consumers don't need to parse the
 * string.
 */
export interface ColorInputChangeEventDetail {
  /** Format-respecting string. Equals `hex` when `[format="hex"]`; equals `oklch` when `[format="oklch"]`. */
  value: string;
  /** Hex form (`#rrggbb`). Gamut-mapped to sRGB. */
  hex: string;
  /** OKLCH string (`oklch(L C H)`, fixed precision). */
  oklch: string;
  /** Parsed OKLCH lightness (0..1). v0.5.13 §-TBD (FB-33 §1-adjacent). */
  l: number;
  /** Parsed OKLCH chroma. */
  c: number;
  /** Parsed OKLCH hue (degrees, NaN ok for achromatic). */
  h: number;
}
export type ColorInputChangeEvent = CustomEvent<ColorInputChangeEventDetail>;
export type ColorInputInputEvent = CustomEvent<ColorInputChangeEventDetail>;

export class UIColorInput extends UIFormElement {
  /** Form field name. */
  name: string;
  /** Current color string in the active `format`. */
  value: string;
  /** Output format — drives the shape of `value`. Detail always carries both `hex` and `oklch`. */
  format: ColorInputFormat;
  /** Disables the trigger button + suppresses the popover. */
  disabled: boolean;
  /** Popover placement relative to the trigger button. */
  placement: 'top' | 'bottom' | 'left' | 'right' | 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
  /** Reflects the inner popover's open state. Set programmatically to open/close without a click. */
  open: boolean;
  /** Generation constraint forwarded to inner picker: clamp OKLCH chroma to at most this value. `Infinity` = unconstrained. v0.5.13 §-TBD (FB-33 §1). */
  maxChroma: number;
  /** Generation constraint forwarded to inner picker: clamp OKLCH lightness to at most this value (0..1). `1` = unconstrained. */
  maxL: number;
  /** Generation constraint forwarded to inner picker: clamp OKLCH lightness to at least this value (0..1). `0` = unconstrained. */
  minL: number;
  /** Generation constraint forwarded to inner picker: maximum allowed signed-shortest-path hue drift in degrees from `baseHue`. `NaN` = unconstrained. */
  hueDriftMax: number;
  /** Reference hue (degrees) for `hueDriftMax`, forwarded to inner picker. `NaN` = picker falls back to its hue at first commit. */
  baseHue: number;

  /** Open the picker programmatically. */
  showPicker(): void;
  /** Close the picker programmatically. */
  hidePicker(): void;

  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: UIColorInput, ev: HTMLElementEventMap[K]) => unknown,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener(type: 'change', listener: (ev: ColorInputChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
  addEventListener(type: 'input', listener: (ev: ColorInputInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
}
