@adia-ai/web-components 0.4.3 → 0.4.5

package/components/col/col.yaml

@@ -18,6 +18,11 @@ props:
       or a numeric rung on the spacing scale ("1"…"16", mapped to --a-space-N).
     type: string
     default: md
+  grow:
+    description: Fills remaining space in a flex parent (e.g. inside a Row). CSS-only attribute via :scope[grow] in col.css.
+    type: boolean
+    default: false
+    reflect: true
   justify:
     description: Justify content
     type: string

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.js

@@ -462,8 +462,8 @@ class UIInput extends UIFormElement {
     if (next === this.valueAsNumber) return;
     this.value = this.#format(next);
     this.syncValue(this.value);
-    this.dispatchEvent(new Event('input', { bubbles: true }));
-    this.dispatchEvent(new Event('change', { bubbles: true }));
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   }
 
   // ── Event handlers ──
@@ -488,7 +488,7 @@ class UIInput extends UIFormElement {
     this.value = text;
     if (!this.#isNativePassword) this.#textEl.toggleAttribute('data-empty', !text);
     this.syncValue(text);
-    this.dispatchEvent(new Event('input', { bubbles: true }));
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
   };
 
   #onBeforeInput = (e) => {
@@ -600,7 +600,7 @@ class UIInput extends UIFormElement {
           e.preventDefault();
           // Commit normalized value before firing form events.
           this.#commitOnBlur();
-          this.dispatchEvent(new Event('change', { bubbles: true }));
+          this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
           this.dispatchEvent(new Event('submit', { bubbles: true }));
           return;
       }
@@ -608,7 +608,7 @@ class UIInput extends UIFormElement {
     }
     if (e.key === 'Enter') {
       e.preventDefault();
-      this.dispatchEvent(new Event('change', { bubbles: true }));
+      this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
       this.dispatchEvent(new Event('submit', { bubbles: true }));
     }
   };
@@ -631,7 +631,7 @@ class UIInput extends UIFormElement {
 
   #onBlur = () => {
     if (this.#isNumberMode) this.#commitOnBlur();
-    this.dispatchEvent(new Event('change', { bubbles: true }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
   #commitOnBlur() {
@@ -650,7 +650,7 @@ class UIInput extends UIFormElement {
     if (this.value !== stored) {
       this.value = stored;
       this.syncValue(stored);
-      this.dispatchEvent(new Event('input', { bubbles: true }));
+      this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
     }
     if (this.#textEl.textContent !== displayed) {
       this.#textEl.textContent = displayed;
@@ -665,8 +665,8 @@ class UIInput extends UIFormElement {
     this.syncValue(this.value);
     this.#textEl.textContent = this.value;
     this.#textEl.toggleAttribute('data-empty', !this.value);
-    this.dispatchEvent(new Event('input', { bubbles: true }));
-    this.dispatchEvent(new Event('change', { bubbles: true }));
+    this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   }
 
   #onPaste = (e) => {

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. */