/**
 * `<toast-ui>` — Notification popup with auto-dismiss. Animated enter/exit.
 *
 * @see https://ui-kit.exe.xyz/site/components/toast
 *
 * HAND-AUTHORED (not codegen'd) per §246 (v0.5.9) — the yaml
 * `props:`/`events:` shape can't express the imperative `static show()`
 * API the runtime ships. `dts-codegen.mjs` keeps this file in its
 * `HAND_AUTHORED_DTS` skip list so subsequent builds preserve the
 * static-method signature.
 */

import { UIElement } from '../../core/element.js';

/** Options accepted by `UIToast.show(opts)` — the imperative one-shot path. */
export interface UIToastShowOptions {
  /** Toast message text. */
  text?: string;
  /** Semantic variant. Legacy alias `"error"` is auto-mapped to `"danger"`. */
  variant?: 'default' | 'info' | 'success' | 'warning' | 'danger' | 'primary' | 'muted' | 'neutral' | 'error';
  /** Auto-dismiss time in milliseconds. 0 disables auto-dismiss. Default `4000`. */
  duration?: number;
  /** Screen position. Default `'bottom-right'`. */
  position?: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
}

/** Returned by `UIToast.show()` — imperative handle for dismiss / update. */
export interface UIToastFeedHandle {
  /** Stable id assigned by `<feed-ui>`. `null` if the toast couldn't be posted. */
  id: string | null;
  /** Dismiss the toast programmatically. */
  dismiss(): void;
  /** Mutate the toast's content in-place (e.g. promote from "loading" to "done"). */
  update(patch: Partial<UIToastShowOptions>): void;
}

export class UIToast extends UIElement {
  /** Auto-dismiss time in milliseconds. 0 disables auto-dismiss. */
  duration: number;
  /** Screen position */
  position: 'top-left' | 'top-center' | 'top-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
  /** Toast message text */
  text: string;
  /** Semantic variant — `default | info | success | warning | danger`. `primary` and `muted` are style hints; canonical "neutral but interesting" tone is `info`. */
  variant: 'default' | 'info' | 'success' | 'warning' | 'danger' | 'primary' | 'muted' | 'neutral';

  /**
   * Post a one-shot toast through the shared `<feed-ui>` host. Imperative
   * alternative to declarative `<toast-ui>`. Returns a `UIToastFeedHandle`
   * for programmatic dismiss / update.
   *
   * §224 (v0.5.9): the spawned `<feed-ui>` container is stamped with
   * `data-spawned-by="toast"` for DOM-query distinction from user-authored
   * `<feed-ui>` containers.
   *
   * Legacy alias `variant: 'error'` is auto-mapped to `variant: 'danger'`.
   *
   * @example
   *   const t = UIToast.show({ text: 'Saved!', variant: 'success' });
   *   setTimeout(() => t.dismiss(), 1000);
   */
  static show(opts?: UIToastShowOptions): UIToastFeedHandle;
}
