@adia-ai/web-components 0.5.16 → 0.5.17

package/CHANGELOG.md

@@ -11,6 +11,15 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.17] - 2026-05-16
+
+### Fixed
+- §339 (FB-41; P2) — `<swatch-ui>` `[auto-contrast]` overrode `[label-position="overlay"]` position. Two `@scope (swatch-ui)` rules at equal specificity (0,3,1) collided on `> [data-label] { position }`; source order favored auto-contrast's `position: relative` over overlay's `position: absolute` → label dropped below tile (host doubled to 2× block-h). Blocks the canonical `label-position="overlay" + auto-contrast` pattern §253 enabled. Fix: drop `position: relative` from `[auto-contrast]` data-label + data-detail rules — z-index works on positioned elements (overlay supplies position: absolute), and non-overlay defaults are flex flow where z-index is irrelevant. 3 NEW vitest cases lock the CSS source structurally.
+- §340 (FB-42; P2) — `<list-item-ui>` `render()` text-branch asymmetry. Icon + description branches had create-if-missing paths; text branch only updated existing stamped spans. Template engine `.text=${expr}` (canonical authoring pattern per USAGE.md) arrives AFTER `connectedCallback` `#stamp()` — `this.text` was `''` at stamp time so no span created, `render()` fired but couldn't recover → primary text silently invisible. Fix: mirror description branch's create-if-missing + remove-when-cleared pattern. NEW `list.test.js` with 5 vitest cases (create-on-prop-set / update / remove / parity-with-description / consumer-stamp non-interference).
+
+### Tests
+- §338 (FB-40; misdiagnosed) — 4 NEW vitest cases in `core/template.test.js` lock the existing FEEDBACK-06 comment-aware `inTag()` fix (line 55-78). FB-40 reported apostrophes-in-HTML-comments crashes claiming the parser mis-classifies subsequent `${…}` placeholders; the cited mechanism is incorrect — `inTag()` has skipped past `<!--…-->` wholesale since FEEDBACK-06 (pre-v0.5.x). The 4 new tests empirically verify the fix covers apostrophe-comment + double-quote-comment + multi-apostrophe + apostrophe+em-dash cases. RESPONSE-40 requests stack-trace evidence for the actual crash mechanism since the cited apostrophe diagnosis is empirically wrong against current source.
+
 ## [0.5.16] - 2026-05-16
 
 ### v0.5.16 §331 — `<swatch-ui>` chrome-slot wrapper-span deep-walk (FB-39; P1)

package/components/list/class.js

@@ -227,9 +227,24 @@ export class UIListItem extends UIElement {
       iconEl.remove();
     }
 
-    // Sync text — only touch elements we stamped.
+    // Sync text — mirror the icon + description branches: create-if-missing
+    // path so post-connect property bindings (template engine `.text=${expr}`)
+    // can stamp the span when `#stamp()` ran with `this.text === ''`. §340
+    // (FB-42) — without this, primary text is silently invisible when set
+    // via property binding (the canonical authoring pattern per USAGE.md).
     const textEl = this.#ownChild('[slot="text"]');
