@adia-ai/web-components 0.5.17 → 0.5.18

package/CHANGELOG.md

@@ -11,6 +11,11 @@ runtime ships in the sibling `@adia-ai/a2ui-runtime` package
 
 _No pending changes._
 
+## [0.5.18] - 2026-05-16
+
+### Fixed
+- §341 (FB-43; P1) — `<swatch-ui>` chrome destroyed when interpolated via parent `html\`\`` template `${chromeFrag}`. `template.js`'s `scan()` replaces `<!--p:N-->` comments with empty text nodes inside the swatch element when the parent template is cloned; `wrap()` later mutates those text nodes in-place via `replaceWith()`. Pre-§341: the swatch's `#stamp()` ran `innerHTML = ''` between the parent's `mount()` and `update()` (synchronous custom-element connectedCallback timing), wiping the text-node placeholders. Parent's `replaceWith()` then ran on detached nodes — silent no-op — leaving wrapper-spans detached and chrome stamped into a subtree that never reached the live DOM. Symptom: chrome interpolated as `${chromeFrag}` was completely invisible (queryable from neither swatch nor host). Blocked Tokens Studio's C1.3 main-palette dogfood migration (~80 swatches inside `repeat()`). **Fix:** preserve empty text nodes + comment nodes (template-engine placeholders) AND display:contents wrapper-spans through `innerHTML = ''`. Detach them before the wipe, re-attach at the canonical chrome position (between tile + badge) after the canonical structure is stamped. Wrapper-spans preserved in-place keep the template-engine's `part.n` reference stable across re-renders → chrome content updates land in the same DOM location automatically. `#absorbChromeSlot()`'s late-arriving wrapper handler also updated: MOVE the wrapper (not hoist chrome out of it) to canonical position — same identity-preservation rationale. **§331 contract refined:** previously chrome was hoisted to be a direct sibling of the swatch's internal elements (`parentElement === swatch`); §341 keeps chrome inside the wrapper-span which is a direct sibling. Visually identical (display:contents collapses the wrapper's box) but the DOM identity is now wrapper-bearing. 3 NEW vitest cases (`FB-43 / §341`) + 3 §331 (FB-39) tests updated for new contract. 15/15 swatch tests passing.
+
 ## [0.5.17] - 2026-05-16
 
 ### Fixed

package/components/swatch/class.js

@@ -234,14 +234,45 @@ export class UISwatch extends UIElement {
     const chromeSlot = Array.from(this.children).filter(
       n => n.getAttribute && n.getAttribute('slot') === 'chrome'
     );
-    // Also collect chrome elements nested inside wrapper-spans (template-render path).
-    for (const wrapper of Array.from(this.children)) {
-      if (wrapper.getAttribute?.('slot') === 'chrome') continue;
-      const nested = wrapper.querySelectorAll?.('[slot="chrome"]');
-      if (nested) for (const n of nested) chromeSlot.push(n);
-    }
     for (const n of chromeSlot) n.remove();
 
+    // §341 (v0.5.x, FB-43): preserve display:contents wrapper-spans that
+    // already contain chrome at #stamp() time (rare — typically when a
+    // setup script pre-built the subtree before connect). AdiaUI's `html\`\``
+    // template engine wraps each `${...}` interpolation in a `<span
+    // style="display: contents">` (per `core/template.js:212` `wrap()`);
+    // re-renders update wrapper contents via `part.n`. Detach + re-attach
+    // at canonical position so they survive innerHTML='' below.
+    const chromeWrappers = Array.from(this.children).filter(n =>
+      n.tagName === 'SPAN' &&
+      n.style?.display === 'contents' &&
+      n.querySelector?.('[slot="chrome"]')
+    );
+    for (const w of chromeWrappers) w.remove();
+
+    // §341 (FB-43): preserve template-engine text-node + comment
+    // placeholders. AdiaUI's `scan()` (template.js:113) replaces
+    // `<!--p:N-->` comments with empty text nodes; `wrap()` later
+    // creates `<span style="display: contents">` and replaces the text
+    // node in-place via `replaceWith(part.n, wrapper)`. For that
+    // replaceWith to work, the text node MUST still be attached when
+    // parent's update() runs (it runs AFTER our connectedCallback
+    // synchronously, so AFTER #stamp()). Pre-§341, innerHTML='' below
+    // wiped the text node → replaceWith no-op → wrapper detached →
+    // chrome stamped into a detached subtree (never reaches DOM).
+    //
+    // Fix: extract empty text + comment nodes before the wipe, re-attach
+    // at the canonical chrome region (between tile and badge). Parent's
+    // update() then replaces them with live wrapper-spans in place;
+    // subsequent re-renders update the wrappers in-place too.
+    const placeholders = [];
+    for (const n of Array.from(this.childNodes)) {
+      if ((n.nodeType === 3 && !n.data) || n.nodeType === 8) {
+        placeholders.push(n);
+      }
+    }
+    for (const p of placeholders) p.remove();
+
     // Capture pre-existing default-slot content so consumer-authored
     // children (e.g. <swatch-ui>Forecast</swatch-ui>) survive stamping.
     // `[slot="chrome"]` children are already removed above, so won't appear here.
@@ -279,6 +310,19 @@ export class UISwatch extends UIElement {
     // `position: absolute; top: 2px; right: 2px` and anchor against the host's
     // padding-box, which matches the tile's geometry in the block layout.
     for (const n of chromeSlot) this.appendChild(n);
+    // §341 (FB-43): re-attach chrome-bearing wrapper-spans at canonical
+    // position. Wrapper preserves the template-engine's `part.n`
+    // reference so parent re-renders can update chrome content in-place
+    // without detaching the wrapper.
+    for (const w of chromeWrappers) this.appendChild(w);
+    // §341 (FB-43): re-attach template-engine placeholders at canonical
+    // chrome region. Parent's pending update() will replace each
+    // placeholder with a live wrapper-span (via `wrap(part)`'s
+    // `replaceWith`), landing chrome content visually between tile +
+    // badge. Without this re-attach, the placeholders would have been
+    // wiped by `innerHTML = ''` and the parent's `replaceWith` would
+    // no-op against a detached node.
+    for (const p of placeholders) this.appendChild(p);
 
     // Badge container — holds one or more <span data-badge-variant="..."> children.
     // Multi-badge support added in v0.4.9 §92 (FEEDBACK-04 follow-up).
@@ -350,9 +394,18 @@ export class UISwatch extends UIElement {
         this.insertBefore(child, this.#badgeEl);
       }
     }
-    // §331 (v0.5.16, FB-39): also handle wrapper-spanned chrome children
-    // that arrive AFTER #stamp() (parent template's late update() pass).
-    // Hoist them OUT of any non-internal wrapper + into the canonical slot.
+    // §331 (v0.5.16, FB-39): handle wrapper-spanned chrome children that
+    // arrive AFTER #stamp() (parent template's late update() pass).
+    //
+    // §341 (FB-43) refinement: move the WRAPPER to canonical position
+    // rather than hoisting chrome OUT of it. The wrapper is the parent
+    // template engine's `part.n` reference; if we extract chrome, the
+    // next parent re-render lands new chrome inside the now-empty
+    // wrapper at the wrapper's original (non-canonical) position. By
+    // moving the wrapper itself to canonical position, future parent
+    // updates land at the right visual location automatically.
+    // Wrapper is `display: contents` → no layout box → chrome anchors
+    // against the swatch's padding-box correctly.
     for (const child of Array.from(this.children)) {
       if (
         child === this.#tileEl ||
@@ -361,11 +414,12 @@ export class UISwatch extends UIElement {
         child === this.#detailEl ||
         child === this.#copyEl
       ) continue;
-      const nested = child.querySelectorAll?.('[slot="chrome"]');
-      if (!nested || !nested.length) continue;
-      for (const n of nested) {
-        this.insertBefore(n, this.#badgeEl);
-      }
+      // Only move display:contents wrappers that actually carry chrome.
+      const isWrapper = child.tagName === 'SPAN' && child.style?.display === 'contents';
+      if (!isWrapper) continue;
+      const hasNested = child.querySelector?.('[slot="chrome"]');
+      if (!hasNested) continue;
+      this.insertBefore(child, this.#badgeEl);
     }
   }
 

package/components/swatch/swatch.test.js

@@ -175,7 +175,10 @@ describe('<swatch-ui> chrome child nested in display:contents wrapper (FB-39 /
     // <span style="display: contents"> (per core/template.js:212 `wrap()`).
     // When consumer writes `html`<swatch-ui>${chromeFrag}</swatch-ui>``,
     // the chromeFrag's content lands NESTED inside a wrapper span — not
-    // as direct children of <swatch-ui>. Pre-§331 the chrome was wiped.
+    // as direct children of <swatch-ui>. Pre-§331 the chrome was wiped;
+    // §341 (FB-43) refined to keep chrome INSIDE the wrapper + move the
+    // wrapper to canonical position (preserves template-engine `part.n`
+    // identity so parent re-renders update in-place).
     const swatch = document.createElement('swatch-ui');
     swatch.setAttribute('shape', 'block');
     swatch.setAttribute('label-position', 'overlay');
@@ -196,18 +199,22 @@ describe('<swatch-ui> chrome child nested in display:contents wrapper (FB-39 /
 
     const found = swatch.querySelector('#wrapped-chrome');
     expect(found).not.toBeNull();
-    // Chrome child should be a direct host sibling positioned between tile + badge.
+    // §341: chrome stays inside the display:contents wrapper; wrapper is
+    // at canonical position (between tile + badge). Visually equivalent
+    // to direct-child placement because display:contents collapses the box.
+    expect(found.parentElement).toBe(wrapper);
+    expect(wrapper.parentElement).toBe(swatch);
     const tile = swatch.querySelector('[data-tile]');
     const badge = swatch.querySelector('[data-badge]');
-    expect(found.parentElement).toBe(swatch);
-    expect(found.previousElementSibling).toBe(tile);
-    expect(found.nextElementSibling).toBe(badge);
+    expect(wrapper.previousElementSibling).toBe(tile);
+    expect(wrapper.nextElementSibling).toBe(badge);
   });
 
   it('handles MULTIPLE chrome children nested in separate wrapper spans', async () => {
     // Each interpolated fragment in html`` gets its own wrapper span,
     // so multi-chrome usage (`${badge}${dot1}${dot2}`) produces multiple
-    // wrapper spans, each containing one chrome child.
+    // wrapper spans, each containing one chrome child. §341: wrappers
+    // stay intact, chrome remains inside them.
     const swatch = document.createElement('swatch-ui');
     swatch.setAttribute('shape', 'block');
     swatch.setAttribute('label-position', 'overlay');
@@ -230,7 +237,10 @@ describe('<swatch-ui> chrome child nested in display:contents wrapper (FB-39 /
     for (const id of ids) {
       const found = swatch.querySelector(`#${id}`);
       expect(found).not.toBeNull();
-      expect(found.parentElement).toBe(swatch);
+      // §341: chrome stays inside its wrapper; wrapper is a direct child of swatch.
+      expect(found.parentElement.tagName).toBe('SPAN');
+      expect(found.parentElement.style.display).toBe('contents');
+      expect(found.parentElement.parentElement).toBe(swatch);
     }
   });
 
@@ -260,11 +270,15 @@ describe('<swatch-ui> chrome child nested in display:contents wrapper (FB-39 /
 
     const found = swatch.querySelector('#late-wrapped');
     expect(found).not.toBeNull();
-    expect(found.parentElement).toBe(swatch);
+    // §341: chrome stays inside wrapper; wrapper is now at canonical
+    // position (between tile and badge) after #absorbChromeSlot()'s
+    // re-positioning of the wrapper.
+    expect(found.parentElement).toBe(wrapper);
+    expect(wrapper.parentElement).toBe(swatch);
     const tile = swatch.querySelector('[data-tile]');
     const badge = swatch.querySelector('[data-badge]');
-    expect(found.previousElementSibling).toBe(tile);
-    expect(found.nextElementSibling).toBe(badge);
+    expect(wrapper.previousElementSibling).toBe(tile);
+    expect(wrapper.nextElementSibling).toBe(badge);
   });
 });
 
@@ -329,3 +343,108 @@ describe('<swatch-ui> [auto-contrast] does not override [label-position="overlay
     expect(block).toMatch(/position\s*:\s*absolute/);
   });
 });
