@adia-ai/web-modules 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -11,6 +11,70 @@ Built from `@adia-ai/web-components` primitives.
 
 _No pending changes._
 
+## [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).
+
+### Changed
+
+- `version`: `0.3.2` → `0.3.3`.
+- `dependencies["@adia-ai/...]`: `^0.3.0` (patch-cut asymmetry — caret already covers 0.3.x; ranges unchanged).
+
+### No source changes
+
+`@adia-ai/web-modules` source is byte-identical to `0.3.2`. The cut is a version bump + ride-along on the lockstep policy.
+
+## [0.3.2] - 2026-05-06
+
+**9-package lockstep patch cut to v0.3.2.** All lockstep members share
+one version per [`docs/specs/package-architecture.md` § 15](../../../docs/specs/package-architecture.md#15-versioning-policy).
+Internal `@adia-ai/*` dep ranges unchanged at `^0.3.0`.
+
+### No source changes
+
+This package's source is byte-identical to v0.3.1. The cut bumps
+version only.
+
+### Changed
+
+- `version`: `0.3.1` → `0.3.2`.
+
 ## [0.3.1] - 2026-05-06
 
 **9-package lockstep patch cut.** All 9 published `@adia-ai/*` packages bump 0.3.0 → 0.3.1 per [`docs/specs/package-architecture.md` § 15](../../docs/specs/package-architecture.md#15-versioning-policy). Internal `@adia-ai/*` dep ranges remain at `^0.3.0` (covers `0.3.1` under semver — patch-cut asymmetry).

package/chat/chat-shell/chat-shell.examples.html

@@ -0,0 +1,85 @@
+<header>
+    <div>
+      <h1>Chat Shell</h1>
+      <div data-actions>
+        <tag-ui size="sm">chat-shell</tag-ui>
+        <tag-ui size="sm" variant="ghost">module-tier</tag-ui>
+      </div>
+    </div>
+    <p>Behavior-only chat orchestrator (LLM-streaming module). Author supplies the DOM structure via <code>[data-chat-messages]</code>, <code>[data-chat-input]</code>, <code>[data-chat-empty]</code>, <code>[data-chat-status]</code> elements; chat-shell wires message streaming, markdown rendering, code-block upgrades, and an LLM integration path via <code>proxy-url</code> (or via external submit).</p>
+  </header>
+
+<section data-section>
+  <h2 variant="section">Basic shape</h2>
+  <p data-note>Author provides the structural DOM; the shell binds the LLM streaming behavior and renders chunks into the messages container.</p>
+  <code-ui language="html">&lt;chat-shell provider="anthropic" model="claude-sonnet-4-7" proxy-url="/api/llm"&gt;
+  &lt;header&gt;
+    &lt;span slot="heading"&gt;Chat&lt;/span&gt;
+    &lt;span slot="description"&gt;claude-sonnet-4-7&lt;/span&gt;
+  &lt;/header&gt;
+
+  &lt;div data-chat-messages&gt;&lt;/div&gt;
+  &lt;div data-chat-empty&gt;
+    &lt;p&gt;Send a message to start.&lt;/p&gt;
+  &lt;/div&gt;
+
+  &lt;div data-chat-input&gt;
+    &lt;input-ui placeholder="Ask anything..." submit-on-enter&gt;&lt;/input-ui&gt;
+  &lt;/div&gt;
+
+  &lt;div data-chat-status&gt;&lt;/div&gt;
+&lt;/chat-shell&gt;</code-ui>
+</section>
+
+<section data-section>
+  <h2 variant="section">Properties</h2>
+  <table>
+    <thead><tr><th>Prop</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td><code>provider</code></td><td>string</td><td>—</td><td>LLM provider name: <code>anthropic | openai | google | stub</code>.</td></tr>
+      <tr><td><code>model</code></td><td>string</td><td>—</td><td>Model identifier (e.g. <code>claude-sonnet-4-7</code>, <code>gpt-4o</code>, <code>gemini-1.5-pro</code>).</td></tr>
+      <tr><td><code>system</code></td><td>string</td><td>—</td><td>System prompt prepended to conversations.</td></tr>
+      <tr><td><code>proxy-url</code></td><td>string</td><td>—</td><td>API proxy endpoint for LLM calls; enables self-contained chat without external submit handler.</td></tr>
+      <tr><td><code>thinking</code></td><td>boolean</td><td><code>false</code></td><td>Enable Anthropic extended-thinking mode.</td></tr>
+      <tr><td><code>streaming</code></td><td>boolean</td><td>—</td><td>Reflected — set while a response is streaming.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Events</h2>
+  <table>
+    <thead><tr><th>Event</th><th>Detail</th></tr></thead>
+    <tbody>
+      <tr><td><code>submit</code></td><td><code>{ text, model }</code> — fired on user message submit before LLM call begins.</td></tr>
+      <tr><td><code>chunk</code></td><td><code>{ text, role }</code> — fired for each streaming chunk.</td></tr>
+      <tr><td><code>complete</code></td><td><code>{ text }</code> — fired when streaming finishes.</td></tr>
+      <tr><td><code>error</code></td><td><code>{ error }</code> — fired on LLM call failures.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Behavior wiring</h2>
+  <table>
+    <thead><tr><th>Affordance</th><th>Author markup</th><th>What the shell does</th></tr></thead>
+    <tbody>
+      <tr><td>Message stream</td><td><code>[data-chat-messages]</code></td><td>Each LLM chunk appended; markdown rendered; <code>code-ui</code> upgraded for code blocks.</td></tr>
+      <tr><td>Input submit</td><td><code>[data-chat-input]</code> containing an <code>&lt;input-ui&gt;</code></td><td>Listens for input's submit event; calls LLM via <code>proxy-url</code> or fires <code>submit</code> for external handler.</td></tr>
+      <tr><td>Empty state</td><td><code>[data-chat-empty]</code></td><td>Hidden when messages are present; shown when empty.</td></tr>
+      <tr><td>Status indicator</td><td><code>[data-chat-status]</code></td><td>Updated with streaming/idle text.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Family pattern (forward-looking)</h2>
+  <p>Per <a href="../../../../.brain/adrs/0023-bespoke-shell-tier-children.md">ADR-0023</a>, future releases extend the bespoke-children family to the chat cluster. Planned children:</p>
+  <ul data-features>
+    <li><code>&lt;chat-thread&gt;</code> — replaces <code>[data-chat-messages]</code>; owns scroll-to-bottom, virtualization, message render</li>
+    <li><code>&lt;chat-composer&gt;</code> — replaces <code>[data-chat-input]</code>; owns file attach, autocomplete, submit-on-enter</li>
+    <li><code>&lt;chat-message&gt;</code> + <code>&lt;chat-message-list&gt;</code> — message-tier semantic markup</li>
+    <li><code>&lt;chat-sidebar&gt;</code> — conversation history rail (mirrors <code>&lt;admin-sidebar&gt;</code>)</li>
+  </ul>
+  <p data-note>Today's <code>data-*</code> shape is fully supported and will continue to work alongside the bespoke vocabulary when it lands.</p>
+</section>

package/chat/chat-shell/chat-shell.html

@@ -0,0 +1,42 @@
+<!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 Shell — 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.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.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-shell.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-shell.examples.html — ${err.message}</p>`;
+      console.error('[chat-shell.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/editor/editor-shell/editor-shell.examples.html

@@ -0,0 +1,71 @@
+<header>
+    <div>
+      <h1>Editor Shell</h1>
+      <div data-actions>
+        <tag-ui size="sm">editor-shell</tag-ui>
+        <tag-ui size="sm" variant="ghost">module-tier</tag-ui>
+      </div>
+    </div>
+    <p>Behavior-only editor shell module for design-tool layouts. Author provides the structural DOM — header (topbar), <code>[data-editor-body]</code> with pane-ui children (<code>[data-left]</code>, <code>[data-right]</code>), <code>[data-canvas]</code> for the central surface, and a footer (statusbar). editor-shell wires <code>select-ui[data-options]</code> for JSON-parsed option lists.</p>
+  </header>
+
+<section data-section>
+  <h2 variant="section">Basic shape</h2>
+  <p data-note>Author supplies the structural DOM — header, body with pane-ui rails + canvas, footer. The shell binds toolbar select wiring + responsive pane collapse.</p>
+  <code-ui language="html">&lt;editor-shell&gt;
+  &lt;header&gt;
+    &lt;icon-ui slot="icon" name="layers"&gt;&lt;/icon-ui&gt;
+    &lt;span slot="heading"&gt;Untitled.fig&lt;/span&gt;
+    &lt;span slot="description"&gt;1920 × 1080&lt;/span&gt;
+    &lt;button-ui slot="action" variant="ghost"&gt;Share&lt;/button-ui&gt;
+  &lt;/header&gt;
+
+  &lt;div data-editor-body&gt;
+    &lt;pane-ui data-left&gt;…tools panel…&lt;/pane-ui&gt;
+    &lt;div data-canvas&gt;…central canvas…&lt;/div&gt;
+    &lt;pane-ui data-right&gt;…inspector panel…&lt;/pane-ui&gt;
+  &lt;/div&gt;
+
+  &lt;footer&gt;
+    &lt;icon-ui slot="icon" name="zoom-in"&gt;&lt;/icon-ui&gt;
+    &lt;span&gt;100%&lt;/span&gt;
+  &lt;/footer&gt;
+&lt;/editor-shell&gt;</code-ui>
+</section>
+
+<section data-section>
+  <h2 variant="section">Slots</h2>
+  <table>
+    <thead><tr><th>Slot</th><th>Purpose</th></tr></thead>
+    <tbody>
+      <tr><td><code>icon</code></td><td>Leading glyph in <code>&lt;header&gt;</code> or <code>&lt;footer&gt;</code> — status dot, app icon, zoom badge.</td></tr>
+      <tr><td><code>heading</code></td><td>Primary label inside chrome bars.</td></tr>
+      <tr><td><code>description</code></td><td>Secondary metadata (document name, artboard size, zoom level).</td></tr>
+      <tr><td><code>action</code></td><td>Trailing control cluster. First <code>[slot="action"]</code> child pushes itself + siblings to the end.</td></tr>
+      <tr><td><code>action-leading</code></td><td>Leading control cluster (back, undo). Pairs with <code>action</code> for dual-cluster bars.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Behavior wiring</h2>
+  <table>
+    <thead><tr><th>Affordance</th><th>Author markup</th><th>What the shell does</th></tr></thead>
+    <tbody>
+      <tr><td>Editor body</td><td><code>[data-editor-body]</code> wrapping <code>pane-ui[data-left]</code>, <code>[data-canvas]</code>, <code>pane-ui[data-right]</code></td><td>Lays out the canvas + flanking panes; handles responsive collapse.</td></tr>
+      <tr><td>Toolbar selects</td><td><code>select-ui[data-options]</code> with JSON in the attribute</td><td>Parses <code>data-options</code> JSON to populate option lists at connect.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Family pattern (forward-looking)</h2>
+  <p>Per <a href="../../../../.brain/adrs/0023-bespoke-shell-tier-children.md">ADR-0023</a>, future releases extend the bespoke-children family to the editor cluster. Planned children:</p>
+  <ul data-features>
+    <li><code>&lt;editor-canvas&gt;</code> — replaces <code>[data-canvas]</code>; owns zoom/pan, viewport state</li>
+    <li><code>&lt;editor-toolbar&gt;</code> — replaces toolbar headers; owns select-ui wiring</li>
+    <li><code>&lt;editor-inspector&gt;</code> + <code>&lt;editor-tools&gt;</code> — replace <code>pane-ui[data-left/right]</code>; owns pane state attributes</li>
+    <li><code>&lt;editor-statusbar&gt;</code> — zoom level, artboard info</li>
+  </ul>
+  <p data-note>Today's <code>data-*</code> shape is fully supported and will continue to work alongside the bespoke vocabulary when it lands.</p>
+</section>

package/editor/editor-shell/editor-shell.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Editor Shell — AdiaUI</title>
+
+  <link rel="stylesheet" href="../../../web-components/styles/resets.css">
+  <link rel="stylesheet" href="../../../web-components/styles/tokens.css">
+  <link rel="stylesheet" href="./editor-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="./editor-shell.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('./editor-shell.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 editor-shell.examples.html — ${err.message}</p>`;
+      console.error('[editor-shell.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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": {
@@ -46,4 +46,4 @@
     "url": "git+https://github.com/adiahealth/gen-ui-kit.git",
     "directory": "packages/web-modules"
   }
-}
+}

