/**
 * `<link-ui>` — Inline navigation primitive — semantic `<a href>` wrapper. Use for
cross-page navigation, footer / Terms-of-Service / Privacy-Policy
inline references, "Sign in" / "Sign up" cross-page links, and any
affordance whose purpose is to take the user somewhere (not to
perform an action).

Sibling of `<button-ui>` — they have separate semantics and must
not be substituted for each other:

| Affordance                | Use            |
|---------------------------|----------------|
| Submit form               | `<button-ui>`  |
| Trigger action / modal    | `<button-ui>`  |
| Copy to clipboard         | `<button-ui>`  |
| Open modal / drawer       | `<button-ui>`  |
| Navigate to another page  | `<link-ui>`    |
| Open external URL         | `<link-ui>`    |
| Anchor jump (#section)    | `<link-ui>`    |
| Inline reference in prose | `<link-ui>`    |

Renders `<a href="…">` internally so middle-click open-in-new-tab,
right-click context menu, hover URL preview, search-engine
crawlability, and bookmark-ability all work without any custom
wiring. ARIA role is "link" (set automatically by `<a>` element).

 *
 * @see https://ui-kit.exe.xyz/site/components/link
 *
 * 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 LinkPressEventDetail {
  /** Link href attribute. */
  href: string;
  /** Link target attribute (e.g. _blank). */
  target: string;
}

export type LinkPressEvent = CustomEvent<LinkPressEventDetail>;

export class UILink extends UIElement {
  /** Stretches the link to fill its container; useful for standalone link rows. */
  block: boolean;
  /** Suppresses navigation + applies muted styling. Sets aria-disabled. */
  disabled: boolean;
  /** Destination URL or anchor. Required for SEO / middle-click / hover preview semantics. If omitted, the link still dispatches the `press` event (so it can be wired through the A2UI action handler system via `handler: "navigate"`), but loses native link behaviors. */
  href: string;
  /** Optional leading icon (Phosphor name). Use sparingly — most inline links don't need an icon. For "open in new tab" affordance, the `target="_blank"` attribute auto-renders a trailing arrow-up-right glyph; the `icon` prop is for leading semantic icons. */
  icon: string;
  /** Explicit `rel` attribute. Defaults to `noopener noreferrer` when `target="_blank"` is set without an explicit rel. */
  rel: string;
  /** Anchor target — same semantics as HTML `<a target>`. Use `_blank` to open in new tab; the implementation automatically adds `rel="noopener noreferrer"` for `_blank` to prevent tab-napping / privacy leaks. */
  target: '' | '_self' | '_blank' | '_parent' | '_top';
  /** Visible link text. Falls back to default-slot content if unset. */
  text: string;
  /** Visual treatment. `default` underlines on rest + hover (standard link affordance). `subtle` underlines only on hover (for tighter designs where always-underlined would be noisy). `quiet` drops the link color and matches surrounding text color (used for footer-link rows where the link affordance is implied by context, not by color). */
  variant: 'default' | 'subtle' | 'quiet';

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