+
+describe('<swatch-ui> chrome survives parent template re-render (FB-43 / §341)', () => {
+  // FB-43 (P1): claim is `template.js` mount() replaceChildren() destroys
+  // chrome children on every re-render. The real mechanism is more subtle:
+  // §331's #stamp() does `innerHTML = ''` which wipes the wrapper-span
+  // created by the parent template engine's wrap() (after collecting
+  // chrome into chromeSlot). The parent template's `part.n` still points
+  // to the now-detached wrapper-span. On parent re-render, applyValue()
+  // stamps the new chrome value INTO the detached wrapper-span — landing
+  // in memory but not in the DOM. Chrome is effectively destroyed.
+  //
+  // This empirical test reproduces the exact scenario.
+  let host;
+  let html, stamp;
+
+  beforeAll(async () => {
+    ({ html, stamp } = await import('../../core/template.js'));
+  });
+
+  beforeEach(() => {
+    host = document.createElement('div');
+    document.body.appendChild(host);
+  });
+
+  // §341 contract: chrome is queryable from swatch + lives inside a
+  // display:contents wrapper-span (the template-engine's stable part.n).
+  // The wrapper sits at canonical chrome position (between tile + badge).
+  // Visually equivalent to direct-child placement because display:contents
+  // collapses the wrapper's box.
+  function assertChromeCanonical(swatch, chrome) {
+    expect(chrome).not.toBeNull();
+    const wrapper = chrome.parentElement;
+    expect(wrapper).not.toBeNull();
+    // The wrapper is the chrome's direct parent + a display:contents span
+    // that's a direct child of the swatch (the template-engine's
+    // wrap()-created stable reference).
+    expect(wrapper.tagName).toBe('SPAN');
+    expect(wrapper.style.display).toBe('contents');
+    expect(wrapper.parentElement).toBe(swatch);
+    // Wrapper sits between tile and badge (canonical chrome region).
+    const tile = swatch.querySelector('[data-tile]');
+    const badge = swatch.querySelector('[data-badge]');
+    expect(tile).not.toBeNull();
+    expect(badge).not.toBeNull();
+    // Walk from tile forward: should hit wrapper before badge.
+    let cursor = tile.nextElementSibling;
+    let foundWrapper = false;
+    while (cursor && cursor !== badge) {
+      if (cursor === wrapper) { foundWrapper = true; break; }
+      cursor = cursor.nextElementSibling;
+    }
+    expect(foundWrapper).toBe(true);
+  }
+
+  it('FB-43: chrome interpolated via html`` template survives first render', async () => {
+    const chromeFrag = html`<span slot="chrome" id="fb43-chrome">P3</span>`;
+    const tpl = html`<swatch-ui label="500" color="#3b82f6">${chromeFrag}</swatch-ui>`;
+    stamp(tpl, host);
+    await new Promise((r) => setTimeout(r, 80));
+
+    const found = host.querySelector('#fb43-chrome');
+    expect(found).not.toBeNull();
+    const swatch = host.querySelector('swatch-ui');
+    assertChromeCanonical(swatch, found);
+  });
+
+  it('FB-43: chrome interpolated via html`` template survives second parent re-stamp (same strings)', async () => {
+    // FB-43's core claim: re-render destroys chrome. Same template strings
+    // → stamp() cache should hit → update() runs. Chrome content updates
+    // in-place inside the preserved wrapper-span.
+    function renderOnce(chromeText) {
+      const chromeFrag = html`<span slot="chrome" id="fb43-chrome">${chromeText}</span>`;
+      return html`<swatch-ui label="500" color="#3b82f6">${chromeFrag}</swatch-ui>`;
+    }
+    stamp(renderOnce('P3'), host);
+    await new Promise((r) => setTimeout(r, 80));
+    expect(host.querySelector('#fb43-chrome')).not.toBeNull();
+
+    // Re-stamp with same template strings (different value).
+    stamp(renderOnce('OOG'), host);
+    await new Promise((r) => setTimeout(r, 80));
+
+    const swatch = host.querySelector('swatch-ui');
+    const chrome = swatch.querySelector('[slot="chrome"]');
+    expect(chrome).not.toBeNull();
+    expect(chrome.textContent).toBe('OOG');
+    assertChromeCanonical(swatch, chrome);
+  });
+
+  it('FB-43: chrome survives N consecutive re-renders (regression stress test)', async () => {
+    function renderOnce(chromeText) {
+      const chromeFrag = html`<span slot="chrome" id="fb43-chrome">${chromeText}</span>`;
+      return html`<swatch-ui label="500" color="#3b82f6">${chromeFrag}</swatch-ui>`;
+    }
+    for (let i = 0; i < 5; i++) {
+      stamp(renderOnce(`label-${i}`), host);
+      await new Promise((r) => setTimeout(r, 60));
+    }
+    const swatch = host.querySelector('swatch-ui');
+    const chrome = swatch.querySelector('[slot="chrome"]');
+    expect(chrome).not.toBeNull();
+    expect(chrome.textContent).toBe('label-4');
+    assertChromeCanonical(swatch, chrome);
+  });
+});

package/package.json

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