@adia-ai/web-modules 0.6.15 → 0.6.17

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog — @adia-ai/web-modules
 
+## [0.6.17] — 2026-05-21
+
+### Fixed
+- **Collapsed sidebar — text labels overflow for vanilla HTML consumers.** When `<admin-sidebar>` collapses to its ≤96px icon-rail state, the existing `@container sidebar (max-width: 96px)` rules in `admin-shell.collapsed.css` target only the AdiaUI primitives (`<nav-ui>`, `<nav-item-ui>`, `<select-ui>`, `<button-ui>`). Consumers that use vanilla HTML inside the sidebar — `<button class="nav-item">Label</button>` with native text nodes, or `<span slot="heading">Brand</span>` for the app wordmark — were not covered, and their text content overflowed the 48px rail via `overflow: visible`. Symptom: "Claims UI" wordmark wrapped to two lines, and nav labels (Dashboard/Claims/Users/Settings) rendered visibly past the rail edge into the content area. Reported by claims-ui-v3 cold-start v0.6.16 screenshot.
+
+  Fix adds a forgiving fallback block to `admin-shell.collapsed.css`:
+  - Clips overflow on the sidebar itself + chrome containers (`admin-topbar`, `admin-statusbar`, `section`, `section-ui`, `nav`) so escaping text descendants stay inside the rail edge.
+  - Hides `[slot="heading"]` children — authors who want a brand mark visible when collapsed should put an `<icon-ui>` or logo image in `[slot="leading"]` instead.
+  - For vanilla `<button class="nav-item">`, `<a class="nav-item">`, and `[data-nav]` — applies `justify-content: center`, `overflow: hidden`, `text-indent: -9999px`, `white-space: nowrap` to clip text labels while preserving icons. Restores `text-indent: 0` on child `<icon-ui>` so the icon itself stays visible.
+
+  Using `<nav-item-ui>` / `<nav-ui>` remains the canonical, more capable path — popover tooltips on hover, badge slots, separator drawing all work via the primitives. The fallback is a safety net for consumers who don't (yet) wire the AdiaUI primitive stack inside the sidebar. Files: `packages/web-modules/shell/admin-shell/css/admin-shell.collapsed.css` (+60 LOC).
+
+### Verification
+- `components.mjs --verify` clean (142 files up-to-date).
+- `verify:traits` 56/56 clean.
+- `check:lockstep` — all 9 at 0.6.17, ranges at ^0.6.0.
+- `eval:diff --engine zettel` cov=49% / avg=90 (baseline-identical).
+- Browser-verified at `http://localhost:5175/` (claims-ui-v3, after copying the updated CSS to local `node_modules`): toggling the sidebar to collapsed state hides `[slot="heading"]` (display=none), applies `text-indent: -9999px` + `overflow: hidden` to vanilla nav buttons, and preserves icon visibility via `text-indent: 0` on `<icon-ui>` descendants. Vision pass confirms no overflow, no "Claims UI" wrapping, icons stacked vertically in the rail.
+
+## [0.6.16] — 2026-05-21
+
+### Fixed
+- **`<admin-page>` layout breaks at narrow viewports when wrapped in `<router-ui>` (sticky-overlap regression).** The bespoke selectors `admin-scroll > admin-page, admin-content > admin-page` use the direct-child combinator. When a router (e.g. `<router-ui>` in chat-ui's docs-site, or any consumer's SPA router) sits between `<admin-scroll>` and `<admin-page>` to stamp routed content, the selector misses, `<admin-page>` falls back to `HTMLUnknownElement` (`display: inline`), and its sticky/flex children silently fail layout. At wide viewports the inline flow happens to land roughly where flex would have placed it; at narrower widths (~700–900px), `<admin-page-header>` (sticky inside inline parent) overlaps `<admin-page-body>` content — the user's screenshot showed h1 "Dashboard" + tabs rendering ON TOP OF the KPI cards (Total Revenue, Subscriptions). Fix: relax the selector to use the descendant combinator (`:is(admin-scroll, admin-content) admin-page`) so any depth of intermediate wrapping (`router-ui`, `slot`, generic divs) still picks up the canonical `display: flex; flex-direction: column; min-height: 100%` layout. `<admin-page>` is never legitimately nested inside another `<admin-page>`, so depth-1 restriction isn't needed. Files: `packages/web-modules/shell/admin-shell/css/admin-shell.bespoke.css` (selector relaxation + inline doc comment explaining the trap).
+
+### Changed
+- **`--page-content-header-bg` token: `--a-canvas-2` → `--a-canvas-1`.** The page-header band now matches the shell + sidebar canvas (`oklch(0.19 0.01 225)` in dark mode) so the admin chrome reads as a continuous wrapper around the page-body's content surface (canvas-0). Previous v0.6.14 value (canvas-2, ΔL=0.08) was chosen under the "elevated step over content" intent, but vision-tests against dense layouts at 1572px viewport in dark mode showed the band still read as flush with body — the ΔL=0.08 step is below human-perceptible threshold for a band of this proportion against this surrounding content density. Reframing as **shell-chrome continuation** rather than as elevated step: the page-header reads as the horizontal arm of the shell's L-shape wrapping the rounded content area. Consumers who want a stronger raised band can override the token at `:root`. Files: `packages/web-modules/shell/admin-shell/css/admin-shell.tokens.css` (token value + history comment).
+
+### Verification
+- `components.mjs --verify` clean (142 files up-to-date).
+- `verify:traits` 56/56 clean.
+- `check:lockstep` — all 9 at 0.6.16, ranges at ^0.6.0.
+- `eval:diff --engine zettel` cov=49% / avg=90 (baseline-identical).
+- Browser-verified at `/site/examples/admin-dashboard` in dark mode at 1280px viewport: `admin-page` computed `display: flex` (was `inline` pre-fix), `flex-direction: column`; `admin-page-header` computed `display: block` (was `inline` pre-fix), `position: sticky`, bg `oklch(0.19 0.01 225)` matches sidebar canvas. Vision pass confirms no overlap between page-header and KPI cards across the layout.
+
 ## [0.6.15] — 2026-05-21
 
 ### Maintenance

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.6.15",
+  "version": "0.6.17",
   "description": "AdiaUI composite custom elements \u2014 shell, chat, editor, runtime clusters built from @adia-ai/web-components primitives. Subpath exports per cluster.",
   "type": "module",
   "exports": {

package/shell/admin-shell/admin-shell.test.js

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const bespokeCSS = readFileSync(resolve(__dirname, 'css/admin-shell.bespoke.css'), 'utf8');
+const collapsedCSS = readFileSync(resolve(__dirname, 'css/admin-shell.collapsed.css'), 'utf8');
+
+// ── Helpers ────────────────────────────────────────────────────────
+function mount(html) {
+  document.body.innerHTML = html;
+  return document.body.firstElementChild;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+// ── Regression guards ─────────────────────────────────────────────
+//
+// These tests document substrate selector decisions that have been
+// regressed and re-fixed at least once each. They run against the raw
+// CSS file content + DOM `element.matches()` rather than computed style,
+// because happy-dom doesn't fully resolve external stylesheet cascade.
+// The trade-off: we don't assert that the rule WAS applied, but we DO
+// assert that the rule's selector REACHES the element it's meant to
+// style — which is the part that broke in v0.6.16.
+
+describe('admin-shell.bespoke.css — selector reachability', () => {
+  it('v0.6.16 fix: admin-page rule uses descendant combinator (not >)', () => {
+    // The previous selector `admin-scroll > admin-page` broke when a
+    // router (e.g. <router-ui>) sat between <admin-scroll> and
+    // <admin-page>. The fix uses :is() + descendant combinator so any
+    // depth of intermediate wrapping still matches.
+    expect(bespokeCSS).toMatch(/:is\(admin-scroll,\s*admin-content\)\s+admin-page\s*\{/);
+    // Negative assertion: the broken direct-child form should not be
+    // present any more (catches accidental reverts).
+    expect(bespokeCSS).not.toMatch(/^admin-scroll\s*>\s*admin-page\s*,/m);
+    expect(bespokeCSS).not.toMatch(/^admin-content\s*>\s*admin-page\s*\{/m);
+  });
+
+  it('admin-page rule reaches admin-page inside <router-ui>', () => {
+    // Synthesize the docs-site DOM shape that hit the v0.6.16 bug.
+    // The selector under test must match <admin-page> via descendant
+    // combinator even when <router-ui> sits between.
+    mount(`
+      <admin-shell>
+        <admin-content>
+          <admin-scroll>
+            <router-ui id="router">
+              <admin-page id="page"></admin-page>
+            </router-ui>
+          </admin-scroll>
+        </admin-content>
+      </admin-shell>
+    `);
+    const page = document.getElementById('page');
+    expect(page).toBeTruthy();
+    // Direct-child match should fail (router-ui sits between)
+    expect(page.matches('admin-scroll > admin-page')).toBe(false);
+    expect(page.matches('admin-content > admin-page')).toBe(false);
+    // Descendant match must succeed (this is what v0.6.17 introduced)
+    expect(page.matches(':is(admin-scroll, admin-content) admin-page')).toBe(true);
+  });
+
+  it('admin-page rule still reaches admin-page as direct child', () => {
+    // Canonical playground/example layout — no router wrapper.
+    // The descendant combinator must still match this case.
+    mount(`
+      <admin-shell>
+        <admin-content>
+          <admin-scroll>
+            <admin-page id="page"></admin-page>
+          </admin-scroll>
+        </admin-content>
+      </admin-shell>
+    `);
+    const page = document.getElementById('page');
+    expect(page.matches(':is(admin-scroll, admin-content) admin-page')).toBe(true);
+  });
+});
+
+describe('admin-shell.collapsed.css — vanilla HTML fallback (v0.6.17)', () => {
+  it('contains the vanilla-HTML fallback block', () => {
+    // v0.6.17 added rules covering <button class="nav-item"> etc. so
+    // text labels don't overflow the 48px rail when the consumer doesn't
+    // use AdiaUI <nav-item-ui> primitives.
+    expect(collapsedCSS).toMatch(/Vanilla-HTML fallback/);
+    expect(collapsedCSS).toMatch(/\[slot="heading"\]\s*\{[\s\S]*?display:\s*none/);
+    expect(collapsedCSS).toMatch(/button\.nav-item/);
+    expect(collapsedCSS).toMatch(/text-indent:\s*-9999px/);
+  });
+
+  it('preserves icon visibility inside vanilla nav buttons', () => {
+    // text-indent:-9999px on the parent must be undone on the icon
+    // child, otherwise the icon disappears with the text. Both rules
+    // must be present in the file.
+    expect(collapsedCSS).toMatch(/button\.nav-item\s*>\s*icon-ui[\s\S]*?text-indent:\s*0/);
+  });
+
+  it('fallback rules sit inside the @container sidebar query', () => {
+    // The vanilla-HTML fallback must be scoped to the collapsed state
+    // (max-width: 96px container query). Outside that scope, the
+    // text-indent: -9999px clip would also break the expanded state.
+    const containerMatch = collapsedCSS.match(/@container\s+sidebar\s*\(max-width:\s*96px\)\s*\{([\s\S]+)\}/);
+    expect(containerMatch).toBeTruthy();
+    const inside = containerMatch[1];
+    expect(inside).toMatch(/Vanilla-HTML fallback/);
+    expect(inside).toMatch(/text-indent:\s*-9999px/);
+  });
+});

package/shell/admin-shell/css/admin-shell.bespoke.css

@@ -72,9 +72,17 @@ admin-shell[mode~="rounded"] > admin-content > admin-scroll {
   border-radius: var(--page-content-radius);
 }
 
-/* ── admin-page ≡ <article data-content-root> ── */
-admin-scroll > admin-page,
-admin-content > admin-page {
+/* ── admin-page ≡ <article data-content-root> ── 
+   Selector covers the canonical direct-child cases AND any indirect descent
+   (e.g. when <router-ui> sits between <admin-scroll> and <admin-page> to
+   stamp routed content; the docs-site at /site/* + every consumer using a
+   router pattern hits this layout). The previous `>` combinator silently
+   broke at narrow viewports because the unmatched <admin-page> rendered as
+   HTMLUnknownElement (display:inline) and its sticky/flex children
+   collapsed on top of each other. The descendant combinator is safe here:
+   <admin-page> is never legitimately nested inside another <admin-page>,
+   so we don't need depth-1 restriction. */
+:is(admin-scroll, admin-content) admin-page {
   display: flex;
   flex-direction: column;
   min-height: 100%;

package/shell/admin-shell/css/admin-shell.collapsed.css

@@ -83,4 +83,64 @@
   button-ui [slot="trailing"] {
     display: none;
   }
+
+  /* ─── Vanilla-HTML fallback ───
+     The primitive-targeted rules above (nav-ui, nav-item-ui, button-ui) cover
+     the canonical AdiaUI composition. Consumers using vanilla HTML inside the
+     sidebar (e.g. <button class="nav-item">Label</button> with native text
+     nodes, or <span slot="heading">Brand</span>) need a forgiving fallback —
+     without it, text labels overflow the 48px collapsed bbox via
+     `overflow: visible` and spill into the content area, producing the
+     "Claims UI wraps to two lines + nav labels visible past the rail" bug
+     reported by claims-ui-v3 cold-start v0.6.16 §sidebar-overflow.
+
+     Strategy: clip the sidebar itself + hide common text-bearing slot
+     children. Icons (<icon-ui>) and avatars (<img>, <avatar-ui>) stay
+     visible. This is a safety net — using <nav-item-ui> / <nav-ui> remains
+     the canonical, more capable path (popover tooltips, badges, etc.). */
+
+  /* Clip the sidebar's chrome containers — text descendants that escape
+     their parent's width are now invisible past the rail edge. */
+  :scope,
+  :is(admin-topbar, admin-statusbar),
+  :is(section, section-ui, nav) {
+    overflow: hidden;
+  }
+
+  /* Hide [slot="heading"] (typically the app brand label in the sidebar's
+     <admin-topbar slot="header">) — keeps the rail clean in collapsed mode.
+     Authors who want a brand mark visible when collapsed should put an
+     <icon-ui> or logo image in [slot="leading"] instead. */
+  [slot="heading"] {
+    display: none;
+  }
+
+  /* Vanilla nav buttons: any <button class="nav-item"> or [data-nav] item
+     not built from nav-item-ui. Hide non-icon children so only the icon
+     remains visible. Detection: a child of the sidebar that is NOT
+     itself an icon/avatar primitive and is NOT an element wrapping such
+     a primitive — i.e., bare text/spans/labels. */
+  button.nav-item,
+  a.nav-item,
+  [data-nav] {
+    /* Center the icon; hide any text by clipping (we can't safely
+       :not(:has(icon-ui)) every child without false-positives, so we
+       clip the box and rely on flex centering the icon). */
+    justify-content: center;
+    overflow: hidden;
+    text-indent: -9999px;  /* push label text off-screen */
+    white-space: nowrap;
+  }
+
+  /* But: keep the icon inside the button visible. text-indent: -9999px
+     would push the icon too — so restore positioning for the icon child
+     and any element that wraps it. */
+  button.nav-item > icon-ui,
+  a.nav-item > icon-ui,
+  [data-nav] > icon-ui,
+  button.nav-item > :has(> icon-ui),
+  a.nav-item > :has(> icon-ui),
+  [data-nav] > :has(> icon-ui) {
+    text-indent: 0;
+  }
 }

package/shell/admin-shell/css/admin-shell.tokens.css

@@ -38,7 +38,7 @@
 
   /* Content area — scroll region inside main */
   --page-content-bg:        var(--a-canvas-0);       /* content surface (lighter than chrome) */
-  --page-content-header-bg: var(--a-canvas-2);       /* sticky page-header band — stronger raised step (ΔL ≈ 0.08 from content) so the band reads clearly on both light and dark themes. Pre-v0.6.14 (--a-canvas-1, ΔL ≈ 0.04) was too subtle in dark mode. */
+  --page-content-header-bg: var(--a-canvas-1);       /* sticky page-header band — matches sidebar/topbar canvas so the shell reads as a continuous L-shape of chrome wrapping the page-body. ΔL=0.04 above body canvas-0. History: v0.6.14 used canvas-2 (ΔL=0.08) under the "elevated step over content" intent, but vision-tests against dense layouts showed the band still read as flush with body. v0.6.15 reframes the page-header as shell-chrome continuation (canvas-1 matches sidebar) rather than as an elevated step — visual cohesion over contrast. Consumers who want a stronger raised band can override this token at :root. */
   --page-content-radius:    var(--a-radius-lg);      /* used by "rounded" mode */
   --page-content-inset:     var(--a-space-10);       /* padding for header/body/footer */
   --page-content-max-width: 1540px;                   /* max-width for content children */