package/shell/admin-command/admin-command.a2ui.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AdminCommand.json",
+  "title": "AdminCommand",
+  "description": "Module-tier command palette wrapper — wraps a native <dialog> and the\ninner <command-ui>. Owns the keyboard shortcut listener, focus\nmanagement, and dismiss handlers. Reflects [open].\n\nSits inside <admin-shell> as a direct child. The host wires\n[data-command-trigger] elements to <admin-command>.show() via lookup.\n\nThis is the bespoke web-component replacement for the legacy\n<dialog data-command> shape. <admin-shell> still recognizes the\nlegacy shape via :is() selector. New code should prefer <admin-command>.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AdminCommand"
+    },
+    "no-shortcut": {
+      "description": "Opts out of the keyboard listener entirely. Use when the host\nwires its own shortcut handling, or when the palette should be\nmouse-only.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "open": {
+      "description": "Reflected — set while the dialog is showing. Synced with both\nprogrammatic .show()/.hide() and native dialog close events\n(esc key, backdrop click).\n",
+      "type": "boolean",
+      "default": false
+    },
+    "shortcut": {
+      "description": "Keyboard shortcut binding. \"cmd+k\" responds only on Mac\n(metaKey); \"ctrl+k\" responds only when ctrlKey; \"both\" (default)\nresponds to either, which is the canonical AdiaUI behavior for\ncross-platform Cmd+K affordance.\n",
+      "type": "string",
+      "enum": [
+        "both",
+        "cmd+k",
+        "ctrl+k"
+      ],
+      "default": "both"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "interaction",
+    "events": {
+      "command-select": {
+        "description": "Forwarded from the inner <command-ui> when an option is chosen. Detail mirrors the inner event's detail.",
+        "detail": {
+          "value": "string"
+        }
+      }
+    },
+    "examples": [],
+    "keywords": [
+      "admin-command",
+      "command-palette",
+      "palette",
+      "cmd-k",
+      "keyboard-shortcut",
+      "quickaction"
+    ],
+    "name": "AdminCommand",
+    "related": [
+      "AdminShell",
+      "AdminSidebar",
+      "Command"
+    ],
+    "slots": {
+      "default": {
+        "description": "Default slot — the inner <command-ui> (and any other content inside the dialog). Authors typically place exactly one <command-ui placeholder=\"…\">."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, palette closed.",
+        "name": "idle"
+      },
+      {
+        "description": "Dialog is showing; first input has focus.",
+        "attribute": "open",
+        "name": "open"
+      }
+    ],
+    "synonyms": {
+      "cmd-k": [
+        "ctrl-k",
+        "command-shortcut"
+      ],
+      "command-palette": [
+        "palette",
+        "quick-action",
+        "omnibox"
+      ]
+    },
+    "tag": "admin-command",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/shell/admin-command/admin-command.examples.html

@@ -0,0 +1,83 @@
+<header>
+    <div>
+      <h1>Admin Command</h1>
+      <div data-actions>
+        <tag-ui size="sm">admin-command</tag-ui>
+      </div>
+    </div>
+    <p>Module-tier command palette wrapper — wraps a native <code>&lt;dialog&gt;</code> and the inner <code>&lt;command-ui&gt;</code>. Owns the keyboard shortcut listener, focus management, and dismiss handlers. Reflects <code>[open]</code>.</p>
+  </header>
+
+<section data-section>
+  <h2 variant="section">Basic shape</h2>
+  <p data-note>Place <code>&lt;admin-command&gt;</code> as a direct child of <code>&lt;admin-shell&gt;</code>. The host wires <code>[data-command-trigger]</code> elements to <code>.show()</code> via lookup; you don't reach across siblings.</p>
+  <code-ui language="html">&lt;admin-shell&gt;
+  …sidebars + content…
+
+  &lt;admin-command&gt;
+    &lt;command-ui placeholder="Search…"&gt;&lt;/command-ui&gt;
+  &lt;/admin-command&gt;
+&lt;/admin-shell&gt;</code-ui>
+</section>
+
+<section data-section>
+  <h2 variant="section">Keyboard shortcut</h2>
+  <table>
+    <thead><tr><th>Value</th><th>Behavior</th></tr></thead>
+    <tbody>
+      <tr><td><code>both</code> (default)</td><td>Responds to Cmd+K (mac) AND Ctrl+K (other platforms) — the AdiaUI cross-platform convention.</td></tr>
+      <tr><td><code>cmd+k</code></td><td>Responds only when <code>metaKey</code> is held.</td></tr>
+      <tr><td><code>ctrl+k</code></td><td>Responds only when <code>ctrlKey</code> is held.</td></tr>
+      <tr><td><code>[no-shortcut]</code></td><td>Disables the keyboard listener entirely. Use when the host wires its own shortcut handling.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">State as attribute</h2>
+  <table>
+    <thead><tr><th>Attribute</th><th>When set</th><th>Use for</th></tr></thead>
+    <tbody>
+      <tr><td><code>open</code></td><td>Dialog is showing</td><td>CSS <code>:has(admin-command[open])</code>; JS <code>.hasAttribute('open')</code>; programmatic round-trip via <code>.toggle()</code></td></tr>
+    </tbody>
+  </table>
+  <p>The <code>[open]</code> attribute is synced both ways — programmatic <code>.show()</code> sets it, native dialog close (esc key, backdrop click) clears it.</p>
+</section>
+
+<section data-section>
+  <h2 variant="section">Public methods</h2>
+  <table>
+    <thead><tr><th>Method</th><th>Effect</th></tr></thead>
+    <tbody>
+      <tr><td><code>.show()</code></td><td>Open via <code>showModal()</code>; focus the inner <code>command-ui</code>; clear its value.</td></tr>
+      <tr><td><code>.hide()</code></td><td>Close the dialog; clear inner palette state.</td></tr>
+      <tr><td><code>.toggle()</code></td><td>Flip open state. Returns the new <code>open</code> value.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Events</h2>
+  <table>
+    <thead><tr><th>Event</th><th>Detail</th></tr></thead>
+    <tbody>
+      <tr><td><code>command-select</code></td><td>Forwarded from the inner <code>command-ui</code> when an option is chosen. Detail mirrors the inner event's detail.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Trigger wiring</h2>
+  <p>Triggers (any element with <code>[data-command-trigger]</code>) live anywhere in the shell — typically a search row in the leading sidebar. The host (<code>&lt;admin-shell&gt;</code>) finds the inner <code>&lt;admin-command&gt;</code> on connect and wires every trigger's click to <code>command.show()</code>.</p>
+  <code-ui language="html">&lt;admin-shell&gt;
+  &lt;admin-sidebar slot="leading"&gt;
+    &lt;nav-ui&gt;
+      &lt;nav-item-ui data-command-trigger icon="magnifying-glass"&gt;Search&lt;/nav-item-ui&gt;
+    &lt;/nav-ui&gt;
+  &lt;/admin-sidebar&gt;
+
+  &lt;admin-command&gt;
+    &lt;command-ui placeholder="Search…"&gt;&lt;/command-ui&gt;
+  &lt;/admin-command&gt;
+&lt;/admin-shell&gt;</code-ui>
+</section>

package/shell/admin-command/admin-command.html

@@ -0,0 +1,42 @@
+<!DOCTYPE html>
+<html lang="en" data-theme="auto">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Admin Command — AdiaUI</title>
+
+  <link rel="stylesheet" href="../../../web-components/styles/resets.css">
+  <link rel="stylesheet" href="../../../web-components/styles/tokens.css">
+  <link rel="stylesheet" href="../admin-shell/admin-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="./admin-command.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('./admin-command.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 admin-command.examples.html — ${err.message}</p>`;
+      console.error('[admin-command.html]', err);
+    }
+  </script>
+
+</body>
+</html>