@adia-ai/web-components 0.5.2 → 0.5.4

package/USAGE.md

@@ -134,6 +134,33 @@ const tpl3 = html`<slider-ui .value=${minL.value * 100} min="0" max="100"></slid
 
 The `.prop=` syntax sets the JS property (not the attribute). The `attr=` syntax sets an attribute. Both round-trip through the signal-backed setter, so either works for reactive updates from your side.
 
+### Template attribute bindings — full / property / no-partial (§152, v0.5.3)
+
+The `html\`` template literal supports three attribute-binding modes:
+
+| Syntax | Behavior |
+|---|---|
+| `attr="${value}"` (or just `attr=${value}`) | **Full attribute replacement.** The entire attribute value is the placeholder. The string `value` becomes the attribute value via `setAttribute()`. Works for any string-typed attribute. |
+| `.prop=${value}` (leading dot) | **Property assignment.** Sets `element.prop = value` directly (bypasses attributes). Preferred for objects, functions, arrays, signals — anything that doesn't serialize to a string. |
+| `attr="prefix-${value}-suffix"` | **NOT SUPPORTED.** Partial interpolation is not implemented — the attribute-part contract is whole-value-only. The framework will `console.warn` at scan time. Compute the full attribute value as a single expression and interpolate the whole. |
+
+Example of the partial-interpolation pitfall and its fix:
+
+```js
+// ❌ NOT SUPPORTED — partial attribute interpolation
+// Will console.warn at scan time + the `{{p:0}}` placeholder text reaches the DOM as literal.
+html`<div style="background:${bgCss}; color:${labelColor}">…</div>`;
+
+// ✅ Compute the full attribute as one expression
+const swatchStyle = `background:${bgCss}; color:${labelColor};`;
+html`<div style="${swatchStyle}">…</div>`;
+
+// ✅ Or use property binding with an object (CSSStyleDeclaration-like)
+html`<div .style=${{ background: bgCss, color: labelColor }}>…</div>`;
+```
+
+**Why the constraint exists**: the engine pre-processes static-string chunks to insert placeholder markers (`{{p:N}}` for attribute positions, `<!--p:N-->` for content positions). At scan time, the post-substitution attribute value must match `^\{\{p:N\}\}$` for the placeholder-to-part mapping to register. Sub-string placeholders break this contract. The runtime guard (added v0.5.3 §152) makes the failure mode explicit instead of silent.
+
 ### Using React, Lit, Vue, Svelte, etc.
 
 When the binding system isn't AdiaUI's `html` tag, the rule generalizes:
@@ -186,6 +213,21 @@ html`<slider-ui .value=${(v) => v * 100} />`
 
 The rule: **inside `.prop=${…}`, anything that reads `.value` directly is a snapshot. Wrap in `() => …` to get reactivity.**
 
