/**
 * `<text-ui>` — Typography wrapper that applies role tokens. Supports truncation and line clamping.
 *
 * @see https://ui-kit.exe.xyz/site/components/text
 *
 * 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 type UITextVariant =
  /** Default body copy. 14px / regular. Paragraphs, multi-line content, running prose. */
  | 'body'
  /** Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers. */
  | 'heading'
  /** Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog. */
  | 'title'
  /** Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section. */
  | 'subsection'
  /** Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners. */
  | 'display'
  /** Annotation under a primary line — smaller + muted. Use for image captions, footnotes. */
  | 'caption'
  /** Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls. */
  | 'label'
  /** Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those). */
  | 'kicker'
  /** Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title. */
  | 'deck'
  /** Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings. */
  | 'section'
  /** Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers. */
  | 'metric'
  /** Inline monospace code reference. Use for inline code within prose. */
  | 'code';

export class UIText extends UIElement {
  /** Override the variant's color token. Permissive: unknown values are no-ops (variant color wins). Added v0.6.18 (FB-10). */
  color: 'default' | 'subtle' | 'strong' | 'accent' | 'danger' | 'success' | 'warning';
  /** Multi-line clamp count (0 = no clamp) */
  lines: number;
  /** Override the variant's font-size on the body ladder (sm/md/lg → --a-body-sm/md/lg). Accepts `@bp` notation: size="sm md@lg" = sm below lg, md from lg up. Added v0.6.18 (FB-10). */
  size: 'sm' | 'md' | 'lg';
  /** When true, applies stronger emphasis (heavier weight + accent color). Styled via :scope[strong] in text.css. Use instead of variant=heading when you want a single emphasized word inline in body copy. */
  strong: boolean;
  /** Display text content. The main payload field for Text components extracted from HTML. */
  textContent: string;
  /** Single-line truncation with ellipsis. Ignored when `lines` is set. */
  truncate: boolean;
  /** Typography variant — sets design-role tokens (size / weight /
tracking / color / leading) per the L0 typography token family.
**PRESENTATIONAL-ONLY (§247, FB-23 §2).** `<text-ui variant="heading">`
does NOT set `role="heading"` + `aria-level` on the host. Document-
outline assistive technology will treat the element as `role="generic"`.
For semantic headings, wrap with native `<h1>`-`<h6>` OR add
`role="heading" aria-level="N"` on the host directly. For visual-only
labels (eyebrows, kickers, captions, deck), the presentational default
is correct. The §221k chooser guide in USAGE.md documents picker heuristics. */
  variant: UITextVariant;
  /** Override the variant's font-weight. Maps to --a-weight / --a-weight-medium / --a-weight-semibold / --a-weight-bold. Permissive: unknown values are no-ops (variant weight wins). Added v0.6.18 (FB-10). */
  weight: 'regular' | 'medium' | 'semibold' | 'bold';
}
