@adia-ai/web-components 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,4 +1,14 @@
 # Changelog — @adia-ai/web-components
+## [0.8.1] — 2026-07-15
+
+### Added
+- **`tags-input-ui` chip slot template (TKT-0023)** (`components/tags-input/`). An author `<template slot="chip">` child is cloned once per committed token, with `{{value}}`/`{{index}}` substituted into every text node and attribute of the clone (single regex pass — a token literally equal to a placeholder can't be re-substituted); the template's first element child is the reconcile unit (positional diff — unchanged tokens keep their DOM node), and chip removal delegates from any `[data-index]` root via a bubbling `remove` event. Falls back to the default `<tag-ui removable text>` when the slot is absent or has no element content. Also fixed the latent `#stampShell()` first-connect `innerHTML` replacement that would have destroyed an author's template before it was ever read. 8 new tests.
+
+### Fixed
+- **`--a-link` / `--a-link-hover` / `--a-link-visited` failed WCAG AA** (`styles/colors/semantics/core.css`; as low as 2.23:1 on the light canvas) — they read the bare `--md-sys-color-primary` CTA fill, tuned for large filled surfaces, not small text. Re-pointed to Material's `-on-surface` state family (the same family `--a-primary-text` uses); clears 4.5:1 with margin in both schemes. Visible change: links render darker (light scheme) / lighter (dark scheme) than 0.8.0. Caught by the rewritten `verify:contrast` repo gate, which now resolves the real token cascade instead of the retired parametric formula.
+
+### Maintenance
+- **`dist/` bundles rebuilt** (tags-input + link-fix payloads; theme-provider CDN script inlines the swept CSS).
 ## [0.8.0] — 2026-07-15
 
 ### BREAKING — Material Design color-token adoption (MINOR cut; see `.claude/docs/MIGRATION GUIDE.md` § v0.8.0)

package/components/tags-input/tags-input.a2ui.json

@@ -227,7 +227,7 @@
     ],
     "slots": {
       "chip": {
-        "description": "Planned: custom chip template, receiving `{value, index}` per\ntoken — NOT YET IMPLEMENTED (TKT-0023; the template mechanism's\nshape needs a design decision before it's built). Every token\ncurrently renders as the fixed default,\n`<tag-ui removable text=\"<value>\">`, with no override path."
+        "description": "Custom per-token chip template (TKT-0023). Provide a single\n`<template slot=\"chip\">` child; it's cloned once per committed\ntoken, with `{{value}}` / `{{index}}` substituted into every text\nnode and attribute value in the clone (e.g.\n`<tag-ui removable text=\"{{value}}\" title=\"Item #{{index}}\">`).\nThe template's first element child is the reconcile unit — data-*\nbookkeeping attrs land on it, so removal / re-render still track\nby position the same way the default chip does. When absent, or\nwhen the template has no element content (malformed), each token\nrenders as the default `<tag-ui removable text=\"<value>\">`.\nReadonly/disabled toggling of the built-in `removable` affordance\nonly applies to the default chip — a custom template always owns\nits own removability, independent of the host's readonly/disabled\nstate."
       }
     },
     "states": [
@@ -261,7 +261,7 @@
         "name": "disabled"
       },
       {
-        "description": "Read-only; chips render without remove affordance.",
+        "description": "Read-only; default chips render without remove affordance (a\ncustom `chip` template owns its own removability and is\nunaffected).",
         "attribute": "readonly",
         "name": "readonly"
       }

package/components/tags-input/tags-input.class.js

@@ -238,6 +238,11 @@ export class UITagsInput extends UIFormElement {
       this.#bindListeners();
       return;
     }
+    // Capture any author-declared chip template (TKT-0023) BEFORE the
+    // wholesale `innerHTML` replacement below, which would otherwise
+    // discard it — the captured reference stays valid (just detached)
+    // across the replacement and gets re-appended after.
+    const chipTemplate = this.querySelector(':scope > template[slot="chip"]');
     const suggestId = `${this.#instanceId}-suggestions`;
     const inputId = `${this.#instanceId}-input`;
     this.innerHTML = `
@@ -257,6 +262,7 @@ export class UITagsInput extends UIFormElement {
       </span>
       <div data-suggestions id="${suggestId}" role="listbox" hidden></div>
     `;
+    if (chipTemplate) this.appendChild(chipTemplate);
     this.#queryRefs();
     this.#bindListeners();
   }
