@adia-ai/web-modules 0.4.4 → 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/README.md +99 -56
  3. package/package.json +7 -1
package/CHANGELOG.md CHANGED
@@ -11,6 +11,40 @@ Built from `@adia-ai/web-components` primitives.
11
11
 
12
12
  _No pending changes._
13
13
 
14
+ ## [0.4.5] - 2026-05-12
15
+
16
+ ### Added — CSS importable via package specifier (§61)
17
+
18
+ Six new `*.css` subpath exports in `package.json` resolve the consumer-side friction with the previous `../node_modules/@adia-ai/web-modules/<cluster>/<elem>/<elem>.css` workaround (fragile under pnpm, Yarn PnP, hoisting).
19
+
20
+ **New form:**
21
+
22
+ ```js
23
+ import '@adia-ai/web-modules/editor/editor-shell.css';
24
+ import '@adia-ai/web-modules/shell/admin-shell.css';
25
+ import '@adia-ai/web-modules/chat/chat-shell.css';
26
+ import '@adia-ai/web-modules/simple/simple-shell.css';
27
+ import '@adia-ai/web-modules/runtime/gen-root.css';
28
+ import '@adia-ai/web-modules/theme/theme-panel.css';
29
+ ```
30
+
31
+ **Implementation** — added to `package.json` `exports`:
32
+
33
+ ```json
34
+ "./shell/*.css": "./shell/*/*.css",
35
+ "./chat/*.css": "./chat/*/*.css",
36
+ "./editor/*.css": "./editor/*/*.css",
37
+ "./simple/*.css": "./simple/*/*.css",
38
+ "./runtime/*.css": "./runtime/*/*.css",
39
+ "./theme/*.css": "./theme/*/*.css"
40
+ ```
41
+
42
+ The pattern key `./<cluster>/*.css` captures the element name; the value's two `*` are both substituted with the captured name, resolving `<cluster>/<elem>.css` requests to `<cluster>/<elem>/<elem>.css` on disk. Existing JS subpath exports (`./<cluster>/*` → `./<cluster>/*/*.js`) are preserved unchanged — both can coexist because `.css` requests don't collide with bare-name `.js` requests. Driven by [consumer feedback](/Users/kimba/Projects/adia/color-app/docs/outbound/FEEDBACK-adia-packages.md) from Design Tokens Studio (claim #6, the only fully-correct item in their 8-claim audit).
43
+
44
+ ### Documentation
45
+
46
+ - `README.md` — peer-deps section enriched. Two additional peer dependencies (`@adia-ai/a2ui-runtime`, `@adia-ai/llm`) clarified as cluster-specific (`runtime` cluster + `chat` cluster, respectively); other clusters (`shell`, `editor`, `simple`, `theme`) can omit them or keep them as `--legacy-peer-deps` warnings under npm; pnpm with auto-install-peers silently installs them. Helps consumers who only want a subset avoid noisy install warnings.
47
+
14
48
  ## [0.4.4] - 2026-05-12
15
49
 
16
50
  ### Ride-along (no source changes)
package/README.md CHANGED
@@ -11,7 +11,17 @@ consumers install only what they need.
11
11
  npm install @adia-ai/web-modules @adia-ai/web-components
12
12
  ```
13
13
 
14
- `@adia-ai/web-components` is a peer dependency (modules compose primitives at runtime). Consumers can import the full barrel or a specific cluster subpath:
14
+ `@adia-ai/web-components` is **always required** (modules compose primitives at runtime). Two additional peer dependencies are declared but **only needed for specific clusters**:
15
+
16
+ | Peer dependency | Required when you use |
17
+ |---|---|
18
+ | `@adia-ai/web-components` (always) | Any cluster |
19
+ | `@adia-ai/a2ui-runtime` | `runtime` cluster (`<gen-root>`, `<a2ui-root>`) — A2UI message → DOM renderer |
20
+ | `@adia-ai/llm` | `chat` cluster (`<chat-shell>`) — LLM proxy + streaming |
21
+
22
+ If you only use `shell`, `editor`, `simple`, or `theme` clusters, those two peers can be omitted (or kept as `--legacy-peer-deps` warnings under npm). pnpm with auto-install-peers will silently install them.
23
+
24
+ ## Import: JS
15
25
 
16
26
  ```js
17
27
  import '@adia-ai/web-modules'; // every cluster
@@ -23,6 +33,21 @@ import '@adia-ai/web-modules/theme'; // theme-panel
23
33
  import '@adia-ai/web-modules/runtime'; // gen-root + a2ui-root
24
34
  ```
25
35
 
36
+ ## Import: CSS (since v0.4.5)
37
+
38
+ CSS imports use the package specifier — the package's `exports` map resolves `.css` requests to the per-element stylesheet on disk:
39
+
40
+ ```js
41
+ import '@adia-ai/web-modules/shell/admin-shell.css';
42
+ import '@adia-ai/web-modules/chat/chat-shell.css';
43
+ import '@adia-ai/web-modules/editor/editor-shell.css';
44
+ import '@adia-ai/web-modules/simple/simple-shell.css';
45
+ import '@adia-ai/web-modules/theme/theme-panel.css';
46
+ import '@adia-ai/web-modules/runtime/gen-root.css';
47
+ ```
48
+
49
+ > **For pre-v0.4.5 consumers:** if you were importing CSS via the relative `node_modules` path (`'../node_modules/@adia-ai/web-modules/editor/editor-shell/editor-shell.css'`), switch to the package-specifier form above. The relative-path form is fragile under pnpm, Yarn PnP, and npm hoisting; the new package-specifier form works under all three.
50
+
26
51
  Each cluster carries a **shell host** (behavior-only orchestrator) plus
27
52
  a **family of bespoke shell-tier children** (cluster-namespaced custom
28
53
  elements with state-as-attribute semantics) per [ADR-0023](../../.brain/adrs/0023-bespoke-shell-tier-children.md). The bespoke vocabulary is the only recognized authoring shape since v0.4.0 ([ADR-0024](../../.brain/adrs/0024-legacy-shell-shapes-retired.md)).
@@ -50,23 +75,28 @@ See [`bespoke-shell-children` skill](../../.agents/skills/bespoke-shell-children
50
75
 
51
76
  ## Quick start
52
77
 
78
+ ESM-only — bundlers (Vite, esbuild, webpack 5+, Rollup) resolve `import` statements for both `.js` and `.css`; in plain HTML, use `<script type="module">` for JS and `<link>` for CSS.
79
+
80
+ ```js
81
+ // JS — register every primitive + the clusters you compose with
82
+ import '@adia-ai/web-components'; // primitives + nav family
83
+ import '@adia-ai/web-modules/shell'; // admin-shell + bespoke children
84
+ import '@adia-ai/web-modules/chat'; // chat-shell + bespoke children (needs @adia-ai/llm)
85
+ import '@adia-ai/web-modules/editor'; // editor-shell + bespoke children
86
+ import '@adia-ai/web-modules/runtime'; // gen-root, a2ui-root (needs @adia-ai/a2ui-runtime)
87
+ import '@adia-ai/web-modules/theme'; // theme-panel (appearance prefs)
88
+
89
+ // CSS — one stylesheet per cluster you use
90
+ import '@adia-ai/web-components/css'; // every primitive's CSS
91
+ import '@adia-ai/web-modules/shell/admin-shell.css';
92
+ import '@adia-ai/web-modules/chat/chat-shell.css';
93
+ import '@adia-ai/web-modules/editor/editor-shell.css';
94
+ import '@adia-ai/web-modules/theme/theme-panel.css';
95
+ ```
96
+
97
+ Then in your markup (bespoke shape, canonical since v0.4.0):
98
+
53
99
  ```html
54
- <!-- CSS for each cluster you import -->
55
- <link rel="stylesheet" href="node_modules/@adia-ai/web-modules/shell/admin-shell/admin-shell.css" />
56
-
57
- <!-- Primitives (nav-ui, nav-group-ui, nav-item-ui live here) -->
58
- <link rel="stylesheet" href="node_modules/@adia-ai/web-components/index.css" />
59
-
60
- <script type="module">
61
- import '@adia-ai/web-components'; // primitives + nav family
62
- import '@adia-ai/web-modules/shell'; // admin-shell + bespoke children
63
- import '@adia-ai/web-modules/chat'; // chat-shell + bespoke children
64
- import '@adia-ai/web-modules/editor'; // editor-shell + bespoke children
65
- import '@adia-ai/web-modules/runtime'; // gen-root, a2ui-root
66
- import '@adia-ai/web-modules/theme'; // theme-panel (appearance prefs)
67
- </script>
68
-
69
- <!-- Bespoke shape (canonical since v0.4.0): -->
70
100
  <admin-shell mode="rounded">
71
101
  <admin-sidebar slot="leading" resizable collapsible>
72
102
  <header-ui>
@@ -83,6 +113,14 @@ See [`bespoke-shell-children` skill](../../.agents/skills/bespoke-shell-children
83
113
  </admin-shell>
84
114
  ```
85
115
 
116
+ **Live demos** for every cluster:
117
+ - [`<admin-shell>`](https://ui-kit.exe.xyz/site/components/admin-shell)
118
+ - [`<chat-shell>`](https://ui-kit.exe.xyz/site/components/chat-shell)
119
+ - [`<editor-shell>`](https://ui-kit.exe.xyz/site/components/editor-shell)
120
+ - [`<simple-shell>`](https://ui-kit.exe.xyz/site/components/simple-shell)
121
+ - [`<theme-panel>`](https://ui-kit.exe.xyz/site/components/theme-panel)
122
+ - [`<gen-root>`](https://ui-kit.exe.xyz/site/components/gen-root) · [`<a2ui-root>`](https://ui-kit.exe.xyz/site/components/a2ui-root)
123
+
86
124
  ## Three-tier architecture
87
125
 
88
126
  ```
@@ -99,56 +137,61 @@ for the rationale and the patterns/modules collapse.
99
137
 
100
138
  ## Migration from `@adia-ai/web-components/patterns`
101
139
 
102
- Before:
103
-
104
- ```js
105
- import '@adia-ai/web-components/patterns/app-shell/app-shell.js';
106
- import '@adia-ai/web-components/patterns/adia-chat/adia-chat.js';
107
- ```
140
+ The `patterns/` directory was extracted from `@adia-ai/web-components` into this package in v0.0.29 ([ADR-0012](../../.brain/adrs/0012-three-tier-architecture-modules.md)). If you're upgrading from a pre-v0.0.29 release:
108
141
 
109
- After:
142
+ ```diff
143
+ - import '@adia-ai/web-components/patterns/app-shell/app-shell.js';
144
+ + import '@adia-ai/web-modules/shell';
110
145
 
111
- ```js
112
- import '@adia-ai/web-modules/shell/app-shell/app-shell.js';
113
- import '@adia-ai/web-modules/chat/adia-chat/adia-chat.js';
146
+ - import '@adia-ai/web-components/patterns/adia-chat/adia-chat.js';
147
+ + import '@adia-ai/web-modules/chat';
114
148
  ```
115
149
 
116
- Or, more idiomatically, import the cluster:
117
-
118
- ```js
119
- import '@adia-ai/web-modules/shell'; // every shell-cluster element
120
- import '@adia-ai/web-modules/chat'; // adia-chat
121
- ```
122
-
123
- CSS paths shift the same way (`/patterns/<x>/<x>.css` →
124
- `/<cluster>/<x>/<x>.css`).
150
+ CSS paths shift the same way. Tag names + class names also changed in v0.0.31 (ADR-0015 — `<app-shell-ui>` → `<admin-shell>`, `<adia-chat-ui>` → `<chat-shell>`, `<adia-editor-ui>` → `<editor-shell>`, `<gen-ui-ui>` → `<gen-root>`) and v0.0.32 (ADR-0016 — module classes drop the `Adia` prefix). And the legacy authoring shapes (`<aside-ui slot>`, `<section data-chat-messages>`, etc.) were retired in v0.4.0 in favor of the bespoke vocabulary — see [ADR-0024](../../.brain/adrs/0024-legacy-shell-shapes-retired.md) for the full migration recipe.
125
151
 
126
152
  ## Layout
127
153
 
128
154
  ```
129
155
  web-modules/
130
- ├── shell/
131
- │ └── admin-shell/ <admin-shell-ui> (full component, 251 LOC JS)
132
- │ Nav primitives (nav-ui, nav-group-ui, nav-item-ui)
133
- │ live in @adia-ai/web-components.
134
- ├── chat/
135
- │ └── adia-chat/
136
- ├── editor/
137
- │ └── adia-editor/
138
- ├── runtime/
139
- │ ├── gen-ui/ <gen-ui> render root
140
- │ └── a2ui-root/ <a2ui-root> A2UI render root
141
- ├── theme/
142
- │ └── theme-panel/ <theme-panel> appearance-preferences control surface
143
- └── index.js barrel re-export of every cluster
156
+ ├── shell/ 9 elements
157
+ │ ├── admin-shell/ <admin-shell> host (87 LOC JS, behavior-only)
158
+ │ ├── admin-sidebar/ resizable + collapsible + localStorage persistence
159
+ │ ├── admin-command/ Cmd+K command palette
160
+ │ └── admin-{topbar,content,statusbar,scroll,page,page-header,page-body}/
161
+ │ CSS-only structural children
162
+ ├── chat/ 6 elements
163
+ │ ├── chat-shell/ <chat-shell> host (streaming-aware)
164
+ │ ├── chat-thread/ scrollable message list
165
+ │ ├── chat-composer/ input + submit + [disabled] propagation
166
+ │ ├── chat-sidebar/ conversation list
167
+ │ └── chat-{empty,header,status}/ CSS-only
168
+ ├── editor/ 5 elements
169
+ │ ├── editor-shell/ <editor-shell> host (toolbar/canvas/sidebar orchestrator)
170
+ │ ├── editor-toolbar/ <editor-toolbar> with [full-screen]
171
+ │ ├── editor-canvas/ <editor-canvas> with [empty]/[focused]
172
+ │ ├── editor-sidebar/ wraps <pane-ui resizable> for delegation
173
+ │ └── editor-{statusbar,canvas-empty}/ CSS-only
174
+ ├── simple/ 3 elements
175
+ │ ├── simple-shell/ <simple-shell> minimal marketing/landing shell
176
+ │ └── simple-{content,hero}/ CSS-only
177
+ ├── runtime/ 2 render roots
178
+ │ ├── gen-root/ <gen-root> turns gen-UI intents into DOM
179
+ │ └── a2ui-root/ <a2ui-root> A2UI protocol → DOM (uses @adia-ai/a2ui-runtime)
180
+ ├── theme/ 1 element
181
+ │ └── theme-panel/ <theme-panel> appearance-preferences control surface
182
+ └── index.js barrel re-export of every cluster
144
183
  ```
145
184
 
146
- Each element directory carries its `.js`, `.css`, `.yaml`, and
147
- `.a2ui.json` files — same shape as `web-components/components/<x>/`.
148
- The yaml + a2ui.json contracts feed the gen-UI catalog at
149
- `packages/a2ui/corpus/catalog-a2ui_0_9.json`; the build script at
150
- `scripts/build/components.mjs` scans both `web-components/components/`
151
- and `web-modules/<cluster>/`.
185
+ Each element directory carries its `.js`, `.css`, `.yaml`, and `.a2ui.json` files — same shape as `web-components/components/<x>/`. The yaml + a2ui.json contracts feed the gen-UI catalog at `packages/a2ui/corpus/catalog-a2ui_0_9.json`; the build script at `scripts/build/components.mjs` scans both `web-components/components/` and `web-modules/<cluster>/`.
186
+
187
+ ## Behavior contract
188
+
189
+ All `<*-shell>` hosts are **behavior-only orchestrators** — they reflect state attributes, propagate slot intent to their bespoke children, and forward events. Visual layout is owned by the children's CSS. Bespoke children fall into two classes:
190
+
191
+ - **JS-bearing children** carry `connected()`/`disconnected()` lifecycle for interactive behavior (`admin-sidebar` resize, `admin-command` palette, `chat-thread` streaming scroll, `editor-canvas` zoom, etc.).
192
+ - **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.
193
+
194
+ 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).
152
195
 
153
196
  ## License
154
197
 
package/package.json CHANGED
@@ -1,22 +1,28 @@
1
1
  {
2
2
  "name": "@adia-ai/web-modules",
3
- "version": "0.4.4",
3
+ "version": "0.4.5",
4
4
  "description": "AdiaUI composite custom elements — shell, chat, editor, runtime clusters built from @adia-ai/web-components primitives. Subpath exports per cluster.",
5
5
  "type": "module",
6
6
  "exports": {
7
7
  ".": "./index.js",
8
8
  "./shell": "./shell/index.js",
9
9
  "./shell/*": "./shell/*/*.js",
10
+ "./shell/*.css": "./shell/*/*.css",
10
11
  "./chat": "./chat/index.js",
11
12
  "./chat/*": "./chat/*/*.js",
13
+ "./chat/*.css": "./chat/*/*.css",
12
14
  "./editor": "./editor/index.js",
13
15
  "./editor/*": "./editor/*/*.js",
16
+ "./editor/*.css": "./editor/*/*.css",
14
17
  "./simple": "./simple/index.js",
15
18
  "./simple/*": "./simple/*/*.js",
19
+ "./simple/*.css": "./simple/*/*.css",
16
20
  "./runtime": "./runtime/index.js",
17
21
  "./runtime/*": "./runtime/*/*.js",
22
+ "./runtime/*.css": "./runtime/*/*.css",
18
23
  "./theme": "./theme/index.js",
19
24
  "./theme/*": "./theme/*/*.js",
25
+ "./theme/*.css": "./theme/*/*.css",
20
26
  "./package.json": "./package.json"
21
27
  },
22
28
  "files": [