/**
 * `<swatch-ui>` — Color/style swatch primitive — a small inline tile representing a single
visual sample. Renders as block, dot, square, line, or dashed depending on
shape; pairs with an optional label slot or attribute. Composed by chart-
legend-ui's per-row swatch and consumed directly by the token-colors /
spacing demo pages.

 *
 * @see https://ui-kit.exe.xyz/site/components/swatch
 *
 * 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 SwatchSelectEventDetail {
  /** The raw [color] attribute value. */
  color: string;
  /** The [label] attribute value. */
  label: string;
  /** The swatch's effective value — [color] when present, else [label]. */
  value: string;
}

export type SwatchSelectEvent = CustomEvent<SwatchSelectEventDetail>;

export class UISwatch extends UIElement {
  /** When set, computes the swatch color's OKLab L and switches the label /
detail color between light + dark so it remains legible against the
tile background. Active when `label-position="overlay"` (where the
label sits ON the tile). Uses a 1px canvas probe to handle any CSS
color form (oklch / hex / hsl / named / var() references).
 */
  autoContrast: boolean;
  /** Optional marker(s) rendered in the upper-right of the tile. Single value
OR comma/space-separated list of variants (v0.4.9+ multi-badge support).
Variants: out-of-gamut (△), p3-only (✦), apca-pass (✓), apca-fail (✗).
Each pip carries an aria-label so screen readers surface the semantic
("Outside sRGB gamut", "Contrast passes APCA", etc.). Unknown variants
are silently dropped.
 */
  badge: string;
  /** Swatch color. Accepts any CSS color value or var() reference. Sets the internal --swatch-color custom property; consumers can also set --swatch-color via inline style. */
  color: string;
  /** When set, renders an inline copy-to-clipboard button. Defaults to copying [color]; override via [copy-value]. */
  copyable: boolean;
  /** Override what gets copied when [copyable] is set. Defaults to [color]. Not reflected (color strings are long; attr round-tripping reads poorly). */
  copyValue: string;
  /** Optional secondary line of text rendered below the label. Typically the raw token value (e.g. "oklch(0.53 0.18 240)") when the swatch represents a design-token step. */
  detail: string;
  /** Optional label rendered next to (or below, for shape="block") the swatch. Use the default slot for richer content. */
  label: string;
  /** §253 (v0.5.12, FB-23 §1). Position the label relative to the tile.
`below` (default) stacks label under the tile (current shape="block"
layout — `flex-direction: column`). `overlay` renders the label
INSIDE the tile via absolute positioning; pair with `[auto-contrast]`
to keep the label legible against the tile color (`data-on-light` /
`data-on-dark` classes auto-stamped per OKLab-L probe). Only meaningful
when `shape="block"` (other shapes are too small for in-tile labels).
Unblocks Tokens Studio's C1.3 dogfood migration (label-inside-the-tile
pattern; blocked 3 cycles on this design call). */
  labelPosition: 'below' | 'overlay';
  /** When set, makes the swatch keyboard-focusable + clickable. Sets role="button" + tabindex="0". Dispatches a "select" event on activation (click / Enter / Space). */
  selectable: boolean;
  /** Reflected visual selected state. Pair with [selectable] to make the swatch behave like a radio-style picker. Sets aria-pressed. */
  selected: boolean;
  /** Visual shape — block (filled tile), dot (small circle), square (small filled square), line (solid hairline), dashed (dashed hairline). */
  shape: 'block' | 'dot' | 'square' | 'line' | 'dashed';
  /** Size preset — sm / md / lg. Drives the swatch's intrinsic dimensions; lg is reserved for the token-scale demo (40 px tall). */
  size: 'sm' | 'md' | 'lg';

  addEventListener<K extends keyof HTMLElementEventMap>(
    type: K,
    listener: (this: UISwatch, ev: HTMLElementEventMap[K]) => unknown,
    options?: boolean | AddEventListenerOptions,
  ): void;
  addEventListener(type: 'select', listener: (ev: SwatchSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
}