+**Dev-mode guard (v0.5.3 §153 / FEEDBACK-07 §3):** primitives that read their value synchronously (e.g. `<slider-ui>`) emit a `console.warn` when their `.value` is assigned a function — this catches the case where the function wasn't wrapped by the template engine (e.g. assigned imperatively `sliderEl.value = fn`, or returned by a framework binding that doesn't recognize the AdiaUI reactivity contract). The warn names the two correct patterns:
+
+```
+[slider-ui] .value received a function. Did you mean:
+  .value=${fn()}            ← call the function to get the current value
+  .value=${signal.value}     ← read the signal's current value
+Functions are not auto-invoked at render time; the slider reads
+.value synchronously. See USAGE.md "Reactive binding" for the
+parent-template-re-read pattern that works across frameworks.
+```
+
+If you see this warn in dev console, either:
+1. You're using AdiaUI's `html\``: ensure the function reads at least one signal value (otherwise the function isn't reactive, just expensive). Pattern A above with `() => signal.value * 100` is correct.
+2. You're using a different framework (React/Lit/Vue): the binding system isn't AdiaUI's `html` engine, so functions don't auto-wrap. Use Pattern B from the parent-template-re-read recipe — read the signal in the parent's render, pass the extracted value imperatively or via your framework's binding.
+
 For more complex derived values, `computed()` gives you a named reactive holder you can pass directly or read in templates:
 
 ```js

package/components/accordion/accordion.a2ui.json

@@ -33,8 +33,14 @@
       "icon-ui"
     ],
     "events": {
-      "change": {
-        "description": "Fired when the set of open panels changes"
+      "toggle": {
+        "description": "Fired when the accordion panel opens or closes (single-pane accordion-ui dispatch — multi-pane group emits the same event per child).",
+        "detail": {
+          "open": {
+            "description": "New open state of the panel.",
+            "type": "boolean"
+          }
+        }
       }
     },
     "examples": [

package/components/accordion/accordion.d.ts

@@ -12,7 +12,12 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type AccordionChangeEvent = CustomEvent<unknown>;
+export interface AccordionToggleEventDetail {
+  /** New open state of the panel. */
+  open: boolean;
+}
+
+export type AccordionToggleEvent = CustomEvent<AccordionToggleEventDetail>;
 
 export class UIAccordion extends UIElement {
   /** Allow multiple panels to be open simultaneously */
@@ -23,5 +28,5 @@ export class UIAccordion extends UIElement {
     listener: (this: UIAccordion, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'change', listener: (ev: AccordionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'toggle', listener: (ev: AccordionToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/accordion/accordion.yaml

@@ -17,8 +17,12 @@ props:
     type: boolean
     default: false
 events:
-  change:
-    description: Fired when the set of open panels changes
+  toggle:
+    description: Fired when the accordion panel opens or closes (single-pane accordion-ui dispatch — multi-pane group emits the same event per child).
+    detail:
+      open:
+        type: boolean
+        description: New open state of the panel.
 slots:
   default:
     description: pane-ui children
@@ -27,6 +31,8 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-down
 a2ui:
   rules: []
 anti_patterns: []

package/components/accordion/class.js

@@ -30,6 +30,12 @@ import { UIElement } from '../../core/element.js';
 // ── Accordion Container ────────────────────────────────────────
 
 export class UIAccordion 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 = ['caret-down'];
+
   static properties = {
     multiple: { type: Boolean, default: false, reflect: true },
   };

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

@@ -47,6 +47,8 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - check
 a2ui:
   rules: []
 anti_patterns: []

package/components/agent-questions/class.js

@@ -50,6 +50,12 @@ function escapeAttr(s) {
 }
 
 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'];
+
   static properties = {
     multi:       { type: Boolean, default: false, reflect: true },
     question:    { type: String,  default: '',    reflect: true },

package/components/agent-reasoning/agent-reasoning.yaml

@@ -62,6 +62,11 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - check-circle
+  - circle
+  - warning
+  - warning-circle
 a2ui:
   rules: []
 anti_patterns: []

package/components/agent-reasoning/class.js

@@ -77,6 +77,12 @@ function formatDuration(ms) {
 }
 
 export class UIAgentReasoning 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-circle', 'circle', 'warning', 'warning-circle'];
+
   static properties = {
     collapsed:       { type: Boolean, default: false,    reflect: true },
     noAutocollapse:  { type: Boolean, default: false,    reflect: true, attribute: 'no-autocollapse' },

package/components/agent-trace/agent-trace.js

@@ -37,6 +37,12 @@
 import { UIElement } from '../../core/element.js';
 
 class UIAgentTrace 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 = ['caret-right', 'circle-fill'];
+
   static properties = {
     // agent-* family is default-visible disclosure (see component-token-contract.md
     // §"Toggle state naming"). Use `collapsed` to hide; bare element shows.

package/components/agent-trace/agent-trace.yaml

@@ -32,6 +32,9 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-right
+  - circle-fill
 a2ui:
   rules: []
 anti_patterns: []

package/components/calendar-picker/calendar-picker.yaml

@@ -71,6 +71,10 @@ states:
   attribute: disabled
 traits: []
 tokens: {}
+requiredIcons:
+  - calendar
+  - caret-left
+  - caret-right
 a2ui:
   rules: []
 anti_patterns: []

package/components/calendar-picker/class.js

@@ -53,6 +53,13 @@ function sameDay(a, b) {
 }
 
 export class UICalendarPicker extends UIFormElement {
+  static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per calendar-picker.yaml
+  // §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 = ['calendar', 'caret-left', 'caret-right'];
+
   static properties = {
     ...UIFormElement.properties,
     label:       { type: String,  default: '', reflect: true },

package/components/canvas/canvas.a2ui.json

@@ -32,16 +32,7 @@
     "composes": [],
     "events": {
       "canvas-interaction": {
-        "description": "Fired on canvas-interaction."
-      },
-      "change": {
-        "description": "Fired when the value changes (on blur for inputs, on selection for pickers)."
-      },
-      "click": {
-        "description": "Fired on pointer click."
-      },
-      "input": {
-        "description": "Fired on each input change during typing."
+        "description": "Fired on canvas interactions (focus, blur, pointer events). Dispatched at canvas.js:50 + :167."
       }
     },
     "examples": [

package/components/canvas/canvas.d.ts

@@ -13,9 +13,6 @@
 import { UIElement } from '../../core/element.js';
 
 export type CanvasInteractionEvent = CustomEvent<unknown>;
-export type CanvasChangeEvent = CustomEvent<unknown>;
-export type CanvasClickEvent = CustomEvent<unknown>;
-export type CanvasInputEvent = CustomEvent<unknown>;
 
 export class UICanvas extends UIElement {
   /** Component property: theme. */
@@ -27,7 +24,4 @@ export class UICanvas extends UIElement {
     options?: boolean | AddEventListenerOptions,
   ): void;
   addEventListener(type: 'canvas-interaction', listener: (ev: CanvasInteractionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'change', listener: (ev: CanvasChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'click', listener: (ev: CanvasClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'input', listener: (ev: CanvasInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/canvas/canvas.yaml

@@ -24,13 +24,7 @@ props:
     default: ''
 events:
   canvas-interaction:
-    description: Fired on canvas-interaction.
-  change:
-    description: Fired when the value changes (on blur for inputs, on selection for pickers).
-  click:
-    description: Fired on pointer click.
-  input:
-    description: Fired on each input change during typing.
+    description: Fired on canvas interactions (focus, blur, pointer events). Dispatched at canvas.js:50 + :167.
 slots:
   default:
     description: Default slot — primary child content.

package/components/card/card.a2ui.json

@@ -76,11 +76,7 @@
     "anti_patterns": [],
     "category": "container",
     "composes": [],
-    "events": {
-      "drag-end": {
-        "description": "Fired when a drag completes."
-      }
-    },
+    "events": {},
     "examples": [
       {
         "description": "Chat interface with message bubbles containing avatar and text pairs, plus an input footer.",

package/components/card/card.d.ts

@@ -12,8 +12,6 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type CardDragEndEvent = CustomEvent<unknown>;
-
 export class UICard extends UIElement {
   /** Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end. */
   draggable: boolean;
@@ -27,11 +25,4 @@ export class UICard extends UIElement {
   size: 'sm' | 'md' | 'lg';
   /** Visual style. `outline` is an alias for `outlined`; `flat` removes shadow; `soft`/`primary` apply tinted surfaces. */
   variant: 'default' | 'outlined' | 'outline' | 'filled' | 'ghost' | 'flat' | 'soft' | 'primary';
-
-  addEventListener<K extends keyof HTMLElementEventMap>(
-    type: K,
-    listener: (this: UICard, ev: HTMLElementEventMap[K]) => unknown,
-    options?: boolean | AddEventListenerOptions,
-  ): void;
-  addEventListener(type: 'drag-end', listener: (ev: CardDragEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/card/card.yaml

@@ -56,9 +56,7 @@ props:
     - flat
     - soft
     - primary
-events:
-  drag-end:
-    description: Fired when a drag completes.
+events: {}
 slots: {}
 states:
 - name: idle

package/components/chat-thread/chat-input.a2ui.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ChatInput.json",
+  "title": "ChatInput",
+  "description": "Composable chat input bar — a self-contained chat-message composer\nthat stamps its OWN inner structure (textarea + model picker + send\nbutton) when authored as a bare `<chat-input-ui>` tag.\n\nIMPORTANT (closes the 2026-05-14 redundant-send-button class): the\ncomponent stamps a built-in send button (paper-plane-right icon,\nprimary variant). DO NOT add a separate Button sibling for \"send\" —\nthe user gets two send buttons. The submit event fires on Enter or\nsend-button click; `detail` is `{ text, model }`.\n\nInner stamped structure (default):\n  <chat-input-ui>\n    <textarea-ui placeholder=\"Type a message...\" rows=\"1\"></textarea-ui>\n    <div slot=\"toolbar\">\n      <select-ui slot=\"model\" placeholder=\"Model\">...</select-ui>\n      <button-ui icon=\"paper-plane-right\" variant=\"primary\" slot=\"send\"></button-ui>\n    </div>\n  </chat-input-ui>\n\nLayout:\n  ┌──────────────────────────────────┐\n  │  textarea (grows vertically)     │\n  ├──────────────────────────────────┤\n  │  [model ▾]           [⏎ send]   │  ← toolbar (model picker + built-in send)\n  └──────────────────────────────────┘\n\nComposite wrapper, not a form field itself. The inner textarea-ui\nis form-associated via UIFormElement and submits through the parent\nform. `chat-input-ui`'s `disabled` / `placeholder` props propagate\nto the inner textarea.\n\nFor module-tier composer surfaces (slot vocabulary for file attach,\nautocomplete, trailing/leading controls), wrap inside\n`<chat-composer>` — see ChatComposer for the module-tier shape.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "ChatInput"
+    },
+    "disabled": {
+      "description": "Disable the entire input. Textarea becomes contenteditable=false;\nsend button disabled.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "loading": {
+      "description": "In-flight / streaming state. Send button disabled, submit events\nsuppressed, but textarea stays editable so the user can draft a\nfollow-up while the model is still responding.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "model": {
+      "description": "Currently selected model value (reflected, two-way with inner\n`<select-ui slot=\"model\">`). Empty when no model picker is shown.\n",
+      "type": "string",
+      "default": ""
+    },
+    "models": {
+      "description": "JSON array of model options for the inner model picker —\n[{value, label}] or [{label, options: [...]}] groups. Empty array\nhides the model picker.\n",
+      "type": "array",
+      "default": []
+    },
+    "placeholder": {
+      "description": "Textarea placeholder. Defaults to \"Type a message...\".",
+      "type": "string",
+      "default": "Type a message..."
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "description": "Adding a separate Button(primary) sibling next to ChatInput for \"send\". The component stamps its own send button (paper-plane-right icon). Two send buttons render side-by-side, confusing users."
+      },
+      {
+        "description": "Stamping a Select next to ChatInput for model picker. The component has a built-in model picker driven by the `models` prop. Set `models=[{value, label}, ...]` instead of stamping a separate Select."
+      },
+      {
+        "description": "Wrapping ChatInput inside <field-ui label=\"...\"> for label association. ChatInput is a composite container, not a form field. For a labeled composer surface, use <chat-composer> + slot label markup."
+      }
+    ],
+    "category": "agent",
+    "composes": [],
+    "events": {
+      "submit": {
+        "description": "Fires when the user presses Enter (without Shift) in the textarea OR clicks the built-in send button. The composer suppresses submission while `[loading]` is set.",
+        "detail": {
+          "model": {
+            "description": "Currently selected model value (empty if no model picker).",
+            "type": "string"
+          },
+          "text": {
+            "description": "Submitted message text from the inner textarea.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Minimal chat input — placeholder, no model picker. Sits inside a chat shell footer.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"ChatInput\", \"placeholder\": \"Ask me anything...\"}\n]",
+        "name": "basic-chat-input"
+      },
+      {
+        "description": "Chat input with model selection. The `models` prop drives the built-in model picker — DO NOT add a separate Select sibling.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"ChatInput\",\n    \"placeholder\": \"Type a message...\",\n    \"model\": \"claude-opus-4-7\",\n    \"models\": [\n      {\"value\": \"claude-opus-4-7\", \"label\": \"Claude Opus 4.7\"},\n      {\"value\": \"claude-haiku-4-5\", \"label\": \"Claude Haiku 4.5\"},\n      {\"value\": \"claude-sonnet-4-5\", \"label\": \"Claude Sonnet 4.5\"}\n    ]\n  }\n]",
+        "name": "chat-input-with-models"
+      },
+      {
+        "description": "Streaming response state. `[loading]` reflects on the host; send button disables; textarea stays editable so the user can draft a follow-up while the LLM is responding.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"ChatInput\",\n    \"placeholder\": \"Drafting follow-up while streaming...\",\n    \"loading\": true\n  }\n]",
+        "name": "chat-input-loading-state"
+      },
+      {
+        "description": "Full chat shell — header + thread + ChatInput in the footer. Note: ChatInput is the sole footer child; no separate send button.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"ChatShell\", \"children\": [\"header\", \"thread\", \"input\"]},\n  {\"id\": \"header\", \"component\": \"ChatHeader\", \"title\": \"Chat\"},\n  {\"id\": \"thread\", \"component\": \"ChatThread\"},\n  {\"id\": \"input\", \"component\": \"ChatInput\", \"placeholder\": \"Send a message...\"}\n]",
+        "name": "chat-shell-with-chat-input"
+      }
+    ],
+    "keywords": [
+      "chat-input",
+      "chat",
+      "message-input",
+      "composer",
+      "send-message",
+      "conversation",
+      "prompt",
+      "submit"
+    ],
+    "name": "UIChatInput",
+    "related": [
+      "ChatShell",
+      "ChatThread",
+      "ChatComposer",
+      "ChatHeader",
+      "TextArea",
+      "Input"
+    ],
+    "slots": {
+      "model": {
+        "description": "Override slot for the model picker. Most authors should NOT override this — set the `models` prop instead."
+      },
+      "send": {
+        "description": "Override slot for the send button only. The default stamped send button has `[icon=\"paper-plane-right\"] [variant=\"primary\"]`. Most authors should NOT override this — the built-in send button IS the send control. Adding a separate Button sibling for \"send\" duplicates this functionality."
+      },
+      "toolbar": {
+        "description": "Override slot for the entire toolbar row (model picker + send button). Most authors should NOT override this — the built-in toolbar handles model selection + send. Use this only when custom toolbar layout is required."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, accepting input. Send button enabled when textarea has content.",
+        "name": "idle"
+      },
+      {
+        "description": "Input fully disabled (typically during initial form setup).",
+        "attribute": "disabled",
+        "name": "disabled"
+      },
+      {
+        "description": "LLM is responding. Send button disabled + submit events suppressed, but textarea stays editable for follow-up drafts.",
+        "attribute": "loading",
+        "name": "loading"
+      }
+    ],
+    "synonyms": {
+      "message-input": [
+        "conversation-input",
+        "prompt-input",
+        "send-bar"
+      ]
+    },
+    "tag": "chat-input-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}