@adia-ai/web-components 0.5.4 → 0.5.6

package/components/accordion/accordion-item.a2ui.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AccordionItem.json",
+  "title": "AccordionItem",
+  "description": "Child of <accordion-ui>. One collapsible section with header + body. Use inside <accordion-ui> only.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AccordionItem"
+    },
+    "open": {
+      "description": "Whether the section is expanded.",
+      "type": "boolean",
+      "default": false
+    },
+    "text": {
+      "description": "Header text — the clickable label that toggles the section.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIAccordionItem",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "accordion-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/accordion/accordion-item.yaml

@@ -0,0 +1,27 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
+# component already existed as a sibling class in the parent's class.js
+# + was registered alongside the parent (e.g. UIList + UIListItem both
+# from list/class.js). The catalog just lacked its own entry. With the
+# §172 sibling-yaml scanner, this file gets picked up next to the parent
+# yaml.
+
+# Child component of <accordion-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIAccordionItem
+tag: accordion-item-ui
+component: AccordionItem
+category: layout
+version: 1
+description: |-
+  Child of <accordion-ui>. One collapsible section with header + body. Use inside <accordion-ui> only.
+
+props:
+  text:
+    description: Header text — the clickable label that toggles the section.
+    type: string
+  open:
+    description: Whether the section is expanded.
+    type: boolean
+    default: false

package/components/action-list/action-item.a2ui.json

@@ -0,0 +1,63 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ActionItem.json",
+  "title": "ActionItem",
+  "description": "Child of <action-list-ui>. One actionable row — icon + label, forwards activation to the parent action-list.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "ActionItem"
+    },
+    "disabled": {
+      "description": "Disables click + keyboard activation; aria-disabled is set.",
+      "type": "boolean",
+      "default": false
+    },
+    "icon": {
+      "description": "Leading icon name (Phosphor).",
+      "type": "string"
+    },
+    "text": {
+      "description": "Action label.",
+      "type": "string"
+    },
+    "value": {
+      "description": "Identifier passed to the action-list change/activate handlers.",
+      "type": "string"
+    },
+    "variant": {
+      "description": "Visual variant (default | accent | danger).",
+      "type": "string",
+      "default": "default"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "navigation",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIActionItem",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "action-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/action-list/action-item.yaml

@@ -0,0 +1,37 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
+# component already existed as a sibling class in the parent's class.js
+# + was registered alongside the parent (e.g. UIList + UIListItem both
+# from list/class.js). The catalog just lacked its own entry. With the
+# §172 sibling-yaml scanner, this file gets picked up next to the parent
+# yaml.
+
+# Child component of <action-list-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIActionItem
+tag: action-item-ui
+component: ActionItem
+category: navigation
+version: 1
+description: |-
+  Child of <action-list-ui>. One actionable row — icon + label, forwards activation to the parent action-list.
+
+props:
+  icon:
+    description: Leading icon name (Phosphor).
+    type: string
+  text:
+    description: Action label.
+    type: string
+  value:
+    description: Identifier passed to the action-list change/activate handlers.
+    type: string
+  variant:
+    description: Visual variant (default | accent | danger).
+    type: string
+    default: 'default'
+  disabled:
+    description: Disables click + keyboard activation; aria-disabled is set.
+    type: boolean
+    default: false

package/components/agent-feedback-bar/class.js

@@ -45,12 +45,17 @@
 
 import { UIElement } from '../../core/element.js';
 
-function makeButton({ icon, text = '' }) {
+function makeButton({ icon, text = '', title = '' }) {
   const btn = document.createElement('button-ui');
   btn.setAttribute('icon', icon);
   btn.setAttribute('variant', 'ghost');
   btn.setAttribute('size', 'sm');
   if (text) btn.setAttribute('text', text);
+  // §190a (v0.5.6): supply title= for icon-only buttons. button-ui's §184
+  // FEEDBACK-08 §8 a11y safety-net mirrors title → aria-label automatically
+  // when the button is icon-only. Closes the per-render console.warn class
+  // captured 2026-05-14 ("Icon-only button is missing an accessible name").
+  if (!text && title) btn.setAttribute('title', title);
   return btn;
 }
 
@@ -142,11 +147,12 @@ export class UIAgentFeedbackBar extends UIElement {
   #build() {
     this.innerHTML = '';
 
-    this.#upEl = makeButton({ icon: 'thumbs-up' });
-    this.#downEl = makeButton({ icon: 'thumbs-down' });
+    this.#upEl = makeButton({ icon: 'thumbs-up', title: 'Rate this response positively' });
+    this.#downEl = makeButton({ icon: 'thumbs-down', title: 'Rate this response negatively' });
     this.#saveEl = makeButton({
       icon: this.saveIcon || 'bookmark-simple',
       text: this.saveLabel || '',
+      title: this.saveLabel ? '' : 'Save this response',
     });
     if (!this.saveLabel) this.#saveEl.hidden = true;
 

package/components/avatar/avatar-group.a2ui.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AvatarGroup.json",
+  "title": "AvatarGroup",
+  "description": "Cluster of overlapping <avatar-ui> children. Stacks the first `max` avatars with a negative inline-start margin; if more children are present, renders a +N overflow indicator.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AvatarGroup"
+    },
+    "max": {
+      "description": "Maximum avatars to show before the +N overflow indicator.",
+      "type": "number",
+      "default": 5
+    },
+    "size": {
+      "description": "Forwards to each child <avatar-ui> (xs|sm|md|lg|xl). Empty uses the per-avatar size.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "feedback",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIAvatarGroup",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "avatar-group-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/avatar/avatar-group.yaml

@@ -0,0 +1,26 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
+# component already existed as a sibling class in the parent's class.js
+# + was registered alongside the parent (e.g. UIList + UIListItem both
+# from list/class.js). The catalog just lacked its own entry. With the
+# §172 sibling-yaml scanner, this file gets picked up next to the parent
+# yaml.
+
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIAvatarGroup
+tag: avatar-group-ui
+component: AvatarGroup
+category: feedback
+version: 1
+description: |-
+  Cluster of overlapping <avatar-ui> children. Stacks the first `max` avatars with a negative inline-start margin; if more children are present, renders a +N overflow indicator.
+
+props:
+  max:
+    description: Maximum avatars to show before the +N overflow indicator.
+    type: number
+    default: 5
+  size:
+    description: Forwards to each child <avatar-ui> (xs|sm|md|lg|xl). Empty uses the per-avatar size.
+    type: string

package/components/avatar/avatar.a2ui.json

@@ -24,7 +24,10 @@
     "name": {
       "description": "Deprecated alias for `text` (logs a one-shot console warning; will be removed in a future release). New code should use `text=` instead.",
       "type": "string",
-      "default": ""
+      "default": "",
+      "deprecated": true,
+      "deprecated_reason": "Use `text` instead. Will be removed in v0.6.0.",
+      "deprecated_since": "0.4.x"
     },
     "shape": {
       "description": "Avatar shape",

package/components/avatar/avatar.yaml

@@ -19,6 +19,13 @@ props:
   name:
     description: "Deprecated alias for `text` (logs a one-shot console warning; will be removed in a future release). New code should use `text=` instead."
     type: string
+    # §179 (v0.5.5): principled deprecation metadata. The build pipeline
+    # propagates this into the sidecar + catalog; the LLM prompt builder
+    # surfaces "(deprecated, do not use)" based on this field rather than
+    # substring-matching the description.
+    deprecated: true
+    deprecated_since: "0.4.x"
+    deprecated_reason: "Use `text` instead. Will be removed in v0.6.0."
     default: ""
   icon:
     description: Phosphor icon name shown instead of initials when `src`/`text` are empty.

package/components/button/class.js

@@ -52,8 +52,47 @@ export class UIButton extends UIElement {
         this.prepend(iconEl);
       }
     }
+
+    // §184 (v0.5.5, FEEDBACK-08 §8): icon-only a11y warning + title→aria-label
+    // auto-derive. Two complementary mechanisms (consumer chooses):
+    //   (a) When [title="Undo"] is set on an icon-only button without an
+    //       explicit aria-label, mirror title → aria-label. Matches the
+    //       common icon-only-button-with-tooltip pattern (zero authoring
+    //       cost — already had to write the tooltip text).
+    //   (b) When the button is icon-only AND has no aria-label AND no
+    //       aria-labelledby AND no title, console.warn ONCE per element
+    //       so the bug class is diagnosable in dev without firing every
+    //       render tick. The warning is suppressed via a one-shot
+    //       WeakSet so subsequent re-renders stay quiet.
+    if (this.icon && !this.text) {
+      const ariaLabel = this.getAttribute('aria-label');
+      const ariaLabelledBy = this.getAttribute('aria-labelledby');
+      const titleAttr = this.getAttribute('title');
+      if (!ariaLabel && !ariaLabelledBy && titleAttr) {
+        this.setAttribute('aria-label', titleAttr);
+      } else if (!ariaLabel && !ariaLabelledBy && !titleAttr) {
+        if (!UIButton.#a11yWarned.has(this)) {
+          UIButton.#a11yWarned.add(this);
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[button-ui] Icon-only button is missing an accessible name.\n` +
+            `  Element: <button-ui icon="${this.icon}">\n` +
+            `  Add one of:\n` +
+            `    aria-label="Undo"        ← explicit accessible name\n` +
+            `    title="Undo"             ← auto-mirrored to aria-label + tooltip\n` +
+            `    aria-labelledby="..."    ← reference an existing label element\n` +
+            `  Without an accessible name screen readers announce nothing meaningful.`
+          );
+        }
+      }
+    }
   }
 
+  // §184: WeakSet of elements we've already warned about. Prevents
+  // repeat warnings across re-renders. GC-friendly — when the element
+  // is gone the entry is collected.
+  static #a11yWarned = new WeakSet();
+
   #onClick = (e) => {
     if (this.disabled) { e.stopPropagation(); return; }
     if (this.type === 'submit') {

package/components/chart/chart.a2ui.json

@@ -47,7 +47,8 @@
         "square",
         "tall"
       ],
-      "default": "std"
+      "default": "std",
+      "deprecated": true
     },
     "color": {
       "description": "Color scheme",
@@ -78,7 +79,8 @@
     "heading": {
       "description": "DEPRECATED (OD-CHART-02). Place chart titles in an enclosing card-ui's `<header><span slot=\"heading\">...</span></header>` instead. Still honored for back-compat; emits a one-shot console.warn per instance when set. Used as the chart's `aria-label` when no explicit label is provided.",
       "type": "string",
-      "default": ""
+      "default": "",
+      "deprecated": true
     },
     "hideAverage": {
       "description": "When true, suppress the overlaid average line",

package/components/list/list-item.a2ui.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ListItem.json",
+  "title": "ListItem",
+  "description": "Child of <list-ui>. One list item with optional icon + text + description, plus arbitrary slotted content (cards, rows). Use inside <list-ui> only.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "description": {
+      "description": "Secondary line below the primary text. Subtle color.",
+      "type": "string"
+    },
+    "component": {
+      "const": "ListItem"
+    },
+    "icon": {
+      "description": "Optional leading icon name (Phosphor).",
+      "type": "string"
+    },
+    "text": {
+      "description": "Primary text. Renders as semibold inline body.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIListItem",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "list-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/list/list-item.yaml

@@ -0,0 +1,29 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
+# component already existed as a sibling class in the parent's class.js
+# + was registered alongside the parent (e.g. UIList + UIListItem both
+# from list/class.js). The catalog just lacked its own entry. With the
+# §172 sibling-yaml scanner, this file gets picked up next to the parent
+# yaml.
+
+# Child component of <list-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIListItem
+tag: list-item-ui
+component: ListItem
+category: layout
+version: 1
+description: |-
+  Child of <list-ui>. One list item with optional icon + text + description, plus arbitrary slotted content (cards, rows). Use inside <list-ui> only.
+
+props:
+  icon:
+    description: Optional leading icon name (Phosphor).
+    type: string
+  text:
+    description: Primary text. Renders as semibold inline body.
+    type: string
+  description:
+    description: Secondary line below the primary text. Subtle color.
+    type: string

package/components/segmented/segmented.d.ts

@@ -6,10 +6,10 @@
 
 import { UIFormElement } from '../../core/form.js';
 
-export interface SegmentedChangeEventDetail {
-  value: string;
+export interface SegmentedChangeEventDetail<V extends string = string> {
+  value: V;
 }
-export type SegmentedChangeEvent = CustomEvent<SegmentedChangeEventDetail>;
+export type SegmentedChangeEvent<V extends string = string> = CustomEvent<SegmentedChangeEventDetail<V>>;
 
 export class UISegmented extends UIFormElement {
   /** Selected segment's value. */

package/components/select/class.js

@@ -37,8 +37,14 @@ export class UISelect extends UIFormElement {
     searchable:  { type: Boolean, default: false, reflect: true },
     freeText:    { type: Boolean, default: false, reflect: true, attribute: 'free-text' },
     divider:     { type: Boolean, default: false, reflect: true },
+    // §184 (v0.5.5, FEEDBACK-08 §7): optional caption beneath the
+    // trigger, wired to aria-describedby on the host.
+    hint:        { type: String,  default: '', reflect: true },
   };
 
+  // §184: per-instance hint id counter for aria-describedby wiring.
+  static #hintSeq = 0;
+
   static template = () => null;
 
   #options = [];
@@ -97,13 +103,21 @@ export class UISelect extends UIFormElement {
       const displayMarkup = this.searchable
         ? `<input slot="display" type="text" role="combobox" aria-autocomplete="list" autocomplete="off" placeholder="${escapeHTML(this.placeholder || '')}" value="${escapeHTML(this.#displayText() === this.placeholder ? '' : this.#displayText())}" />`
         : `<span slot="display">${escapeHTML(this.#displayText())}</span>`;
+      // §184 (v0.5.5, FEEDBACK-08 §7): optional hint slot beneath the
+      // trigger. Mirrors slider-ui's hint pattern + matches the
+      // schema-declared `hint` prop on switch-ui (which had the spec
+      // but not the rendering until this arc).
+      const hintId = this.hint ? `select-hint-${++UISelect.#hintSeq}` : '';
+      const hintMarkup = this.hint ? `<span slot="hint" id="${hintId}">${escapeHTML(this.hint)}</span>` : '';
       this.innerHTML = `
         <span slot="trigger">
           ${leading}
           ${displayMarkup}
           <icon-ui name="caret-up-down" slot="caret"></icon-ui>
         </span>
+        ${hintMarkup}
       `;
+      if (this.hint) this.setAttribute('aria-describedby', hintId);
 
       if (this.searchable) {
         // Detach from previous search input if any

package/components/select/select.a2ui.json

@@ -46,6 +46,11 @@
       "type": "boolean",
       "default": false
     },
+    "hint": {
+      "description": "§184 (v0.5.5, FEEDBACK-08 §7): small caption rendered beneath the select. Sets `aria-describedby` on the host so screen readers announce it as a description (distinct from `aria-label`, which comes from `label`). Does not conflict with the in-component `label`.",
+      "type": "string",
+      "default": ""
+    },
     "icon": {
       "description": "Leading icon name rendered inside the trigger",
       "type": "string",

package/components/select/select.css

@@ -308,3 +308,13 @@ select-ui[divider] [role="group"] + [role="group"] {
   margin-top: var(--a-space-1);
   padding-top: var(--a-space-1);
 }
+
+/* ── Hint (§184, v0.5.5, FEEDBACK-08 §7) ──
+   Caption beneath the trigger; wired to aria-describedby on the host. */
+select-ui > [slot="hint"] {
+  display: block;
+  margin-top: var(--select-hint-mt, var(--a-space-1));
+  font-size: var(--select-hint-size, var(--a-fine-size));
+  color: var(--select-hint-fg, var(--a-fg-muted));
+  line-height: var(--select-hint-lh, 1.4);
+}

package/components/select/select.d.ts

@@ -16,10 +16,10 @@ export interface SelectOption {
   divider?: boolean;
 }
 
-export interface SelectChangeEventDetail {
-  value: string;
+export interface SelectChangeEventDetail<V extends string = string> {
+  value: V;
 }
-export type SelectChangeEvent = CustomEvent<SelectChangeEventDetail>;
+export type SelectChangeEvent<V extends string = string> = CustomEvent<SelectChangeEventDetail<V>>;
 
 export interface SelectActionEventDetail {
   action: string;

package/components/select/select.yaml

@@ -67,6 +67,11 @@ props:
     description: Label text above the trigger
     type: string
     default: ""
+  hint:
+    description: |-
+      §184 (v0.5.5, FEEDBACK-08 §7): small caption rendered beneath the select. Sets `aria-describedby` on the host so screen readers announce it as a description (distinct from `aria-label`, which comes from `label`). Does not conflict with the in-component `label`.
+    type: string
+    default: ""
   maxlength:
     description: Maximum character length for validation
     type: number