@adia-ai/web-modules 0.6.29 → 0.6.31

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # 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)
+
+- **Five new JS bundles** under `dist/`: `dist/everything.min.js` (kitchen-sink — primitives + a2ui-runtime + all 4 shells, 734 KB raw / ~250 KB gzipped — **the CodePen-target bundle**), plus four per-shell variants (`dist/shell/admin-shell.min.js`, `dist/chat/chat-shell.min.js`, `dist/editor/editor-shell.min.js`, `dist/simple/simple-shell.min.js`).
+- **Five new exports**: `./everything` → kitchen-sink path; `./shell/admin-shell/js-bundled`, `./chat/chat-shell/js-bundled`, `./editor/editor-shell/js-bundled`, `./simple/simple-shell/js-bundled` → per-shell paths. Existing cluster exports (`./shell`, `./chat`, etc.) unchanged.
+- Per-shell JS bundles assume `@adia-ai/web-components` JS is loaded first (small surface, ~6KB each except chat-shell which inlines chat-thread + composer ~230 KB). Kitchen-sink `everything.min.js` is self-contained.
+- **Pick ONE JS bundle path per page** — mixing causes `customElements.define` to throw "name already defined". The kitchen-sink path is the CodePen choice.
+
+### Documentation — README CDN section + AI-agent discoverability
+
+- **README.md** grows two new sections: "CDN (no bundler)" with the bundle URLs + size table + choice tree, and "Using with AI agents" pointing at the `adia-ui-kit` skill.
+- New site doc: [`/site/getting-started/cdn-usage`](https://ui-kit.exe.xyz/site/getting-started/cdn-usage) — full CodePen template + worked examples.
+- New `examples/codepen.html` — working CDN template in the repo (drop-in copy-paste for demos).
+
 ## [0.6.29] — 2026-05-23
 
 ### Added — `dist/<cluster>/<shell>.min.css` rolled-up CDN-ready bundles (4 shells)

package/README.md

@@ -11,6 +11,98 @@ consumers install only what they need.
 npm install @adia-ai/web-modules @adia-ai/web-components
 ```
 
+## CDN — no bundler (CodePen, marketing pages, static HTML)
+
+Since **v0.6.30**, both this package and `@adia-ai/web-components` ship pre-flattened + minified bundles under `dist/` that work via jsdelivr/unpkg with zero build tooling.
+
+**Kitchen-sink one-tag setup (CodePen / demos / drop-into-any-HTML):**
+
+```html
+<!-- CSS: all primitives + the shell tier you use -->
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6.30/dist/web-components.min.css">
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.6.30/dist/shell/admin-shell.min.css">
+
+<!-- JS: everything in one bundle (primitives + all 4 shells + a2ui-runtime; ~190 KB gzipped) -->
+<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 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>
+    <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):**
+
+```html
+<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.6.30/dist/web-components.min.js"></script>
+<script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.6.30/dist/shell/admin-shell.min.js"></script>
+```
+
+| Bundle | Path | Gzipped | Contents | When to use |
+|---|---|---|---|---|
+| **Everything** | `/dist/everything.min.js` | **~250 KB** | All primitives + a2ui-runtime + all 4 shells | **CodePen / one-tag demos** |
+| Admin shell | `/dist/shell/admin-shell.min.js` | ~6 KB | Shell registration; needs `web-components.min.js` first | Admin app, no chat/editor |
+| Chat shell | `/dist/chat/chat-shell.min.js` | ~230 KB | Includes chat-thread/composer | Chat surface |
+| Editor shell | `/dist/editor/editor-shell.min.js` | ~6 KB | Shell registration; needs primitives first | Editor surface |
+| Simple shell | `/dist/simple/simple-shell.min.js` | ~5.6 KB | Shell registration; needs primitives first | Settings / forms |
+
+**Pick ONE bundle path.** Mixing `everything.min.js` with a separate `web-components.min.js` causes `customElements.define` to throw "name already defined". For CodePen the kitchen-sink path is correct.
+
+**npm-installed consumers stay on the existing cluster exports** (`./shell`, `./chat`, etc.). The new `*/bundled` (CSS) and `*/js-bundled` + `./everything` (JS) exports are additive — only consumers without a bundler need them.
+
+See the [CDN usage guide](https://ui-kit.exe.xyz/site/cdn-usage) for a full CodePen template + worked examples.
+
+### Using with AI agents
+
+When composing UI with an AI coding agent (Claude Code / Cursor / Windsurf / Claude Desktop), load the **`adia-ui-kit` skill** in the harness — it encodes the 95-primitive catalog, composition patterns for all shells (admin / chat / editor / simple), and the Plan-Execute-Verify discipline that renders the composed surface in a real demo to verify intent. Skill lives at [`.agents/skills/adia-ui-kit/`](https://github.com/adiahealth/gen-ui-kit/tree/main/.agents/skills/adia-ui-kit) in the repo.
+
 `@adia-ai/web-components` is **always required** (modules compose primitives at runtime). Two additional peer dependencies are declared but **only needed for specific clusters**:
 
 | Peer dependency | Required when you use |
@@ -120,7 +212,7 @@ hunt for it:
 Future clusters on the strategic horizon: `data` (kanban, filters,
 table-toolbar), `agent` (agent-trace, reasoning panels).
 
-See [`bespoke-shell-children` skill](../../.agents/skills/bespoke-shell-children/SKILL.md) for the canonical decomposition recipe used by all three families.
+See [`adia-ui-authoring` skill, `references/shell-patterns.md`](../../.agents/skills/adia-ui-authoring/references/shell-patterns.md) (absorbed `bespoke-shell-children`) for the canonical decomposition recipe used by all three families.
 
 ## Quick start
 
@@ -244,7 +336,7 @@ All `<*-shell>` hosts are **behavior-only orchestrators** — they reflect state
 - **JS-bearing children** carry `connected()`/`disconnected()` lifecycle for interactive behavior (`admin-sidebar` resize, `admin-command` palette, `chat-thread` streaming scroll, `editor-canvas` zoom, etc.).
 - **CSS-only children** (no `.js` file — only `.yaml` + `.css` + `.a2ui.json`) declare slot intent for the host's styling system to attach against. Don't author a `.js` for these; the host handles their behavior via attribute selectors.
 
-The decomposition recipe (when to JS-bearing vs CSS-only, how to namespace state attributes, slot vocabulary conventions) is captured in the [`bespoke-shell-children` skill](../../.agents/skills/bespoke-shell-children/SKILL.md).
+The decomposition recipe (when to JS-bearing vs CSS-only, how to namespace state attributes, slot vocabulary conventions) is captured in the [`adia-ui-authoring` skill, `references/shell-patterns.md`](../../.agents/skills/adia-ui-authoring/references/shell-patterns.md) (absorbed `bespoke-shell-children`).
 
 ## License