@adia-ai/web-modules 0.3.3 → 0.3.5

package/CHANGELOG.md

@@ -11,6 +11,66 @@ Built from `@adia-ai/web-components` primitives.
 
 _No pending changes._
 
+## [0.3.5] - 2026-05-07
+
+### Added
+
+- **Chat cluster bespoke family** — second cluster decomposed per ADR-0023, proving the family pattern is replicable.
+  - **`<chat-thread streaming?>`** — JS-bearing (106 LOC + 8 unit tests). Replaces legacy `<section data-chat-messages>`. Owns scroll-to-bottom on new message (with user-scroll-up suspension), `[streaming]` and `[empty]` reflected attributes. Public API: `.scrollToBottom()` / `.scrollToBottomInstant()`.
+  - **`<chat-composer disabled?>`** — JS-bearing (100 LOC + 9 unit tests). Wraps `<chat-input-ui>` (or any input-like child). Forwards inner submit as `composer-submit` event (bespoke name to prevent double-fire). Propagates `[disabled]` to inner input.
+  - **`<chat-sidebar slot="leading|trailing" resizable collapsible>`** — JS-bearing (227 LOC + 10 unit tests). Mirrors `<admin-sidebar>`. Cluster-namespaced localStorage prefix (`adia-chat-sidebar-{name}`).
+  - **3 CSS-only structural children** — `<chat-header>`, `<chat-status>`, `<chat-empty>` (visibility driven by parent `<chat-thread>[empty]`).
+
+- **CSS bridge** `chat/chat-shell/css/chat-shell.bespoke.css` (196 LOC) — maps the 6 bespoke chat tags to existing CSS without touching legacy layer files. Imported last in `chat-shell.css`.
+
+- **`chat/index.js` exports** all 4 JS-bearing chat children (ChatShell + ChatThread + ChatComposer + ChatSidebar). Subpath import unchanged: `import '@adia-ai/web-modules/chat'`.
+
+### Changed
+
+- **`<chat-shell>` host** — now coordinates bespoke children rather than centralizing their behavior. `connected()` reads BOTH legacy + bespoke shapes via priority chain. Listens for `composer-submit` on bespoke composer, `submit` on legacy input (mutually exclusive). `startStreaming()` / `stopStreaming()` propagate `[streaming]` to `<chat-thread>`.
+
+- **`chat-shell.examples.html` reorganized** — split "Basic shape" into "Basic shape (legacy)" + new "Basic shape (bespoke — recommended)" + "State as attribute" section with CSS `:has()` examples.
+
+### Backwards compatibility
+
+Legacy authoring shapes (`<section data-chat-messages>`, `<chat-input-ui data-chat-input>`, `[data-chat-empty]`, `[data-chat-status]`) all still work identically. Mixed markup renders the same. Migration is opt-in.
+
+## [0.3.4] - 2026-05-07
+
+### Added
+
+- **`<admin-sidebar slot="leading|trailing" resizable collapsible>`** — first JS-bearing bespoke shell-tier child per ADR-0023. 227 LOC + 10 unit tests. Owns: resize drag with snap thresholds (96 floor / 160 min-usable), `[collapsed]` reflected attribute, localStorage persistence (`adia-sidebar-{name}`), ResizeObserver for narrow-mode children. Public API: `.toggle()` / `.collapse()` / `.expand()`. Events: `sidebar-toggle`, `sidebar-resize` (both bubble).
+
+- **`<admin-command shortcut="cmd+k|ctrl+k|both">`** — second JS-bearing bespoke child. 156 LOC + 9 unit tests. Owns: keyboard shortcut listener (default both Cmd+K + Ctrl+K), dialog focus management, dismiss handlers, dialog wrapping. Reflects `[open]`. Public API: `.show()` / `.hide()` / `.toggle()`. Forwards `command-select` events.
+
+- **7 CSS-only structural children** for the admin shell cluster: `<admin-content>`, `<admin-topbar>`, `<admin-statusbar>`, `<admin-scroll>`, `<admin-page>`, `<admin-page-header>`, `<admin-page-body>`. Pure CSS-only stubs (no `.js`, no own `.css`) — same pattern as `web-components/components/aside/`. Styled by parent `<admin-shell>` via tag-presence selectors.
+
+- **CSS bridge** `shell/admin-shell/css/admin-shell.bespoke.css` — maps the 7 bespoke tags to existing CSS layer rules without touching legacy CSS files.
+
+- **Sibling shell demo pages** (closes A1 from admin-shell deep review):
+  - `chat/chat-shell/chat-shell.html` + `.examples.html`
+  - `editor/editor-shell/editor-shell.html` + `.examples.html`
+
+- **`shell/index.js` exports** all 3 JS-bearing children (AdminShell + AdminSidebar + AdminCommand). Subpath import unchanged: `import '@adia-ai/web-modules/shell'`.
+
+### Changed
+
+- **`<admin-shell>` host** — now coordinates bespoke children rather than centralizing their behavior. Source LOC actually grew (261 → 305) because the legacy compatibility layer is preserved inline (per ADR-0023 Phase 1 backwards-compat); once legacy shapes deprecate in Phase 3, the host drops to ~80 LOC.
+
+- **`admin-shell.examples.html` reorganized** — split "Basic shape" into "Basic shape (legacy)" + "Basic shape (bespoke — recommended)" with full 9-element bespoke composition + new "State as attribute" section with CSS `:has()` examples + ADR-0023 cross-reference.
+
+- **`--nav-*` tokens in `admin-shell.tokens.css` documented as shell-context overrides** (closes G4 from deep review). They're not canonical; canonical lives in `nav.css`, `nav-group.css`, `nav-item.css` `:where()` roots.
+
+### Fixed
+
+- **G1**: `data-sidebar-{name}-collapsed` states removed from `admin-shell.yaml` — they were declared but never set in JS. New semantic: `[collapsed]` reflected on `<admin-sidebar>` directly.
+
+- **G2 + G3**: Phantom attrs (`leading-min/max-width`, `[cmd-k]`) removed from `admin-shell.examples.html` behavior-wiring table.
+
+### Backwards compatibility
+
+Legacy authoring shapes (`<aside data-sidebar="leading">`, `<dialog data-command>`, `<div data-resize>`, `[data-sidebar-toggle]`, `<aside-ui slot="leading">`) all still work identically. Mixed markup (some bespoke, some legacy) renders the same. Migration is opt-in.
+
 ## [0.3.3] - 2026-05-07
 
 **Lockstep cut.** All 9 published `@adia-ai/*` packages now share version `0.3.3`, governed by [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy).

