@adia-ai/web-components 0.0.24 → 0.0.25

package/components/app-shell/app-shell.a2ui.json

@@ -0,0 +1,136 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AppShell.json",
+  "title": "AppShell",
+  "description": "Application shell layout. Holds a leading nav rail, a main column\n(topbar + scroll area + statusbar), an optional trailing inspector,\nand an optional command-palette `<dialog>`. The component wires\nsidebar toggle, sidebar resize, and Cmd+K shortcut on top of the\nlong-lived CSS pattern that already targets `app-shell-ui` as a tag.\nChildren use native HTML semantic elements (`<aside data-sidebar>`,\n`<main>`, `<header>`, `<section>`, `<footer>`); the existing\nCSS scopes by tag.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "cmdK": {
+      "description": "Installs a global Cmd+K / Ctrl+K listener that opens the inner\n`<dialog data-command>` via `showModal()`. No-op when no such\ndialog is present.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "AppShell"
+    },
+    "leadingCollapsed": {
+      "description": "Reflects to the leading aside's `[data-collapsed]`. Toggled\nprogrammatically (`shell.toggleLeading()`) or via a click on any\nelement with `[data-sidebar-toggle=\"leading\"]` inside the shell.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "leadingMaxWidth": {
+      "description": "Maximum leading-aside width (px) when resizing.",
+      "type": "number",
+      "default": 480
+    },
+    "leadingMinWidth": {
+      "description": "Minimum leading-aside width (px) when resizing.",
+      "type": "number",
+      "default": 48
+    },
+    "mode": {
+      "description": "Space-separated list of layout modes. `rounded` adds border-radius\nto the scroll section; `borderless` removes chrome borders (content\nborders persist). Pass both for a soft, edgeless shell.\n",
+      "type": "string",
+      "default": ""
+    },
+    "trailingCollapsed": {
+      "description": "Reflects to the trailing aside's `[data-collapsed]`. Toggled via\n`shell.toggleTrailing()` or `[data-sidebar-toggle=\"trailing\"]`.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "trailingMaxWidth": {
+      "description": "Maximum trailing-aside width (px) when resizing.",
+      "type": "number",
+      "default": 480
+    },
+    "trailingMinWidth": {
+      "description": "Minimum trailing-aside width (px) when resizing.",
+      "type": "number",
+      "default": 48
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "container",
+    "events": {
+      "command-close": {
+        "description": "Fired after the command-palette `<dialog>` closes."
+      },
+      "command-open": {
+        "description": "Fired after the command-palette `<dialog>` opens."
+      },
+      "sidebar-toggle": {
+        "description": "Fired after a sidebar's collapsed state flips. Detail:\n`{ side: 'leading'|'trailing', collapsed: boolean }`.\n"
+      }
+    },
+    "examples": [
+      {
+        "description": "Documentation shell — leading nav, topbar with breadcrumb, scroll content, statusbar.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"AppShell\",\n    \"mode\": \"rounded\",\n    \"cmdK\": true,\n    \"children\": [\"leading\", \"main\", \"cmd\"]\n  },\n  {\n    \"id\": \"leading\",\n    \"component\": \"Aside\",\n    \"data-sidebar\": \"leading\",\n    \"children\": [\"nav-hdr\", \"nav-list\", \"nav-ftr\"]\n  },\n  {\n    \"id\": \"nav-hdr\",\n    \"component\": \"Header\",\n    \"children\": []\n  },\n  {\n    \"id\": \"nav-list\",\n    \"component\": \"Section\",\n    \"children\": []\n  },\n  {\n    \"id\": \"nav-ftr\",\n    \"component\": \"Footer\",\n    \"children\": []\n  },\n  {\n    \"id\": \"main\",\n    \"component\": \"Column\",\n    \"children\": [\"topbar\", \"scroll\", \"statusbar\"]\n  },\n  {\n    \"id\": \"topbar\",\n    \"component\": \"Header\",\n    \"children\": []\n  },\n  {\n    \"id\": \"scroll\",\n    \"component\": \"Section\",\n    \"scroll\": true,\n    \"children\": []\n  },\n  {\n    \"id\": \"statusbar\",\n    \"component\": \"Footer\",\n    \"children\": []\n  },\n  {\n    \"id\": \"cmd\",\n    \"component\": \"Modal\",\n    \"data-command\": true,\n    \"children\": []\n  }\n]",
+        "name": "docs-shell"
+      }
+    ],
+    "keywords": [
+      "app-shell",
+      "shell",
+      "layout",
+      "sidebar",
+      "topbar",
+      "command-palette",
+      "cmdK",
+      "dashboard-shell"
+    ],
+    "name": "AdiaAppShell",
+    "related": [
+      "aside",
+      "header",
+      "footer",
+      "section",
+      "drawer",
+      "modal",
+      "command",
+      "app-nav",
+      "section-nav"
+    ],
+    "slots": {
+      "default": {
+        "description": "Composes from native HTML children: `<aside data-sidebar=\"leading\">`,\n`<main>` (with `<header>`, `<section>`, `<footer>` inside),\noptional `<aside data-sidebar=\"trailing\">`, optional\n`<dialog data-command>`. The existing pattern CSS scopes each\nchild by tag + attribute; no `slot=` attributes needed.\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "Leading aside collapsed via attribute / API.",
+        "name": "leading-collapsed"
+      },
+      {
+        "description": "Trailing aside collapsed via attribute / API.",
+        "name": "trailing-collapsed"
+      },
+      {
+        "description": "Command-palette dialog is showing.",
+        "name": "command-open"
+      }
+    ],
+    "synonyms": {},
+    "tag": "app-shell-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/app-shell/app-shell.css

@@ -0,0 +1,16 @@
+/* ═══════════════════════════════════════════════════════════════
+   <app-shell-ui> component CSS
+
+   The substantive CSS lives in `patterns/app-shell/css/*.css` —
+   that surface predates this component and already targets
+   `app-shell-ui` as a tag. We re-import it here so consumers
+   importing this component's CSS get the full styling without
+   duplication. A future cleanup may invert the relationship
+   (move the CSS into this folder and have the pattern import
+   from here, or retire the pattern folder entirely once all
+   consumers have migrated to the component).
+
+   Companion ADR: .brain/adrs/0009-promote-app-shell-and-page-to-components.md
+   ═══════════════════════════════════════════════════════════════ */
+
+@import "../../patterns/app-shell/app-shell.css";

package/components/app-shell/app-shell.js

@@ -0,0 +1,202 @@
+/**
+ * <app-shell-ui> — Application shell layout component.
+ *
+ * Promotes the long-lived `patterns/app-shell/` CSS pattern (which already
+ * targeted `app-shell-ui` as a tag) to a real custom element. CSS continues
+ * to live in `patterns/app-shell/app-shell.css` (re-imported from this
+ * component's CSS); the JS layer adds:
+ *
+ *   - sidebar toggle (delegated [data-sidebar-toggle="leading|trailing"])
+ *   - sidebar resize (pointer drag on [data-resize])
+ *   - command-palette wiring (delegated [data-command-trigger] +
+ *     optional Cmd+K global shortcut when [cmd-k])
+ *
+ * Authoring shape (consumer markup, unchanged from the pre-existing pattern):
+ *
+ *   <app-shell-ui mode="rounded borderless" cmd-k>
+ *     <aside data-sidebar="leading">       <-- nav rail
+ *       <header>...</header>
+ *       <section>...</section>
+ *       <footer>...</footer>
+ *       <div data-resize></div>
+ *     </aside>
+ *     <main>
+ *       <header>...</header>               <-- topbar
+ *       <section>...</section>             <-- scroll area
+ *       <footer>...</footer>               <-- statusbar
+ *     </main>
+ *     <aside data-sidebar="trailing">...</aside>   <!-- optional inspector -->
+ *     <dialog data-command>                <!-- optional cmd palette -->
+ *       <command-ui>...</command-ui>
+ *     </dialog>
+ *   </app-shell-ui>
+ *
+ * Attributes:
+ *   mode                — space-separated list: "rounded" | "borderless" | both.
+ *   leading-collapsed   — boolean, reflects to leading aside's [data-collapsed].
+ *   trailing-collapsed  — boolean, reflects to trailing aside's [data-collapsed].
+ *   cmd-k               — boolean, installs Cmd+K / Ctrl+K global listener
+ *                         that opens the inner <dialog data-command> via
+ *                         showModal(). No-op when no such dialog is present.
+ *   leading-min-width   — minimum width when resizing leading sidebar (px).
+ *   leading-max-width   — maximum width (px).
+ *   trailing-min-width / trailing-max-width — same for trailing.
+ *
+ * API:
+ *   shell.toggleLeading()   shell.toggleTrailing()
+ *   shell.openCommand()     shell.closeCommand()
+ *
+ * Events (bubbling):
+ *   sidebar-toggle  { detail: { side: 'leading'|'trailing', collapsed: boolean } }
+ *   command-open    no detail
+ *   command-close   no detail
+ *
+ * Spec: docs/specs/genui-multiturn-architecture.md (orthogonal — gen-UI uses
+ * this layer). ADR: .brain/adrs/0009-promote-app-shell-and-page-to-components.md.
+ */
+
+import { AdiaElement } from '../../core/element.js';
+
+const DEFAULT_MIN_WIDTH = 48;
+const DEFAULT_MAX_WIDTH = 480;
+
+class AdiaAppShell extends AdiaElement {
+  static properties = {
+    mode:               { type: String,  default: '',    reflect: true },
+    leadingCollapsed:   { type: Boolean, default: false, attribute: 'leading-collapsed',  reflect: true },
+    trailingCollapsed:  { type: Boolean, default: false, attribute: 'trailing-collapsed', reflect: true },
+    cmdK:               { type: Boolean, default: false, attribute: 'cmd-k',              reflect: true },
+    leadingMinWidth:    { type: Number,  default: DEFAULT_MIN_WIDTH, attribute: 'leading-min-width' },
+    leadingMaxWidth:    { type: Number,  default: DEFAULT_MAX_WIDTH, attribute: 'leading-max-width' },
+    trailingMinWidth:   { type: Number,  default: DEFAULT_MIN_WIDTH, attribute: 'trailing-min-width' },
+    trailingMaxWidth:   { type: Number,  default: DEFAULT_MAX_WIDTH, attribute: 'trailing-max-width' },
+  };
+
+  static template = () => null;
+
+  #bound = false;
+  #drag = null; // { aside, startX, startW, side }
+
+  connected() {
+    if (!this.#bound) {
+      this.#bound = true;
+      this.addEventListener('click', this.#onClick);
+      this.addEventListener('pointerdown', this.#onPointerDown);
+    }
+    document.addEventListener('keydown', this.#onKeydown);
+  }
+
+  disconnected() {
+    document.removeEventListener('keydown', this.#onKeydown);
+    document.removeEventListener('pointermove', this.#onResizeMove);
+    document.removeEventListener('pointerup', this.#onResizeUp);
+    this.#drag = null;
+  }
+
+  render() {
+    const leading = this.querySelector(':scope > aside[data-sidebar="leading"]');
+    if (leading) leading.toggleAttribute('data-collapsed', !!this.leadingCollapsed);
+    const trailing = this.querySelector(':scope > aside[data-sidebar="trailing"]');
+    if (trailing) trailing.toggleAttribute('data-collapsed', !!this.trailingCollapsed);
+  }
+
+  // ── API ─────────────────────────────────────────────────────────
+
+  toggleLeading() {
+    this.leadingCollapsed = !this.leadingCollapsed;
+    this.dispatchEvent(new CustomEvent('sidebar-toggle', {
+      bubbles: true,
+      detail: { side: 'leading', collapsed: this.leadingCollapsed },
+    }));
+  }
+
+  toggleTrailing() {
+    this.trailingCollapsed = !this.trailingCollapsed;
+    this.dispatchEvent(new CustomEvent('sidebar-toggle', {
+      bubbles: true,
+      detail: { side: 'trailing', collapsed: this.trailingCollapsed },
+    }));
+  }
+
+  openCommand() {
+    const dialog = this.querySelector(':scope > dialog[data-command]');
+    if (!dialog || dialog.open) return;
+    dialog.showModal();
+    this.dispatchEvent(new CustomEvent('command-open', { bubbles: true }));
+  }
+
+  closeCommand() {
+    const dialog = this.querySelector(':scope > dialog[data-command]');
+    if (!dialog || !dialog.open) return;
+    dialog.close();
+    this.dispatchEvent(new CustomEvent('command-close', { bubbles: true }));
+  }
+
+  // ── Delegated click ─────────────────────────────────────────────
+
+  #onClick = (e) => {
+    const toggle = e.target.closest('[data-sidebar-toggle]');
+    if (toggle && this.contains(toggle)) {
+      const side = toggle.getAttribute('data-sidebar-toggle');
+      if (side === 'leading') { this.toggleLeading(); return; }
+      if (side === 'trailing') { this.toggleTrailing(); return; }
+    }
+    const trigger = e.target.closest('[data-command-trigger]');
+    if (trigger && this.contains(trigger)) {
+      this.openCommand();
+    }
+  };
+
+  // ── Cmd+K / Ctrl+K ──────────────────────────────────────────────
+
+  #onKeydown = (e) => {
+    if (!this.cmdK) return;
+    if ((e.metaKey || e.ctrlKey) && e.key.toLowerCase() === 'k') {
+      e.preventDefault();
+      this.openCommand();
+    }
+  };
+
+  // ── Resize handle ───────────────────────────────────────────────
+  // Pointerdown on a [data-resize] inside one of the asides starts a drag.
+  // Leading aside grows when dragged right; trailing aside grows when
+  // dragged left (mirrors `<pane-ui>[side]` semantics).
+
+  #onPointerDown = (e) => {
+    const handle = e.target.closest('[data-resize]');
+    if (!handle) return;
+    const aside = handle.closest(':scope > aside[data-sidebar]');
+    if (!aside || aside.parentElement !== this) return;
+
+    const side = aside.getAttribute('data-sidebar'); // 'leading' | 'trailing'
+    this.#drag = {
+      aside,
+      side,
+      startX: e.clientX,
+      startW: aside.getBoundingClientRect().width,
+    };
+    handle.setPointerCapture?.(e.pointerId);
+    document.addEventListener('pointermove', this.#onResizeMove);
+    document.addEventListener('pointerup', this.#onResizeUp, { once: true });
+    e.preventDefault();
+  };
+
+  #onResizeMove = (e) => {
+    if (!this.#drag) return;
+    const { aside, side, startX, startW } = this.#drag;
+    const dx = e.clientX - startX;
+    const min = side === 'leading' ? this.leadingMinWidth  : this.trailingMinWidth;
+    const max = side === 'leading' ? this.leadingMaxWidth  : this.trailingMaxWidth;
+    const next = Math.max(min, Math.min(max, startW + (side === 'leading' ? dx : -dx)));
+    aside.style.width = `${next}px`;
+  };
+
+  #onResizeUp = () => {
+    this.#drag = null;
+    document.removeEventListener('pointermove', this.#onResizeMove);
+  };
+}
+
+customElements.define('app-shell-ui', AdiaAppShell);
+
+export { AdiaAppShell };

package/components/app-shell/app-shell.yaml

@@ -0,0 +1,183 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdiaAppShell
+tag: app-shell-ui
+component: AppShell
+category: container
+version: 1
+description: |
+  Application shell layout. Holds a leading nav rail, a main column
+  (topbar + scroll area + statusbar), an optional trailing inspector,
+  and an optional command-palette `<dialog>`. The component wires
+  sidebar toggle, sidebar resize, and Cmd+K shortcut on top of the
+  long-lived CSS pattern that already targets `app-shell-ui` as a tag.
+  Children use native HTML semantic elements (`<aside data-sidebar>`,
+  `<main>`, `<header>`, `<section>`, `<footer>`); the existing
+  CSS scopes by tag.
+props:
+  mode:
+    description: |
+      Space-separated list of layout modes. `rounded` adds border-radius
+      to the scroll section; `borderless` removes chrome borders (content
+      borders persist). Pass both for a soft, edgeless shell.
+    type: string
+    default: ""
+    reflect: true
+  leadingCollapsed:
+    description: |
+      Reflects to the leading aside's `[data-collapsed]`. Toggled
+      programmatically (`shell.toggleLeading()`) or via a click on any
+      element with `[data-sidebar-toggle="leading"]` inside the shell.
+    type: boolean
+    default: false
+    attribute: leading-collapsed
+    reflect: true
+  trailingCollapsed:
+    description: |
+      Reflects to the trailing aside's `[data-collapsed]`. Toggled via
+      `shell.toggleTrailing()` or `[data-sidebar-toggle="trailing"]`.
+    type: boolean
+    default: false
+    attribute: trailing-collapsed
+    reflect: true
+  cmdK:
+    description: |
+      Installs a global Cmd+K / Ctrl+K listener that opens the inner
+      `<dialog data-command>` via `showModal()`. No-op when no such
+      dialog is present.
+    type: boolean
+    default: false
+    attribute: cmd-k
+    reflect: true
+  leadingMinWidth:
+    description: Minimum leading-aside width (px) when resizing.
+    type: number
+    default: 48
+    attribute: leading-min-width
+  leadingMaxWidth:
+    description: Maximum leading-aside width (px) when resizing.
+    type: number
+    default: 480
+    attribute: leading-max-width
+  trailingMinWidth:
+    description: Minimum trailing-aside width (px) when resizing.
+    type: number
+    default: 48
+    attribute: trailing-min-width
+  trailingMaxWidth:
+    description: Maximum trailing-aside width (px) when resizing.
+    type: number
+    default: 480
+    attribute: trailing-max-width
+events:
+  sidebar-toggle:
+    description: |
+      Fired after a sidebar's collapsed state flips. Detail:
+      `{ side: 'leading'|'trailing', collapsed: boolean }`.
+  command-open:
+    description: Fired after the command-palette `<dialog>` opens.
+  command-close:
+    description: Fired after the command-palette `<dialog>` closes.
+slots:
+  default:
+    description: |
+      Composes from native HTML children: `<aside data-sidebar="leading">`,
+      `<main>` (with `<header>`, `<section>`, `<footer>` inside),
+      optional `<aside data-sidebar="trailing">`, optional
+      `<dialog data-command>`. The existing pattern CSS scopes each
+      child by tag + attribute; no `slot=` attributes needed.
+states:
+  - name: idle
+    description: Default, ready for interaction.
+  - name: leading-collapsed
+    description: Leading aside collapsed via attribute / API.
+  - name: trailing-collapsed
+    description: Trailing aside collapsed via attribute / API.
+  - name: command-open
+    description: Command-palette dialog is showing.
+traits: []
+tokens: {}
+a2ui:
+  rules: []
+anti_patterns: []
+examples:
+  - name: docs-shell
+    description: Documentation shell — leading nav, topbar with breadcrumb, scroll content, statusbar.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "AppShell",
+          "mode": "rounded",
+          "cmdK": true,
+          "children": ["leading", "main", "cmd"]
+        },
+        {
+          "id": "leading",
+          "component": "Aside",
+          "data-sidebar": "leading",
+          "children": ["nav-hdr", "nav-list", "nav-ftr"]
+        },
+        {
+          "id": "nav-hdr",
+          "component": "Header",
+          "children": []
+        },
+        {
+          "id": "nav-list",
+          "component": "Section",
+          "children": []
+        },
+        {
+          "id": "nav-ftr",
+          "component": "Footer",
+          "children": []
+        },
+        {
+          "id": "main",
+          "component": "Column",
+          "children": ["topbar", "scroll", "statusbar"]
+        },
+        {
+          "id": "topbar",
+          "component": "Header",
+          "children": []
+        },
+        {
+          "id": "scroll",
+          "component": "Section",
+          "scroll": true,
+          "children": []
+        },
+        {
+          "id": "statusbar",
+          "component": "Footer",
+          "children": []
+        },
+        {
+          "id": "cmd",
+          "component": "Modal",
+          "data-command": true,
+          "children": []
+        }
+      ]
+keywords:
+  - app-shell
+  - shell
+  - layout
+  - sidebar
+  - topbar
+  - command-palette
+  - cmdK
+  - dashboard-shell
+synonyms: {}
+related:
+  - aside
+  - header
+  - footer
+  - section
+  - drawer
+  - modal
+  - command
+  - app-nav
+  - section-nav

package/components/aside/aside.a2ui.json

@@ -0,0 +1,84 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Aside.json",
+  "title": "Aside",
+  "description": "Side region — styled by closest container parent (AppShell / Drawer / Card).\nHolds nav rails, secondary actions, or supplementary content. CSS-only slot\nstub: no own behavior; the container parent reads `[collapsible]` and\n`[width]` to wire collapse + width. For interactive resize / collapse\nbehavior, compose with `<pane-ui>` inside: aside = semantic role,\npane = resizable / collapsible primitive.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "collapsible": {
+      "description": "Marks the aside as collapsible. The container parent (AppShell, Drawer)\nreads this and wires the toggle affordance + ARIA + state. The aside\nitself ships no collapse logic.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "Aside"
+    },
+    "width": {
+      "description": "Token-bound width hint. The container parent reads this to set the\naside column width — `rail` (compact icon-only nav), `panel` (full\nnav text), `wide` (workspace pane). Empty string defers to parent default.\n",
+      "type": "string",
+      "enum": [
+        "",
+        "rail",
+        "panel",
+        "wide"
+      ],
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "container",
+    "events": {},
+    "examples": [
+      {
+        "description": "Card laid out as a header / aside / section, with the aside holding a nav list.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\"hdr\", \"side\", \"main\"]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\"title\"]\n  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Settings\"\n  },\n  {\n    \"id\": \"side\",\n    \"component\": \"Aside\",\n    \"width\": \"rail\",\n    \"children\": [\"nav\"]\n  },\n  {\n    \"id\": \"nav\",\n    \"component\": \"List\",\n    \"children\": []\n  },\n  {\n    \"id\": \"main\",\n    \"component\": \"Section\",\n    \"children\": []\n  }\n]",
+        "name": "card-with-side-nav"
+      }
+    ],
+    "keywords": [
+      "aside",
+      "sidebar",
+      "rail",
+      "panel",
+      "side-region",
+      "nav-rail"
+    ],
+    "name": "AdiaAside",
+    "related": [
+      "app-shell",
+      "drawer",
+      "pane",
+      "section",
+      "header"
+    ],
+    "slots": {
+      "default": {
+        "description": "Default slot — primary child content (typically `<list-ui>`, `<tree-ui>`, or app-nav primitives)."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      }
+    ],
+    "synonyms": {},
+    "tag": "aside-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/aside/aside.yaml

@@ -0,0 +1,100 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdiaAside
+tag: aside-ui
+component: Aside
+category: container
+version: 1
+description: |
+  Side region — styled by closest container parent (AppShell / Drawer / Card).
+  Holds nav rails, secondary actions, or supplementary content. CSS-only slot
+  stub: no own behavior; the container parent reads `[collapsible]` and
+  `[width]` to wire collapse + width. For interactive resize / collapse
+  behavior, compose with `<pane-ui>` inside: aside = semantic role,
+  pane = resizable / collapsible primitive.
+props:
+  collapsible:
+    description: |
+      Marks the aside as collapsible. The container parent (AppShell, Drawer)
+      reads this and wires the toggle affordance + ARIA + state. The aside
+      itself ships no collapse logic.
+    type: boolean
+    default: false
+    reflect: true
+  width:
+    description: |
+      Token-bound width hint. The container parent reads this to set the
+      aside column width — `rail` (compact icon-only nav), `panel` (full
+      nav text), `wide` (workspace pane). Empty string defers to parent default.
+    type: string
+    default: ""
+    enum:
+      - ""
+      - rail
+      - panel
+      - wide
+    reflect: true
+events: {}
+slots:
+  default:
+    description: "Default slot — primary child content (typically `<list-ui>`, `<tree-ui>`, or app-nav primitives)."
+states:
+  - name: idle
+    description: Default, ready for interaction.
+traits: []
+tokens: {}
+a2ui:
+  rules: []
+anti_patterns: []
+examples:
+  - name: card-with-side-nav
+    description: Card laid out as a header / aside / section, with the aside holding a nav list.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Card",
+          "children": ["hdr", "side", "main"]
+        },
+        {
+          "id": "hdr",
+          "component": "Header",
+          "children": ["title"]
+        },
+        {
+          "id": "title",
+          "component": "Text",
+          "slot": "heading",
+          "textContent": "Settings"
+        },
+        {
+          "id": "side",
+          "component": "Aside",
+          "width": "rail",
+          "children": ["nav"]
+        },
+        {
+          "id": "nav",
+          "component": "List",
+          "children": []
+        },
+        {
+          "id": "main",
+          "component": "Section",
+          "children": []
+        }
+      ]
+keywords:
+  - aside
+  - sidebar
+  - rail
+  - panel
+  - side-region
+  - nav-rail
+synonyms: {}
+related:
+  - app-shell
+  - drawer
+  - pane
+  - section
+  - header

package/components/footer/footer.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Footer.json",
   "title": "Footer",
-  "description": "Card footer. Contains actions, pagination, or summary. Typically holds Buttons.",
+  "description": "Footer — styled by closest container parent (Card / Drawer / Modal / Page / AppShell). Contains actions, pagination, or summary. Typically holds Buttons.",
   "type": "object",
   "allOf": [
     {

package/components/footer/footer.yaml

@@ -6,7 +6,7 @@ tag: footer-ui
 component: Footer
 category: container
 version: 1
-description: Card footer. Contains actions, pagination, or summary. Typically holds Buttons.
+description: Footer — styled by closest container parent (Card / Drawer / Modal / Page / AppShell). Contains actions, pagination, or summary. Typically holds Buttons.
 props:
   justify:
     description: Horizontal alignment of children

package/components/header/header.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Header.json",
   "title": "Header",
-  "description": "Card header. Contains heading text and optional action slot.",
+  "description": "Header — styled by closest container parent (Card / Drawer / Modal / Page / AppShell). Contains heading text and optional action slot.",
   "type": "object",
   "allOf": [
     {
@@ -17,7 +17,7 @@
       "const": "Header"
     },
     "padding": {
-      "description": "Bare attribute — enables default header padding. Card's own `padding` prop sets scale.",
+      "description": "Bare attribute — enables default header padding. The container parent's own `padding` prop sets the scale.",
       "type": "boolean",
       "default": false
     }

package/components/header/header.yaml

@@ -6,10 +6,10 @@ tag: header-ui
 component: Header
 category: container
 version: 1
-description: Card header. Contains heading text and optional action slot.
+description: Header — styled by closest container parent (Card / Drawer / Modal / Page / AppShell). Contains heading text and optional action slot.
 props:
   padding:
-    description: Bare attribute — enables default header padding. Card's own `padding` prop sets scale.
+    description: Bare attribute — enables default header padding. The container parent's own `padding` prop sets the scale.
     type: boolean
     default: false
     reflect: true

package/components/index.js

@@ -24,6 +24,8 @@ export { AdiaSegmented } from './segmented/segmented.js';
 export { AdiaRange } from './range/range.js';
 export { AdiaTree, AdiaTreeItem } from './tree/tree.js';
 export { AdiaPane } from './pane/pane.js';
+export { AdiaAppShell } from './app-shell/app-shell.js';
+export { AdiaPage } from './page/page.js';
 export { AdiaChatInput } from './chat/chat-input.js';
 export { AdiaChat } from './chat/chat.js';
 export { AdiaDrawer } from './drawer/drawer.js';

package/components/page/page.a2ui.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Page.json",
+  "title": "Page",
+  "description": "Page container. Holds page-level chrome — header / content / footer —\nand manages max-width clamps, padding scale, optional scroll-container,\nand an optional sticky-header sentinel. Compose with the slot\nprimitives (`<header-ui>`, `<section-ui>`, `<footer-ui>`); the page's\n@scope rules style them. Drop in directly, or nest inside an\n`<app-shell-ui>`'s main column.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "Page"
+    },
+    "maxWidth": {
+      "description": "Token-bound max-width clamp. `prose` (65ch) for reading pages,\n`narrow` (80ch) for tight forms, `wide` (1080px) for data-rich\npages, `full` for unconstrained. Empty defers to parent / 100%.\nCentered horizontally via `margin-inline: auto`.\n",
+      "type": "string",
+      "enum": [
+        "",
+        "prose",
+        "narrow",
+        "wide",
+        "full"
+      ],
+      "default": ""
+    },
+    "padding": {
+      "description": "Page-padding scale from the spacing system. Accepts `0`–`8`\n(mapped to `--a-space-N`). Empty (no value) applies the\n`--page-padding-default` token; `0` removes padding.\n",
+      "type": "string",
+      "default": ""
+    },
+    "scroll": {
+      "description": "Sets the page as a scroll container. `overflow-y: auto`, full\nheight, contained overscroll. Use when the page IS the scroll\nsurface (standalone pages); leave off when nested inside a parent\nthat already manages scroll (e.g. inside an `<app-shell-ui>`'s\nmain `<section>`).\n",
+      "type": "boolean",
+      "default": false
+    },
+    "stickyHeader": {
+      "description": "Installs an IntersectionObserver sentinel before the first\n`<header>` / `<header-ui>` child. When the sentinel scrolls out\nof view the page gains `[data-header-stuck]`, which the CSS\nuses to add a border + shadow to the header. No-op when no\nheader is present.\n",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "container",
+    "events": {},
+    "examples": [
+      {
+        "description": "Reading page with sticky header, 65ch column, padding scale 6.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Page\",\n    \"stickyHeader\": true,\n    \"maxWidth\": \"prose\",\n    \"padding\": \"6\",\n    \"children\": [\"hdr\", \"body\"]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\"title\"]\n  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"variant\": \"display\",\n    \"textContent\": \"Reading Page\"\n  },\n  {\n    \"id\": \"body\",\n    \"component\": \"Section\",\n    \"children\": []\n  }\n]",
+        "name": "prose-page"
+      },
+      {
+        "description": "Wide-clamp dashboard page acting as a scroll container.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Page\",\n    \"scroll\": true,\n    \"maxWidth\": \"wide\",\n    \"padding\": \"4\",\n    \"children\": [\"hdr\", \"body\"]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": []\n  },\n  {\n    \"id\": \"body\",\n    \"component\": \"Section\",\n    \"children\": []\n  }\n]",
+        "name": "dashboard-page"
+      }
+    ],
+    "keywords": [
+      "page",
+      "layout",
+      "container",
+      "scroll",
+      "sticky-header",
+      "max-width",
+      "padding",
+      "prose-page",
+      "dashboard-page"
+    ],
+    "name": "AdiaPage",
+    "related": [
+      "app-shell",
+      "card",
+      "section",
+      "header",
+      "footer"
+    ],
+    "slots": {
+      "default": {
+        "description": "Composes from the slot primitives — `<header-ui>` (page header),\n`<section-ui>` (main content), optional `<footer-ui>`. Native\n`<header>` / `<section>` / `<footer>` also work; the @scope rules\ntarget both via `:where(header, header-ui)`.\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      },
+      {
+        "description": "Header has scrolled past the sentinel; visual cue applied.",
+        "name": "header-stuck"
+      }
+    ],
+    "synonyms": {},
+    "tag": "page-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/page/page.css

@@ -0,0 +1,68 @@
+@scope (page-ui) {
+  :where(:scope) {
+    /* ── Max-width clamps ── */
+    --page-max-width-prose:  65ch;
+    --page-max-width-narrow: 80ch;
+    --page-max-width-wide:   1080px;
+    --page-max-width-full:   100%;
+
+    /* ── Padding default (when [padding] is set without a value) ── */
+    --page-padding-default:  var(--a-space-6);
+
+    /* ── Surfaces ── */
+    --page-bg:               var(--a-canvas-0);
+    --page-fg:               var(--a-fg);
+
+    /* ── Sticky-header chrome (when [data-header-stuck]) ── */
+    --page-sticky-bg:        var(--a-canvas-0);
+    --page-sticky-border:    1px solid var(--a-border-subtle);
+    --page-sticky-shadow:    var(--a-shadow-sm);
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: block;
+    width: 100%;
+    background: var(--page-bg);
+    color: var(--page-fg);
+  }
+
+  /* ── max-width clamps ── */
+  :scope[max-width="prose"]  { max-width: var(--page-max-width-prose);  margin-inline: auto; }
+  :scope[max-width="narrow"] { max-width: var(--page-max-width-narrow); margin-inline: auto; }
+  :scope[max-width="wide"]   { max-width: var(--page-max-width-wide);   margin-inline: auto; }
+  :scope[max-width="full"]   { max-width: var(--page-max-width-full); }
+
+  /* ── Padding scale (mirrors --a-space-N) ── */
+  :scope[padding=""]  { padding: var(--page-padding-default); }
+  :scope[padding="0"] { padding: 0; }
+  :scope[padding="1"] { padding: var(--a-space-1); }
+  :scope[padding="2"] { padding: var(--a-space-2); }
+  :scope[padding="3"] { padding: var(--a-space-3); }
+  :scope[padding="4"] { padding: var(--a-space-4); }
+  :scope[padding="5"] { padding: var(--a-space-5); }
+  :scope[padding="6"] { padding: var(--a-space-6); }
+  :scope[padding="7"] { padding: var(--a-space-7); }
+  :scope[padding="8"] { padding: var(--a-space-8); }
+
+  /* ── Scroll container ── */
+  :scope[scroll] {
+    overflow-y: auto;
+    height: 100%;
+    overscroll-behavior: contain;
+  }
+
+  /* ── Sticky-header support ── */
+  :scope[sticky-header] > :where(header, header-ui) {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    background: var(--page-sticky-bg);
+    transition: border-color 150ms ease, box-shadow 150ms ease;
+  }
+
+  :scope[data-header-stuck] > :where(header, header-ui) {
+    border-block-end: var(--page-sticky-border);
+    box-shadow: var(--page-sticky-shadow);
+  }
+}

package/components/page/page.js

@@ -0,0 +1,88 @@
+/**
+ * <page-ui> — Page container.
+ *
+ * Holds page-level chrome — header / content / footer — and manages
+ * max-width clamps, padding scale, optional scroll-container, and an
+ * optional sticky-header sentinel. Compose with the slot primitives
+ * (`<header-ui>`, `<section-ui>`, `<footer-ui>`); the page's @scope
+ * rules style them.
+ *
+ * Authoring:
+ *   <page-ui sticky-header max-width="prose" padding="6">
+ *     <header-ui>...</header-ui>     <!-- page title + actions -->
+ *     <section-ui>...</section-ui>   <!-- main content -->
+ *     <footer-ui>...</footer-ui>     <!-- optional -->
+ *   </page-ui>
+ *
+ * Attributes:
+ *   scroll          — boolean. Page is the scroll container (overflow-y: auto).
+ *   max-width       — '' | 'prose' (65ch) | 'narrow' (80ch) | 'wide' (1080px) | 'full' (100%).
+ *   padding         — '' | '0'..'8' (mapped to --a-space-N).
+ *   sticky-header   — boolean. Installs IntersectionObserver sentinel before the
+ *                     first <header> / <header-ui> child; sets [data-header-stuck]
+ *                     on the page when the sentinel scrolls out of view.
+ *
+ * ADR: .brain/adrs/0009-promote-app-shell-and-page-to-components.md.
+ */
+
+import { AdiaElement } from '../../core/element.js';
+
+class AdiaPage extends AdiaElement {
+  static properties = {
+    scroll:       { type: Boolean, default: false, reflect: true },
+    maxWidth:     { type: String,  default: '',    attribute: 'max-width', reflect: true },
+    padding:      { type: String,  default: '',    reflect: true },
+    stickyHeader: { type: Boolean, default: false, attribute: 'sticky-header', reflect: true },
+  };
+
+  static template = () => null;
+
+  #sentinel = null;
+  #observer = null;
+
+  connected() {
+    if (this.stickyHeader) this.#installSticky();
+  }
+
+  disconnected() {
+    this.#teardownSticky();
+  }
+
+  render() {
+    // Sticky-header attribute changes between renders → install / tear down.
+    if (this.stickyHeader && !this.#sentinel) this.#installSticky();
+    if (!this.stickyHeader && this.#sentinel) this.#teardownSticky();
+  }
+
+  #installSticky() {
+    const header = this.querySelector(':scope > :is(header, header-ui)');
+    if (!header) return;
+
+    if (!this.#sentinel) {
+      this.#sentinel = document.createElement('div');
+      this.#sentinel.setAttribute('data-page-sentinel', '');
+      this.#sentinel.style.cssText = 'height: 0; width: 0; pointer-events: none;';
+      header.insertAdjacentElement('beforebegin', this.#sentinel);
+    }
+
+    if (!this.#observer) {
+      this.#observer = new IntersectionObserver((entries) => {
+        this.toggleAttribute('data-header-stuck', !entries[0].isIntersecting);
+      }, { threshold: 0 });
+    }
+
+    this.#observer.observe(this.#sentinel);
+  }
+
+  #teardownSticky() {
+    this.#observer?.disconnect();
+    this.#observer = null;
+    this.#sentinel?.remove();
+    this.#sentinel = null;
+    this.removeAttribute('data-header-stuck');
+  }
+}
+
+customElements.define('page-ui', AdiaPage);
+
+export { AdiaPage };

package/components/page/page.yaml

@@ -0,0 +1,148 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdiaPage
+tag: page-ui
+component: Page
+category: container
+version: 1
+description: |
+  Page container. Holds page-level chrome — header / content / footer —
+  and manages max-width clamps, padding scale, optional scroll-container,
+  and an optional sticky-header sentinel. Compose with the slot
+  primitives (`<header-ui>`, `<section-ui>`, `<footer-ui>`); the page's
+  @scope rules style them. Drop in directly, or nest inside an
+  `<app-shell-ui>`'s main column.
+props:
+  scroll:
+    description: |
+      Sets the page as a scroll container. `overflow-y: auto`, full
+      height, contained overscroll. Use when the page IS the scroll
+      surface (standalone pages); leave off when nested inside a parent
+      that already manages scroll (e.g. inside an `<app-shell-ui>`'s
+      main `<section>`).
+    type: boolean
+    default: false
+    reflect: true
+  maxWidth:
+    description: |
+      Token-bound max-width clamp. `prose` (65ch) for reading pages,
+      `narrow` (80ch) for tight forms, `wide` (1080px) for data-rich
+      pages, `full` for unconstrained. Empty defers to parent / 100%.
+      Centered horizontally via `margin-inline: auto`.
+    type: string
+    default: ""
+    enum:
+      - ""
+      - prose
+      - narrow
+      - wide
+      - full
+    attribute: max-width
+    reflect: true
+  padding:
+    description: |
+      Page-padding scale from the spacing system. Accepts `0`–`8`
+      (mapped to `--a-space-N`). Empty (no value) applies the
+      `--page-padding-default` token; `0` removes padding.
+    type: string
+    default: ""
+    reflect: true
+  stickyHeader:
+    description: |
+      Installs an IntersectionObserver sentinel before the first
+      `<header>` / `<header-ui>` child. When the sentinel scrolls out
+      of view the page gains `[data-header-stuck]`, which the CSS
+      uses to add a border + shadow to the header. No-op when no
+      header is present.
+    type: boolean
+    default: false
+    attribute: sticky-header
+    reflect: true
+events: {}
+slots:
+  default:
+    description: |
+      Composes from the slot primitives — `<header-ui>` (page header),
+      `<section-ui>` (main content), optional `<footer-ui>`. Native
+      `<header>` / `<section>` / `<footer>` also work; the @scope rules
+      target both via `:where(header, header-ui)`.
+states:
+  - name: idle
+    description: Default, ready for interaction.
+  - name: header-stuck
+    description: Header has scrolled past the sentinel; visual cue applied.
+traits: []
+tokens: {}
+a2ui:
+  rules: []
+anti_patterns: []
+examples:
+  - name: prose-page
+    description: Reading page with sticky header, 65ch column, padding scale 6.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Page",
+          "stickyHeader": true,
+          "maxWidth": "prose",
+          "padding": "6",
+          "children": ["hdr", "body"]
+        },
+        {
+          "id": "hdr",
+          "component": "Header",
+          "children": ["title"]
+        },
+        {
+          "id": "title",
+          "component": "Text",
+          "variant": "display",
+          "textContent": "Reading Page"
+        },
+        {
+          "id": "body",
+          "component": "Section",
+          "children": []
+        }
+      ]
+  - name: dashboard-page
+    description: Wide-clamp dashboard page acting as a scroll container.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Page",
+          "scroll": true,
+          "maxWidth": "wide",
+          "padding": "4",
+          "children": ["hdr", "body"]
+        },
+        {
+          "id": "hdr",
+          "component": "Header",
+          "children": []
+        },
+        {
+          "id": "body",
+          "component": "Section",
+          "children": []
+        }
+      ]
+keywords:
+  - page
+  - layout
+  - container
+  - scroll
+  - sticky-header
+  - max-width
+  - padding
+  - prose-page
+  - dashboard-page
+synonyms: {}
+related:
+  - app-shell
+  - card
+  - section
+  - header
+  - footer

