@adia-ai/web-modules 0.3.3 → 0.3.5

package/shell/admin-command/admin-command.js

@@ -0,0 +1,161 @@
+/**
+ * <admin-command shortcut="cmd+k|ctrl+k|both">
+ *   <command-ui placeholder="Search…"></command-ui>
+ * </admin-command>
+ *
+ * Module-tier command palette — wraps a native <dialog> and the inner
+ * <command-ui>. Owns the keyboard shortcut listener, focus management,
+ * and dismiss handlers. Reflects [open].
+ *
+ * Reflected attributes:
+ *   [open]                       — set while the dialog is showing
+ *
+ * Author-supplied attributes:
+ *   [shortcut="cmd+k"|"ctrl+k"|"both"]
+ *                                — keyboard shortcut. Default "both"
+ *                                  (responds to Cmd+K on Mac and Ctrl+K
+ *                                  on other platforms).
+ *   [no-shortcut]                — opts out of the keyboard listener
+ *                                  entirely. Use when the host wires
+ *                                  its own shortcut handling.
+ *
+ * Public methods:
+ *   .show()      — open the palette (via showModal)
+ *   .hide()      — close
+ *   .toggle()    — flip open state
+ *
+ * Events forwarded from inner <command-ui>:
+ *   command-select  — bubbles. detail: { value, ... }
+ *
+ * Authors composing into <admin-shell> just drop this in as a child;
+ * the host does NOT reach inside. <admin-shell> wires
+ * [data-command-trigger] elements to this.show() via a lookup.
+ *
+ * Backwards compat: <admin-shell> still recognizes the legacy
+ * <dialog data-command> shape and wires the same shortcut. New code
+ * should prefer <admin-command>.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+class AdminCommand extends UIElement {
+  static properties = {
+    open: { type: Boolean, default: false, reflect: true },
+    shortcut: { type: String, default: 'both', reflect: true },
+    noShortcut: { type: Boolean, default: false, reflect: true, attribute: 'no-shortcut' },
+  };
+
+  static template = () => null;
+
+  #keyHandler = null;
+  #cmdEl = null;
+  #dialog = null;
+
+  connected() {
+    // Find or construct the dialog. If author supplies <dialog>, use it.
+    // Otherwise, wrap the slotted content in a fresh <dialog>.
+    this.#dialog = this.querySelector(':scope > dialog');
+    if (!this.#dialog) {
+      this.#dialog = document.createElement('dialog');
+      // Move all children into the dialog
+      while (this.firstChild) this.#dialog.appendChild(this.firstChild);
+      this.appendChild(this.#dialog);
+    }
+    this.#cmdEl = this.querySelector('command-ui');
+
+    this.#wireDialog();
+    this.#wireCommand();
+    if (!this.noShortcut) this.#wireShortcut();
+  }
+
+  disconnected() {
+    if (this.#keyHandler) {
+      document.removeEventListener('keydown', this.#keyHandler);
+      this.#keyHandler = null;
+    }
+  }
+
+  // ── Public API ──
+
+  show() {
+    if (!this.#dialog) return;
+    if (this.#dialog.open) return;
+    this.#dialog.showModal();
+    if (this.#cmdEl) {
+      this.#cmdEl.open = true;
+      this.#cmdEl.value = '';
+      this.#cmdEl.focus();
+    }
+    this.open = true;
+  }
+
+  hide() {
+    if (!this.#dialog) return;
+    if (!this.#dialog.open) return;
+    this.#dialog.close();
+    if (this.#cmdEl) this.#cmdEl.open = false;
+    this.open = false;
+  }
+
+  toggle() {
+    if (this.open) {
+      this.hide();
+    } else {
+      this.show();
+    }
+    return this.open;
+  }
+
+  // ── Wiring ──
+
+  #wireDialog() {
+    if (!this.#dialog) return;
+
+    // Backdrop click closes
+    this.#dialog.addEventListener('click', (e) => {
+      if (e.target === this.#dialog) this.hide();
+    });
+
+    // Native dialog close (esc key, etc.) syncs [open]
+    this.#dialog.addEventListener('close', () => {
+      if (this.#cmdEl) this.#cmdEl.open = false;
+      this.open = false;
+    });
+  }
+
+  #wireCommand() {
+    if (!this.#cmdEl) return;
+
+    this.#cmdEl.addEventListener('dismiss', () => this.hide());
+    this.#cmdEl.addEventListener('select', (e) => {
+      // Forward as command-select; let consumers decide what to do
+      this.dispatchEvent(new CustomEvent('command-select', {
+        bubbles: true,
+        detail: e.detail,
+      }));
+      this.hide();
+    });
+  }
+
+  #wireShortcut() {
+    const matches = (e) => {
+      const isMac = e.metaKey;
+      const isCtrl = e.ctrlKey;
+      if (e.key !== 'k') return false;
+      if (this.shortcut === 'cmd+k') return isMac;
+      if (this.shortcut === 'ctrl+k') return isCtrl;
+      // 'both' (default)
+      return isMac || isCtrl;
+    };
+
+    this.#keyHandler = (e) => {
+      if (!matches(e)) return;
+      e.preventDefault();
+      this.toggle();
+    };
+    document.addEventListener('keydown', this.#keyHandler);
+  }
+}
+
+customElements.define('admin-command', AdminCommand);
+export { AdminCommand };

package/shell/admin-command/admin-command.test.js

@@ -0,0 +1,115 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import '../../../web-components/core/element.js';
+import './admin-command.js';
+
+const tick = () => new Promise((r) => queueMicrotask(r));
+
+function mount(html) {
+  const wrap = document.createElement('div');
+  wrap.innerHTML = html;
+  document.body.appendChild(wrap);
+  return wrap.firstElementChild;
+}
+
+// happy-dom's <dialog> support is partial — showModal/close need to be
+// patched into noops that toggle the .open getter via a flag. The real
+// browser does this natively.
+function patchDialogPolyfill(dialog) {
+  let isOpen = false;
+  Object.defineProperty(dialog, 'open', {
+    get: () => isOpen,
+    set: (v) => { isOpen = !!v; },
+    configurable: true,
+  });
+  dialog.showModal = function () {
+    isOpen = true;
+    this.dispatchEvent(new Event('toggle'));
+  };
+  dialog.close = function () {
+    isOpen = false;
+    this.dispatchEvent(new Event('close'));
+  };
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+describe('admin-command', () => {
+  it('registers admin-command as a custom element', () => {
+    expect(customElements.get('admin-command')).toBeDefined();
+  });
+
+  it('defaults to open=false, shortcut="both"', () => {
+    const cmd = mount('<admin-command></admin-command>');
+    expect(cmd.open).toBe(false);
+    expect(cmd.shortcut).toBe('both');
+  });
+
+  it('exposes .show() / .hide() / .toggle() public methods', () => {
+    const cmd = mount('<admin-command></admin-command>');
+    expect(typeof cmd.show).toBe('function');
+    expect(typeof cmd.hide).toBe('function');
+    expect(typeof cmd.toggle).toBe('function');
+  });
+
+  it('reflects [open] when .show() is called', async () => {
+    const cmd = mount('<admin-command></admin-command>');
+    const dialog = cmd.shadowRoot?.querySelector('dialog') ?? cmd.querySelector('dialog');
+    if (dialog) patchDialogPolyfill(dialog);
+    cmd.show();
+    await tick();
+    expect(cmd.open).toBe(true);
+    expect(cmd.hasAttribute('open')).toBe(true);
+  });
+
+  it('clears [open] when .hide() is called', async () => {
+    const cmd = mount('<admin-command></admin-command>');
+    const dialog = cmd.shadowRoot?.querySelector('dialog') ?? cmd.querySelector('dialog');
+    if (dialog) patchDialogPolyfill(dialog);
+    cmd.show();
+    await tick();
+    cmd.hide();
+    await tick();
+    expect(cmd.open).toBe(false);
+    expect(cmd.hasAttribute('open')).toBe(false);
+  });
+
+  it('toggle() flips open state and returns the new value', async () => {
+    const cmd = mount('<admin-command></admin-command>');
+    const dialog = cmd.shadowRoot?.querySelector('dialog') ?? cmd.querySelector('dialog');
+    if (dialog) patchDialogPolyfill(dialog);
+    const after1 = cmd.toggle();
+    await tick();
+    expect(after1).toBe(true);
+    const after2 = cmd.toggle();
+    await tick();
+    expect(after2).toBe(false);
+  });
+
+  it('removes Cmd+K listener on disconnect', () => {
+    const cmd = mount('<admin-command></admin-command>');
+    const removeSpy = vi.spyOn(document, 'removeEventListener');
+    cmd.remove();
+    const removedTypes = removeSpy.mock.calls.map((args) => args[0]);
+    expect(removedTypes).toContain('keydown');
+  });
+
+  it('honors [no-shortcut] — does not toggle on Cmd+K', async () => {
+    // Verify behavior, not listener registration (happy-dom timing makes
+    // spy-based tests unreliable for synchronous custom-element lifecycle).
+    const cmd = mount('<admin-command no-shortcut></admin-command>');
+    const dialog = cmd.querySelector(':scope > dialog');
+    if (dialog) patchDialogPolyfill(dialog);
+    const event = new KeyboardEvent('keydown', { key: 'k', metaKey: true });
+    document.dispatchEvent(event);
+    await tick();
+    expect(cmd.open).toBe(false);
+    cmd.remove();
+  });
+
+  it('accepts shortcut="cmd+k"', () => {
+    const cmd = mount('<admin-command shortcut="cmd+k"></admin-command>');
+    expect(cmd.shortcut).toBe('cmd+k');
+  });
+});

package/shell/admin-command/admin-command.yaml

@@ -0,0 +1,102 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdminCommand
+tag: admin-command
+component: AdminCommand
+category: interaction
+version: 1
+description: |
+  Module-tier command palette wrapper — wraps a native <dialog> and the
+  inner <command-ui>. Owns the keyboard shortcut listener, focus
+  management, and dismiss handlers. Reflects [open].
+
+  Sits inside <admin-shell> as a direct child. The host wires
+  [data-command-trigger] elements to <admin-command>.show() via lookup.
+
+  This is the bespoke web-component replacement for the legacy
+  <dialog data-command> shape. <admin-shell> still recognizes the
+  legacy shape via :is() selector. New code should prefer <admin-command>.
+
+props:
+  open:
+    description: |
+      Reflected — set while the dialog is showing. Synced with both
+      programmatic .show()/.hide() and native dialog close events
+      (esc key, backdrop click).
+    type: boolean
+    default: false
+    reflect: true
+
+  shortcut:
+    description: |
+      Keyboard shortcut binding. "cmd+k" responds only on Mac
+      (metaKey); "ctrl+k" responds only when ctrlKey; "both" (default)
+      responds to either, which is the canonical AdiaUI behavior for
+      cross-platform Cmd+K affordance.
+    type: string
+    default: both
+    enum:
+      - both
+      - cmd+k
+      - ctrl+k
+    reflect: true
+
+  no-shortcut:
+    description: |
+      Opts out of the keyboard listener entirely. Use when the host
+      wires its own shortcut handling, or when the palette should be
+      mouse-only.
+    type: boolean
+    default: false
+    reflect: true
+
+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
+
+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:
+  - name: idle
+    description: Default, palette closed.
+  - name: open
+    attribute: open
+    description: Dialog is showing; first input has focus.
+
+traits: []
+
+a2ui:
+  rules:
+    - >-
+      admin-command wraps a native <dialog>; the inner <command-ui>
+      is the actual palette. Keyboard shortcut defaults to both
+      Cmd+K (mac) and Ctrl+K (other) — the AdiaUI convention.
+    - >-
+      Place admin-command as a direct child of admin-shell, NOT inside
+      a sidebar or main column. The host coordinates triggers
+      ([data-command-trigger]) by reaching across siblings.
+
+keywords:
+  - admin-command
+  - command-palette
+  - palette
+  - cmd-k
+  - keyboard-shortcut
+  - quickaction
+
+synonyms:
+  command-palette: [palette, quick-action, omnibox]
+  cmd-k: [ctrl-k, command-shortcut]
+
+related:
+  - AdminShell
+  - AdminSidebar
+  - Command

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

@@ -0,0 +1,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AdminContent.json",
+  "title": "AdminContent",
+  "description": "Module-tier shell main-column container. CSS-only — no behavior, no\nJS. Sits inside <admin-shell> as the center column between leading\nand trailing sidebars. Authors compose chrome bars + scroll surface\nvia slot vocabulary.\n\nThis is the bespoke replacement for the legacy raw <main> element\ninside admin-shell. Both shapes still render correctly per ADR-0023\nPhase 1 backwards-compat; new code should prefer <admin-content>.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AdminContent"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "events": {},
+    "examples": [],
+    "keywords": [
+      "admin-content",
+      "main",
+      "center-column",
+      "workspace"
+    ],
+    "name": "AdminContent",
+    "related": [
+      "AdminShell",
+      "AdminSidebar",
+      "AdminTopbar",
+      "AdminStatusbar",
+      "AdminScroll",
+      "AdminPage"
+    ],
+    "slots": {
+      "default": {
+        "description": "Default content — typically <admin-topbar slot=\"header\">, an <admin-scroll> wrapping content, and an optional <admin-statusbar slot=\"footer\">."
+      },
+      "footer": {
+        "description": "Bottom chrome bar — typically <admin-statusbar>."
+      },
+      "header": {
+        "description": "Top chrome bar — typically <admin-topbar>."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, the only state.",
+        "name": "idle"
+      }
+    ],
+    "synonyms": {
+      "main": [
+        "content",
+        "center",
+        "workspace"
+      ]
+    },
+    "tag": "admin-content",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

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

@@ -0,0 +1,33 @@
+<header>
+    <div>
+      <h1>Admin Content</h1>
+      <div data-actions>
+        <tag-ui size="sm">admin-content</tag-ui>
+        <tag-ui size="sm" variant="ghost">CSS-only</tag-ui>
+      </div>
+    </div>
+    <p>Module-tier shell main-column container. CSS-only. Sits inside <admin-shell> as the center column between leading and trailing sidebars.</p>
+  </header>
+
+<section data-section>
+  <h2 variant="section">Role</h2>
+  <p>This is a CSS-only structural stub — no JavaScript, no behavior. The shell host (<code>&lt;admin-shell&gt;</code>) styles it via tag-presence. Authors compose it with sibling bespoke children to express semantic shell-tier structure.</p>
+</section>
+
+<section data-section>
+  <h2 variant="section">Composition</h2>
+  <p>Typical placement inside <code>&lt;admin-shell&gt;</code>:</p>
+  <code-ui language="html">&lt;admin-shell&gt;
+  &lt;admin-sidebar slot="leading"&gt;…&lt;/admin-sidebar&gt;
+  &lt;admin-content&gt;
+    &lt;admin-topbar slot="header"&gt;…&lt;/admin-topbar&gt;
+    &lt;admin-scroll&gt;…&lt;/admin-scroll&gt;
+    &lt;admin-statusbar slot="footer"&gt;…&lt;/admin-statusbar&gt;
+  &lt;/admin-content&gt;
+&lt;/admin-shell&gt;</code-ui>
+</section>
+
+<section data-section>
+  <h2 variant="section">Slot vocabulary</h2>
+  <p>See the <a href="../admin-shell/admin-shell.html"><code>admin-shell</code></a> demo for the full composition pattern. CSS-only stubs declare slot intent; the parent shell handles layout.</p>
+</section>

package/shell/admin-content/admin-content.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 Content — 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-shell/admin-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('./admin-content.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-content.examples.html — ${err.message}</p>`;
+      console.error('[admin-content.html]', err);
+    }
+  </script>
+
+</body>
+</html>

package/shell/admin-content/admin-content.yaml

@@ -0,0 +1,63 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdminContent
+tag: admin-content
+component: AdminContent
+category: layout
+version: 1
+description: |
+  Module-tier shell main-column container. CSS-only — no behavior, no
+  JS. Sits inside <admin-shell> as the center column between leading
+  and trailing sidebars. Authors compose chrome bars + scroll surface
+  via slot vocabulary.
+
+  This is the bespoke replacement for the legacy raw <main> element
+  inside admin-shell. Both shapes still render correctly per ADR-0023
+  Phase 1 backwards-compat; new code should prefer <admin-content>.
+
+props: {}
+
+events: {}
+
+slots:
+  default:
+    description: >-
+      Default content — typically <admin-topbar slot="header">, an
+      <admin-scroll> wrapping content, and an optional
+      <admin-statusbar slot="footer">.
+  header:
+    description: >-
+      Top chrome bar — typically <admin-topbar>.
+  footer:
+    description: >-
+      Bottom chrome bar — typically <admin-statusbar>.
+
+states:
+  - name: idle
+    description: Default, the only state.
+
+traits: []
+
+a2ui:
+  rules:
+    - >-
+      admin-content is the bespoke replacement for raw <main> inside
+      admin-shell. CSS-only; the shell's css/main.css selectors target
+      both shapes via :is(main, admin-content).
+
+keywords:
+  - admin-content
+  - main
+  - center-column
+  - workspace
+
+synonyms:
+  main: [content, center, workspace]
+
+related:
+  - AdminShell
+  - AdminSidebar
+  - AdminTopbar
+  - AdminStatusbar
+  - AdminScroll
+  - AdminPage

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

@@ -0,0 +1,74 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AdminPage.json",
+  "title": "AdminPage",
+  "description": "Module-tier page wrapper. CSS-only — no behavior, no JS. Provides\nthe page-content-root container query (named `page-content`) so\ndescendants can adapt to available content width (sidebars expanded\nvs collapsed) instead of viewport width. Stamps the sticky-band\nlayout: <admin-page-header> + <admin-page-body> + optional footer.\n\nReplaces the legacy <article data-content-root> shape per ADR-0023.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AdminPage"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "events": {},
+    "examples": [],
+    "keywords": [
+      "admin-page",
+      "page-content",
+      "container-query-host"
+    ],
+    "name": "AdminPage",
+    "related": [
+      "AdminShell",
+      "AdminContent",
+      "AdminScroll",
+      "AdminPageHeader",
+      "AdminPageBody"
+    ],
+    "slots": {
+      "default": {
+        "description": "Default — typically <admin-page-header> + <admin-page-body>."
+      },
+      "body": {
+        "description": "Centered reading column (alternate slot for the body band)."
+      },
+      "footer": {
+        "description": "Sticky bottom band."
+      },
+      "header": {
+        "description": "Sticky top band (alternate slot for the header band)."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, the only state.",
+        "name": "idle"
+      }
+    ],
+    "synonyms": {
+      "page-content": [
+        "content-area",
+        "content-root",
+        "document-region"
+      ]
+    },
+    "tag": "admin-page",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}