@adia-ai/web-modules 0.6.16 → 0.6.18

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog — @adia-ai/web-modules
 
+## [0.6.18] — 2026-05-21
+
+### Added — `admin-sidebar` resize-handle diagnostic (FB-17)
+
+- **`<admin-sidebar resizable>` now warns when no `[data-resize]` child is
+  present.** `#setupResizeHandle()` previously returned silently when the
+  author-supplied drag-handle element was missing, leaving `resizable` a no-op
+  with zero diagnostic signal. It now emits a one-shot `console.warn`
+  (WeakSet-guarded) naming the fix. Warning-only; no functional change.
+  (~22 LOC `admin-sidebar.js`.)
+
+### Docs
+
+- **Live `<admin-sidebar>` variant gallery + collapse/expand demo** added to `admin-shell.html` and `admin-shell.examples.html` — covers the resizable / collapsible / variant axes in one browsable surface.
+
+### Note
+
+- The headline v0.6.18 work shipped in `@adia-ai/web-components` — `stat-ui` + `table-ui` `loading` props (FB-12 P2) and `text-ui` `size` / `color` / `weight` / `text-align` overlay attributes (FB-10). See `packages/web-components/CHANGELOG.md#0618--2026-05-21` for details.
+
+## [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.6.16",
+  "version": "0.6.18",
   "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.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-sidebar/admin-sidebar.js

@@ -54,6 +54,10 @@ class AdminSidebar extends UIElement {
 
   static template = () => null;
 
+  // FEEDBACK-17: elements already warned about a missing [data-resize]
+  // handle — one-shot per element so re-renders stay quiet. GC-friendly.
+  static #warnedNoHandle = new WeakSet();
+
   // The width the sidebar had before being collapsed — used for restore.
   // Map keyed by sidebar name allows multiple sidebars on one host.
   #previousExpandedWidth = '';
@@ -149,7 +153,23 @@ class AdminSidebar extends UIElement {
 
   #setupResizeHandle() {
     const handle = this.querySelector(':scope > [data-resize]');
-    if (!handle) return;
+    if (!handle) {
+      // FEEDBACK-17: `resizable` opts in to drag-resize but relies on an
+      // author-supplied `[data-resize]` child. A silent return left authors
+      // with a no-op `resizable` attribute and zero diagnostic signal.
+      if (!AdminSidebar.#warnedNoHandle.has(this)) {
+        AdminSidebar.#warnedNoHandle.add(this);
+        // eslint-disable-next-line no-console
+        console.warn(
+          '[admin-sidebar] `resizable` is set but no `[data-resize]` child ' +
+          'was found. Add `<div data-resize></div>` as a direct child to ' +
+          'enable drag-to-resize. (Unlike `collapsible`, `resizable` requires ' +
+          'this author-supplied handle.)',
+          this,
+        );
+      }
+      return;
+    }
 
     const slot = this.getAttribute('slot');
     const isLeading = slot === 'leading';