@@ -299,29 +305,38 @@ export class UITagsInput extends UIFormElement {
   }
 
   // ── Render chips ──
+  //
+  // SPEC-042 §chip slot (TKT-0023): an author-provided
+  // `<template slot="chip">` overrides the default `<tag-ui>` render, one
+  // clone per token. `{{value}}` / `{{index}}` are substituted into every
+  // text node and attribute value in the cloned subtree — declarative, no
+  // JS required, so it works from static markup and a2ui-generated pages.
 
   #renderChips() {
     if (!this.#chipList) return;
-    // Reconcile in place: existing chips that still match keep their nodes
-    // (so the user's :hover / :focus / animation states don't flicker on
-    // each typed-character render); excess chips get dropped; new chips
-    // append at the end.
-    const existing = Array.from(this.#chipList.querySelectorAll(':scope > tag-ui'));
+    const template = this.querySelector(':scope > template[slot="chip"]');
+    const mode = template ? 'custom' : 'default';
+    // Reconcile in place: an existing chip at a position keeps its node
+    // when its value + mode haven't changed (so :hover / :focus / animation
+    // states don't flicker on each typed-character render); a changed or
+    // absent position gets a fresh node; excess chips drop; new ones append.
+    const existing = Array.from(this.#chipList.children);
     for (let i = 0; i < this.#value.length; i++) {
       const v = this.#value[i];
-      let chip = existing[i];
-      if (!chip) {
-        chip = document.createElement('tag-ui');
-        chip.setAttribute('role', 'listitem');
-        this.#chipList.appendChild(chip);
-      }
-      chip.setAttribute('text', v);
-      if (this.readonly || this.disabled) {
-        chip.removeAttribute('removable');
-      } else {
-        chip.setAttribute('removable', '');
+      const current = existing[i];
+      const reusable = current && current.dataset.chipMode === mode && current.dataset.chipValue === v;
+      if (reusable) {
+        current.setAttribute('data-index', String(i));
+        if (!template) {
+          if (this.readonly || this.disabled) current.removeAttribute('removable');
+          else current.setAttribute('removable', '');
+        }
+        continue;
       }
-      chip.setAttribute('data-index', String(i));
+      const fresh = template ? this.#buildCustomChip(template, v, i) : this.#buildDefaultChip(v, i);
+      if (current) this.#chipList.replaceChild(fresh, current);
+      else this.#chipList.appendChild(fresh);
+      existing[i] = fresh;
     }
     // Drop overflow chips.
     for (let i = this.#value.length; i < existing.length; i++) {
@@ -329,6 +344,58 @@ export class UITagsInput extends UIFormElement {
     }
   }
 
+  #buildDefaultChip(value, index) {
+    const chip = document.createElement('tag-ui');
+    chip.setAttribute('role', 'listitem');
+    chip.setAttribute('text', value);
+    if (!(this.readonly || this.disabled)) chip.setAttribute('removable', '');
+    chip.setAttribute('data-index', String(index));
+    chip.dataset.chipMode = 'default';
+    chip.dataset.chipValue = value;
+    return chip;
+  }
+
+  #buildCustomChip(template, value, index) {
+    const frag = template.content.cloneNode(true);
+    this.#substitutePlaceholders(frag, value, index);
+    // Reconcile unit = first element child (ignores incidental whitespace
+    // text nodes from formatted template markup).
+    const root = frag.firstElementChild;
+    if (!root) return this.#buildDefaultChip(value, index); // malformed template — degrade to default rather than render nothing
+    root.setAttribute('role', 'listitem');
+    root.setAttribute('data-index', String(index));
+    root.dataset.chipMode = 'custom';
+    root.dataset.chipValue = value;
+    return root;
+  }
+
+  /** Replace `{{value}}` / `{{index}}` in every text node + attribute of
+   *  `root` (a cloned template fragment), in place. Single-pass regex —
+   *  chained `.replaceAll()` calls would let a token whose literal text is
+   *  `{{index}}` get re-matched by the second pass after the first pass
+   *  substitutes it in. */
+  #substitutePlaceholders(root, value, index) {
+    const idxStr = String(index);
+    const substitute = (str) =>
+      str.replace(/\{\{value\}\}|\{\{index\}\}/g, (m) => (m === '{{value}}' ? value : idxStr));
+    const walker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT);
+    let node;
+    // eslint-disable-next-line no-cond-assign
+    while ((node = walker.nextNode())) {
+      if (node.nodeType === Node.TEXT_NODE) {
+        if (node.data.includes('{{')) {
+          node.data = substitute(node.data);
+        }
+      } else {
+        for (const attr of node.attributes) {
+          if (attr.value.includes('{{')) {
+            attr.value = substitute(attr.value);
+          }
+        }
+      }
+    }
+  }
+
   #renderSuggestions() {
     if (!this.#suggestEl) return;
     const typed = this.#inputEl ? (this.#inputEl.textContent || '').trim().toLowerCase() : '';
@@ -516,7 +583,12 @@ export class UITagsInput extends UIFormElement {
   }
 
   #handleChipRemove(e) {
-    const chip = e.target.closest('tag-ui[data-index]');
+    // `[data-index]` (not `tag-ui[data-index]`) — a chip-slot template
+    // (TKT-0023) may wrap its own `<tag-ui removable>` inside an arbitrary
+    // root element; `data-index` is stamped on whichever node is the
+    // reconcile unit for that position (see `#buildCustomChip`), so
+    // `closest()` finds the right ancestor regardless of its tag name.
+    const chip = e.target.closest('[data-index]');
     if (!chip) return;
     // tag-ui's `remove` CustomEvent bubbles SYNCHRONOUSLY before tag-ui's
     // own `this.remove()` runs (see tag/tag.class.js:59-63 — dispatch then
@@ -525,8 +597,9 @@ export class UITagsInput extends UIFormElement {
     // positional reconcile in `#renderChips()` mutates the WRONG chip's
     // text — visually erasing one or more adjacent chips. Pre-emptively
     // detach the source chip ourselves so the DOM matches `#value` before
-    // render. tag-ui's later `this.remove()` is a harmless no-op on an
-    // already-detached node.
+    // render. tag-ui's later `this.remove()` is a harmless no-op — either
+    // on an already-detached node (default chip == the tag-ui itself), or
+    // on a nested tag-ui whose ancestor `chip` root was just detached.
     e.stopPropagation();
     const idx = Number(chip.dataset.index);
     if (!Number.isInteger(idx)) return;

package/components/tags-input/tags-input.test.js

@@ -320,6 +320,115 @@ describe('tags-input-ui — disabled / readonly / form', () => {
   });
 });
 