package/chat/chat-composer/chat-composer.a2ui.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ChatComposer.json",
+  "title": "ChatComposer",
+  "description": "Module-tier chat composer wrapper — replaces legacy <chat-input-ui\ndata-chat-input> direct child of <chat-shell> per ADR-0023.\nForwards submit events as 'composer-submit', propagates [disabled]\nto the inner input, provides slot vocabulary for future composer\nsurfaces (file attach, autocomplete, model picker).\n\nSits inside <chat-shell> as the input region (typically inside or\nalongside the footer). Authors place an inner <chat-input-ui>\n(or input-ui / textarea-ui) as the primary input.\n\nBackwards compat — <chat-shell> still recognizes the legacy\n<chat-input-ui data-chat-input> shape via :is() selector. New\ncode should prefer <chat-composer>.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "ChatComposer"
+    },
+    "disabled": {
+      "description": "Reflected — set by the host while streaming, or by application\ncode. Propagated to the inner input element automatically.\n",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "input",
+    "events": {
+      "composer-submit": {
+        "description": "Bubbles when the inner input fires its 'submit' event. Detail mirrors the inner event's detail (typically text + model).",
+        "detail": {
+          "model": "string",
+          "text": "string"
+        }
+      }
+    },
+    "examples": [],
+    "keywords": [
+      "chat-composer",
+      "chat-input",
+      "composer",
+      "message-input",
+      "conversation-input"
+    ],
+    "name": "ChatComposer",
+    "related": [
+      "ChatShell",
+      "ChatThread",
+      "ChatInput",
+      "Input",
+      "Textarea"
+    ],
+    "slots": {
+      "default": {
+        "description": "Default — primary input child (typically <chat-input-ui> or <input-ui submit-on-enter>)."
+      },
+      "attach": {
+        "description": "Future — attachment trigger button (paperclip icon to upload)."
+      },
+      "leading": {
+        "description": "Leading controls — autocomplete trigger, voice input, etc."
+      },
+      "trailing": {
+        "description": "Trailing controls — model picker, send button override, etc."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, accepting input.",
+        "name": "idle"
+      },
+      {
+        "description": "Input is disabled (typically during LLM streaming).",
+        "attribute": "disabled",
+        "name": "disabled"
+      }
+    ],
+    "synonyms": {
+      "composer": [
+        "message-input",
+        "chat-input",
+        "conversation-input"
+      ]
+    },
+    "tag": "chat-composer",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/chat/chat-composer/chat-composer.examples.html

@@ -0,0 +1,28 @@
+<header>
+    <div>
+      <h1>Chat Composer</h1>
+      <div data-actions>
+        <tag-ui size="sm">chat-composer</tag-ui>
+        <tag-ui size="sm" variant="ghost">JS-bearing</tag-ui>
+      </div>
+    </div>
+    <p>Module-tier chat composer wrapper — forwards submit events, propagates [disabled], slot vocabulary for future composer surfaces.</p>
+  </header>
+
+<section data-section>
+  <h2 variant="section">Role</h2>
+  <p>Forwards inner submit events as <code>composer-submit</code>, propagates <code>[disabled]</code> to the inner input, slot vocabulary for future composer surfaces (file attach, autocomplete trigger, model picker). JS-bearing.</p>
+</section>
+
+<section data-section>
+  <h2 variant="section">Composition</h2>
+  <p>Typical placement inside <code>&lt;chat-shell&gt;</code>:</p>
+  <code-ui language="html">&lt;chat-composer&gt;
+  &lt;chat-input-ui placeholder="Message…" submit-on-enter&gt;&lt;/chat-input-ui&gt;
+&lt;/chat-composer&gt;</code-ui>
+</section>
+
+<section data-section>
+  <h2 variant="section">Family</h2>
+  <p>Per <a href="../../../../.brain/adrs/0023-bespoke-shell-tier-children.md">ADR-0023</a>, the chat cluster's bespoke family — <code>&lt;chat-shell&gt;</code> (host), <code>&lt;chat-thread&gt;</code>, <code>&lt;chat-composer&gt;</code>, <code>&lt;chat-sidebar&gt;</code> (JS-bearing) + <code>&lt;chat-header&gt;</code>, <code>&lt;chat-status&gt;</code>, <code>&lt;chat-empty&gt;</code> (CSS-only). Mirrors the admin cluster's pattern.</p>
+</section>

package/chat/chat-composer/chat-composer.html

@@ -0,0 +1,43 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Chat Composer — AdiaUI</title>
+
+  <link rel="stylesheet" href="../../../web-components/styles/resets.css">
+  <link rel="stylesheet" href="../../../web-components/styles/tokens.css">
+  <link rel="stylesheet" href="../chat-shell/chat-shell.css">
+  <link rel="stylesheet" href="../../../web-components/components/code/code.css">
+  <link rel="stylesheet" href="../../../web-components/components/tag/tag.css">
+
+  <script type="module" src="../chat-shell/chat-shell.js"></script>
+  <script type="module" src="./chat-composer.js"></script>
+  <script type="module" src="../../../web-components/components/code/code.js"></script>
+  <script type="module" src="../../../web-components/components/tag/tag.js"></script>
+
+  <style>
+    :where(html, body) { margin: 0; min-height: 100vh; background: var(--a-bg); color: var(--a-fg); font-family: var(--a-font); }
+    main { max-width: 960px; margin-inline: auto; padding: var(--a-space-6) var(--a-space-5); }
+  </style>
+</head>
+<body>
+
+  <main id="demo-root">
+    <p>Loading examples…</p>
+  </main>
+
+  <script type="module">
+    const root = document.getElementById('demo-root');
+    try {
+      const res = await fetch('./chat-composer.examples.html');
+      if (!res.ok) throw new Error(`fetch failed (${res.status})`);
+      root.innerHTML = await res.text();
+    } catch (err) {
+      root.innerHTML = `<p style="color:var(--a-danger-strong);">Failed to load chat-composer.examples.html — ${err.message}</p>`;
+      console.error('[chat-composer.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/chat/chat-composer/chat-composer.js

@@ -0,0 +1,107 @@
+/**
+ * <chat-composer disabled?>
+ *   <chat-input-ui placeholder="..." submit-on-enter></chat-input-ui>
+ *   <!-- future: <button-ui slot="attach" icon="paperclip">  -->
+ * </chat-composer>
+ *
+ * Module-tier chat composer wrapper — replaces legacy
+ * <chat-input-ui data-chat-input> direct child of <chat-shell>
+ * per ADR-0023. Owns:
+ *
+ *   - Forward submit events from inner <chat-input-ui> as
+ *     'composer-submit' (so the host doesn't reach inside)
+ *   - [disabled] reflected attribute, propagated to inner input
+ *   - Slot vocabulary for future composer surfaces (file attach,
+ *     autocomplete trigger, model picker, etc.)
+ *   - Focus delegation — .focus() / .clear() proxy to inner input
+ *
+ * Reflected attributes:
+ *   [disabled]  — set by host while streaming; propagated to
+ *                 inner <chat-input-ui>
+ *
+ * Public methods:
+ *   .focus()      — focus inner input
+ *   .clear()      — clear inner input value
+ *   .input()      — getter: returns inner <chat-input-ui> reference
+ *
+ * Events forwarded from inner input:
+ *   composer-submit  — bubbles. detail: { text, model }
+ *
+ * The host (<chat-shell>) reads either <chat-composer> or
+ * [data-chat-input] / <chat-input-ui> via :is() selector for
+ * backwards compat.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+class ChatComposer extends UIElement {
+  static properties = {
+    disabled: { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  #inputEl = null;
+  #onSubmit = null;
+
+  connected() {
+    this.#inputEl = this.querySelector('chat-input-ui') || this.querySelector('input-ui') || this.querySelector('textarea-ui');
+
+    this.#onSubmit = (e) => {
+      // Re-emit as 'composer-submit' so host listens to one event
+      // regardless of which inner input it is
+      this.dispatchEvent(new CustomEvent('composer-submit', {
+        bubbles: true,
+        detail: e.detail || {},
+      }));
+    };
+    this.#inputEl?.addEventListener('submit', this.#onSubmit);
+
+    // Sync initial disabled state to inner input
+    this.#syncDisabled();
+  }
+
+  disconnected() {
+    if (this.#inputEl && this.#onSubmit) {
+      this.#inputEl.removeEventListener('submit', this.#onSubmit);
+    }
+    this.#inputEl = null;
+    this.#onSubmit = null;
+  }
+
+  // Reflected attribute change — propagate to inner input
+  attributeChangedCallback(name, oldVal, newVal) {
+    super.attributeChangedCallback?.(name, oldVal, newVal);
+    if (name === 'disabled') {
+      this.#syncDisabled();
+    }
+  }
+
+  // ── Public API ──
+
+  focus() {
+    this.#inputEl?.focus?.();
+  }
+
+  clear() {
+    this.#inputEl?.clear?.();
+  }
+
+  get input() {
+    return this.#inputEl;
+  }
+
+  // ── Internal ──
+
+  #syncDisabled() {
+    if (!this.#inputEl) return;
+    if (this.disabled) {
+      this.#inputEl.setAttribute('disabled', '');
+    } else {
+      this.#inputEl.removeAttribute('disabled');
+    }
+  }
+}
+
+customElements.define('chat-composer', ChatComposer);
+export { ChatComposer };

package/chat/chat-composer/chat-composer.test.js

@@ -0,0 +1,112 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import '../../../web-components/core/element.js';
+import './chat-composer.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('chat-composer', () => {
+  it('registers chat-composer as a custom element', () => {
+    expect(customElements.get('chat-composer')).toBeDefined();
+  });
+
+  it('defaults to disabled=false', () => {
+    const c = mount('<chat-composer></chat-composer>');
+    expect(c.disabled).toBe(false);
+  });
+
+  it('reflects [disabled] via property assignment', async () => {
+    const c = mount('<chat-composer></chat-composer>');
+    c.disabled = true;
+    await tick();
+    expect(c.hasAttribute('disabled')).toBe(true);
+  });
+
+  it('exposes .focus() / .clear() / .input getter', () => {
+    const c = mount('<chat-composer></chat-composer>');
+    expect(typeof c.focus).toBe('function');
+    expect(typeof c.clear).toBe('function');
+    expect('input' in c).toBe(true);
+  });
+
+  it('returns null .input when no inner input element', () => {
+    const c = mount('<chat-composer></chat-composer>');
+    expect(c.input).toBeNull();
+  });
+
+  it('forwards inner submit as composer-submit event', async () => {
+    // Plain input-like element with submit dispatch
+    const wrap = document.createElement('div');
+    wrap.innerHTML = `<chat-composer>
+      <chat-input-ui></chat-input-ui>
+    </chat-composer>`;
+    document.body.appendChild(wrap);
+    const composer = wrap.firstElementChild;
+    const innerInput = composer.querySelector('chat-input-ui');
+
+    const onComposerSubmit = vi.fn();
+    composer.addEventListener('composer-submit', onComposerSubmit);
+
+    innerInput.dispatchEvent(new CustomEvent('submit', { detail: { text: 'hello' } }));
+    await tick();
+
+    expect(onComposerSubmit).toHaveBeenCalledTimes(1);
+    expect(onComposerSubmit.mock.calls[0][0].detail).toEqual({ text: 'hello' });
+  });
+
+  it('propagates [disabled] to inner input via attribute', async () => {
+    const wrap = document.createElement('div');
+    wrap.innerHTML = `<chat-composer>
+      <chat-input-ui></chat-input-ui>
+    </chat-composer>`;
+    document.body.appendChild(wrap);
+    const composer = wrap.firstElementChild;
+    const innerInput = composer.querySelector('chat-input-ui');
+
+    composer.disabled = true;
+    await tick();
+
+    expect(innerInput.hasAttribute('disabled')).toBe(true);
+
+    composer.disabled = false;
+    await tick();
+
+    expect(innerInput.hasAttribute('disabled')).toBe(false);
+  });
+
+  it('cleanup on disconnect — removes inner submit listener', () => {
+    const wrap = document.createElement('div');
+    wrap.innerHTML = `<chat-composer>
+      <chat-input-ui></chat-input-ui>
+    </chat-composer>`;
+    document.body.appendChild(wrap);
+    const composer = wrap.firstElementChild;
+    const innerInput = composer.querySelector('chat-input-ui');
+    const removeSpy = vi.spyOn(innerInput, 'removeEventListener');
+
+    composer.remove();
+
+    const removedTypes = removeSpy.mock.calls.map((args) => args[0]);
+    expect(removedTypes).toContain('submit');
+  });
+
+  it('handles input-ui as inner input fallback', () => {
+    const wrap = document.createElement('div');
+    wrap.innerHTML = `<chat-composer>
+      <input-ui></input-ui>
+    </chat-composer>`;
+    document.body.appendChild(wrap);
+    const composer = wrap.firstElementChild;
+    expect(composer.input?.tagName?.toLowerCase()).toBe('input-ui');
+  });
+});

package/chat/chat-composer/chat-composer.yaml

@@ -0,0 +1,91 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: ChatComposer
+tag: chat-composer
+component: ChatComposer
+category: input
+version: 1
+description: |
+  Module-tier chat composer wrapper — replaces legacy <chat-input-ui
+  data-chat-input> direct child of <chat-shell> per ADR-0023.
+  Forwards submit events as 'composer-submit', propagates [disabled]
+  to the inner input, provides slot vocabulary for future composer
+  surfaces (file attach, autocomplete, model picker).
+
+  Sits inside <chat-shell> as the input region (typically inside or
+  alongside the footer). Authors place an inner <chat-input-ui>
+  (or input-ui / textarea-ui) as the primary input.
+
+  Backwards compat — <chat-shell> still recognizes the legacy
+  <chat-input-ui data-chat-input> shape via :is() selector. New
+  code should prefer <chat-composer>.
+
+props:
+  disabled:
+    description: |
+      Reflected — set by the host while streaming, or by application
+      code. Propagated to the inner input element automatically.
+    type: boolean
+    default: false
+    reflect: true
+
+events:
+  composer-submit:
+    description: >-
+      Bubbles when the inner input fires its 'submit' event.
+      Detail mirrors the inner event's detail (typically text + model).
+    detail:
+      text: string
+      model: string
+
+slots:
+  default:
+    description: >-
+      Default — primary input child (typically <chat-input-ui> or
+      <input-ui submit-on-enter>).
+  attach:
+    description: >-
+      Future — attachment trigger button (paperclip icon to upload).
+  trailing:
+    description: >-
+      Trailing controls — model picker, send button override, etc.
+  leading:
+    description: >-
+      Leading controls — autocomplete trigger, voice input, etc.
+
+states:
+  - name: idle
+    description: Default, accepting input.
+  - name: disabled
+    attribute: disabled
+    description: Input is disabled (typically during LLM streaming).
+
+traits: []
+
+a2ui:
+  rules:
+    - >-
+      chat-composer is the bespoke replacement for legacy
+      <chat-input-ui data-chat-input> inside <chat-shell>. Place an
+      inner <chat-input-ui submit-on-enter> as the primary input.
+    - >-
+      The host listens for 'composer-submit' on the composer (not on
+      the inner input). The event detail mirrors the inner submit
+      event so existing handlers Just Work.
+
+keywords:
+  - chat-composer
+  - chat-input
+  - composer
+  - message-input
+  - conversation-input
+
+synonyms:
+  composer: [message-input, chat-input, conversation-input]
+
+related:
+  - ChatShell
+  - ChatThread
+  - ChatInput
+  - Input
+  - Textarea

package/chat/chat-empty/chat-empty.a2ui.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ChatEmpty.json",
+  "title": "ChatEmpty",
+  "description": "Module-tier chat empty state. CSS-only — no behavior, no JS. Sits\nas the first child of <chat-thread> as the empty state placeholder.\nVisibility is driven by <chat-thread>'s [empty] reflected attribute\nvia CSS (no JS toggling needed) — when messages arrive, the parent\nthread loses [empty] and CSS hides this stub.\n\nReplaces the legacy <empty-state-ui data-chat-empty> child of the\nmessages container per ADR-0023. Both shapes still work via\nbackwards compat; new code should prefer <chat-empty>.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "ChatEmpty"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "feedback",
+    "events": {},
+    "examples": [],
+    "keywords": [
+      "chat-empty",
+      "empty-state",
+      "placeholder",
+      "no-messages"
+    ],
+    "name": "ChatEmpty",
+    "related": [
+      "ChatShell",
+      "ChatThread",
+      "EmptyState"
+    ],
+    "slots": {
+      "default": {
+        "description": "Empty state content — typically an icon + heading + description. Authors compose with <empty-state-ui> as a child, or supply inline content directly."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, visible.",
+        "name": "idle"
+      },
+      {
+        "description": "Hidden via parent <chat-thread>:not([empty]) selector.",
+        "name": "hidden"
+      }
+    ],
+    "synonyms": {
+      "chat-empty": [
+        "empty-state",
+        "placeholder",
+        "no-conversations"
+      ]
+    },
+    "tag": "chat-empty",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/chat/chat-empty/chat-empty.examples.html

@@ -0,0 +1,34 @@
+<header>
+    <div>
+      <h1>Chat Empty</h1>
+      <div data-actions>
+        <tag-ui size="sm">chat-empty</tag-ui>
+        <tag-ui size="sm" variant="ghost">CSS-only</tag-ui>
+      </div>
+    </div>
+    <p>Module-tier chat empty state. CSS-only. Visibility driven by parent <chat-thread>'s [empty] reflected attribute.</p>
+  </header>
+
+<section data-section>
+  <h2 variant="section">Role</h2>
+  <p>Empty state placeholder. CSS-only. Visibility driven automatically by parent <code>&lt;chat-thread&gt;</code>'s <code>[empty]</code> reflected attribute — no JS toggling needed.</p>
+</section>
+
+<section data-section>
+  <h2 variant="section">Composition</h2>
+  <p>Typical placement inside <code>&lt;chat-shell&gt;</code>:</p>
+  <code-ui language="html">&lt;chat-thread&gt;
+  &lt;chat-empty&gt;
+    &lt;empty-state-ui
+      icon="chat-circle"
+      heading="Hello!"
+      description="Ask me anything."&gt;&lt;/empty-state-ui&gt;
+  &lt;/chat-empty&gt;
+  &lt;!-- Messages get appended here; chat-empty auto-hides --&gt;
+&lt;/chat-thread&gt;</code-ui>
+</section>
+
+<section data-section>
+  <h2 variant="section">Family</h2>
+  <p>Per <a href="../../../../.brain/adrs/0023-bespoke-shell-tier-children.md">ADR-0023</a>, the chat cluster's bespoke family — <code>&lt;chat-shell&gt;</code> (host), <code>&lt;chat-thread&gt;</code>, <code>&lt;chat-composer&gt;</code>, <code>&lt;chat-sidebar&gt;</code> (JS-bearing) + <code>&lt;chat-header&gt;</code>, <code>&lt;chat-status&gt;</code>, <code>&lt;chat-empty&gt;</code> (CSS-only). Mirrors the admin cluster's pattern.</p>
+</section>