@adia-ai/web-modules 0.8.40 → 0.8.41

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog — @adia-ai/web-modules
 
+## [0.8.41] — 2026-08-17
+
+### Added
+- **`a2ui-root` — surface lifecycle integration (gh#1364 + follow-up gh#1433; `spec-a2ui-surface-lifecycle.md`, ADR-0061).** The `doc` setter is now an atomic `replaceDoc()`: per surfaceId, an EXISTING surface regenerates through a begin → apply → commit bracket so old content stays visible until the new answer commits (no blank frame — "the blank flash is the bug", OD-2), and surfaces the new doc no longer declares are torn down. New reflected rolled-up `[pending]` attribute (true while any surface has an in-flight generation), driven by the renderer's bubbling `surface-pending`/`surface-committed`/`surface-aborted` events; default pending/stale styling ships in `runtime/a2ui-root/a2ui-root.css`. `runtime/a2ui-root/a2ui-root.js` + `a2ui-root.test.js`.
+
+### Changed
+- **BREAKING, no deprecation aliases — composite-side renames from the global-attribute-shadowing sweep (gh#1335).** `invoice-detail-ui`/`invoice-history-ui`/`dashboard-layout-ui[density]` converge onto the global grammar (`compact`/`spacious`/unset — the component-local enums are gone); `dashboard-layout-ui[gap]` → `[band-gap]`. See the migration guide's [§ Shipped in `0.8.41` — global-attribute-shadowing collision sweep](../../.claude/docs/MIGRATION%20GUIDE.md).
+- **BREAKING, no deprecation alias — `data-*` states converge to bare attributes (gh#1332, Category A).** `integrations-page-ui`'s `empty-search`/`empty-data` states (was `[data-empty-search]`/`[data-empty-data]`) and `onboarding-checklist-ui`'s `complete` state (was `[data-complete]`) now match their own sibling states' bare-attribute convention (`loading`, `collapsed`). Any CSS/script targeting the old forms moves to `[empty-search]`/`[empty-data]`/`[complete]`. The same sweep (PR #1438) stamped declared API-state attributes across the module tier per the ADR-0060 anatomy-marker convention.
+- **BREAKING for raw A2UI documents only — `admin-shell`'s catalog identity is now `AdminShell` (gh#1427).** `admin-shell.yaml` and `embed-shell.yaml` both declared `component: AppShell`, so the catalog build silently dropped `admin-shell`'s entry (embed-shell's fragment won); `embed-shell` keeps `AppShell`. A raw a2ui tree with `{"component": "AppShell"}` meaning the stable admin shell updates to `AdminShell`; the `<admin-shell>` tag and JS API are unaffected.
+- **`billing-overview` family recomposed from layout primitives (gh#1519).** The billing overview page family now composes the shared layout primitives instead of bespoke wrappers — `billing/billing-overview/`.
+- **`dashboard-layout` — chart band adopts the chart-in-card bleed/legend convention (#1399).** Charts in the band render with the card-bleed + legend placement the dashboard pattern library established.
+- **`admin-roster` — persona-import composes the `upload-ui` primitive (#1398)** instead of a hand-rolled native file picker.
+
+### Fixed
+- **`table-toolbar` hides the title cluster when it has nothing to show (ADIA2-8897).** An empty title/description cluster no longer reserves its grid column, so toolbars with only actions/filters align flush.
+
+### Maintenance
+- **`dist/` bundles rebuilt** in this cut's window — carried by the entries above plus the web-components SSR shape-1 sweep (gh#1430/gh#1436) and yaml/sidecar regenerations (ADR-0067 `parts:`, ADR-0069 derived-resync); regenerated artifacts, not independent edits.
+- **`agent-admin/` touched in this release window** (6 file(s), e.g. `admin-roster/admin-roster.a2ui.json`) — carried by the entries above.
+- **`chat/` touched in this release window** (14 file(s), e.g. `chat-composer/chat-composer.a2ui.json`) — carried by the entries above.
+- **`editor/` touched in this release window** (14 file(s), e.g. `editor-canvas-empty/editor-canvas-empty.a2ui.json`) — carried by the entries above.
+- **`feedback/` touched in this release window** (1 file(s), e.g. `confirm-dialog/confirm-dialog.a2ui.json`) — carried by the entries above.
+- **`form/` touched in this release window** (1 file(s), e.g. `form-popover/form-popover.a2ui.json`) — carried by the entries above.
+- **`settings/` touched in this release window** (6 file(s), e.g. `integrations-page/integrations-page.a2ui.json`) — carried by the entries above.
+- **`simple/` touched in this release window** (6 file(s), e.g. `simple-content/simple-content.a2ui.json`) — carried by the entries above.
+- **`theme/` touched in this release window** (1 file(s), e.g. `theme-panel/theme-panel.a2ui.json`) — carried by the entries above.
+
 ## [0.8.40] — 2026-08-15
 
 ### Fixed

package/README.md

@@ -22,7 +22,7 @@ Since **v0.6.30**, both this package and `@adia-ai/web-components` ship pre-flat
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-components@0.8/dist/web-components.min.css">
 <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.8/dist/shell/admin-shell.min.css">
 
-<!-- JS: everything in one bundle (primitives + all 4 shells + a2ui-runtime; ~190 KB gzipped) -->
+<!-- JS: everything in one bundle (primitives + all 4 shells + the @adia-ai/a2ui runtime; ~424 KB gzipped) -->
 <script type="module" src="https://cdn.jsdelivr.net/npm/@adia-ai/web-modules@0.8/dist/everything.min.js"></script>
 
 <admin-shell mode="rounded borderless">
@@ -87,7 +87,7 @@ Since **v0.6.30**, both this package and `@adia-ai/web-components` ship pre-flat
 
 | 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** |
+| **Everything** | `/dist/everything.min.js` | **~424 KB** | All primitives + the @adia-ai/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 |
@@ -119,7 +119,7 @@ When composing UI with an AI coding agent (Claude Code / Cursor / Windsurf / Cla
 | Peer dependency | Required when you use |
 |---|---|
 | `@adia-ai/web-components` (always) | Any cluster |
-| `@adia-ai/a2ui-runtime` | `runtime` cluster (`<gen-root>`, `<a2ui-root>`) — A2UI message → DOM renderer |
+| `@adia-ai/a2ui` | `runtime` cluster (`<gen-root>`, `<a2ui-root>`) — A2UI message → DOM renderer |
 | `@adia-ai/llm` | `chat` cluster (`<chat-shell>`) — LLM proxy + streaming |
 
 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.
@@ -250,7 +250,7 @@ import '@adia-ai/web-components';        // primitives + nav family
 import '@adia-ai/web-modules/shell';     // admin-shell + bespoke children
 import '@adia-ai/web-modules/chat';      // chat-shell + bespoke children (needs @adia-ai/llm)
 import '@adia-ai/web-modules/editor';    // editor-shell + bespoke children
-import '@adia-ai/web-modules/runtime';   // gen-root, a2ui-root (needs @adia-ai/a2ui-runtime)
+import '@adia-ai/web-modules/runtime';   // gen-root, a2ui-root (needs @adia-ai/a2ui)
 import '@adia-ai/web-modules/theme';     // theme-panel (appearance prefs)
 
 // CSS — one stylesheet per cluster you use (REQUIRED — see callout above)
@@ -343,13 +343,13 @@ web-modules/
 │   └── simple-{content,hero}/   CSS-only
 ├── runtime/               2 render roots
 │   ├── gen-root/          <gen-root> turns gen-UI intents into DOM
-│   └── a2ui-root/         <a2ui-root> A2UI protocol → DOM (uses @adia-ai/a2ui-runtime)
+│   └── a2ui-root/         <a2ui-root> A2UI protocol → DOM (uses @adia-ai/a2ui)
 ├── theme/                 1 element
 │   └── theme-panel/       <theme-panel> appearance-preferences control surface
 └── index.js               barrel re-export of every cluster
 ```
 
-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/gen-ui/a2ui/corpus/catalog-a2ui_0_9.json`; the build script at `scripts/build/components.mjs` scans both `web-components/components/` and `web-modules/<cluster>/`.
+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/gen-ui/a2ui/catalog/catalog-a2ui_0_9.json`; the build script at `scripts/build/components.mjs` scans both `web-components/components/` and `web-modules/<cluster>/`.
 
 ## Behavior contract
 

package/agent-admin/admin-roster/admin-roster.a2ui.json

@@ -94,6 +94,7 @@
       "menu"
     ],
     "name": "UIAdminRoster",
+    "parts": {},
     "related": [
       "AdminSettings",
       "AgentAdmin",

package/agent-admin/admin-roster/admin-roster.css

@@ -64,7 +64,7 @@
     box-sizing: border-box;
   }
 
-  :scope [data-part="row"][data-active="true"] {
+  :scope [data-part="row"][aria-checked="true"] {
     --menu-item-bg:        var(--admin-roster-active-bg);
     --menu-item-fg:        var(--admin-roster-active-fg);
     --menu-item-fg-hover:  var(--admin-roster-active-fg);
@@ -76,7 +76,7 @@
     visibility: hidden;
   }
 
-  :scope [data-part="row"][data-active="true"] [data-part="row-check"] {
+  :scope [data-part="row"][aria-checked="true"] [data-part="row-check"] {
     visibility: visible;
   }
 
@@ -90,4 +90,12 @@
     display: flex;
     gap: var(--a-space-2);
   }
+
+  /* Reuses <upload-ui> as the picker engine behind the visible "Import"
+     button (gh#1360) — display:none, not visually-hidden-ui: this node
+     is never meant to reach AT (aria-hidden + out of tab order above),
+     unlike a sr-only label that stays AT-visible on purpose. */
+  :scope [data-part="import-file"] {
+    display: none;
+  }
 }

package/agent-admin/admin-roster/admin-roster.js

@@ -20,20 +20,50 @@
  *
  * Import/export rides `@adia-ai/persona`'s persona-file functions
  * verbatim — this composite never re-implements the file format. Export
- * downloads a `.json` via a throwaway object URL; import reads a chosen
- * file through `input[type=file]`, calls `importPersona` (which always
- * MINTS a new persona — never overwrites an existing one, even on an id
- * collision) and re-emits it upward as `persona-import` so a host can
- * append it to its own persona list and persist it.
+ * downloads a `.json` via a throwaway object URL; import reuses the
+ * `<upload-ui>` primitive (packages/web-components/components/upload/) as
+ * its file-picking engine — a `display:none` `<upload-ui data-part=
+ * "import-file">` sits in the template (`accept="application/json"`
+ * shapes its PICKER only — upload-ui's drop path forwards dropped files
+ * unfiltered, so this module re-checks "exactly one JSON-named/typed
+ * file" itself before importing), and the toolbar's visible "Import" icon button
+ * (gh#1360, replacing a hand-rolled `input[type=file]`) delegates the
+ * click to upload-ui's own dropzone part (`[data-dropzone]` — this
+ * framework's light-DOM "part" hook, styled by upload.css and driven by
+ * upload.class.js the same way; there is no public `.open()`/`.pick()`
+ * method on the primitive, so this is the narrowest supported trigger
+ * point short of a primitive change — see the ticket's Findings for the
+ * gap this surfaced). upload-ui's own `showOpenFilePicker` (+
+ * `input[type=file]` fallback) does the picking; its documented `change`
+ * event (`{ value, files }`, upload.d.ts) is read here, then handed to
+ * `importPersona` (which always MINTS a new persona — never overwrites an
+ * existing one, even on an id collision) and re-emitted upward as
+ * `persona-import` so a host can append it to its own persona list and
+ * persist it.
  *
  * Per ADR-0027 — composites that programmatically create primitives in
  * render() do NOT auto-import those primitives; a consumer imports
- * <button-ui> + <icon-ui> + <menu-item-ui> (menu.js) alongside this module.
+ * <button-ui> + <icon-ui> + <menu-item-ui> (menu.js) + <upload-ui>
+ * alongside this module.
  */
 
 import { UIElement, html } from '@adia-ai/web-components/core/element';
 import { exportPersona, importPersona } from '@adia-ai/persona';
 
+// The template's <upload-ui accept="application/json"> — one value, both
+// the picker filter and the drop-side check below derive from it.
+const IMPORT_ACCEPT = 'application/json';
+
+// A file "indicates JSON" when either its MIME type is the accept value or
+// its name carries a .json suffix — OS drops routinely leave `type` empty
+// for .json, and a picker-chosen file may be typed but oddly named, so
+// either signal suffices; neither alone is required.
+function isJsonFile(file) {
+  if (!file) return false;
+  if (file.type === IMPORT_ACCEPT) return true;
+  return /\.json$/i.test(String(file.name || ''));
+}
+
 class UIAdminRoster extends UIElement {
   static properties = {
     personas: { type: Array, default: [] },
@@ -43,7 +73,6 @@ class UIAdminRoster extends UIElement {
   static template = (host) => host._renderTemplate();
 
   #headerId = `admin-roster-h-${Math.random().toString(36).slice(2, 8)}`;
-  #fileInput = null;
 
   attributeChangedCallback(name, oldVal, newVal) {
     if (name === 'personas') {
@@ -94,6 +123,7 @@ class UIAdminRoster extends UIElement {
         <button-ui data-action="export" text="Export" icon="download-simple" variant="ghost" size="sm"
           .disabled=${!activeId}></button-ui>
         <button-ui data-action="import" text="Import" icon="upload-simple" variant="ghost" size="sm"></button-ui>
+        <upload-ui data-part="import-file" accept=${IMPORT_ACCEPT} aria-hidden="true" tabindex="-1"></upload-ui>
       </div>
     `;
   }
@@ -109,7 +139,6 @@ class UIAdminRoster extends UIElement {
         role="menuitemradio"
         tabindex="0"
         aria-checked=${String(isActive)}
-        data-active=${isActive}
         text=${persona.label ?? persona.id}
         subtitle=${persona.category ?? ''}
       >
@@ -175,24 +204,43 @@ class UIAdminRoster extends UIElement {
     URL.revokeObjectURL(url);
   }
 
+  // <upload-ui> exposes no public open()/pick() method (upload.d.ts) — the
+  // narrowest supported trigger is clicking its own `[data-dropzone]` part
+  // (the same node upload.class.js binds its click/keydown/drag listeners
+  // to, and upload.css styles by), so showOpenFilePicker (+ its
+  // input[type=file] fallback) runs exactly as it would for a directly
+  // clicked <upload-ui>.
   #triggerImport() {
-    if (!this.#fileInput) {
-      this.#fileInput = this.ownerDocument.createElement('input');
-      this.#fileInput.type = 'file';
-      this.#fileInput.accept = 'application/json';
-      this.#fileInput.setAttribute('data-part', 'import-file');
-      this.#fileInput.style.display = 'none';
-      this.appendChild(this.#fileInput);
-    }
-    this.#fileInput.value = '';
-    this.#fileInput.click();
+    const upload = this.querySelector('[data-part="import-file"]');
+    upload?.querySelector('[data-dropzone]')?.click();
   }
 
+  // Fires on the bubbling `change` <upload-ui> dispatches on itself
+  // (upload.d.ts's documented UploadChangeEvent — { value, files }).
+  //
+  // upload-ui's `accept` / `multiple` only shape its PICKER; its drop path
+  // (upload.class.js #onDrop) forwards `dataTransfer.files` unfiltered. So
+  // the single-JSON-file contract is enforced here: exactly one file whose
+  // name or MIME type says JSON — anything else is rejected through the
+  // same `persona-import-error` path a malformed file takes.
   #onImportFileChange = async (e) => {
-    const input = e.target;
-    if (!input || input !== this.#fileInput) return;
-    const file = input.files?.[0];
-    if (!file) return;
+    const target = e.target;
+    if (!target || target.getAttribute?.('data-part') !== 'import-file') return;
+    const files = Array.isArray(e.detail?.files) ? e.detail.files : [];
+    if (files.length === 0) return;
+    const reject = (message) => this.dispatchEvent(new CustomEvent('persona-import-error', {
+      bubbles: true,
+      detail: { error: message },
+    }));
+    if (files.length !== 1) {
+      reject(`Import expects exactly one .json file (got ${files.length})`);
+      return;
+    }
+    const [file] = files;
+    if (!isJsonFile(file)) {
+      reject(`Import expects a .json file (got "${file?.name || 'unnamed file'}")`);
+      return;
+    }
     try {
       const text = await file.text();
       const existingIds = (Array.isArray(this.personas) ? this.personas : []).map((p) => p.id);

package/agent-admin/admin-settings/admin-settings.a2ui.json

@@ -80,6 +80,7 @@
       "agent"
     ],
     "name": "UIAdminSettings",
+    "parts": {},
     "related": [
       "AdminRoster",
       "AgentAdmin"

package/agent-admin/agent-admin/agent-admin.a2ui.json

@@ -91,6 +91,7 @@
       "store-swap"
     ],
     "name": "UIAgentAdmin",
+    "parts": {},
     "related": [
       "AdminRoster",
       "AdminSettings",

package/billing/billing-overview/billing-overview.a2ui.json

@@ -15,7 +15,10 @@
   "properties": {
     "account": {
       "description": "Aggregate billing snapshot — source of truth for the whole\ndashboard. Shape:\n  {plan: {id, name, price, cycle, currency, status},\n   status: \"active\" | \"trialing\" | \"past_due\" | \"canceled\" | \"paused\",\n   billingCycle: \"month\" | \"year\",\n   currentSpend: number,\n   seats: {used: number, total: number},\n   nextInvoiceDate: ISO 8601 date string,\n   paymentMethods: [...],          // forwarded to payment-method-list\n   invoices: [...],                // forwarded to invoice-history\n   plans?: [...],                  // forwarded to plan-picker; omitted when planSection is \"hidden\"\n   dunning?: {amount, currency, dueAt, cardLast4?, reason?}}\nNull + no `data-stream-src` renders the empty state.\n",
-      "type": "object",
+      "type": [
+        "object",
+        "null"
+      ],
       "default": null
     },
     "component": {
@@ -86,6 +89,11 @@
       "tag-ui",
       "text-ui",
       "alert-ui",
+      "avatar-ui",
+      "col-ui",
+      "row-ui",
+      "grid-ui",
+      "progress-ui",
       "plan-picker-ui",
       "payment-method-list-ui",
       "invoice-history-ui",
@@ -155,6 +163,7 @@
       "past-due"
     ],
     "name": "UIBillingOverview",
+    "parts": {},
     "related": [
       "PlanPicker",
       "PaymentMethodList",