@adia-ai/web-components 0.5.10 → 0.5.11

package/USAGE.md

@@ -1057,6 +1057,35 @@ const tpl = html`
 
 Same rule applies to nested `<style>` and `<script>` blocks inside `html\`...\`` — anything that contains a literal backtick must be escaped (`\\\``) or rephrased.
 
+### §250 — Template parser — invariants + unsupported syntaxes (FEEDBACK-27)
+
+`html\`\`` is intentionally smaller than `lit-html`. The parser recognizes exactly four placeholder shapes; anything else fails (some loudly, some silently — §250 graduates every documented failure to load-time `console.warn`).
+
+| Syntax | Behavior | Notes |
+|---|---|---|
+| `attr=${val}` (full attribute interpolation) | ✅ Supported. Writes the stringified value to the attribute. | The whole attribute value must be the placeholder — `attr="prefix-${val}"` is **NOT** supported (silent garbage pre-v0.5.3; load-time warn v0.5.3 §152+). |
+| `.prop=${val}` (property binding) | ✅ Supported. Assigns to the JS property, NOT the DOM attribute. | This is the canonical pattern for boolean state + object values. Custom elements reflect declared `static properties` to DOM attributes automatically — set `.disabled = true` and the host reflects `[disabled]`. |
+| `@event=${handler}` (event listener) | ✅ Supported. Calls `addEventListener(event, handler)`. | `handler` can be a function or a signal-wrapped function. |
+| `?attr=${bool}` (Lit-style boolean attribute) | ❌ **NOT supported (load-time `console.warn` v0.5.11 §250).** | Pre-§250: silently registered a literal `?attr` attribute (browser ignored it). v0.5.11 §250 emits a `console.warn` at scan time + degrades to no-op. Use `.attr=${bool}` instead. |
+
+**Migration for `?attr=${bool}` patterns:**
+
+```js
+// ❌ Lit-style boolean attribute — silently inert pre-v0.5.11; warns + no-ops post-§250
+html`<button-ui ?disabled=${isLoading}>Save</button-ui>`;
+
+// ✅ Property binding — the primitive reflects the property to [disabled] for you
+html`<button-ui .disabled=${isLoading}>Save</button-ui>`;
+```
+
+Why AdiaUI doesn't implement `?attr=`: custom elements declare their reflective property/attribute mapping via `static properties = { disabled: { type: Boolean, reflect: true } }`. The runtime handles the property-to-attribute reflection automatically. Adding a `?attr=` shape would create two valid syntaxes for the same effect — discoverability tax without behavioral benefit.
+
+**Other documented parser invariants** (closed in earlier cycles):
+
+- HTML comments containing apostrophes (`<!-- foo's bar -->`) — fixed at parser level in v0.5.3 §155. Native; no consumer action needed.
+- HTML comments containing quoted attributes (`<!-- attr="value" -->`) — same fix (v0.5.3 §155).
+- Backticks inside HTML comments — see §221i above (JS-spec footgun; not a parser bug).
+
 ### §221j — Typography token cheatsheet
 
 Quick-reference for component-CSS authoring. Cross-reference [`styles/typography.css`](./styles/typography.css):

package/core/template.js

@@ -175,6 +175,25 @@ function scan(fragment, count) {
         } else if (name[0] === '.') {
           n.removeAttribute(name);
           parts[i] = { t: 'p', n, name: name.slice(1), c: undefined, _fx: null };
+        } else if (name[0] === '?') {
+          // §250 (v0.5.11, FEEDBACK-27): Lit-style boolean attribute syntax
+          // (`?attr=${bool}`) is NOT supported. Without this branch, the
+          // attribute name registers verbatim including the `?` — silent
+          // inert binding. Strip the bogus attribute, warn loudly + degrade
+          // to a no-op text-node part so nothing reaches the DOM.
+          // Consumers should use `.attr=${bool}` (property binding); AdiaUI
+          // primitives reflect properties to DOM attributes automatically.
+          // Parallel structural fix to v0.5.3 §152 partial-interpolation warn.
+          n.removeAttribute(name);
+          // eslint-disable-next-line no-console
+          console.warn(
+            `[template] Lit-style boolean attribute "${name}=" is not supported.\n` +
+            `  Element: <${n.tagName.toLowerCase()}>\n` +
+            `  Use .${name.slice(1)}=\${value} (property binding) instead — ` +
+            `the primitive reflects the property to the DOM attribute for you.\n` +
+            `  See USAGE.md § Template parser — invariants + unsupported syntaxes.`
+          );
+          parts[i] = { t: 'n', n: document.createTextNode(''), c: undefined, _fx: null };
         } else {
           parts[i] = { t: 'a', n, name, c: undefined, _fx: null };
         }

