@adia-ai/web-modules 0.6.30 → 0.6.31

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog — @adia-ai/web-modules
 
+## [0.6.31] — 2026-05-23
+
+### Fixed — `admin-shell.examples` taming CSS inlined (docs site render fix)
+
+- **`shell/admin-shell/admin-shell.examples.html`** — the docs router at `/site/components/admin-shell` loads this `.examples.html` directly (via `template: "doc"` in `site/sitemap.json`); it does NOT load the wrapper `admin-shell.html` with its inline `<style>` block. Net effect: the `.sidebar-gallery`, `.shell-states`, `.ad-switcher`, `.ad-menu`, `.ad-brand-logo` classes were never styled on the docs site, so the demo `<admin-shell>` instances rendered with their default `position:fixed` full-viewport layout — overlapping the docs page chrome. Fix: inline the taming CSS (~110 lines from `admin-shell.html` lines 42-151) into `admin-shell.examples.html` at the top. Matches the precedent set by `editor-shell.examples.html` + `responsive-shell-sidebar.examples.html` which both inline demo-specific CSS. Not tarball-affecting (`!shell/**/*.examples.html` exclusion in `files:`) — docs-surface only, but `ui-kit.exe.xyz/site/components/admin-shell` reflects the fix.
+
+### Documentation — README CDN example uses canonical hierarchy
+
+- **`README.md`** — the CDN "Kitchen-sink one-tag setup" example replaced the broken stub `<admin-sidebar><!-- nav --></admin-sidebar>` with the full canonical hierarchy: `<admin-sidebar slot="leading" resizable collapsible>` containing `<admin-topbar slot="header"><span slot="heading">My App</span></admin-topbar>` + `<section-ui><nav-ui><nav-item-ui icon="…" text="…"/></nav-ui></section-ui>` + `<div data-resize></div>`; `<admin-content>` containing `<admin-topbar>` (breadcrumb) + `<admin-scroll><admin-page><admin-page-header><header><div><h1>+<div data-actions></div></div><p></header></admin-page-header><admin-page-body><button-ui/></admin-page-body></admin-page></admin-scroll></admin-content>`. Trailing HTML comment block teaches the canonical rules inline: `<nav-ui>+<nav-item-ui>` for sidebar nav (NOT `<menu-ui>`), `<admin-topbar slot="header">` inside `<admin-sidebar>`, `<admin-statusbar slot="footer">` inside `<admin-sidebar>`, `<admin-scroll>` wraps `<admin-page>` inside `<admin-content>`, `<admin-page-header>` wraps an inner `<header>` with `<div><h1>+<div data-actions></div></div><p>` (add `data-flush` on `<header>` to drop bottom border). README ships in npm tarball — consumers reading via npmjs.com see the canonical pattern.
+
 ## [0.6.30] — 2026-05-23
 
 ### Added — JS bundles + `./everything` kitchen-sink export (CDN / CodePen)

package/README.md

@@ -26,11 +26,56 @@ Since **v0.6.30**, both this package and `@adia-ai/web-components` ship pre-flat
 <script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.6.30/dist/everything.min.js"></script>
 
 <admin-shell mode="rounded borderless">
-  <admin-sidebar><!-- nav --></admin-sidebar>
+  <admin-sidebar slot="leading" resizable collapsible>
+    <admin-topbar slot="header">
+      <span slot="heading">My App</span>
+    </admin-topbar>
+    <section-ui>
+      <nav-ui>
+        <nav-item-ui icon="house" text="Home" selected></nav-item-ui>
+        <nav-item-ui icon="gear" text="Settings"></nav-item-ui>
+      </nav-ui>
+    </section-ui>
+    <div data-resize></div>
+  </admin-sidebar>
   <admin-content>
-    <button-ui variant="primary" text="Click me"></button-ui>
+    <admin-topbar>
+      <breadcrumb-ui><span>Dashboard</span></breadcrumb-ui>
+    </admin-topbar>
+    <admin-scroll>
+      <admin-page>
+        <admin-page-header>
+          <header>
+            <div>
+              <h1>Dashboard</h1>
+              <div data-actions>
+                <button-ui text="Share" variant="outline" size="sm"></button-ui>
+              </div>
+            </div>
+            <p>Welcome back.</p>
+          </header>
+        </admin-page-header>
+        <admin-page-body>
+          <button-ui variant="primary" text="Click me"></button-ui>
+        </admin-page-body>
+      </admin-page>
+    </admin-scroll>
   </admin-content>
 </admin-shell>
+
+<!--
+  Canonical admin-shell hierarchy (matches ui-kit.exe.xyz/site/index.html):
+  - <nav-ui> + <nav-item-ui> is THE primitive pair for sidebar navigation.
+  - <menu-ui> / <menu-item-ui> are for popover action menus (dropdowns), NOT for nav.
+  - <admin-topbar slot="header"> goes inside <admin-sidebar> (workspace switcher / brand).
+  - <admin-statusbar slot="footer"> goes inside <admin-sidebar> (user switcher / sign-in).
+  - <admin-scroll> wraps <admin-page> inside <admin-content>.
+  - <admin-page-header> wraps an inner <header> with <div><h1>+<div data-actions></div></div><p>.
+    The <div data-actions> slot is right-aligned for page-level action buttons.
+    Use <header data-flush> to drop the bottom border.
+  Reference: https://ui-kit.exe.xyz/site/examples/admin-dashboard +
+             https://github.com/adiahealth/gen-ui-kit/blob/main/site/templates/settings.html
+-->
 ```
 
 **Per-shell setup (advanced — only one shell tier loaded):**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.6.30",
+  "version": "0.6.31",
   "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": {