/**
 * `<chart-legend-ui>` — Standalone legend primitive for the AdiaUI chart family. Renders a row of badge-ui chips (swatch + label) that are keyboard-focusable and click-toggleable. Composes with chart-ui via [for] id-ref (auto-mirror) or via explicit [items] JSON.
 *
 * @see https://ui-kit.exe.xyz/site/components/chart-legend
 *
 * 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 ChartLegendToggleEventDetail {
  /** New visibility state (true = visible). */
  active: boolean;
  /** Series key identifier. */
  key: string;
  /** Visibility mode (default "hide"). */
  mode: string;
}

export type ChartLegendToggleEvent = CustomEvent<ChartLegendToggleEventDetail>;

export class UIChartLegend extends UIElement {
  /** JSON array of {key, label, slot?, pct?} legend items. Takes precedence over [for] when both are provided. */
  items: string;
  /** id-ref of a chart-ui / heatmap-ui to mirror series from. */
  for: string;
  /** Series-toggle mode emitted via the `toggle` event. `hide` removes the series from the render; `opacity` fades it. Wired via [for] on chart-ui. */
  onToggle: 'hide' | 'opacity';
  /** Layout hint — drives flex-direction. Actual placement follows DOM order. */
  position: 'top' | 'bottom' | 'left' | 'right';
  /** Swatch shape. Maps to badge-ui's icon for dot/square variants. */
  shape: 'dot' | 'square' | 'line' | 'dashed';
  /** When set, rows are non-interactive <span>s (no click, no toggle). */
  static: boolean;

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