@adia-ai/web-modules 0.7.9 → 0.7.11

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

@@ -0,0 +1,92 @@
+/**
+ * <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).
+ *
+ * Extends UIElement (the shell base) so the declarative trait pattern works:
+ * `<embed-shell traits="resizable">` applies the real `resizable` trait (drag any
+ * edge to resize + a `resize-end` event), not a CSS stand-in. The trait is imported
+ * here so it's registered for declarative lookup.
+ */
+import { UIElement } from '../../../web-components/core/element.js';
+import '../../../web-components/traits/resizable/resizable.js'; // register `resizable` for traits="resizable"
+
+class EmbedShell extends UIElement {
+  static template = () => null; // behavior-only, light-DOM — keep the consumer's children
+
+  connected() {
+    this.addEventListener('click', this.#onClick);
+    this.addEventListener('embed:open', this.#onEmbedOpen);
+    this.addEventListener('keydown', this.#onKeydown);
+  }
+
+  // Stable #field arrows — connect/reconnect re-adds are idempotent (the browser
+  // dedups identical listeners), satisfying the trait system's symmetric-lifecycle rule.
+  #onClick = (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();
+  };
+  #onEmbedOpen = (e) => this.toggle(e.detail?.panel);
+  #onKeydown = (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.test.js

@@ -0,0 +1,127 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import './embed-shell.js'; // registers <embed-shell>
+
+// A minimal consumer shape: one [app] surface with two [opens] triggers, plus
+// two named [panel] surfaces (one carrying a [close] trigger). The shell owns
+// layout, not content — divs stand in for the real consumer surfaces.
+function mount() {
+  document.body.innerHTML = `
+    <embed-shell>
+      <div app>
+        <button id="open-chat" opens="chat">chat</button>
+        <button id="open-settings" opens="settings">settings</button>
+      </div>
+      <div panel="chat"><button id="close" close>x</button></div>
+      <div panel="settings"></div>
+    </embed-shell>`;
+  return document.body.querySelector('embed-shell');
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+// ── open / close / toggle ─────────────────────────────────────────
+describe('embed-shell — open / close / toggle API', () => {
+  it('open(name) reflects [panel] on the shell + sets [active] on the matching surface', () => {
+    const shell = mount();
+    shell.open('chat');
+    expect(shell.getAttribute('panel')).toBe('chat');
+    expect(shell.querySelector('[panel="chat"]').hasAttribute('active')).toBe(true);
+    expect(shell.panel).toBe('chat');
+  });
+
+  it('open(name) switches the active panel — only one [active] at a time', () => {
+    const shell = mount();
+    shell.open('chat');
+    shell.open('settings');
+    expect(shell.getAttribute('panel')).toBe('settings');
+    expect(shell.querySelector('[panel="chat"]').hasAttribute('active')).toBe(false);
+    expect(shell.querySelector('[panel="settings"]').hasAttribute('active')).toBe(true);
+  });
+
+  it('open() with no matching [panel] is a no-op (consumer must provide the surface)', () => {
+    const shell = mount();
+    shell.open('nope');
+    expect(shell.hasAttribute('panel')).toBe(false);
+  });
+
+  it('open() ignores an empty name', () => {
+    const shell = mount();
+    shell.open('');
+    expect(shell.hasAttribute('panel')).toBe(false);
+  });
+
+  it('close() clears [panel] + [active]; .panel reads ""', () => {
+    const shell = mount();
+    shell.open('chat');
+    shell.close();
+    expect(shell.hasAttribute('panel')).toBe(false);
+    expect(shell.querySelector('[panel="chat"]').hasAttribute('active')).toBe(false);
+    expect(shell.panel).toBe('');
+  });
+
+  it('toggle() opens when closed, closes when the same panel is already open', () => {
+    const shell = mount();
+    shell.toggle('chat');
+    expect(shell.panel).toBe('chat');
+    shell.toggle('chat');
+    expect(shell.panel).toBe('');
+  });
+
+  it('emits embed:change with the new panel name on open, "" on close', () => {
+    const shell = mount();
+    const seen = [];
+    shell.addEventListener('embed:change', (e) => seen.push(e.detail.panel));
+    shell.open('chat');
+    shell.close();
+    expect(seen).toEqual(['chat', '']);
+  });
+});
+
+// ── delegated triggers + inbound events ───────────────────────────
+describe('embed-shell — delegated triggers + events', () => {
+  it('[opens] click toggles the named panel', () => {
+    const shell = mount();
+    shell.querySelector('#open-chat').click();
+    expect(shell.panel).toBe('chat');
+    shell.querySelector('#open-chat').click(); // same trigger toggles it back off
+    expect(shell.panel).toBe('');
+  });
+
+  it('[opens] switches directly between panels', () => {
+    const shell = mount();
+    shell.querySelector('#open-chat').click();
+    shell.querySelector('#open-settings').click();
+    expect(shell.panel).toBe('settings');
+  });
+
+  it('[close] click dismisses the open panel', () => {
+    const shell = mount();
+    shell.open('chat');
+    shell.querySelector('#close').click();
+    expect(shell.panel).toBe('');
+  });
+
+  it('embed:open event opens/toggles a panel', () => {
+    const shell = mount();
+    shell.querySelector('[app]').dispatchEvent(
+      new CustomEvent('embed:open', { detail: { panel: 'settings' }, bubbles: true }),
+    );
+    expect(shell.panel).toBe('settings');
+  });
+
+  it('Escape closes the open panel', () => {
+    const shell = mount();
+    shell.open('chat');
+    shell.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    expect(shell.panel).toBe('');
+  });
+
+  it('Escape is a no-op when no panel is open', () => {
+    const shell = mount();
+    // Should not throw; panel stays closed.
+    shell.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    expect(shell.panel).toBe('');
+  });
+});

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';