-    if (this.#wasStamped(textEl)) textEl.textContent = this.text;
+    if (this.text) {
+      if (textEl) {
+        if (this.#wasStamped(textEl)) textEl.textContent = this.text;
+      } else {
+        const el = this.#stampMark(document.createElement('span'));
+        el.setAttribute('slot', 'text');
+        el.textContent = this.text;
+        this.appendChild(el);
+      }
+    } else if (this.#wasStamped(textEl)) {
+      textEl.remove();
+    }
 
     // Sync description — only touch elements we stamped.
     const descEl = this.#ownChild('[slot="description"]');

package/components/list/list.test.js

@@ -0,0 +1,106 @@
+/**
+ * <list-item-ui> behavioral tests.
+ *
+ * Initial scope: FB-42 / §340 regression coverage — `render()`'s text
+ * branch can now create the slot element when `this.text` is set
+ * post-connect (e.g. via template-engine property binding), matching
+ * the icon + description branches' create-if-missing pattern.
+ *
+ * Test setup note: happy-dom connects custom elements synchronously
+ * during innerHTML parsing. To exercise the post-connect property-set
+ * timing (template-engine path), tests use `document.createElement` +
+ * `host.appendChild()` to connect with empty `text`, then set the
+ * property AFTER connect to trigger render()'s recovery path.
+ */
+
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+
+beforeAll(async () => {
+  await import('./list.js');
+});
+
+describe('<list-item-ui> render() text branch — post-connect property binding (FB-42 / §340)', () => {
+  let host;
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+
+  it('creates [slot="text"] span when .text is set AFTER connectedCallback (template-engine timing)', async () => {
+    const li = document.createElement('list-item-ui');
+    host.appendChild(li);
+    // connectedCallback fires here with this.text === '' — span NOT stamped
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).toBeNull();
+
+    // Template engine sets the property post-connect
+    li.text = 'Primary text via property binding';
+    await new Promise((r) => setTimeout(r, 30));
+
+    const textSpan = li.querySelector('[slot="text"]');
+    expect(textSpan).not.toBeNull();
+    expect(textSpan.textContent).toBe('Primary text via property binding');
+  });
+
+  it('updates existing [slot="text"] span when .text changes', async () => {
+    const li = document.createElement('list-item-ui');
+    li.setAttribute('text', 'initial');
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+
+    const textSpan = li.querySelector('[slot="text"]');
+    expect(textSpan).not.toBeNull();
+    expect(textSpan.textContent).toBe('initial');
+
+    li.text = 'updated';
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]').textContent).toBe('updated');
+  });
+
+  it('removes stamped [slot="text"] span when .text is cleared', async () => {
+    const li = document.createElement('list-item-ui');
+    li.setAttribute('text', 'will be removed');
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).not.toBeNull();
+
+    li.text = '';
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).toBeNull();
+  });
+
+  it('text branch parity with description branch — both create-if-missing post-connect', async () => {
+    const li = document.createElement('list-item-ui');
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+    expect(li.querySelector('[slot="text"]')).toBeNull();
+    expect(li.querySelector('[slot="description"]')).toBeNull();
+
+    li.text = 'primary';
+    li.description = 'secondary';
+    await new Promise((r) => setTimeout(r, 30));
+
+    expect(li.querySelector('[slot="text"]')?.textContent).toBe('primary');
+    expect(li.querySelector('[slot="description"]')?.textContent).toBe('secondary');
+  });
+
+  it('does not stamp [slot="text"] for unauthored consumer-provided text content', async () => {
+    // If the consumer provides their own [slot="text"] child (e.g. for
+    // richer markup), the render() branch must NOT touch it.
+    const li = document.createElement('list-item-ui');
+    const userSpan = document.createElement('span');
+    userSpan.setAttribute('slot', 'text');
+    userSpan.innerHTML = '<strong>bold</strong> user';
+    li.appendChild(userSpan);
+    host.appendChild(li);
+    await new Promise((r) => setTimeout(r, 30));
+
+    li.text = 'attempt to set';
+    await new Promise((r) => setTimeout(r, 30));
+
+    const span = li.querySelector('[slot="text"]');
+    expect(span).toBe(userSpan); // identity preserved
+    expect(span.innerHTML).toBe('<strong>bold</strong> user'); // markup preserved
+  });
+});

package/components/swatch/swatch.css

@@ -255,9 +255,20 @@
      stamps [data-on-light] or [data-on-dark] on the label. The label then
      swaps fg color so it remains legible against the tile background.
      Only fires for shape="block" (label sits ON the tile); for other
-     shapes the label is beside the tile and uses the normal chrome fg. */
+     shapes the label is beside the tile and uses the normal chrome fg.
+
+     §339 (FB-41): the auto-contrast rules previously set `position:
+     relative` which collided at equal specificity (0,3,1) with the
+     overlay rule's `position: absolute` (line 164). Source order made
+     the later auto-contrast rule win, so `[label-position="overlay"]
+     [auto-contrast]` resolved the label to `position: relative`,
+     dropping it OUT of overlay and below the tile (host height doubled).
+     Fix: drop `position: relative` from auto-contrast. `z-index: 1`
+     only does work on a positioned element; the overlay rule already
+     supplies `position: absolute` for the overlay case. For the
+     non-overlay default (label below tile), the label is in normal
+     flow and doesn't overlap anything, so z-index is irrelevant. */
   :scope[shape="block"][auto-contrast] > [data-label] {
-    position: relative;
     z-index: 1;
   }
   :scope[shape="block"][auto-contrast] > [data-label][data-on-dark] {
@@ -268,7 +279,6 @@
   }
   /* Detail line follows the same auto-contrast choice. */
   :scope[shape="block"][auto-contrast] > [data-detail] {
-    position: relative;
     z-index: 1;
   }
   :scope[shape="block"][auto-contrast] > [data-label][data-on-dark] ~ [data-detail] {

package/components/swatch/swatch.test.js

@@ -267,3 +267,65 @@ describe('<swatch-ui> chrome child nested in display:contents wrapper (FB-39 /
     expect(found.nextElementSibling).toBe(badge);
   });
 });
