@adia-ai/web-components 0.7.25 → 0.7.27

package/CHANGELOG.md

@@ -1,4 +1,23 @@
 # Changelog — @adia-ai/web-components
+## [0.7.27] — 2026-07-12
+
+Fixes harvested from the /site → A2UI docs migration's live operator reports (TKT-0002…0006) — each was a real framework defect the migration surfaced, not a docs-only issue — plus the router race that three separate flake classes traced back to.
+
+### Added
+- **`richtext-ui` (`components/richtext/`) — `flush` boolean prop: paragraph-grade embedding mode.** Removes the article chrome (the `[data-richtext-body]` `space-8`/`space-6` padding, the 45rem reading measure, the component's own canvas background, and the trailing paragraph margin) so rendered markdown sits flush in a host column like a plain text block. Use it when richtext carries a single paragraph or fragment inside an already-measured layout (doc pages, cards); leave it off for standalone articles and chat transcripts, which keep the article treatment unchanged. Motivation: the docs transpiler rides richtext for every paragraph with inline code marks — 1,672 instances across 275 pages each carried article insets (TKT-0004 B).
+
+### Fixed
+- **`router-ui` (`core/provider.js`) — `#loadContent` claims a monotonic navigation token BEFORE any await.** A navigation that started earlier but fetched its content slowly could resume after a faster follow-up navigation had fully rendered, and — because nothing sequenced completion against navigation order — legitimately clobber the newer route's content while `data-route-path` still named the new route. Reproduced deterministically (2s-delayed boot fetch: old code showed `path=button` with the Dashboard DOM). The token is re-checked after every await (content fetch, templateResolver, setup import); a superseded call neither writes `innerHTML` nor emits `route-loaded`. This was the root mechanism behind the site-a2ui migration's "no-artifact despite a valid artifact" residue and its batch-sweep flakes.
+- **`nav-ui` (`components/nav/`) — collapsed-mode flyouts no longer re-open after selecting an item (TKT-0005).** The flyout popover is appended inside its `nav-group-ui`, so an option click bubbled to `nav-ui`'s delegated click handler, whose collapsed branch called `group.showPopover()` for any click landing inside the group — instantly re-opening the flyout the option's own handler had just closed. The collapsed branch now ignores clicks originating inside `[popover]`, mirroring the header guard the expanded branch always had.
+- **`core/markdown.js` — inline code spans survive emphasis/link regexes.** `inline()` now extracts backtick code spans into placeholders before applying the bold/italic/link transforms and restores them verbatim after — code spans containing `*`, `_`, `[`, or `]` no longer render mangled. New unit suite (`core/markdown.test.js`, 6 cases).
+
+### Maintenance
+- `dist/` CDN bundles regenerated (`web-components.min.css`, `web-components.min.js`, `theme-provider.min.js`) carrying the richtext `flush` rules + the router/nav/markdown fixes.
+
+## [0.7.26] — 2026-07-04
+
+### Fixed
+- **`empty-state-ui` (`components/empty-state/`) — the AI-composition rule no longer recommends `variant="outline"` for secondary/retry actions.** The `a2ui: rules:` guidance in `components/empty-state/empty-state.yaml` said "Prefer `[variant="primary"]` for create-flows; `[variant="outline"]` for retry / secondary actions" — reinforcing a repo-wide habit of reaching for `outline` just to mark a button as non-primary, when the unstyled default already IS the secondary look (`:where(:scope)` base tokens read `--a-ui-bg`, distinct from `variant="primary"`'s `--a-primary` accent fill). Corrected to: `variant="primary"` for the create-flow CTA, leave `variant` unset for retry/secondary. Regenerated `catalog-a2ui_0_9_rules.txt` from the yaml SoT (never hand-edited); mirrored the same correction into `components/empty-state/empty-state.examples.html`'s doc list. Root-cause investigation (corpus evidence: 446 `button-ui` tags harvested, only 30 bare vs. 91 explicit `outline` + 215 `ghost`) + the companion fixes in `@adia-ai/a2ui-compose` are in that package's changelog.
 
 ## [0.7.25] — 2026-07-03
 
@@ -406,7 +425,7 @@ Upstream consumer findings from `adia-pay` against installed `0.7.23` (F1–F6).
 
 ### Changed — `slot="caret"` disclosure-indicator convention + FEEDBACK-89 (ADR-0036)
 
-- **`components/tree/` (`tree-item-ui`) + `components/pane/` (`pane-ui`)** — renamed the expand/collapse indicator slot `slot="chevron"` → **`slot="caret"`** (and tokens `--*-chevron-*` → `--*-caret-*`, e.g. `--tree-caret-size`, `--pane-caret-fg`), standardizing on the slot name already used by `accordion-item-ui` / `nav-group-ui` / `select-ui` and matching the Phosphor `caret-*` icon vocabulary. **No backward-compat alias** (hard rename; the caret is auto-stamped, so blast radius is small). See [ADR-0036](../../.brain/adrs/0036-caret-slot-disclosure-convention.md).
+- **`components/tree/` (`tree-item-ui`) + `components/pane/` (`pane-ui`)** — renamed the expand/collapse indicator slot `slot="chevron"` → **`slot="caret"`** (and tokens `--*-chevron-*` → `--*-caret-*`, e.g. `--tree-caret-size`, `--pane-caret-fg`), standardizing on the slot name already used by `accordion-item-ui` / `nav-group-ui` / `select-ui` and matching the Phosphor `caret-*` icon vocabulary. **No backward-compat alias** (hard rename; the caret is auto-stamped, so blast radius is small). See `ADR-0036`.
 - **`tree-item-ui` adopt-or-stamp (FEEDBACK-89)** — `#stamp()` now adopts a consumer's declarative `slot="caret"` and `slot="actions"` children into the auto-stamped row instead of leaving them as siblings below it. A `<button-ui slot="actions">` (the natural way to add a per-row action — add / rename / overflow) now lands inline in the styled, hover-revealed actions area. The host `#onClick` already excludes `[slot="actions"] *` from row selection, so adoption is click-safe. +3 unit tests.
 - **`dist/` CDN bundles** (`web-components.min.css` + `web-components.min.js`) regenerated to carry the renamed `--*-caret-*` tokens + caret stamp logic.
 
@@ -3229,7 +3248,7 @@ Companion to the corpus simplification arc in `@adia-ai/a2ui-{runtime,compose,co
 
 Catalog (`packages/a2ui/corpus/catalog-a2ui_0_9.json`) regenerated to pick up every yaml addition. `verify:traits` clean at 56/56; `components --verify` clean at 125 files.
 
-See root [CHANGELOG.md `[Unreleased]`](../../CHANGELOG.md) for the cross-cutting arc narrative + [.claude/docs/journal/2026/05/2026-05-12.md](../../.claude/docs/journal/2026/05/2026-05-12.md) §§ 43 / 44 / 50 / 51 for per-§ details.
+See root [CHANGELOG.md `[Unreleased]`](../../CHANGELOG.md) for the cross-cutting arc narrative + `.claude/docs/journal/2026/05/2026-05-12.md` §§ 43 / 44 / 50 / 51 for per-§ details.
 ## [0.4.3] - 2026-05-11
 
 ### Added
@@ -3245,7 +3264,7 @@ See root [CHANGELOG.md `[Unreleased]`](../../CHANGELOG.md) for the cross-cutting
 
 ### Lockstep
 
-9-package coordinated PATCH cut to v0.4.3 (per [`.claude/docs/specs/package-architecture.md` § 15](../../.claude/docs/specs/package-architecture.md#15-versioning-policy)). Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4.0` covers `0.4.x` under semver). Ratifies [ADR-0027](../../.brain/adrs/0027-cross-primitive-composition-imports.md) — cross-primitive composition imports are the consumer's responsibility; the primitive's `.js` does NOT side-effect-import composed primitives. Source files touched: `components/input/input.{js,css,yaml,a2ui.json}`. See root [CHANGELOG.md `## [0.4.3]`](../../CHANGELOG.md) for the cut narrative.
+9-package coordinated PATCH cut to v0.4.3 (per [`.claude/docs/specs/package-architecture.md` § 15](../../.claude/docs/specs/package-architecture.md#15-versioning-policy)). Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4.0` covers `0.4.x` under semver). Ratifies `ADR-0027` — cross-primitive composition imports are the consumer's responsibility; the primitive's `.js` does NOT side-effect-import composed primitives. Source files touched: `components/input/input.{js,css,yaml,a2ui.json}`. See root [CHANGELOG.md `## [0.4.3]`](../../CHANGELOG.md) for the cut narrative.
 ## [0.4.2] - 2026-05-11
 
 ### Changed
@@ -3282,7 +3301,7 @@ See root [CHANGELOG.md `[Unreleased]`](../../CHANGELOG.md) for the cross-cutting
 
 ### Lockstep
 
-9-package coordinated PATCH cut to v0.4.2 (per [`.claude/docs/specs/package-architecture.md` § 15](../../.claude/docs/specs/package-architecture.md#15-versioning-policy)). Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4.0` covers `0.4.x` under semver). ADR-0025 ([`.brain/adrs/0025-no-native-form-controls.md`](../../.brain/adrs/0025-no-native-form-controls.md)) ratified — codifies the "no native or suppressed-native interactive widgets in primitives" principle that the `<input-ui type="number">` rewrite implements; `password` remains the documented exception (physically requires `<input type="password">` for `-webkit-text-security`). See root [CHANGELOG.md `## [0.4.2]`](../../CHANGELOG.md) for the cut narrative.
+9-package coordinated PATCH cut to v0.4.2 (per [`.claude/docs/specs/package-architecture.md` § 15](../../.claude/docs/specs/package-architecture.md#15-versioning-policy)). Internal `@adia-ai/*` dep ranges stay at `^0.4.0` (patch-cut asymmetry — `^0.4.0` covers `0.4.x` under semver). ADR-0025 (`.brain/adrs/0025-no-native-form-controls.md`) ratified — codifies the "no native or suppressed-native interactive widgets in primitives" principle that the `<input-ui type="number">` rewrite implements; `password` remains the documented exception (physically requires `<input type="password">` for `-webkit-text-security`). See root [CHANGELOG.md `## [0.4.2]`](../../CHANGELOG.md) for the cut narrative.
 ## [0.4.1] - 2026-05-10
 
 ### Ride-along (no source changes)
@@ -3733,7 +3752,7 @@ edge instead of leaving the column reading as dead width. Per-row
 
 ### Added — Trait test coverage at 100% + `<traits-host>` wrapper (2026-05-02)
 
-Follow-up landing on top of the v0.2.1 trait-system work — closes the two follow-up items from [ADR-0018](../../.brain/adrs/0018-trait-source-of-truth-and-declarative-attribute.md).
+Follow-up landing on top of the v0.2.1 trait-system work — closes the two follow-up items from `ADR-0018`.
 
 - **31 new per-trait behavior test files.** Every trait in `traits/` now has a sibling `.test.js`. Total trait-suite footprint: **44 files / 169 tests** (was 12 / 68). Coverage: **42/42 = 100%** (41 trait files + `traits-host`).
 - **`verify:traits` CI gate flipped from soft-warning to hard-fail.** `npm run verify:traits` exits non-zero if any trait file lacks a sibling `.test.js`, with the offending names listed in the failure message. Verified via mutation test: deleting `active-state.test.js` immediately fails the gate; restoring it returns to clean.
@@ -3753,7 +3772,7 @@ Follow-up landing on top of the v0.2.1 trait-system work — closes the two foll
 
 ### Added — Trait system source-of-truth + declarative `traits=` attribute (2026-05-02)
 
-Rolls up under [ADR-0018](../../.brain/adrs/0018-trait-source-of-truth-and-declarative-attribute.md). Consumer-visible additions and one core change to UIElement's lifecycle.
+Rolls up under `ADR-0018`. Consumer-visible additions and one core change to UIElement's lifecycle.
 
 - **`defineTrait()` schema extended.** Now requires `category` (one of nine canonical values, frozen in `define.js`) and `description` (≥ 11 chars). All 40 trait files updated to declare both inline. Build-time throw on missing fields.
 - **New `getTrait(name)` export from `traits/define.js`.** Returns the trait factory for a kebab-case name, or null if not yet imported. `getTraitSchema(name)` now reads from the same registry (was a separate map).

package/components/empty-state/empty-state.yaml

@@ -116,9 +116,11 @@ a2ui:
       magnifying-glass).
     - >-
       Put AT MOST ONE CTA in slot="action". It should be the single
-      next step (Create, Retry, Clear filters). Prefer
-      [variant="primary"] for create-flows; [variant="outline"] for
-      retry / secondary actions.
+      next step (Create, Retry, Clear filters). Use [variant="primary"]
+      for a create-flow CTA; leave [variant] unset for retry / secondary
+      actions — the default (no attribute) already IS the secondary
+      look, so don't add [variant="outline"] just to mark something as
+      non-primary.
     - >-
       Use [minimal] for inline empty rows inside <table-ui> /
       <list-ui> where full-canvas chrome is too prominent. The

package/components/nav/nav.class.js

@@ -121,6 +121,13 @@ export class UINav extends UIElement {
     if (group && this.contains(group)) {
       const isCollapsed = this.collapsed || this.getBoundingClientRect().width <= 96;
       if (isCollapsed) {
+        // The flyout popover is appended INSIDE the group, so an option
+        // click bubbles here after the option's own handler has selected
+        // and hidePopover()'d — re-showing would instantly reopen the
+        // flyout the user just dismissed (TKT-0005, 2026-07-12). The
+        // expanded branch below guards on the header; this is the
+        // collapsed-branch equivalent.
+        if (e.target.closest('[popover]')) return;
         group.showPopover?.();
       } else {
         const header = group.querySelector(':scope > [slot="header"]');

package/components/richtext/richtext.a2ui.json

@@ -16,6 +16,11 @@
     "component": {
       "const": "RichText"
     },
+    "flush": {
+      "description": "Paragraph-grade embedding mode — removes the article chrome (body padding and the 45rem reading measure, plus the trailing paragraph margin) so the rendered markdown sits flush in a host column like a plain text block. Use when richtext carries a single paragraph or fragment inside an already-measured layout (doc pages, cards); leave off for standalone articles and chat transcripts.",
+      "type": "boolean",
+      "default": false
+    },
     "markdown": {
       "description": "Component property: markdown.",
       "type": "string",

package/components/richtext/richtext.css

@@ -98,6 +98,26 @@
     padding: var(--richtext-py) var(--richtext-px);
   }
 
+  /* [flush] — paragraph-grade embedding (yaml `flush` prop): drop the
+     article chrome (padding, 45rem measure, own canvas background) so the
+     markdown sits in a host column like a plain text block. The trailing
+     child keeps no bottom margin — rhythm belongs to the host layout's
+     gap, matching text-ui paragraphs in the doc column (TKT-0004: every
+     code-bearing doc paragraph rides richtext). */
+  :scope[flush] {
+    background: transparent;
+    overflow-y: visible;
+  }
+
+  :scope[flush] [data-richtext-body] {
+    max-width: none;
+    padding: 0;
+  }
+
+  :scope[flush] [data-richtext-body] > :last-child {
+    margin-bottom: 0;
+  }
+
   /* ── Headings ── */
 
   [data-richtext-body] h1 {

package/components/richtext/richtext.d.ts

@@ -21,6 +21,8 @@ editable>.
 import { UIElement } from '../../core/element.js';
 
 export class UIRichText extends UIElement {
+  /** Paragraph-grade embedding mode — removes the article chrome (body padding and the 45rem reading measure, plus the trailing paragraph margin) so the rendered markdown sits flush in a host column like a plain text block. Use when richtext carries a single paragraph or fragment inside an already-measured layout (doc pages, cards); leave off for standalone articles and chat transcripts. */
+  flush: boolean;
   /** Component property: markdown. */
   markdown: string;
   /** Source URL (image, iframe, etc.). */

package/components/richtext/richtext.yaml

@@ -23,6 +23,16 @@ props:
     description: Source URL (image, iframe, etc.).
     type: string
     default: ''
+  flush:
+    description: >-
+      Paragraph-grade embedding mode — removes the article chrome (body
+      padding and the 45rem reading measure, plus the trailing paragraph
+      margin) so the rendered markdown sits flush in a host column like a
+      plain text block. Use when richtext carries a single paragraph or
+      fragment inside an already-measured layout (doc pages, cards); leave
+      off for standalone articles and chat transcripts.
+    type: boolean
+    default: false
 events: {}
 slots:
   default:

package/core/markdown.js

@@ -86,16 +86,41 @@ export function renderMarkdown(src) {
   return out.join('\n');
 }
 
+// Placeholder marker for protected code-span content — \0 can't occur in
+// authored markdown, so it round-trips unambiguously through the regex pass.
+const CODE_PH = (n) => `\0CODE${n}\0`;
+const CODE_PH_RE = /\0CODE(\d+)\0/g;
+
 function inline(text) {
-  return esc(text)
+  const escaped = esc(text);
+
+  // 1. Extract inline-code spans FIRST and protect their (already-escaped,
+  //    HTML-safe) raw content behind a placeholder — otherwise a code span
+  //    containing `*`/`_` (e.g. `--a-chrome-*`, `foo_bar`) gets its content
+  //    mangled by the emphasis regexes below before the code regex ever
+  //    sees it (root cause of the inline-flow gap — see
+  //    site-a2ui/FINDINGS.md "No inline-flow construct").
+  const codeSpans = [];
+  let out = escaped.replace(/`([^`]+)`/g, (_, code) => {
+    const i = codeSpans.length;
+    codeSpans.push(code);
+    return CODE_PH(i);
+  });
+
+  // 2. Now it's safe to apply emphasis + links to the remaining (non-code)
+  //    text — code-span content is inert placeholder text at this point.
+  out = out
     // Bold **text** or __text__
     .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
     .replace(/__(.+?)__/g, '<strong>$1</strong>')
     // Italic *text* or _text_
     .replace(/\*(.+?)\*/g, '<em>$1</em>')
     .replace(/_(.+?)_/g, '<em>$1</em>')
-    // Inline code `code`
-    .replace(/`([^`]+)`/g, '<code>$1</code>')
     // Links [text](url)
     .replace(/\[([^\]]+)\]\(([^)]+)\)/g, '<a href="$2">$1</a>');
+
+  // 3. Restore the protected code spans verbatim.
+  out = out.replace(CODE_PH_RE, (_, i) => `<code>${codeSpans[Number(i)]}</code>`);
+
+  return out;
 }

package/core/markdown.test.js

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import { renderMarkdown } from './markdown.js';
+
+// ── inline() protect-verbatim-regions regression (site-a2ui/FINDINGS.md
+//    "No inline-flow construct" — root cause: emphasis regexes ran BEFORE
+//    code-span extraction, so any code span containing `*`/`_` mangled) ──
+
+describe('renderMarkdown — inline code spans survive markdown-unsafe content', () => {
+  it('code span containing an asterisk is not treated as emphasis', () => {
+    const html = renderMarkdown('Use `--a-chrome-*` for chrome tokens.');
+    expect(html).toContain('<code>--a-chrome-*</code>');
+    expect(html).not.toContain('<em>');
+    expect(html).not.toContain('<strong>');
+  });
+
+  it('code span containing underscores is not treated as emphasis', () => {
+    const html = renderMarkdown('Call `foo_bar_baz()` to run it.');
+    expect(html).toContain('<code>foo_bar_baz()</code>');
+    expect(html).not.toContain('<em>');
+  });
+
+  it('code span containing double-asterisks is not treated as bold', () => {
+    const html = renderMarkdown('The pattern `**not-bold**` is literal.');
+    expect(html).toContain('<code>**not-bold**</code>');
+    expect(html).not.toContain('<strong>');
+  });
+
+  it('bold, italic, code, and link combine correctly within one run', () => {
+    const html = renderMarkdown('This is **bold**, this is *italic*, this is `code_with_*` and this is [a link](https://example.com).');
+    expect(html).toContain('<strong>bold</strong>');
+    expect(html).toContain('<em>italic</em>');
+    expect(html).toContain('<code>code_with_*</code>');
+    expect(html).toContain('<a href="https://example.com">a link</a>');
+  });
+
+  it('adjacent code spans do not bleed into each other', () => {
+    const html = renderMarkdown('First `a_b` then `c*d` then plain _italic_ text.');
+    expect(html).toContain('<code>a_b</code>');
+    expect(html).toContain('<code>c*d</code>');
+    expect(html).toContain('<em>italic</em>');
+  });
+
+  it('HTML-unsafe characters inside a code span are still escaped', () => {
+    const html = renderMarkdown('Use `<script>` tags carefully.');
+    expect(html).toContain('<code>&lt;script&gt;</code>');
+  });
+});

package/core/provider.js

@@ -165,6 +165,19 @@ export class UIRouter extends UIProvider {
   #cache = new Map();
   #ownCtrl = null;
   #lastPath = null;
+  // Monotonic navigation token — claimed at #loadContent ENTRY, before any
+  // await, so completion order can never impersonate navigation order. A
+  // call that awaits (content fetch, templateResolver) and finds a newer
+  // token on resume is superseded: it must neither write innerHTML nor
+  // emit route-loaded. Incident (2026-07-12, prod deploy verify run
+  // 29199534931): the boot route's SLOW content fetch resumed AFTER a
+  // fast follow-up navigation had fully rendered — downstream guards that
+  // sequence at templateResolver entry saw the late resumer as "newest"
+  // and let it clobber the newer route's content (data-route-path said
+  // the new route; the DOM showed the old one). Same class as the
+  // "no-artifact despite a valid artifact" and batch-sweep flakes in
+  // site-a2ui/FINDINGS.md — the cancellation belongs HERE, at the source.
+  #navSeq = 0;
 
   get #ctrl() { return this.#ownCtrl || this.controller; }
 
@@ -214,6 +227,7 @@ export class UIRouter extends UIProvider {
   }
 
   async #loadContent(route, ctrl) {
+    const nav = ++this.#navSeq; // claim BEFORE any await — see #navSeq
     let html;
     if (this.#cache.has(route.content)) {
       html = this.#cache.get(route.content);
@@ -228,10 +242,12 @@ export class UIRouter extends UIProvider {
         return;
       }
     }
+    if (nav !== this.#navSeq) return; // superseded while fetching content
 
     // Template resolver hook — lets the site wrap content in a template before injection
     if (this.templateResolver) {
       html = await this.templateResolver(html, route);
+      if (nav !== this.#navSeq) return; // superseded while resolving
     }
 
     this.innerHTML = html;
@@ -267,6 +283,7 @@ export class UIRouter extends UIProvider {
         if (mod.default) mod.default(this);
       } catch { /* setup module is optional */ }
     }
+    if (nav !== this.#navSeq) return; // superseded during setup import — no phantom route-loaded
 
     const state = ctrl.getState();
     this.emit('route-loaded', {