@adia-ai/web-components 0.5.14 → 0.5.16

package/components/text/text.a2ui.json

@@ -36,7 +36,7 @@
       "default": false
     },
     "variant": {
-      "description": "Typography variant — sets role tokens (size/weight/tracking/color).",
+      "description": "Typography variant — sets design-role tokens (size / weight /\ntracking / color / leading) per the L0 typography token family.\n**PRESENTATIONAL-ONLY (§247, FB-23 §2).** `<text-ui variant=\"heading\">`\ndoes NOT set `role=\"heading\"` + `aria-level` on the host. Document-\noutline assistive technology will treat the element as `role=\"generic\"`.\nFor semantic headings, wrap with native `<h1>`-`<h6>` OR add\n`role=\"heading\" aria-level=\"N\"` on the host directly. For visual-only\nlabels (eyebrows, kickers, captions, deck), the presentational default\nis correct. The §221k chooser guide in USAGE.md documents picker heuristics.",
       "type": "string",
       "enum": [
         "body",
@@ -52,7 +52,21 @@
         "metric",
         "code"
       ],
-      "default": "body"
+      "default": "body",
+      "enum_descriptions": {
+        "title": "Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog.",
+        "body": "Default body copy. 14px / regular. Paragraphs, multi-line content, running prose.",
+        "caption": "Annotation under a primary line — smaller + muted. Use for image captions, footnotes.",
+        "code": "Inline monospace code reference. Use for inline code within prose.",
+        "deck": "Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title.",
+        "display": "Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners.",
+        "heading": "Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers.",
+        "kicker": "Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those).",
+        "label": "Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls.",
+        "metric": "Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers.",
+        "section": "Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings.",
+        "subsection": "Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section."
+      }
     }
   },
   "required": [

package/components/text/text.d.ts

@@ -1,41 +1,28 @@
 /**
- * `<text-ui>` — Typography wrapper that applies role tokens. Supports
- * truncation and line clamping.
+ * `<text-ui>` — Typography wrapper that applies role tokens. Supports truncation and line clamping.
  *
  * @see https://ui-kit.exe.xyz/site/components/text
  *
- * HAND-AUTHORED (not codegen'd) per §247 (v0.5.10) — the yaml `enum:` schema
- * carries variant names but not per-value descriptions; codegen emits a
- * single property-level JSDoc and loses the per-variant disambiguation that
- * the §221k chooser guide documents. Hand-authored .d.ts carries per-variant
- * JSDoc inline so IDE hover surfaces the disambiguation at authoring time.
- * Also carries the FB-23 §2 ARIA-role disclaimer on the property doc.
- * `dts-codegen.mjs` keeps this file in its `HAND_AUTHORED_DTS` skip list.
+ * 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';
 
-/**
- * Typography variants — visual rank from `display` (largest, hero) to
- * `code` (inline monospace). Pick by intent, not by visual size — every
- * variant has a distinct typographic role per §221k chooser guide.
- *
- * See `packages/web-components/USAGE.md` "v0.5.9 — Consumer-feedback
- * discoverability sweep" §221k for the picker heuristics.
- */
 export type UITextVariant =
   /** Default body copy. 14px / regular. Paragraphs, multi-line content, running prose. */
   | 'body'
-  /** Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners. */
-  | 'display'
-  /** Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog. */
-  | 'title'
   /** 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'
-  /** Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings. */
-  | 'section'
+  /** 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. */
@@ -44,34 +31,30 @@ export type UITextVariant =
   | '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 `\`code\`` inline within prose. */
+  /** Inline monospace code reference. Use for inline code within prose. */
   | 'code';
 
 export class UIText extends UIElement {
-  /**
-   * 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 (screen-reader heading-navigation, document
-   * outline), wrap with native `<h1>`-`<h6>` OR add
-   * `role="heading" aria-level="N"` on the host element directly.
-   *
-   * For visual-only labels (eyebrows, kickers, captions, deck), the
-   * presentational default is correct. The §221k chooser guide in USAGE.md
-   * documents the picker heuristics.
-   */
-  variant: UITextVariant;
-  /** 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;
-  /** Single-line truncation with ellipsis. Ignored when `lines` is set. */
-  truncate: boolean;
-  /** Multi-line clamp count (0 = no clamp). Sets `--_text-lines` for `-webkit-line-clamp`. */
+  /** Multi-line clamp count (0 = no clamp) */
   lines: number;
+  /** 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;
 }

package/components/text/text.yaml

@@ -28,7 +28,16 @@ props:
     default: ""
     dynamic: true
   variant:
-    description: Typography variant — sets role tokens (size/weight/tracking/color).
+    description: |-
+      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.
     type: string
     default: body
     enum:
@@ -44,6 +53,21 @@ props:
       - section
       - metric
       - code
+    # §324 (v0.5.15, FB-23 §3 retire): per-variant JSDoc surfaces at IDE
+    # hover via codegen. Retires the HAND_AUTHORED_DTS skip for text.d.ts.
+    enum_descriptions:
+      body: Default body copy. 14px / regular. Paragraphs, multi-line content, running prose.
+      display: Top-level hero / brand display. Tallest visual rank. Use for page-level hero one-liners.
+      title: Page title (visual rank H1). Largest under display. Use at the top of an authoritative page or dialog.
+      heading: Major page heading (visual rank H2). 16-18px / bold. Use for major sub-section dividers.
+      subsection: Sub-landmark within a section (visual rank H3). 14px / semibold. Use for card titles within a section.
+      section: Inline form-group / navlist heading (visual rank H4). Small-cap. Use for form group labels, nav list headings.
+      caption: Annotation under a primary line — smaller + muted. Use for image captions, footnotes.
+      label: Form-control label (above an `<input-ui>` / `<select-ui>` etc). UI-sized + medium-weight. Use for field labels bound to form controls.
+      kicker: Eyebrow text above a `title`. UPPERCASE + small + tracking. Use for content eyebrows (NOT form labels — use `label` for those).
+      deck: Sub-title under a `title`. One-line lead, slightly larger than body. Use for the lead sentence after a title.
+      metric: Numeric KPI / big-number stat. Bold + large. Use for dashboard metric numbers.
+      code: Inline monospace code reference. Use for inline code within prose.
 events: {}
 slots: {}
 states:

package/components/toolbar/toolbar.css

@@ -104,7 +104,7 @@ toolbar-ui [data-toolbar-spillover-menu]:popover-open {
   min-width: 10rem;
   font-family: inherit;
   font-size: var(--a-ui-size);
-  color: var(--a-fg);
+  color: var(--toolbar-fg);
   /* Stack overflow items as rows (each row can be a group with its own gap). */
   display: flex;
   flex-direction: column;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.14",
+  "version": "0.5.16",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",

package/styles/colors/semantics.css

@@ -116,20 +116,21 @@
   --a-fg-muted:      var(--a-canvas-text-muted);
   --a-fg-strong:     var(--a-canvas-text-strong);
   --a-fg-hover:      var(--a-canvas-text-strong);
-  --a-fg-active:     var(--a-canvas-text-strong);
+  /* ADR-0028: --a-fg-{active,invalid} retired (zero consumers). Use
+     `--a-ui-text-active` / `--a-ui-text-invalid` for form-control state,
+     or define a per-primitive `--<comp>-fg-{active,invalid}` token. */
   --a-fg-selected:   var(--a-canvas-text-strong);
   --a-fg-disabled:   var(--a-canvas-text-disabled);
-  --a-fg-invalid:    var(--a-danger-text);
   --a-fg-inverse:    var(--a-canvas-text-inverse);
 
   --a-border:          var(--a-canvas-border);
   --a-border-subtle:   var(--a-canvas-border-subtle);
   --a-border-strong:   var(--a-canvas-border-strong);
   --a-border-hover:    var(--a-canvas-border-strong);
-  --a-border-active:   var(--a-accent-border);
-  --a-border-selected: var(--a-accent-border);
-  --a-border-disabled: var(--a-canvas-border-subtle);
-  --a-border-invalid:  var(--a-danger-border);
+  /* ADR-0028: --a-border-{active,selected,disabled,invalid} retired (zero
+     consumers). Per-primitive `--<comp>-border-{state}` is the override
+     surface; `--a-focus-ring` carries focus-active borders for form
+     controls. */
 
   /* ══════════════════════════════════════════════════════════════
      ACCENT — Interactive, links, focus (source for --a-primary-*)
@@ -172,23 +173,12 @@
   --a-primary-bg:           var(--a-accent-strong);
   --a-primary-bg-hover:     var(--a-accent-hover);
   --a-primary-bg-active:    var(--a-accent-active);
-  --a-primary-bg-selected:  var(--a-accent-selected);
-  --a-primary-bg-disabled:  var(--a-accent-muted);
-  --a-primary-bg-invalid:   var(--a-danger-muted);
 
   --a-primary-fg:           var(--a-accent-05-tint);
   --a-primary-fg-hover:     var(--a-accent-text-strong);
-  --a-primary-fg-active:    var(--a-accent-text-strong);
-  --a-primary-fg-selected:  var(--a-accent-text-strong);
-  --a-primary-fg-disabled:  var(--a-accent-text-disabled);
-  --a-primary-fg-invalid:   var(--a-danger-text);
 
   --a-primary-border:           var(--a-accent-border);
   --a-primary-border-hover:     var(--a-accent-border-strong);
-  --a-primary-border-active:    var(--a-accent-border-strong);
-  --a-primary-border-selected:  var(--a-accent-border-strong);
-  --a-primary-border-disabled:  var(--a-accent-border-subtle);
-  --a-primary-border-invalid:   var(--a-danger-border);
 
   /* Legacy shorthand — keep until all components migrate to --a-primary-* */
   --a-primary:       var(--a-primary-bg);
@@ -200,16 +190,9 @@
   --a-accent-bg:           var(--a-primary-bg);
   --a-accent-bg-hover:     var(--a-primary-bg-hover);
   --a-accent-bg-active:    var(--a-primary-bg-active);
-  --a-accent-bg-selected:  var(--a-primary-bg-selected);
-  --a-accent-bg-disabled:  var(--a-primary-bg-disabled);
-  --a-accent-bg-invalid:   var(--a-primary-bg-invalid);
 
   --a-accent-fg:           var(--a-primary-fg);
   --a-accent-fg-hover:     var(--a-primary-fg-hover);
-  --a-accent-fg-active:    var(--a-primary-fg-active);
-  --a-accent-fg-selected:  var(--a-primary-fg-selected);
-  --a-accent-fg-disabled:  var(--a-primary-fg-disabled);
-  --a-accent-fg-invalid:   var(--a-primary-fg-invalid);
 
   /* accent border is already defined at L2 (--a-accent-border*);
      L3 matches L2 since both resolve to the same scheme-aware value. */
@@ -239,24 +222,12 @@
   /* L3 — Brand surface role matrix */
   --a-brand-bg:           var(--a-brand-strong);
   --a-brand-bg-hover:     var(--a-brand-hover);
-  --a-brand-bg-active:    var(--a-brand-active);
-  --a-brand-bg-selected:  var(--a-brand-selected);
-  --a-brand-bg-disabled:  var(--a-brand-muted);
-  --a-brand-bg-invalid:   var(--a-danger-muted);
 
   --a-brand-fg:           var(--a-brand-text-strong);
   --a-brand-fg-hover:     var(--a-brand-text-strong);
-  --a-brand-fg-active:    var(--a-brand-text-strong);
-  --a-brand-fg-selected:  var(--a-brand-text-strong);
-  --a-brand-fg-disabled:  var(--a-brand-text-disabled);
-  --a-brand-fg-invalid:   var(--a-danger-text);
 
   /* L3 border state matrix — rest state is --a-brand-border (L2 above). */
   --a-brand-border-hover:    var(--a-brand-border-strong);
-  --a-brand-border-active:   var(--a-brand-border-strong);
-  --a-brand-border-selected: var(--a-brand-border-strong);
-  --a-brand-border-disabled: var(--a-brand-border-subtle);
-  --a-brand-border-invalid:  var(--a-danger-border);
 
   /* ══════════════════════════════════════════════════════════════
      INFO
@@ -283,24 +254,12 @@
   /* L3 — Info surface role matrix */
   --a-info-bg:           var(--a-info-strong);
   --a-info-bg-hover:     var(--a-info-hover);
-  --a-info-bg-active:    var(--a-info-active);
-  --a-info-bg-selected:  var(--a-info-selected);
-  --a-info-bg-disabled:  var(--a-info-muted);
-  --a-info-bg-invalid:   var(--a-danger-muted);
 
   --a-info-fg:           var(--a-info-text-strong);
   --a-info-fg-hover:     var(--a-info-text-strong);
-  --a-info-fg-active:    var(--a-info-text-strong);
-  --a-info-fg-selected:  var(--a-info-text-strong);
-  --a-info-fg-disabled:  var(--a-info-text-disabled);
-  --a-info-fg-invalid:   var(--a-danger-text);
 
   /* L3 border state matrix — rest state is --a-info-border (L2 above). */
   --a-info-border-hover:    var(--a-info-border-strong);
-  --a-info-border-active:   var(--a-info-border-strong);
-  --a-info-border-selected: var(--a-info-border-strong);
-  --a-info-border-disabled: var(--a-info-border-subtle);
-  --a-info-border-invalid:  var(--a-danger-border);
 
   /* ══════════════════════════════════════════════════════════════
      SUCCESS
@@ -327,24 +286,12 @@
   /* L3 — Success surface role matrix */
   --a-success-bg:           var(--a-success-strong);
   --a-success-bg-hover:     var(--a-success-hover);
-  --a-success-bg-active:    var(--a-success-active);
-  --a-success-bg-selected:  var(--a-success-selected);
-  --a-success-bg-disabled:  var(--a-success-muted);
-  --a-success-bg-invalid:   var(--a-danger-muted);
 
   --a-success-fg:           var(--a-success-text-strong);
   --a-success-fg-hover:     var(--a-success-text-strong);
-  --a-success-fg-active:    var(--a-success-text-strong);
-  --a-success-fg-selected:  var(--a-success-text-strong);
-  --a-success-fg-disabled:  var(--a-success-text-disabled);
-  --a-success-fg-invalid:   var(--a-danger-text);
 
   /* L3 border state matrix — rest state is --a-success-border (L2 above). */
   --a-success-border-hover:    var(--a-success-border-strong);
-  --a-success-border-active:   var(--a-success-border-strong);
-  --a-success-border-selected: var(--a-success-border-strong);
-  --a-success-border-disabled: var(--a-success-border-subtle);
-  --a-success-border-invalid:  var(--a-danger-border);
 
   /* ══════════════════════════════════════════════════════════════
      WARNING
@@ -372,24 +319,12 @@
   /* L3 — Warning surface role matrix */
   --a-warning-bg:           var(--a-warning-strong);
   --a-warning-bg-hover:     var(--a-warning-hover);
-  --a-warning-bg-active:    var(--a-warning-active);
-  --a-warning-bg-selected:  var(--a-warning-selected);
-  --a-warning-bg-disabled:  var(--a-warning-muted);
-  --a-warning-bg-invalid:   var(--a-danger-muted);
 
   --a-warning-fg:           var(--a-warning-text-strong);
   --a-warning-fg-hover:     var(--a-warning-text-strong);
-  --a-warning-fg-active:    var(--a-warning-text-strong);
-  --a-warning-fg-selected:  var(--a-warning-text-strong);
-  --a-warning-fg-disabled:  var(--a-warning-text-disabled);
-  --a-warning-fg-invalid:   var(--a-danger-text);
 
   /* L3 border state matrix — rest state is --a-warning-border (L2 above). */
   --a-warning-border-hover:    var(--a-warning-border-strong);
-  --a-warning-border-active:   var(--a-warning-border-strong);
-  --a-warning-border-selected: var(--a-warning-border-strong);
-  --a-warning-border-disabled: var(--a-warning-border-subtle);
-  --a-warning-border-invalid:  var(--a-danger-border);
 
   /* ══════════════════════════════════════════════════════════════
      DANGER
@@ -418,24 +353,12 @@
   /* L3 — Danger surface role matrix */
   --a-danger-bg:           var(--a-danger-strong);
   --a-danger-bg-hover:     var(--a-danger-hover);
-  --a-danger-bg-active:    var(--a-danger-active);
-  --a-danger-bg-selected:  var(--a-danger-selected);
-  --a-danger-bg-disabled:  var(--a-danger-muted);
-  --a-danger-bg-invalid:   var(--a-danger-muted);
 
   --a-danger-fg:           var(--a-danger-text-strong);
   --a-danger-fg-hover:     var(--a-danger-text-strong);
-  --a-danger-fg-active:    var(--a-danger-text-strong);
-  --a-danger-fg-selected:  var(--a-danger-text-strong);
-  --a-danger-fg-disabled:  var(--a-danger-text-disabled);
-  --a-danger-fg-invalid:   var(--a-danger-text);
 
   /* L3 border state matrix — rest state is --a-danger-border (L2 above). */
   --a-danger-border-hover:    var(--a-danger-border-strong);
-  --a-danger-border-active:   var(--a-danger-border-strong);
-  --a-danger-border-selected: var(--a-danger-border-strong);
-  --a-danger-border-disabled: var(--a-danger-border-subtle);
-  --a-danger-border-invalid:  var(--a-danger-border);
 
   /* ══════════════════════════════════════════════════════════════
      BUCKETS — sequential 5-step ramp per family for data-vis consumers