+
+describe('<swatch-ui> [auto-contrast] does not override [label-position="overlay"] position (FB-41 / §339)', () => {
+  // Structural CSS-source-string assertion: happy-dom does not resolve
+  // @scope CSS specificity reliably, so we verify the fix by reading
+  // swatch.css text and asserting the auto-contrast rules don't carry
+  // `position: relative` (which collided at equal specificity with the
+  // overlay rule's `position: absolute` via source order).
+  //
+  // Pre-§339: `:scope[shape="block"][auto-contrast] > [data-label]`
+  // declared `position: relative; z-index: 1`. Combined with overlay
+  // attribute, the later rule won → label dropped out of overlay layout.
+  //
+  // Post-§339: only `z-index: 1` remains (z-index is no-op on static
+  // elements but harmless; for the overlay case it stacks above the
+  // tile correctly via the overlay rule's `position: absolute`).
+  it('auto-contrast label rule does NOT declare position: relative (regression for FB-41)', async () => {
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const url = await import('node:url');
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const css = fs.readFileSync(path.join(here, 'swatch.css'), 'utf8');
+    const match = css.match(
+      /:scope\[shape="block"\]\[auto-contrast\]\s*>\s*\[data-label\]\s*\{([^}]*)\}/
+    );
+    expect(match).not.toBeNull();
+    const block = match[1];
+    expect(block).not.toMatch(/position\s*:\s*relative/);
+    expect(block).toMatch(/z-index\s*:\s*1/);
+  });
+
+  it('auto-contrast detail rule does NOT declare position: relative (regression for FB-41)', async () => {
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const url = await import('node:url');
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const css = fs.readFileSync(path.join(here, 'swatch.css'), 'utf8');
+    const match = css.match(
+      /:scope\[shape="block"\]\[auto-contrast\]\s*>\s*\[data-detail\]\s*\{([^}]*)\}/
+    );
+    expect(match).not.toBeNull();
+    const block = match[1];
+    expect(block).not.toMatch(/position\s*:\s*relative/);
+    expect(block).toMatch(/z-index\s*:\s*1/);
+  });
+
+  it('overlay rule still declares position: absolute (regression for FB-41)', async () => {
+    // Defensive: also assert the overlay rule's `position: absolute` is
+    // still in place — if a future refactor drops it, the §253 contract
+    // breaks regardless of the auto-contrast collision.
+    const fs = await import('node:fs');
+    const path = await import('node:path');
+    const url = await import('node:url');
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const css = fs.readFileSync(path.join(here, 'swatch.css'), 'utf8');
+    const match = css.match(
+      /:scope\[shape="block"\]\[label-position="overlay"\]\s*>\s*\[data-label\]\s*\{([^}]*)\}/
+    );
+    expect(match).not.toBeNull();
+    const block = match[1];
+    expect(block).toMatch(/position\s*:\s*absolute/);
+  });
+});

package/core/template.test.js

@@ -95,3 +95,87 @@ describe('html template — §250 (v0.5.11) ?attr=${bool} silent-failure trap',
     expect(warnSpy).not.toHaveBeenCalled();
   });
 });
+
+describe('html template — FB-40 (v0.5.16) apostrophe in HTML comments does NOT mis-classify subsequent placeholders', () => {
+  // FEEDBACK-06 §1 P0 (long resolved) made `inTag()` comment-aware:
+  // when scan() hits `<!--` outside a string context, it jumps past
+  // `-->` wholesale. FB-40 (filed 2026-05-16 post-v0.5.16 cut) reported
+  // crashes attributed to apostrophes in comments. This suite verifies
+  // empirically that the comment-aware logic still holds — the FB-40
+  // diagnosis is mistaken about the mechanism (the existing fix covers
+  // the apostrophe-in-comment case).
+
+  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('@event=${handler} placeholder AFTER apostrophe-bearing comment is classified as attribute-position', () => {
+    let received = null;
+    const handler = (e) => { received = e; };
+    const tpl = html`
+      <div>
+        <!-- editor-shell's named slots -->
+        <button data-test="probe" @click=${handler}>X</button>
+      </div>
+    `;
+    stamp(tpl, container);
+    const btn = container.querySelector('[data-test="probe"]');
+    expect(btn).not.toBeNull();
+    btn.click();
+    expect(received).not.toBeNull();
+    expect(received.type).toBe('click');
+  });
+
+  it('double-quote in HTML comment does not mis-classify subsequent attribute placeholder', () => {
+    const tpl = html`
+      <div>
+        <!-- the "Stop Override" button below -->
+        <button data-test="probe" data-id=${'42'}></button>
+      </div>
+    `;
+    stamp(tpl, container);
+    const btn = container.querySelector('[data-test="probe"]');
+    expect(btn).not.toBeNull();
+    expect(btn.getAttribute('data-id')).toBe('42');
+  });
+
+  it('multiple apostrophes across multiple comments still keep subsequent placeholders attribute-position', () => {
+    let received = null;
+    const tpl = html`
+      <div>
+        <!-- one's first comment -->
+        <span>x</span>
+        <!-- two's second comment -->
+        <button data-test="probe" @click=${(e) => { received = e; }}></button>
+      </div>
+    `;
+    stamp(tpl, container);
+    container.querySelector('[data-test="probe"]').click();
+    expect(received).not.toBeNull();
+  });
+
+  it('apostrophe + em-dash (U+2014) in a single comment does not break parsing', () => {
+    // dts-export-drawer.ts case from FB-40's cited crashes:
+    // <!-- 2026-05-14 — migrated number inputs ... -->
+    let received = null;
+    const tpl = html`
+      <div>
+        <!-- 2026-05-14 — author's notes about migrated number inputs -->
+        <button data-test="probe" @click=${(e) => { received = e; }}></button>
+      </div>
+    `;
+    stamp(tpl, container);
+    container.querySelector('[data-test="probe"]').click();
+    expect(received).not.toBeNull();
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "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",