@adia-ai/web-components 0.5.1 → 0.5.3

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,12 @@ function sameDay(a, b) {
 }
 
 export class UICalendarPicker extends UIFormElement {
+  // §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/color-picker/class.js

@@ -123,6 +123,12 @@ function gamutMapChroma(L, C, H) {
 // ── Component ────────────────────────────────────────────
 
 export class UIColorPicker extends UIFormElement {
+  // §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 = ['copy'];
+
   static properties = {
     ...UIFormElement.properties,
     value:    { type: String,  default: '#3b82f6', reflect: true },

package/components/color-picker/color-picker.yaml

@@ -95,6 +95,8 @@ states:
     attribute: disabled
 traits: []
 tokens: {}
+requiredIcons:
+  - copy
 a2ui:
   rules: []
 anti_patterns: []

package/components/command/class.js

@@ -34,6 +34,12 @@ import { UIElement } from '../../core/element.js';
  *   dismiss — Escape pressed
  */
 export class UICommand 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 = ['magnifying-glass'];
+
   static properties = {
     placeholder: { type: String, default: 'Type a command...', reflect: true },
     open:        { type: Boolean, default: false, reflect: true },

package/components/command/command.yaml

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

package/components/drawer/class.js

@@ -50,6 +50,13 @@ export class UIDrawer extends UIElement {
   #previousFocus = null;
   #closeTimer = null;
   #dialogRef = null;
+  // §156 (v0.5.3): track the reason the drawer closed so the dispatched
+  // `close` CustomEvent carries `detail.reason`. Set at each entry point
+  // (escape → 'escape', backdrop → 'backdrop', close-button → 'close-button',
+  // any other path defaults to 'programmatic'). Reset to 'programmatic'
+  // after dispatch so a subsequent .open=false from consumer code
+  // doesn't carry a stale reason. Per FEEDBACK-06 §2.
+  #closeReason = 'programmatic';
 
   static properties = {
     text:      { type: String,  default: '', reflect: true },
@@ -95,11 +102,15 @@ export class UIDrawer extends UIElement {
   }
 
   #onPress = (e) => {
-    if (e.target.closest('[slot="close"]')) this.open = false;
+    if (e.target.closest('[slot="close"]')) {
+      this.#closeReason = 'close-button';
+      this.open = false;
+    }
   };
 
   #onDialogCancel = (e) => {
     e.preventDefault();
+    this.#closeReason = 'escape';
     if (!this.permanent) this.open = false;
   };
 
@@ -107,11 +118,22 @@ export class UIDrawer extends UIElement {
     this.open = false;
     this.#previousFocus?.focus();
     this.#previousFocus = null;
-    this.dispatchEvent(new Event('close', { bubbles: true }));
+    // §156 (v0.5.3): emit a CustomEvent with typed detail.reason. Capture
+    // and reset #closeReason so a subsequent programmatic close doesn't
+    // inherit the prior reason. Per FEEDBACK-06 §2.
+    const reason = this.#closeReason;
+    this.#closeReason = 'programmatic';
+    this.dispatchEvent(new CustomEvent('close', {
+      detail: { reason },
+      bubbles: true,
+    }));
   };
 
   #onDialogClick = (e) => {
-    if (e.target === this.#dialogRef && !this.permanent) this.open = false;
+    if (e.target === this.#dialogRef && !this.permanent) {
+      this.#closeReason = 'backdrop';
+      this.open = false;
+    }
   };
 
   connected() {

package/components/drawer/drawer.a2ui.json

@@ -63,7 +63,19 @@
     "composes": [],
     "events": {
       "close": {
-        "description": "Fired when the drawer is dismissed via close button or backdrop click"
+        "description": "Fired when the drawer closes via any path (close button, backdrop, Escape key, or programmatic `.open = false`). The `detail.reason` field distinguishes which.",
+        "detail": {
+          "reason": {
+            "description": "`'escape'` (Escape key) / `'backdrop'` (backdrop click) / `'close-button'` ([slot=\"close\"] button click) / `'programmatic'` (consumer set `.open = false` from JS). Defaults to `'programmatic'` when no event-driven path captured a reason. Added v0.5.3 §156 per FEEDBACK-06 §2.",
+            "type": "string",
+            "enum": [
+              "escape",
+              "backdrop",
+              "close-button",
+              "programmatic"
+            ]
+          }
+        }
       }
     },
     "examples": [

package/components/drawer/drawer.d.ts

@@ -12,7 +12,12 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type DrawerCloseEvent = CustomEvent<unknown>;
+export interface DrawerCloseEventDetail {
+  /** `'escape'` (Escape key) / `'backdrop'` (backdrop click) / `'close-button'` ([slot="close"] button click) / `'programmatic'` (consumer set `.open = false` from JS). Defaults to `'programmatic'` when no event-driven path captured a reason. Added v0.5.3 §156 per FEEDBACK-06 §2. */
+  reason: 'escape' | 'backdrop' | 'close-button' | 'programmatic';
+}
+
+export type DrawerCloseEvent = CustomEvent<DrawerCloseEventDetail>;
 
 export class UIDrawer extends UIElement {
   /** Controls visibility. When false, backdrop and panel are removed from DOM. */

package/components/drawer/drawer.yaml

@@ -49,7 +49,17 @@ props:
     default: ""
 events:
   close:
-    description: Fired when the drawer is dismissed via close button or backdrop click
+    description: Fired when the drawer closes via any path (close button, backdrop, Escape key, or programmatic `.open = false`). The `detail.reason` field distinguishes which.
+    detail:
+      reason:
+        type: string
+        enum: [escape, backdrop, close-button, programmatic]
+        description: >-
+          `'escape'` (Escape key) / `'backdrop'` (backdrop click) /
+          `'close-button'` ([slot="close"] button click) /
+          `'programmatic'` (consumer set `.open = false` from JS).
+          Defaults to `'programmatic'` when no event-driven path
+          captured a reason. Added v0.5.3 §156 per FEEDBACK-06 §2.
 slots:
   backdrop:
     description: Scrim overlay behind the drawer (stamped by the component).

package/components/pane/class.js

@@ -47,6 +47,12 @@
 import { UIElement } from '../../core/element.js';
 
 export class UIPane 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'];
+
   static properties = {
     collapsed:  { type: Boolean, default: false, reflect: true },
     resizable:  { type: Boolean, default: false, reflect: true },

package/components/pane/pane.yaml

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

package/components/row/row.a2ui.json

@@ -55,11 +55,7 @@
     "anti_patterns": [],
     "category": "layout",
     "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/row/row.d.ts

@@ -12,8 +12,6 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type RowDragEndEvent = CustomEvent<unknown>;
-
 export class UIRow extends UIElement {
   /** Align items */
   align: string;
@@ -27,11 +25,4 @@ export class UIRow extends UIElement {
   justify: string;
   /** Enable flex wrap */
   wrap: boolean;
-
-  addEventListener<K extends keyof HTMLElementEventMap>(
-    type: K,
-    listener: (this: UIRow, ev: HTMLElementEventMap[K]) => unknown,
-    options?: boolean | AddEventListenerOptions,
-  ): void;
-  addEventListener(type: 'drag-end', listener: (ev: RowDragEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/row/row.yaml

@@ -36,9 +36,7 @@ props:
     description: Enable flex wrap
     type: boolean
     default: false
-events:
-  drag-end:
-    description: "Fired when a drag completes."
+events: {}
 slots:
   default:
     description: "Default slot — primary child content."

package/components/select/class.js

@@ -19,6 +19,12 @@ function escapeHTML(s) {
 }
 
 export class UISelect extends UIFormElement {
+  // §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-up-down'];
+
   static properties = {
     ...UIFormElement.properties,
     placeholder: { type: String,  default: 'Select...', reflect: true },

package/components/select/select.yaml

@@ -127,6 +127,8 @@ states:
     attribute: disabled
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-up-down
 a2ui:
   rules: []
 anti_patterns: []

package/components/slider/class.js

@@ -95,6 +95,31 @@ export class UISlider extends UIFormElement {
   render() {
     if (!this.#trackEl) return;
 
+    // §153 (v0.5.3): function-typed `.value` runtime guard. Per FEEDBACK-07
+    // §3, consumers sometimes pass `() => signal.value * 100` expecting
+    // auto-subscribe; AdiaUI's reactive system (template.js `isFn` branch)
+    // does wrap functions in effects + call them per dep change, but the
+    // result of `v()` must be a number for `#pct` / `#format` to work.
+    // When the function returns non-number (e.g. doesn't read a signal,
+    // returns object/string) OR when consumers bypass the template engine
+    // (manual `sliderEl.value = someFunction`), `this.value` ends up as
+    // the function itself — `#pct` does NaN math, thumb stays at 0%,
+    // silent fail. Warn loudly + skip render so the bug class is
+    // diagnosable in dev. See USAGE.md "Reactive binding" for the
+    // documented patterns.
+    if (typeof this.value === 'function') {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[slider-ui] .value received a function. Did you mean:\n' +
+        '  .value=${fn()}            ← call the function to get the current value\n' +
+        '  .value=${signal.value}     ← read the signal\'s current value\n' +
+        'Functions are not auto-invoked at render time; the slider reads\n' +
+        '.value synchronously. See USAGE.md "Reactive binding" for the\n' +
+        'parent-template-re-read pattern that works across frameworks.'
+      );
+      return;
+    }
+
     const pct = this.#pct;
     const fill = this.querySelector('[slot="fill"]');
     if (fill) fill.style.width = `${pct}%`;

package/components/table/class.js

@@ -91,6 +91,12 @@ function csvEscape(val) {
 // ── Component ────────────────────────────────────────────────────────────────
 
 export class UITable 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', 'caret-up-down', 'table'];
+
   static properties = {
     sortable:   { type: Boolean, default: false, reflect: true },
     selectable: { type: Boolean, default: false, reflect: true },