package/core/template.test.js

@@ -0,0 +1,97 @@
+/**
+ * core/template.js — focused tests for the §250 (v0.5.11) `?attr=${bool}`
+ * silent-failure-trap close. Surfaced by FEEDBACK-27 against v0.5.10 source.
+ *
+ * Pre-§250: `?disabled=${true}` registered a literal `?disabled` DOM
+ * attribute with no console warning. Consumer ergonomics gap — Lit-familiar
+ * developers reach for the most ergonomic syntax + ship inert bindings.
+ *
+ * Post-§250: scan-time `console.warn` fires + the bogus part is degraded to
+ * a no-op text-node, so nothing reaches the DOM. Migration path is
+ * `.attr=${bool}` (property binding) — primitives reflect properties to DOM
+ * attributes automatically.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { html, stamp } from './template.js';
+
+describe('html template — §250 (v0.5.11) ?attr=${bool} silent-failure trap', () => {
+  let container;
+  let warnSpy;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    container.remove();
+    warnSpy.mockRestore();
+  });
+
+  it('fires console.warn at scan time when ?attr=${bool} is encountered', () => {
+    const tpl = html`<div ?disabled=${true}></div>`;
+    stamp(tpl, container);
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = warnSpy.mock.calls[0][0];
+    expect(msg).toMatch(/Lit-style boolean attribute/);
+    expect(msg).toMatch(/\?disabled=/);
+    expect(msg).toMatch(/\.disabled=/);  // migration path mentioned
+  });
+
+  it('does NOT register a literal "?attr" attribute on the DOM node', () => {
+    const tpl = html`<div ?disabled=${true} data-test="probe"></div>`;
+    stamp(tpl, container);
+
+    const node = container.querySelector('[data-test="probe"]');
+    expect(node).not.toBeNull();
+    expect(node.getAttribute('?disabled')).toBeNull();
+    expect(node.hasAttribute('?disabled')).toBe(false);
+  });
+
+  it('does NOT set the matching DOM attribute either (no Lit-attr semantics)', () => {
+    // AdiaUI intentionally does not implement `?attr=${bool}` semantics.
+    // The warn + degrade-to-no-op path means truthy `?disabled` does NOT
+    // add `[disabled]` to the DOM. Consumer must use `.disabled=` for that.
+    const tpl = html`<div ?disabled=${true} data-test="probe"></div>`;
+    stamp(tpl, container);
+
+    const node = container.querySelector('[data-test="probe"]');
+    expect(node.hasAttribute('disabled')).toBe(false);
+  });
+
+  it('fires the warn even when the bound value is falsy', () => {
+    // Lit's `?attr=${false}` removes the attribute. AdiaUI's contract is
+    // "this syntax is not supported, period" — warn fires regardless of
+    // truthiness to maximize visibility of the authoring error.
+    const tpl = html`<div ?disabled=${false}></div>`;
+    stamp(tpl, container);
+
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+  });
+
+  it('does not warn on canonical .prop=${val} (no false positive)', () => {
+    // Make sure the new `?`-prefix branch doesn't accidentally fire on
+    // adjacent canonical syntaxes.
+    const tpl = html`<div .className=${'x'}></div>`;
+    stamp(tpl, container);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('does not warn on canonical @event=${handler} (no false positive)', () => {
+    const tpl = html`<div @click=${() => {}}></div>`;
+    stamp(tpl, container);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it('does not warn on canonical attr=${value} (no false positive)', () => {
+    const tpl = html`<div data-id=${'42'}></div>`;
+    stamp(tpl, container);
+
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.10",
+  "version": "0.5.11",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",