@adia-ai/web-components 0.4.3 → 0.4.4

package/components/field/field.a2ui.json

@@ -42,7 +42,20 @@
   ],
   "unevaluatedProperties": false,
   "x-adiaui": {
-    "anti_patterns": [],
+    "anti_patterns": [
+      {
+        "description": "Wrapping a check-ui (or switch-ui / radio-ui / toggle-ui) in field-ui. The widget already carries its own visible [label] via the CSS attr() pattern; field-ui adds a redundant label row and the inline-mode `justify-self: end` rule for compact controls pushes the widget to the right edge of the row, breaking the expected \"checkbox-left, label-right\" consent-row layout.",
+        "right": "<check-ui label=\"I agree to the Terms of Service\"></check-ui>\n",
+        "rule": "Small self-labeling widgets MUST NOT be wrapped in field-ui.",
+        "wrong": "<field-ui inline>\n  <check-ui label=\"I agree to the Terms of Service\"></check-ui>\n</field-ui>\n"
+      },
+      {
+        "description": "Using field-ui[inline] around a switch-ui to build a settings row. The settings-row layout (label-left, control-right) IS the switch-ui's own [label] rendering — field-ui adds no value and breaks the layout via the `justify-self: end` rule for compact widgets.",
+        "right": "<switch-ui label=\"Email notifications\"></switch-ui>\n",
+        "rule": "Use the widget's own [label] attribute for settings + consent rows. field-ui is for wide-control rows only.",
+        "wrong": "<field-ui inline label=\"Email notifications\">\n  <switch-ui></switch-ui>\n</field-ui>\n"
+      }
+    ],
     "category": "form",
     "events": {},
     "examples": [
@@ -69,14 +82,12 @@
       "input",
       "select",
       "textarea",
-      "check",
-      "radio",
-      "switch",
-      "slider"
+      "slider",
+      "range"
     ],
     "slots": {
       "default": {
-        "description": "The form control — input-ui, select-ui, textarea-ui, check-ui, switch-ui, radio-ui, slider-ui, etc. Auto-id'd for the label's [for] binding."
+        "description": "The form control — a WIDE control like input-ui, select-ui, textarea-ui, slider-ui, range-ui, calendar-picker-ui, color-picker-ui, upload-ui, otp-input-ui. Auto-id'd for the label's [for] binding.\nDO NOT wrap small self-labeling widgets here. check-ui, switch-ui, radio-ui, toggle-ui all carry their own [label] attribute that renders inline next to the control — wrapping them in field-ui produces broken layouts (settings-row `justify-self: end` rule pushes the control to the trailing edge, away from the label that field-ui stamps; the widget's own label then renders again on the right, creating a doubled / right-justified affordance). See anti_patterns below for the canonical alternatives."
       },
       "action": {
         "description": "Button adjacent to the control for inline actions (clear, reset, help popover)."

package/components/field/field.test.js

@@ -1,6 +1,12 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import '../../core/element.js';
 import './field.js';
+// Preload <input-ui> at module top so the error-mirror test can rely on
+// UIFormElement being registered without a dynamic import. The dynamic
+// `await import('../input/input.js')` inside the test body was a known
+// flake source under the full-suite parallel transform pipeline; moving
+// it to top-level removes that race entirely.
+import '../input/input.js';
 
 const tick = () => new Promise((r) => queueMicrotask(r));
 
@@ -116,8 +122,8 @@ describe('field-ui', () => {
     // Per field.js error-mirror architecture: field-ui reads .error from
     // the CHILD UIFormElement control (not from its own attribute). So
     // the test sets [error] on <input-ui> (UIFormElement-extending) — not
-    // <input> (raw HTML, no .error getter).
-    await import('../input/input.js');
+    // <input> (raw HTML, no .error getter). input-ui is preloaded at the
+    // top of this file to avoid a flake-prone dynamic import here.
     const f = mount('<field-ui label="E" hint="hi"><input-ui error="Required"></input-ui></field-ui>');
     await tick();
     const hint = f.querySelector('[data-field-hint]');

package/components/field/field.yaml

@@ -53,9 +53,20 @@ props:
 slots:
   default:
     description: >-
-      The form control — input-ui, select-ui, textarea-ui,
-      check-ui, switch-ui, radio-ui, slider-ui, etc. Auto-id'd for
-      the label's [for] binding.
+      The form control — a WIDE control like input-ui, select-ui,
+      textarea-ui, slider-ui, range-ui, calendar-picker-ui,
+      color-picker-ui, upload-ui, otp-input-ui. Auto-id'd for the
+      label's [for] binding.
+
+      DO NOT wrap small self-labeling widgets here. check-ui,
+      switch-ui, radio-ui, toggle-ui all carry their own [label]
+      attribute that renders inline next to the control — wrapping
+      them in field-ui produces broken layouts (settings-row
+      `justify-self: end` rule pushes the control to the trailing
+      edge, away from the label that field-ui stamps; the widget's
+      own label then renders again on the right, creating a doubled
+      / right-justified affordance). See anti_patterns below for the
+      canonical alternatives.
   trailing:
     description: >-
       Secondary text or badge aligned with the label in the stacked
@@ -93,8 +104,38 @@ tokens:
   --field-error-size:
     description: Error text size.
 a2ui:
-  rules: []
-anti_patterns: []
+  rules:
+    - "field-ui is for WIDE controls (input-ui, select-ui, textarea-ui, slider-ui, etc.) that need a separate label row. Small self-labeling widgets (check-ui, switch-ui, radio-ui, toggle-ui) carry their own [label] attribute and MUST NOT be wrapped in field-ui."
+    - "field-ui[inline] is for inline WIDE-control rows (e.g. search field with trailing kbd hint), NOT for compact-widget rows. For settings rows or consent rows, use the widget's own [label] attribute directly without a field-ui wrapper."
+anti_patterns:
+  - description: >-
+      Wrapping a check-ui (or switch-ui / radio-ui / toggle-ui) in
+      field-ui. The widget already carries its own visible [label]
+      via the CSS attr() pattern; field-ui adds a redundant label row
+      and the inline-mode `justify-self: end` rule for compact
+      controls pushes the widget to the right edge of the row,
+      breaking the expected "checkbox-left, label-right" consent-row
+      layout.
+    wrong: |
+      <field-ui inline>
+        <check-ui label="I agree to the Terms of Service"></check-ui>
+      </field-ui>
+    right: |
+      <check-ui label="I agree to the Terms of Service"></check-ui>
+    rule: Small self-labeling widgets MUST NOT be wrapped in field-ui.
+  - description: >-
+      Using field-ui[inline] around a switch-ui to build a settings
+      row. The settings-row layout (label-left, control-right) IS the
+      switch-ui's own [label] rendering — field-ui adds no value and
+      breaks the layout via the `justify-self: end` rule for compact
+      widgets.
+    wrong: |
+      <field-ui inline label="Email notifications">
+        <switch-ui></switch-ui>
+      </field-ui>
+    right: |
+      <switch-ui label="Email notifications"></switch-ui>
+    rule: Use the widget's own [label] attribute for settings + consent rows. field-ui is for wide-control rows only.
 examples:
   - name: stacked-email-field
     description: >-
@@ -146,7 +187,8 @@ related:
   - input
   - select
   - textarea
-  - check
-  - radio
-  - switch
   - slider
+  - range
+  # check, switch, radio, toggle removed from related — they are
+  # self-labeling widgets that should NOT be wrapped in field-ui.
+  # See anti_patterns above.

package/components/index.js

@@ -11,6 +11,7 @@ import '../core/data-stream.js';
 
 export { UIIcon } from './icon/icon.js';
 export { UIButton } from './button/button.js';
+export { UILink } from './link/link.js';
 export { UIInput } from './input/input.js';
 export { UITextarea } from './textarea/textarea.js';
 export { UICheck } from './check/check.js';

package/components/input/input.a2ui.json

@@ -38,6 +38,11 @@
       "type": "boolean",
       "default": false
     },
+    "autocomplete": {
+      "description": "Browser autofill behavior per HTML autocomplete spec. Routed via setAttribute to the host element. Common values: off, on, cc-number, cc-exp, cc-csc, cc-name, email, username, current-password, new-password, one-time-code, given-name, family-name, street-address, postal-code.",
+      "type": "string",
+      "default": ""
+    },
     "component": {
       "const": "Input"
     },
@@ -51,6 +56,21 @@
       "type": "string",
       "default": ""
     },
+    "inputmode": {
+      "description": "Mobile keyboard hint per HTML inputmode spec. Routed via setAttribute to the host element. Values: text, decimal, numeric, tel, search, email, url.",
+      "type": "string",
+      "enum": [
+        "text",
+        "decimal",
+        "numeric",
+        "tel",
+        "search",
+        "email",
+        "url",
+        "none"
+      ],
+      "default": null
+    },
     "label": {
       "description": "Inline label rendered as a leading caption inside the input chrome, between any prefix and the value. Wires aria-labelledby on the editable surface. For stacked label / hint / error compositions, wrap with field-ui.",
       "type": "string",

package/components/input/input.yaml

@@ -64,6 +64,21 @@ props:
     description: Minimum character length for validation
     type: number
     default: null
+  inputmode:
+    description: >-
+      Mobile keyboard hint per HTML inputmode spec. Routed via setAttribute
+      to the host element. Values: text, decimal, numeric, tel, search, email, url.
+    type: string
+    default: null
+    enum: [text, decimal, numeric, tel, search, email, url, none]
+  autocomplete:
+    description: >-
+      Browser autofill behavior per HTML autocomplete spec. Routed via
+      setAttribute to the host element. Common values: off, on, cc-number,
+      cc-exp, cc-csc, cc-name, email, username, current-password, new-password,
+      one-time-code, given-name, family-name, street-address, postal-code.
+    type: string
+    default: ""
   min:
     description: Minimum numeric value. Applies when `type="number"`. Clamps + drives aria-valuemin
       + the [-] button's disabled state.

package/components/link/link.a2ui.json

@@ -0,0 +1,166 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Link.json",
+  "title": "Link",
+  "description": "Inline navigation primitive — semantic `<a href>` wrapper. Use for\ncross-page navigation, footer / Terms-of-Service / Privacy-Policy\ninline references, \"Sign in\" / \"Sign up\" cross-page links, and any\naffordance whose purpose is to take the user somewhere (not to\nperform an action).\n\nSibling of `<button-ui>` — they have separate semantics and must\nnot be substituted for each other:\n\n| Affordance                | Use            |\n|---------------------------|----------------|\n| Submit form               | `<button-ui>`  |\n| Trigger action / modal    | `<button-ui>`  |\n| Copy to clipboard         | `<button-ui>`  |\n| Open modal / drawer       | `<button-ui>`  |\n| Navigate to another page  | `<link-ui>`    |\n| Open external URL         | `<link-ui>`    |\n| Anchor jump (#section)    | `<link-ui>`    |\n| Inline reference in prose | `<link-ui>`    |\n\nRenders `<a href=\"…\">` internally so middle-click open-in-new-tab,\nright-click context menu, hover URL preview, search-engine\ncrawlability, and bookmark-ability all work without any custom\nwiring. ARIA role is \"link\" (set automatically by `<a>` element).\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "block": {
+      "description": "Stretches the link to fill its container; useful for standalone link rows.",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "Link"
+    },
+    "disabled": {
+      "description": "Suppresses navigation + applies muted styling. Sets aria-disabled.",
+      "type": "boolean",
+      "default": false
+    },
+    "href": {
+      "description": "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.",
+      "type": "string",
+      "default": ""
+    },
+    "icon": {
+      "description": "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.",
+      "type": "string",
+      "default": ""
+    },
+    "rel": {
+      "description": "Explicit `rel` attribute. Defaults to `noopener noreferrer` when `target=\"_blank\"` is set without an explicit rel.",
+      "type": "string",
+      "default": ""
+    },
+    "target": {
+      "description": "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.",
+      "type": "string",
+      "enum": [
+        "",
+        "_self",
+        "_blank",
+        "_parent",
+        "_top"
+      ],
+      "default": ""
+    },
+    "text": {
+      "description": "Visible link text. Falls back to default-slot content if unset.",
+      "type": "string",
+      "default": ""
+    },
+    "variant": {
+      "description": "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).",
+      "type": "string",
+      "enum": [
+        "default",
+        "subtle",
+        "quiet"
+      ],
+      "default": "default"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      "❌ `<button-ui variant=\"link\">` — was removed. Migrate to `<link-ui>` if the affordance is navigation, or to `<button-ui variant=\"ghost\">` if the affordance is an action that wants understated styling.",
+      "❌ `<link-ui>` with no `href` AND no `press` handler — a link to nowhere is a bug. Either set `href` or wire a navigate action handler.",
+      "❌ `<link-ui>` for form submission — submission is a button concern. Use `<button-ui type=\"submit\">`."
+    ],
+    "category": "content",
+    "events": {
+      "press": {
+        "description": "Bubbles when the link is activated by click or Enter. Detail: `{ href, target }`. Fires BEFORE the browser's native navigation so handlers can `preventDefault()` and route through the A2UI action handler system. If no handler intercepts, native navigation proceeds."
+      }
+    },
+    "examples": [
+      {
+        "title": "Inline link in a sentence",
+        "code": "<text-ui>\n  I agree to the\n  <link-ui text=\"Terms of Service\" href=\"/terms\"></link-ui>\n  and\n  <link-ui text=\"Privacy Policy\" href=\"/privacy\"></link-ui>.\n</text-ui>\n"
+      },
+      {
+        "title": "External link with new-tab target",
+        "code": "<link-ui text=\"Read the spec\" href=\"https://example.com/spec\" target=\"_blank\"></link-ui>\n"
+      },
+      {
+        "title": "Footer link row",
+        "code": "<row-ui justify=\"center\" gap=\"2\">\n  <link-ui text=\"Already have an account?\" variant=\"quiet\" href=\"/signin\"></link-ui>\n  <link-ui text=\"Sign in\" href=\"/signin\"></link-ui>\n</row-ui>\n"
+      }
+    ],
+    "keywords": [
+      "link",
+      "anchor",
+      "navigation",
+      "hyperlink",
+      "href",
+      "navigate",
+      "route",
+      "url"
+    ],
+    "name": "UILink",
+    "related": [
+      "Button",
+      "NavItem",
+      "Breadcrumb"
+    ],
+    "slots": {
+      "default": {
+        "description": "Link text content when the `text` prop is unused."
+      }
+    },
+    "states": [
+      {
+        "description": "Default rest state — underlined (or per variant).",
+        "name": "idle"
+      },
+      {
+        "description": "Color shifts to `--a-link-hover`.",
+        "name": "hover"
+      },
+      {
+        "description": "Auto-styled via `:visited` pseudo when navigating to a previously-visited URL.",
+        "name": "visited"
+      },
+      {
+        "description": "Suppressed activation; muted text color; aria-disabled.",
+        "name": "disabled"
+      }
+    ],
+    "synonyms": {
+      "Link": [
+        "Anchor",
+        "Hyperlink",
+        "NavLink"
+      ]
+    },
+    "tag": "link-ui",
+    "tokens": {
+      "--link-color": {
+        "description": "Resting link color. Default `var(--a-link)`."
+      },
+      "--link-color-hover": {
+        "description": "Hover-state color. Default `var(--a-link-hover)`."
+      },
+      "--link-color-visited": {
+        "description": "Visited-state color. Default `var(--a-link-visited)`."
+      },
+      "--link-underline-offset": {
+        "description": "Distance between baseline and underline. Default `2px`."
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/link/link.css

@@ -0,0 +1,102 @@
+/* <link-ui> — inline navigation primitive.
+
+   The custom element wraps a real <a> element. Style the anchor (not
+   the host) so the rendered hyperlink inherits the proper text-decoration
+   + focus-ring behavior from the native element. The host is `display:
+   inline` so it flows in sentence context by default. */
+
+@scope (link-ui) {
+  :where(:scope) {
+    --link-color:           var(--a-link);
+    --link-color-hover:     var(--a-link-hover);
+    --link-color-visited:   var(--a-link-visited);
+    --link-underline-offset: 2px;
+    --link-focus-ring:      var(--a-focus-ring);
+  }
+
+  :scope {
+    display: inline;
+    color: var(--link-color);
+    /* The text-decoration is on the inner <a>, not the host, so that
+       host-level color overrides cascade correctly. */
+  }
+
+  :scope > a {
+    color: inherit;
+    text-decoration: underline;
+    text-underline-offset: var(--link-underline-offset);
+    cursor: pointer;
+    /* Standard transition for color hover. */
+    transition: color var(--a-duration-fast) var(--a-easing);
+  }
+
+  /* When the anchor contains an icon, present it inline with text. */
+  :scope > a:has(icon-ui) {
+    display: inline-flex;
+    align-items: baseline;
+    gap: var(--a-space-1);
+  }
+
+  :scope > a:hover {
+    color: var(--link-color-hover);
+  }
+
+  :scope > a:visited {
+    color: var(--link-color-visited);
+  }
+
+  /* Focus ring on the anchor (the actual focusable element). */
+  :scope > a:focus-visible {
+    outline: none;
+    box-shadow: var(--link-focus-ring);
+    border-radius: var(--a-radius-sm);
+  }
+
+  /* ── Variants ── */
+
+  /* `subtle` — no underline until hover. For tighter designs. */
+  :scope[variant="subtle"] > a {
+    text-decoration: none;
+  }
+  :scope[variant="subtle"] > a:hover,
+  :scope[variant="subtle"] > a:focus-visible {
+    text-decoration: underline;
+  }
+
+  /* `quiet` — drop link color; match surrounding text. The link
+     affordance is implied by hover behavior + cursor. For "Already
+     have an account?" type prose where the link role is contextual. */
+  :scope[variant="quiet"] {
+    --link-color: inherit;
+    --link-color-hover: var(--a-link-hover);
+  }
+  :scope[variant="quiet"] > a {
+    text-decoration: none;
+  }
+  :scope[variant="quiet"] > a:hover {
+    text-decoration: underline;
+  }
+
+  /* ── Layout modifiers ── */
+
+  :scope[block] {
+    display: block;
+  }
+  :scope[block] > a {
+    display: block;
+  }
+
+  /* ── Disabled ── */
+
+  :scope[disabled] > a {
+    color: var(--a-fg-disabled);
+    cursor: not-allowed;
+    text-decoration-color: var(--a-fg-disabled);
+    pointer-events: none;
+  }
+}
+
+/* `:scope:state` selectors inside @scope have known Safari-17 issues,
+   per the comment in button.css. None used here — :focus-visible and
+   :hover are on the inner <a>, not on :scope — so this component
+   is unaffected. */

package/components/link/link.js

@@ -0,0 +1,177 @@
+/**
+ * <link-ui> — Inline navigation primitive.
+ *
+ *   <link-ui text="Terms of Service" href="/terms"></link-ui>
+ *   <link-ui href="https://example.com" target="_blank">Read more</link-ui>
+ *   <link-ui text="Sign in" variant="quiet" href="/signin"></link-ui>
+ *
+ * Semantic <a href> wrapper for cross-page navigation. Sibling of
+ * <button-ui> — the two are NOT interchangeable:
+ *   - <button-ui>: triggers an action (submit, open modal, copy, run handler)
+ *   - <link-ui>:   navigates to a URL (real <a href> under the hood)
+ *
+ * The previous design conflated these via `<button-ui variant="link">`,
+ * which produced a button DOM with link-look styling — accessibility
+ * trees announced "button" for things screen-reader users expected to
+ * be links, middle-click did nothing instead of opening new tabs,
+ * search engines didn't see the link targets.
+ *
+ * Implementation: stamps an internal <a> element on connected() unless
+ * a child <a> is already present (slot-passthrough mode for advanced
+ * authoring). Renders the `text` prop into a <span> inside the <a>.
+ * For target="_blank", auto-adds rel="noopener noreferrer" unless an
+ * explicit rel is set.
+ *
+ * Properties:
+ *   text     — visible label
+ *   href     — destination URL (required for native nav semantics)
+ *   target   — _self | _blank | _parent | _top
+ *   rel      — explicit rel (defaults to noopener noreferrer for _blank)
+ *   variant  — default | subtle | quiet
+ *   block    — full-width row
+ *   disabled — suppress activation
+ *   icon     — optional leading Phosphor icon
+ *
+ * Events:
+ *   press — bubbles on click/Enter with detail { href, target }. Fires
+ *           BEFORE native navigation. preventDefault() the underlying
+ *           click event to suppress native nav and route through the
+ *           A2UI action-handler system.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+class UILink extends UIElement {
+  static properties = {
+    text:     { type: String,  default: '', reflect: true },
+    href:     { type: String,  default: '', reflect: true },
+    target:   { type: String,  default: '', reflect: true },
+    rel:      { type: String,  default: '', reflect: true },
+    variant:  { type: String,  default: 'default', reflect: true },
+    block:    { type: Boolean, default: false, reflect: true },
+    disabled: { type: Boolean, default: false, reflect: true },
+    icon:     { type: String,  default: '', reflect: true },
+  };
+
+  static template = () => null;
+
+  #onClick = (e) => {
+    if (this.disabled) {
+      e.preventDefault();
+      return;
+    }
+    // Dispatch press BEFORE native navigation so handlers can intercept.
+    const detail = { href: this.href, target: this.target };
+    const press = new CustomEvent('press', {
+      bubbles: true,
+      cancelable: true,
+      detail,
+    });
+    const allowed = this.dispatchEvent(press);
+    // If a handler called preventDefault on the press event, suppress
+    // the underlying anchor's native navigation too.
+    if (!allowed) e.preventDefault();
+  };
+
+  #onKey = (e) => {
+    // Links are activated by Enter only (NOT Space — that's button
+    // semantics). The native <a> handles this already, but we wire it
+    // explicitly for the disabled-suppression case.
+    if (this.disabled && e.key === 'Enter') {
+      e.preventDefault();
+    }
+  };
+
+  #ensureAnchor() {
+    // If author provided their own <a> child, leave it alone. Otherwise
+    // stamp one with the configured href/target/rel and mark it as
+    // autostamped so render() knows it owns the anchor's attrs +
+    // content. Slot-passthrough mode (author <a> child) preserves all
+    // author-set attrs across re-renders.
+    let a = this.querySelector(':scope > a');
+    if (!a) {
+      a = document.createElement('a');
+      a.dataset.autostamped = 'true';
+      this.appendChild(a);
+    }
+    // Move any direct text/icon children into the anchor so they inherit
+    // its semantics. Skip nodes already inside the anchor.
+    const toMove = [];
+    for (const node of this.childNodes) {
+      if (node === a) continue;
+      if (node.parentNode === this) toMove.push(node);
+    }
+    for (const node of toMove) a.appendChild(node);
+    return a;
+  }
+
+  connected() {
+    const a = this.#ensureAnchor();
+    this.addEventListener('click', this.#onClick);
+    this.addEventListener('keydown', this.#onKey);
+    // Disabled handling — aria-disabled rather than removing href, so
+    // the disabled state is announced to screen readers.
+    if (this.disabled) this.setAttribute('aria-disabled', 'true');
+  }
+
+  render() {
+    const a = this.querySelector(':scope > a');
+    if (!a) return;
+
+    // Slot-passthrough detection: if the author provided their own <a>
+    // child, leave its href/target/rel alone — they intentionally
+    // configured the anchor directly. We only manage anchors we
+    // auto-stamped (marked via data-autostamped).
+    const isAutostamped = a.dataset.autostamped === 'true';
+
+    if (isAutostamped) {
+      // href: empty string = no native nav, but element is still
+      // activatable via press event (handler-driven navigation).
+      if (this.href) a.setAttribute('href', this.href);
+      else a.removeAttribute('href');
+
+      // target: passed through verbatim.
+      if (this.target) a.setAttribute('target', this.target);
+      else a.removeAttribute('target');
+
+      // rel: explicit rel wins; otherwise auto-add noopener noreferrer
+      // for _blank to prevent tab-napping / referrer leakage.
+      if (this.rel) {
+        a.setAttribute('rel', this.rel);
+      } else if (this.target === '_blank') {
+        a.setAttribute('rel', 'noopener noreferrer');
+      } else {
+        a.removeAttribute('rel');
+      }
+    }
+
+    // Disabled — keep the anchor in the tree (so SR announcement works)
+    // but communicate state via aria-disabled. Click handler short-
+    // circuits when disabled is set. This applies to both autostamped
+    // and slot-passthrough modes.
+    if (this.disabled) {
+      this.setAttribute('aria-disabled', 'true');
+      a.setAttribute('tabindex', '-1');
+    } else {
+      this.removeAttribute('aria-disabled');
+      a.removeAttribute('tabindex');
+    }
+
+    // text + icon — stamp into the anchor when the props are set and
+    // this is an autostamped anchor. Don't touch author-provided
+    // anchors' content.
+    if (isAutostamped) {
+      const iconHTML = this.icon ? `<icon-ui name="${this.icon}"></icon-ui>` : '';
+      const textHTML = this.text ? `<span>${this.text}</span>` : '';
+      a.innerHTML = `${iconHTML}${textHTML}`;
+    }
+  }
+
+  disconnected() {
+    this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('keydown', this.#onKey);
+  }
+}
+
+customElements.define('link-ui', UILink);
+export { UILink };