+describe('tags-input-ui — chip slot template (TKT-0023)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('with no template, renders the default <tag-ui removable text>', async () => {
+    const el = mount('<tags-input-ui value=\'["a"]\'></tags-input-ui>');
+    await tick();
+    const chip = el.querySelector(':scope > [data-chip-list] > *');
+    expect(chip.tagName.toLowerCase()).toBe('tag-ui');
+    expect(chip.getAttribute('text')).toBe('a');
+    expect(chip.hasAttribute('removable')).toBe(true);
+  });
+
+  it('an author <template slot="chip"> overrides the default render, substituting {{value}}/{{index}}', async () => {
+    const el = mount(`
+      <tags-input-ui value='["alpha","beta"]'>
+        <template slot="chip"><tag-ui removable text="{{value}}" title="Item #{{index}}"></tag-ui></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const chips = el.querySelectorAll(':scope > [data-chip-list] > *');
+    expect(chips).toHaveLength(2);
+    expect(chips[0].getAttribute('text')).toBe('alpha');
+    expect(chips[0].getAttribute('title')).toBe('Item #0');
+    expect(chips[1].getAttribute('text')).toBe('beta');
+    expect(chips[1].getAttribute('title')).toBe('Item #1');
+  });
+
+  it('the chip template survives the first-connect shell stamp (not wiped by innerHTML replacement)', async () => {
+    const el = mount(`
+      <tags-input-ui value='["x"]'>
+        <template slot="chip"><span class="custom">{{value}}</span></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    expect(el.querySelector(':scope > template[slot="chip"]')).toBeTruthy();
+    const chip = el.querySelector(':scope > [data-chip-list] > .custom');
+    expect(chip?.textContent).toBe('x');
+  });
+
+  it('substitutes {{value}}/{{index}} in attribute values, not just text content', async () => {
+    const el = mount(`
+      <tags-input-ui value='["a","b"]'>
+        <template slot="chip"><span data-slot-value="{{value}}" data-slot-index="{{index}}">{{value}}</span></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const chips = el.querySelectorAll(':scope > [data-chip-list] > span');
+    expect(chips[0].dataset.slotValue).toBe('a');
+    expect(chips[0].dataset.slotIndex).toBe('0');
+    expect(chips[1].dataset.slotValue).toBe('b');
+    expect(chips[1].dataset.slotIndex).toBe('1');
+  });
+
+  it('reconciles by position: adding a token appends without recreating existing custom chips', async () => {
+    const el = mount(`
+      <tags-input-ui value='["a"]'>
+        <template slot="chip"><span>{{value}}</span></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const first = el.querySelector(':scope > [data-chip-list] > span');
+    el.addToken('b');
+    await tick();
+    const chips = el.querySelectorAll(':scope > [data-chip-list] > span');
+    expect(chips).toHaveLength(2);
+    expect(chips[0]).toBe(first); // unchanged position — same node, no flicker
+    expect(chips[1].textContent).toBe('b');
+  });
+
+  it('a custom chip participates in removal via a bubbling `remove` event from a nested tag-ui', async () => {
+    const el = mount(`
+      <tags-input-ui value='["a","b"]'>
+        <template slot="chip"><span class="wrap"><tag-ui removable text="{{value}}"></tag-ui></span></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const nestedTag = el.querySelector(':scope > [data-chip-list] .wrap tag-ui[text="a"]');
+    nestedTag.dispatchEvent(new CustomEvent('remove', { bubbles: true }));
+    await tick();
+    expect(el.value).toEqual(['b']);
+  });
+
+  it('a malformed template (no element content) degrades to the default chip rather than rendering nothing', async () => {
+    const el = mount(`
+      <tags-input-ui value='["a"]'>
+        <template slot="chip">   </template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const chip = el.querySelector(':scope > [data-chip-list] > *');
+    expect(chip.tagName.toLowerCase()).toBe('tag-ui');
+    expect(chip.getAttribute('text')).toBe('a');
+  });
+
+  it('a token literally equal to "{{index}}" is not clobbered by the index substitution pass', async () => {
+    const el = mount(`
+      <tags-input-ui value='["{{index}}","real"]'>
+        <template slot="chip"><span data-slot-index="{{index}}">{{value}}</span></template>
+      </tags-input-ui>
+    `);
+    await tick();
+    const chips = el.querySelectorAll(':scope > [data-chip-list] > span');
+    expect(chips[0].textContent).toBe('{{index}}');
+    expect(chips[0].dataset.slotIndex).toBe('0');
+    expect(chips[1].textContent).toBe('real');
+    expect(chips[1].dataset.slotIndex).toBe('1');
+  });
+});
+
 describe('tags-input-ui — change event', () => {
   beforeEach(() => { document.body.innerHTML = ''; });
 

package/components/tags-input/tags-input.yaml

@@ -186,11 +186,20 @@ events:
 slots:
   chip:
     description: |-
-      Planned: custom chip template, receiving `{value, index}` per
-      token — NOT YET IMPLEMENTED (TKT-0023; the template mechanism's
-      shape needs a design decision before it's built). Every token
-      currently renders as the fixed default,
-      `<tag-ui removable text="<value>">`, with no override path.
+      Custom per-token chip template (TKT-0023). Provide a single
+      `<template slot="chip">` child; it's cloned once per committed
+      token, with `{{value}}` / `{{index}}` substituted into every text
+      node and attribute value in the clone (e.g.
+      `<tag-ui removable text="{{value}}" title="Item #{{index}}">`).
+      The template's first element child is the reconcile unit — data-*
+      bookkeeping attrs land on it, so removal / re-render still track
+      by position the same way the default chip does. When absent, or
+      when the template has no element content (malformed), each token
+      renders as the default `<tag-ui removable text="<value>">`.
+      Readonly/disabled toggling of the built-in `removable` affordance
+      only applies to the default chip — a custom template always owns
+      its own removability, independent of the host's readonly/disabled
+      state.
 states:
   - name: idle
     description: No tokens; no typed text.
@@ -210,7 +219,10 @@ states:
     description: Non-interactive; dimmed.
     attribute: disabled
   - name: readonly
-    description: Read-only; chips render without remove affordance.
+    description: |-
+      Read-only; default chips render without remove affordance (a
+      custom `chip` template owns its own removability and is
+      unaffected).
     attribute: readonly
 traits: []
 tokens: