@adia-ai/web-components 0.8.4 → 0.8.6

package/components/adia-mark/adia-mark.yaml

@@ -0,0 +1,121 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIAdiaMark
+tag: adia-mark-ui
+status: stable
+component: AdiaMark
+category: display
+version: 1
+description: >-
+  The Adia brand mark — a rounded square with the "Adia" wordmark cut out
+  in a contrasting color. Token-driven: the background always reads as
+  the current scheme's inverse surface, and the wordmark always reads as
+  the current scheme's inverse foreground, so a single asset replaces
+  separate light/dark/transparent static exports (gh#283). Not an
+  `icon-ui` registry entry — icon-ui is the Phosphor-glyph registry only;
+  this is a fixed, one-off brand image, a separate delivery shape.
+props:
+  size:
+    description: Diameter of the square mark. Matches avatar-ui's size ladder for visual consistency when the two sit side by side (e.g. an app switcher row).
+    type: string
+    default: md
+    enum:
+      - xs
+      - sm
+      - md
+      - lg
+      - xl
+    reflect: true
+  inline:
+    description: Renders as `display:inline-block` instead of the block-level default (ADR-0037) — set this when the mark sits beside a text run (a topbar brand slot) rather than standing alone.
+    type: boolean
+    default: false
+    reflect: true
+events: {}
+slots: {}
+states:
+  - name: default
+    description: The only state — a static, non-interactive brand mark.
+traits: []
+tokens:
+  --adia-mark-size:
+    description: Width and height of the square mark.
+    default: 2.5rem
+  --adia-mark-radius:
+    description: Corner radius of the background square.
+    default: var(--a-radius-lg)
+  --adia-mark-bg:
+    description: Background fill — always the inverse surface token, regardless of variant or scheme.
+    default: var(--a-canvas-surface-inverse)
+  --adia-mark-fg:
+    description: Wordmark fill — always the inverse foreground token, regardless of variant or scheme.
+    default: var(--a-fg-inverse)
+a2ui:
+  rules:
+    - Use <AdiaMark> for the Adia brand/app-identity mark — a favicon-style app-switcher tile, a splash/loading screen, an about-panel header. Do not use it as a generic icon; it has no [name] prop and always renders the same wordmark.
+    - Do not wrap <AdiaMark> in <Icon> or pass it a color/tone override — the background/foreground pairing is fixed by design (always inverse-on-inverse for contrast), not a themeable variant.
+    - Prefer <AdiaMark size="sm"> in a nav/topbar brand slot (a Row alongside the product name); reserve larger sizes (lg, xl) for splash screens or empty-state headers. Set [inline] only when the mark sits directly inside a run of prose text, not inside a Row/flex layout (block-level children compose fine as flex items already).
+anti_patterns:
+  - wrong: |
+      <icon-ui name="adia"></icon-ui>
+    why: |
+      icon-ui only resolves Phosphor glyph names from the registry; there
+      is no "adia" Phosphor icon, and registering one would misuse a
+      third-party glyph set for a proprietary brand mark.
+    fix: |
+      <adia-mark-ui size="sm"></adia-mark-ui>
+  - wrong: |
+      <adia-mark-ui style="--adia-mark-bg: #171818; --adia-mark-fg: #E2E3E4;"></adia-mark-ui>
+    why: |
+      Hardcoding the fill colors defeats the entire point of gh#283 —
+      the mark is supposed to track the inverse-surface/inverse-foreground
+      tokens automatically across scheme changes, not be pinned to one
+      scheme's static values.
+    fix: |
+      <adia-mark-ui size="sm"></adia-mark-ui>
+examples:
+  - name: topbar-brand-mark
+    description: Small brand mark in an admin-shell topbar, beside the product name.
+    a2ui: >-
+      [
+        {
+          "id": "brand-row",
+          "component": "Row",
+          "gap": "2",
+          "align": "center",
+          "children": ["mark", "name"]
+        },
+        {
+          "id": "mark",
+          "component": "AdiaMark",
+          "size": "sm"
+        },
+        {
+          "id": "name",
+          "component": "Text",
+          "variant": "heading",
+          "text": "Adia"
+        }
+      ]
+keywords:
+  - adia
+  - brand
+  - logo
+  - wordmark
+  - mark
+  - identity
+  - favicon
+synonyms:
+  logo:
+    - adia
+    - brand
+    - mark
+    - wordmark
+  brand:
+    - adia
+    - logo
+    - mark
+    - identity
+related:
+  - Icon
+  - Avatar
+  - Image

package/components/agent-questions/agent-questions.a2ui.json

@@ -45,7 +45,8 @@
     "anti_patterns": [],
     "category": "agent",
     "composes": [
-      "button-ui"
+      "button-ui",
+      "option-card-ui"
     ],
     "events": {
       "questions-answer": {

package/components/agent-questions/agent-questions.class.js

@@ -41,20 +41,11 @@
 
 import { UIElement } from '../../core/element.js';
 
-function escapeText(s) {
-  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
-
-function escapeAttr(s) {
-  return String(s).replace(/"/g, '&quot;');
-}
-
 export class UIAgentQuestions extends UIElement {
-  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
-  // consumer markup). Aggregated by installIconLoadersForRegistered()
-  // across all defined elements. Audited by check-required-icons.mjs
-  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
-  static requiredIcons = ['check'];
+  // gh issue 276 wave 4: options now render as <option-card-ui> (which
+  // composes icon-ui itself for the leading `icon` prop). This primitive
+  // no longer stamps any icon directly, so no requiredIcons entry is
+  // needed here — see check-required-icons.mjs (slot 11).
 
   static properties = {
     multi:       { type: Boolean, default: false, reflect: true },
@@ -87,6 +78,9 @@ export class UIAgentQuestions extends UIElement {
 
   disconnected() {
     this.#submitEl?.removeEventListener('press', this.#onSubmit);
+    this.#optionsEl?.removeEventListener('change', this.#onCardChange);
+    this.#optionsEl?.removeEventListener('click', this.#onOptionsClickCapture, true);
+    this.#optionsEl?.removeEventListener('keydown', this.#onOptionsKeydownCapture, true);
     this.#questionEl = this.#helperEl = this.#optionsEl = this.#submitEl = null;
   }
 
@@ -121,6 +115,20 @@ export class UIAgentQuestions extends UIElement {
 
     this.#optionsEl = document.createElement('div');
     this.#optionsEl.setAttribute('data-questions-options', '');
+    // Single-select: option-card-ui's own radiogroup machinery handles
+    // click + keyboard natively and fires `change` when a card becomes
+    // selected — we just listen for it.
+    this.#optionsEl.addEventListener('change', this.#onCardChange);
+    // Multi-select: option-card-ui is radio-only (its #select() no-ops
+    // once checked, and Enter/Space call that private method directly
+    // rather than dispatching a click), so there is no toggle-off hook
+    // to attach to. Intercept at the container's CAPTURE phase — before
+    // the card's own bubble-phase listeners ever run — and drive
+    // checked/aria state ourselves. Single mode never reaches these
+    // (guarded by `if (!this.multi) return`), so its native behavior is
+    // untouched.
+    this.#optionsEl.addEventListener('click', this.#onOptionsClickCapture, true);
+    this.#optionsEl.addEventListener('keydown', this.#onOptionsKeydownCapture, true);
 
     this.#submitEl = document.createElement('button-ui');
     this.#submitEl.setAttribute('text', this.submitLabel || 'Continue');
@@ -139,33 +147,28 @@ export class UIAgentQuestions extends UIElement {
     this.#optionsEl.innerHTML = '';
 
     for (const opt of this.#options) {
-      const card = document.createElement('button');
-      card.type = 'button';
+      const card = document.createElement('option-card-ui');
       card.setAttribute('data-questions-option', '');
-      card.setAttribute('role', this.multi ? 'checkbox' : 'radio');
-      card.setAttribute('aria-checked', this.#selected.has(opt.id) ? 'true' : 'false');
-      if (this.#selected.has(opt.id)) card.setAttribute('data-selected', '');
-      if (this.#answered) card.setAttribute('disabled', '');
-
-      const iconHTML = opt.icon
-        ? `<icon-ui name="${escapeAttr(opt.icon)}" color="muted" data-questions-option-icon></icon-ui>`
-        : '';
-      const checkHTML = `
-        <span data-questions-option-check aria-hidden="true">
-          <icon-ui name="check" size="sm" color="accent"></icon-ui>
-        </span>`;
-
-      card.innerHTML = `
-        ${iconHTML}
-        <span data-questions-option-body>
-          <span data-questions-option-label>${escapeText(opt.label || '')}</span>
-          ${opt.description ? `<span data-questions-option-desc>${escapeText(opt.description)}</span>` : ''}
-        </span>
-        ${checkHTML}
-      `;
-
-      card.addEventListener('click', () => this.#pick(opt));
+      card.setAttribute('data-questions-option-id', opt.id);
+      // Shared name → siblings form option-card-ui's own radiogroup
+      // (single mode). Inert in multi mode: #select() never runs there
+      // (see the capture-phase override below), so the shared name has
+      // no sibling-uncheck effect to guard against.
+      card.name = 'questions-option';
+      card.value = opt.id;
+      card.heading = opt.label || '';
+      card.description = opt.description || '';
+      card.icon = opt.icon || '';
+
       this.#optionsEl.appendChild(card);
+
+      // Multi mode: override the radio role option-card-ui sets on
+      // connect — this is a checkbox group, and aria-checked (which the
+      // primitive keeps in sync with `.checked` regardless of role) is
+      // valid for either.
+      if (this.multi) card.setAttribute('role', 'checkbox');
+      card.checked = this.#selected.has(opt.id);
+      card.disabled = this.#answered;
     }
 
     if (this.#submitEl) {
@@ -173,22 +176,62 @@ export class UIAgentQuestions extends UIElement {
     }
   }
 
-  #pick(opt) {
-    if (this.#answered) return;
-    if (this.multi) {
-      if (this.#selected.has(opt.id)) this.#selected.delete(opt.id);
-      else this.#selected.add(opt.id);
-      this.#render();
-    } else {
-      this.#selected.clear();
-      this.#selected.add(opt.id);
-      this.#answered = true;
-      this.#render();
-      this.dispatchEvent(new CustomEvent('questions-answer', {
-        bubbles: true,
-        detail: { selected: [opt.id], option: opt },
-      }));
+  /** Single mode — option-card-ui's own radiogroup fired `change` because
+   *  a card just became selected (it never fires on becoming unselected,
+   *  so this is always a genuine new pick). */
+  #onCardChange = (e) => {
+    if (this.multi || this.#answered) return;
+    const id = e.detail?.value;
+    const opt = this.#options.find((o) => o.id === id);
+    if (!opt) return;
+    this.#selected.clear();
+    this.#selected.add(opt.id);
+    this.#answered = true;
+    this.#render();
+    this.dispatchEvent(new CustomEvent('questions-answer', {
+      bubbles: true,
+      detail: { selected: [opt.id], option: opt },
+    }));
+  };
+
+  /** Multi mode — capture-phase click override (see #build). Stops the
+   *  event before option-card-ui's own bubble-phase click handler runs,
+   *  since that handler can only select, never deselect. */
+  #onOptionsClickCapture = (e) => {
+    if (!this.multi) return;
+    const card = e.target.closest?.('option-card-ui[data-questions-option]');
+    if (!card || !this.#optionsEl.contains(card)) return;
+    e.stopPropagation();
+    this.#toggleMulti(card);
+  };
+
+  /** Multi mode — capture-phase keydown override. Space/Enter toggle
+   *  (mirroring click); arrow keys are swallowed rather than forwarded
+   *  to option-card-ui's own forced-select navigation, since checkbox
+   *  groups here never had arrow-key nav (Tab-only, as before). */
+  #onOptionsKeydownCapture = (e) => {
+    if (!this.multi) return;
+    const card = e.target.closest?.('option-card-ui[data-questions-option]');
+    if (!card || !this.#optionsEl.contains(card)) return;
+    if (e.key === ' ' || e.key === 'Enter') {
+      e.preventDefault();
+      e.stopPropagation();
+      this.#toggleMulti(card);
+      return;
     }
+    if (e.key === 'ArrowDown' || e.key === 'ArrowUp' || e.key === 'ArrowLeft' || e.key === 'ArrowRight') {
+      e.stopPropagation();
+    }
+  };
+
+  #toggleMulti(card) {
+    if (this.#answered) return;
+    const id = card.dataset.questionsOptionId;
+    const opt = this.#options.find((o) => o.id === id);
+    if (!opt) return;
+    if (this.#selected.has(opt.id)) this.#selected.delete(opt.id);
+    else this.#selected.add(opt.id);
+    this.#render();
   }
 
   #onSubmit = () => {

package/components/agent-questions/agent-questions.css

@@ -18,8 +18,6 @@
     --agent-questions-option-bg-sel:   var(--md-sys-color-primary-container);
     --agent-questions-option-border:   var(--md-sys-color-neutral-outline-variant);
     --agent-questions-option-border-sel: var(--a-primary-bg);
-    --agent-questions-check-bg:        var(--a-primary-bg);
-    --agent-questions-check-fg:        var(--md-sys-color-primary-on-primary);
 
     /* ── Layout ── */
     --agent-questions-gap:             var(--a-space-2);
@@ -27,9 +25,6 @@
     --agent-questions-option-padding:  var(--a-space-3);
     --agent-questions-option-radius:   var(--a-radius);
     --agent-questions-q-padding:       var(--a-space-1);
-    --agent-questions-option-body-gap: var(--a-space-0-5);
-    /* Component-intrinsic measurement; no --a-space-* equivalent */
-    --agent-questions-check-size:      20px;
 
     /* ── Motion ── */
     --agent-questions-duration:        var(--a-duration-fast);
@@ -61,108 +56,34 @@
     gap: var(--agent-questions-gap);
   }
 
+  /* gh issue 276 wave 4: options render as <option-card-ui> now — it owns
+     its own box model, borders, hover/checked/disabled states, focus ring,
+     and heading/description/icon layout via its own @scope'd CSS. This
+     re-points its token surface to agent-questions' existing tokens so the
+     migration doesn't shift the look; it does not restyle the card itself.
+     One deliberate visual difference: the selected indicator is now
+     option-card-ui's authentic filled-radio-dot recipe (shared with
+     plan-picker-ui) rather than the bespoke check-glyph badge the native
+     buttons drew — that badge doesn't exist as an option-card-ui slot. */
   [data-questions-option] {
-    display: flex;
-    /* Top-align so the leading icon stays with the label's first line
-       when a description wraps below; we restore visual centering on
-       the icon and check by nudging them to the label's first-line
-       center via margin-top. Centering the whole row dragged the icon
-       down to the body's vertical midpoint, which sat between label
-       and description rather than on the label. */
-    align-items: start;
-    gap: var(--agent-questions-option-gap);
-    padding: var(--agent-questions-option-padding);
-    border: 1px solid var(--agent-questions-option-border);
-    border-radius: var(--agent-questions-option-radius);
-    background: var(--agent-questions-option-bg);
-    color: inherit;
-    cursor: pointer;
-    text-align: start;
-    font: inherit;
-    /* font-family floor — see segment.css rationale (inline default). */
-    font-family: var(--agent-questions-font-family, var(--a-font-family-ui));
-    transition:
-      background var(--agent-questions-duration) var(--agent-questions-easing),
-      border-color var(--agent-questions-duration) var(--agent-questions-easing);
-    min-width: 0;
+    --option-card-padding-block:  var(--agent-questions-option-padding);
+    --option-card-padding-inline: var(--agent-questions-option-padding);
+    --option-card-radius:         var(--agent-questions-option-radius);
+    --option-card-gap-x:          var(--agent-questions-option-gap);
+    --option-card-bg:             var(--agent-questions-option-bg);
+    --option-card-border:         var(--agent-questions-option-border);
+    --option-card-bg-hover:       var(--agent-questions-option-bg-hover);
+    /* Match prior behavior: hover changed background only, never border. */
+    --option-card-border-hover:   var(--agent-questions-option-border);
+    --option-card-bg-checked:     var(--agent-questions-option-bg-sel);
+    --option-card-border-checked: var(--agent-questions-option-border-sel);
+    --option-card-heading-color:  var(--agent-questions-label-fg);
+    --option-card-heading-weight: var(--agent-questions-label-weight);
+    --option-card-heading-size:   var(--agent-questions-label-size);
+    --option-card-desc-color:     var(--agent-questions-desc-fg);
+    --option-card-desc-size:      var(--agent-questions-desc-size);
+    --option-card-duration:       var(--agent-questions-duration);
+    --option-card-easing:         var(--agent-questions-easing);
     width: 100%;
   }
-
-  [data-questions-option]:hover {
-    background: var(--agent-questions-option-bg-hover);
-  }
-
-  [data-questions-option][data-selected] {
-    background: var(--agent-questions-option-bg-sel);
-    border-color: var(--agent-questions-option-border-sel);
-  }
-
-  [data-questions-option][disabled] {
-    cursor: default;
-    opacity: 0.7;
-  }
-
-  [data-questions-option]:focus-visible {
-    outline: 2px solid var(--agent-questions-option-border-sel);
-    outline-offset: 2px;
-  }
-
-  [data-questions-option-icon] {
-    flex-shrink: 0;
-    /* Align the leading icon's center with the label's first-line
-       center. `1.5em` matches the label's effective line-height
-       (label is `font-size:` only — line-height inherits as 1.5).
-       `var(--a-icon-size)` is icon-ui's rendered height. Centering
-       the icon inside one line-box of the label's height puts its
-       midpoint on the label's first-line midpoint. We use em on the
-       icon's own font-size (which icon-ui keeps at the option's
-       font-size) so the offset scales with whatever the consumer
-       sets `--agent-questions-label-size` to. */
-    margin-top: calc((1.5em - var(--a-icon-size, 1em)) / 2);
-  }
-
-  [data-questions-option-body] {
-    flex: 1;
-    min-width: 0;
-    display: flex;
-    flex-direction: column;
-    gap: var(--agent-questions-option-body-gap);
-  }
-
-  [data-questions-option-label] {
-    font-size: var(--agent-questions-label-size);
-    font-weight: var(--agent-questions-label-weight);
-    color: var(--agent-questions-label-fg);
-  }
-
-  [data-questions-option-desc] {
-    font-size: var(--agent-questions-desc-size);
-    color: var(--agent-questions-desc-fg);
-    line-height: 1.4;
-  }
-
-  [data-questions-option-check] {
-    width: var(--agent-questions-check-size);
-    height: var(--agent-questions-check-size);
-    border-radius: 50%;
-    flex-shrink: 0;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    background: transparent;
-    opacity: 0;
-    transition: opacity var(--agent-questions-duration) var(--agent-questions-easing);
-    /* Match the leading-icon offset so a row of [icon · label · check]
-       reads as one horizontal line aligned to the label's first line. */
-    margin-top: calc((1.5em - var(--agent-questions-check-size)) / 2);
-  }
-
-  [data-questions-option][data-selected] [data-questions-option-check] {
-    background: var(--agent-questions-check-bg);
-    opacity: 1;
-  }
-
-  [data-questions-option][data-selected] [data-questions-option-check] icon-ui {
-    color: var(--agent-questions-check-fg);
-  }
 }

package/components/agent-questions/agent-questions.yaml

@@ -19,6 +19,7 @@ description: |
 # do NOT auto-import them. Consumer (or demo shell) must explicitly import.
 composes:
   - button-ui
+  - option-card-ui  # gh issue 276 wave 4
 props:
   helper:
     description: Helper text.

package/components/button/button.class.js

@@ -50,7 +50,11 @@ export class UIButton extends UIElement {
   static template = () => null;
 
   connected() {
-    this.setAttribute('role', 'button');
+    // Respect consumer-authored ARIA — a composite may stamp button-ui as
+    // role="tab" (swiper dots), role="gridcell"-hosted day buttons
+    // (calendar), etc. Same contract as tabindex below: default only when
+    // the author said nothing (operator ruling 2026-07-17, gh#276 wave 4).
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'button');
     // Respect a consumer-authored tabindex (e.g. a mouse-only tabindex="-1"
     // affordance like combobox's clear x, or a roving-tabindex composite) —
     // only default the focusable state when the author said nothing.

package/components/calendar-grid/calendar-grid.a2ui.json

@@ -70,7 +70,9 @@
       }
     ],
     "category": "input",
-    "composes": [],
+    "composes": [
+      "button-ui"
+    ],
     "events": {
       "change": {
         "description": "User selected a date. detail.value is the ISO string."

package/components/calendar-grid/calendar-grid.class.js

@@ -164,10 +164,13 @@ export class UICalendarGrid extends UIElement {
     const rangeTo   = (rs && re && rs <= re) ? re : null;
 
     // Header — Prev / Title / Next
+    // <button-ui variant="ghost" icon="…"> (gh issue 276 wave 4) — button-ui
+    // respects the consumer-authored tabindex="-1", so the nav carets stay
+    // out of the roving-tabindex day-grid's tab sequence exactly as before.
     let h = `<div data-cal-header>
-      <button data-cal-prev type="button" aria-label="Previous month" tabindex="-1"><icon-ui name="caret-left"></icon-ui></button>
+      <button-ui variant="ghost" size="xs" icon="caret-left" data-cal-prev aria-label="Previous month" tabindex="-1"></button-ui>
       <span data-cal-title>${MONTHS_LONG[month]} ${year}</span>
-      <button data-cal-next type="button" aria-label="Next month" tabindex="-1"><icon-ui name="caret-right"></icon-ui></button>
+      <button-ui variant="ghost" size="xs" icon="caret-right" data-cal-next aria-label="Next month" tabindex="-1"></button-ui>
     </div>`;
 
     // Day-of-week header
@@ -183,7 +186,7 @@ export class UICalendarGrid extends UIElement {
     // Previous-month trailing days (outside, disabled)
     for (let i = firstDay - 1; i >= 0; i--) {
       const day = daysInPrev - i;
-      h += `<button type="button" data-cal-day data-outside disabled tabindex="-1">${day}</button>`;
+      h += `<button-ui variant="ghost" data-cal-day data-outside disabled tabindex="-1" text="${day}"></button-ui>`;
     }
 
     // Current-month days
@@ -206,7 +209,6 @@ export class UICalendarGrid extends UIElement {
       const isRangeEnd   = !!(rangeTo   && sameDay(date, rangeTo));
 
       const attrs = [
-        'type="button"',
         'data-cal-day',
         `data-date="${iso}"`,
         isToday      ? 'data-today' : '',
@@ -219,14 +221,17 @@ export class UICalendarGrid extends UIElement {
         `tabindex="${isFocused ? '0' : '-1'}"`,
       ].filter(Boolean).join(' ');
 
-      h += `<button ${attrs}>${d}</button>`;
+      // <button-ui variant="ghost" text="…"> (gh issue 276 wave 4) — the day
+      // number moves from element text content to the `text` attribute,
+      // which button-ui renders via CSS attr(text) on its ::after.
+      h += `<button-ui variant="ghost" ${attrs} text="${d}"></button-ui>`;
     }
 
     // Next-month leading days
     const totalCells = firstDay + daysInMonth;
     const remaining  = (7 - (totalCells % 7)) % 7;
     for (let d = 1; d <= remaining; d++) {
-      h += `<button type="button" data-cal-day data-outside disabled tabindex="-1">${d}</button>`;
+      h += `<button-ui variant="ghost" data-cal-day data-outside disabled tabindex="-1" text="${d}"></button-ui>`;
     }
 
     h += '</div>';