package/components/section/section.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/Section.json",
   "title": "Section",
-  "description": "Content section inside a Card. Groups related content between Header and Footer.",
+  "description": "Content section — styled by closest container parent (Card / Drawer / Modal / Page / AppShell). Groups related content between Header and Footer. `[scroll]` only kicks in inside Card / Drawer / Modal — Page and AppShell own their own scroll containers.",
   "type": "object",
   "allOf": [
     {

package/components/section/section.yaml

@@ -6,7 +6,7 @@ tag: section-ui
 component: Section
 category: container
 version: 1
-description: Content section inside a Card. Groups related content between Header and Footer.
+description: Content section — styled by closest container parent (Card / Drawer / Modal / Page / AppShell). Groups related content between Header and Footer. `[scroll]` only kicks in inside Card / Drawer / Modal — Page and AppShell own their own scroll containers.
 props:
   scroll:
     description: Enable overflow scrolling

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-utils.",
   "type": "module",
   "exports": {

package/patterns/app-shell/app-shell.css

@@ -1,6 +1,18 @@
 /* ═══════════════════════════════════════════════════════════════
    App Shell — <app-shell-ui> pattern component CSS
 
+   ⚠ DEPRECATED PATH (2026-04-29): preserved as an alias for one
+   release while consumers migrate. The CSS now lives behind the
+   <app-shell-ui> custom element at
+   packages/web-components/components/app-shell/ and ships via
+   packages/web-components/styles/components.css.
+
+   Migration: drop the explicit <link rel="stylesheet"> to this file —
+   styles/components.css now bundles the same content via the new
+   component.
+
+   Companion ADR: ../../../../.brain/adrs/0009-promote-app-shell-and-page-to-components.md.
+
    Split into constituent parts for maintainability.
    Import order matters: tokens first, then structure, then overrides.
    ═══════════════════════════════════════════════════════════════ */

package/styles/components.css

@@ -26,6 +26,8 @@
 @import "../components/range/range.css";
 @import "../components/tree/tree.css";
 @import "../components/pane/pane.css";
+@import "../components/app-shell/app-shell.css";
+@import "../components/page/page.css";
 @import "../components/chat/chat-input.css";
 @import "../components/chat/chat.css";
 @import "../components/drawer/drawer.css";