@adia-ai/web-modules 0.7.8 → 0.7.10

package/shell/embed-shell/embed-shell.js

@@ -0,0 +1,80 @@
+/**
+ * <embed-shell> — embedded multi-surface shell.
+ *
+ * Composes a primary `[app]` surface with secondary `[panel="<name>"]` surfaces
+ * the consumer provides, and arranges them responsively. Peer of admin-shell /
+ * editor-shell / chat-shell. Light-DOM (P1). Content-agnostic: it orchestrates
+ * whatever `[app]` + `[panel]` children it's given — it owns layout, not content.
+ *
+ * Contract (clean attributes — ADR-0024, no data-*):
+ *   <embed-shell>
+ *     <x app>…</x>                      ← the primary surface (one)
+ *     <y panel="chat">…</y>             ← a secondary surface (any number)
+ *     <z panel="settings">…</z>
+ *   </embed-shell>
+ *   …anywhere inside: <button opens="chat">  ← trigger (delegated)
+ *                     <button close>          ← dismiss the open panel
+ *
+ * State (reflected, ADR-0023):
+ *   embed-shell[panel="chat"]            ← which panel is open ('' / absent = none)
+ *   <y panel="chat" active>              ← the open panel carries [active] (CSS hook)
+ *
+ * Events:
+ *   embed:open  (in)  detail:{panel}     ← request to open/toggle a panel
+ *   embed:change(out) detail:{panel}     ← emitted after the open panel changes
+ *
+ * Layout lives in embed-shell.css: ≥760px the open panel is a 50/50 column; <760px
+ * it's a cover sheet (translateY — identity at rest, so popovers inside still anchor).
+ */
+class EmbedShell extends HTMLElement {
+  #wired = false;
+
+  connectedCallback() {
+    if (this.#wired) return;
+    this.#wired = true;
+    this.addEventListener('click', (e) => {
+      const opener = e.target.closest?.('[opens]');
+      if (opener && this.contains(opener)) { this.toggle(opener.getAttribute('opens')); return; }
+      const closer = e.target.closest?.('[close]');
+      if (closer && this.contains(closer)) this.close();
+    });
+    this.addEventListener('embed:open', (e) => this.toggle(e.detail?.panel));
+    this.addEventListener('keydown', (e) => {
+      if (e.key === 'Escape' && this.panel) { e.stopPropagation(); this.close(); }
+    });
+  }
+
+  /** the open panel's name, or '' */
+  get panel() { return this.getAttribute('panel') || ''; }
+
+  toggle(name) { return this.panel === name ? this.close() : this.open(name); }
+
+  open(name) {
+    if (!name) return;
+    const el = this.querySelector(`:scope > [panel="${CSS.escape(name)}"]`);
+    if (!el) return; // consumer must provide a matching [panel] surface
+    for (const p of this.querySelectorAll(':scope > [panel][active]')) {
+      if (p !== el) p.removeAttribute('active');
+    }
+    el.setAttribute('active', '');     // CSS show/slide hook
+    this.setAttribute('panel', name);  // reflected state
+    // focus the panel without scrolling the framed surface (preventScroll)
+    requestAnimationFrame(() =>
+      el.querySelector('[autofocus], [close], button-ui, [tabindex]')?.focus?.({ preventScroll: true }));
+    this.#emit(name);
+  }
+
+  close() {
+    if (!this.panel) return;
+    this.querySelector(':scope > [panel][active]')?.removeAttribute('active');
+    this.removeAttribute('panel');
+    this.#emit('');
+  }
+
+  #emit(panel) {
+    this.dispatchEvent(new CustomEvent('embed:change', { detail: { panel }, bubbles: true }));
+  }
+}
+
+customElements.define('embed-shell', EmbedShell);
+export { EmbedShell };

package/shell/embed-shell/embed-shell.yaml

@@ -0,0 +1,74 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: EmbedShell
+tag: embed-shell
+status: draft
+component: AppShell
+category: layout
+version: 1
+description: |
+  Embedded multi-surface shell — composes a primary [app] surface with secondary
+  [panel="<name>"] surfaces the consumer provides, arranging them responsively.
+  Peer of <admin-shell>. Content-agnostic: it orchestrates whatever [app] +
+  [panel] children it is given (it owns layout, not content), so any embedded app
+  supplies its own surfaces.
+
+  >=760px the open panel is an EQUAL 50/50 column beside the app and the frame
+  grows to fit; <760px it is a cover sheet that slides up over the app (identity
+  transform at rest, so popovers inside still anchor). Clean attribute contract
+  (ADR-0024, no data-*): [app], [panel="<name>"], trigger [opens="<name>"],
+  [close]; reflects [panel] on the shell + [active] on the open panel.
+
+props:
+  panel:
+    type: string
+    reflect: true
+    description: |
+      The open panel's name (empty / absent = none). Reflected state. Set it by
+      clicking an [opens="<name>"] trigger, dispatching an `embed:open` event, or
+      calling .open(name) / .close() / .toggle(name).
+
+events:
+  "embed:open":
+    description: Request to open or toggle a panel (consumed by the shell).
+    detail:
+      panel: string
+  "embed:change":
+    description: Fired after the open panel changes.
+    detail:
+      panel: string
+
+slots:
+  default:
+    description: >-
+      Document-order children: one [app] primary surface + any number of
+      [panel="<name>"] secondary surfaces. The shell always shows [app] and reveals
+      the open [panel] (50/50 column >=760px, cover sheet <760px). Triggers
+      ([opens], [close]) may live anywhere inside.
+
+states:
+  - name: idle
+    description: No panel open — the app fills the frame.
+  - name: open
+    description: A panel is open ([panel="<name>"] reflected; the panel carries [active]).
+
+traits:
+  - resizable
+
+a2ui:
+  rules:
+    - >-
+      embed-shell takes exactly one [app] child + any number of [panel="<name>"]
+      children. It owns layout, not content — the consumer supplies the surfaces.
+    - >-
+      Open a panel with an [opens="<name>"] trigger anywhere inside, or an
+      `embed:open` event; dismiss with [close]. Do not toggle visibility manually —
+      the shell reflects [panel] + sets [active] on the open panel.
+    - >-
+      Use clean attributes (ADR-0024) — [app], [panel], [opens], [close] — not the
+      legacy data-* shapes.
+
+keywords: [embed, shell, layout, panel, multi-pane, cover-sheet, app-shell]
+synonyms:
+  embed: [embedded, shell, app-shell, multi-pane]
+  panel: [pane, sheet, drawer]
+related: [AdminShell, Frame, Drawer]

package/shell/index.js

@@ -1,3 +1,4 @@
 export { AdminShell } from './admin-shell/admin-shell.js';
 export { AdminSidebar } from './admin-sidebar/admin-sidebar.js';
 export { AdminCommand } from './admin-command/admin-command.js';
+export { EmbedShell } from './embed-shell/embed-shell.js';