@adia-ai/web-modules 0.0.4

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

@@ -0,0 +1,129 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AppShell.json",
+  "title": "AppShell",
+  "description": "Behavior-only application shell. Wires sidebar toggles, resize handles,\na Cmd+K command palette, and a ResizeObserver that drives responsive\nsidebar collapse. Author supplies the DOM (aside[data-sidebar], main,\ndialog[data-command]); admin-shell binds the interactions.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AppShell"
+    },
+    "mode": {
+      "description": "Layout variant — default is bordered surface; rounded softens edges; borderless removes the outer chrome.",
+      "type": "string",
+      "enum": [
+        "",
+        "rounded",
+        "borderless"
+      ],
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "events": {
+      "command-select": {
+        "description": "Forwarded from the command palette when an option is chosen.",
+        "detail": {
+          "value": "string"
+        }
+      },
+      "sidebar-resize": {
+        "description": "Fired as a sidebar is dragged; debounced on the trailing edge.",
+        "detail": {
+          "sidebar": "string",
+          "width": "number"
+        }
+      },
+      "sidebar-toggle": {
+        "description": "Fired when a sidebar is collapsed or expanded.",
+        "detail": {
+          "expanded": "boolean",
+          "sidebar": "string"
+        }
+      }
+    },
+    "examples": [],
+    "keywords": [
+      "app-shell",
+      "shell",
+      "layout",
+      "admin",
+      "dashboard",
+      "sidebar",
+      "nav"
+    ],
+    "name": "AdminShell",
+    "related": [
+      "Nav",
+      "NavGroup",
+      "NavItem",
+      "Command"
+    ],
+    "slots": {
+      "description": {
+        "description": "Secondary metadata inside any chrome bar. Muted + --a-ui-sm size."
+      },
+      "default": {
+        "description": "Author-supplied page DOM. Expected structure — aside[data-sidebar] for navigation, main for content, optional dialog[data-command] for Cmd+K."
+      },
+      "action": {
+        "description": "Trailing control cluster inside any chrome bar. The first [slot=\"action\"] child pushes itself (and siblings) to the end; subsequent siblings flow with gap. Coexists with legacy <span data-spacer> / <div data-actions> hooks for one release — new code should prefer slots."
+      },
+      "action-leading": {
+        "description": "Leading (inline-start) control cluster inside any chrome bar. Pairs with [slot=\"action\"] for dual-cluster chrome (e.g. back button + breadcrumb on the left, primary actions on the right). Replaces the legacy <span data-spacer> hack."
+      },
+      "heading": {
+        "description": "Primary label inside any chrome bar. Medium-weight + strong fg."
+      },
+      "icon": {
+        "description": "Leading glyph inside any chrome bar — > main > header / footer and [data-sidebar] > header / footer. Muted color, flex-align."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, interactive shell.",
+        "name": "idle"
+      },
+      {
+        "description": "Leading sidebar is collapsed; content expands.",
+        "attribute": "data-sidebar-leading-collapsed",
+        "name": "collapsed-leading"
+      },
+      {
+        "description": "Trailing sidebar (inspector) is collapsed.",
+        "attribute": "data-sidebar-trailing-collapsed",
+        "name": "collapsed-trailing"
+      }
+    ],
+    "synonyms": {
+      "admin": [
+        "dashboard",
+        "shell",
+        "app-shell"
+      ],
+      "dashboard": [
+        "admin",
+        "shell",
+        "app-shell"
+      ]
+    },
+    "tag": "admin-shell",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/shell/admin-shell/admin-shell.css

@@ -0,0 +1,14 @@
+/* ═══════════════════════════════════════════════════════════════
+   admin-shell — Module CSS (admin app layout shell)
+
+   Split into constituent parts for maintainability.
+   Import order matters: tokens first, then structure, then overrides.
+   ═══════════════════════════════════════════════════════════════ */
+
+@import "./css/admin-shell.tokens.css";
+@import "./css/admin-shell.shell.css";
+@import "./css/admin-shell.main.css";
+@import "./css/admin-shell.sidebar.css";
+@import "./css/admin-shell.collapsed.css";
+@import "./css/admin-shell.templates.css";
+@import "./css/admin-shell.helpers.css";

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

@@ -0,0 +1,261 @@
+/**
+ * <admin-shell mode="rounded borderless">
+ *   <aside data-sidebar="leading">...</aside>     (or <aside-ui slot="leading">)
+ *   <main>...</main>
+ *   <aside data-sidebar="trailing">...</aside>    (or <aside-ui slot="trailing">)
+ *   <dialog data-command>...</dialog>
+ * </admin-shell>
+ *
+ * Behavior-only app shell. Stamps no HTML — the page author writes the
+ * structure using semantic elements + data attributes. Both the legacy
+ * `aside[data-sidebar]` and the slot-vocabulary `aside-ui[slot]`
+ * authoring shapes are recognised; #sidebarName() reads from either.
+ * The component auto-wires four JS behaviors that CSS can't handle:
+ *
+ *   1. Sidebar resize (drag handle with snap thresholds)
+ *   2. Sidebar toggle (collapse/restore width)
+ *   3. Command palette (Cmd+K keyboard shortcut)
+ *   4. ResizeObserver (select placement in narrow sidebars)
+ *
+ * CSS handles everything else: layout, collapse, container queries,
+ * sticky headers, scroll containment, mode composition.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+const SNAP_THRESHOLD = 96;
+const SNAP_MIN_USABLE = 160;
+
+class AdminShell extends UIElement {
+  static properties = {
+    mode: { type: String, default: '', reflect: true },
+  };
+
+  static template = () => null;
+
+  #sidebarWidths = new Map();
+  #resizeCleanups = [];
+  #sidebarRO = null;
+  #cmdKeyHandler = null;
+
+  connected() {
+    this.#setupToggles();
+    this.#setupResizeHandles();
+    this.#setupCommandPalette();
+    this.#setupResizeObserver();
+  }
+
+  disconnected() {
+    // Clean up resize handles
+    for (const cleanup of this.#resizeCleanups) cleanup();
+    this.#resizeCleanups = [];
+
+    // Clean up ResizeObserver
+    this.#sidebarRO?.disconnect();
+    this.#sidebarRO = null;
+
+    // Clean up Cmd+K
+    if (this.#cmdKeyHandler) {
+      document.removeEventListener('keydown', this.#cmdKeyHandler);
+      this.#cmdKeyHandler = null;
+    }
+  }
+
+  // ── Sidebar persistence ────────────────────────────────────
+
+  // Selector that matches both legacy raw-HTML and slot-vocabulary forms.
+  static #SIDEBAR_SEL = ':is([data-sidebar], aside-ui[slot="leading"], aside-ui[slot="trailing"])';
+
+  // Helper: read sidebar name from either authoring shape.
+  #sidebarName(el) {
+    return el.getAttribute('data-sidebar') ?? el.getAttribute('slot');
+  }
+
+  #persistSidebar(sidebarName, width) {
+    try { localStorage.setItem(`adia-sidebar-${sidebarName}`, width); } catch {}
+  }
+
+  #restoreSidebars() {
+    for (const sidebar of this.querySelectorAll(AdminShell.#SIDEBAR_SEL)) {
+      const name = this.#sidebarName(sidebar);
+      try {
+        const saved = localStorage.getItem(`adia-sidebar-${name}`);
+        if (saved) {
+          sidebar.style.width = saved;
+          // Only store as the "previous expanded width" if it's actually expanded.
+          // If collapsed, keep the default expanded width so toggle can restore it.
+          const w = parseFloat(saved);
+          if (isNaN(w) || w > SNAP_THRESHOLD) {
+            this.#sidebarWidths.set(name, saved);
+          }
+        }
+      } catch {}
+    }
+  }
+
+  // ── 1. Sidebar toggle ──────────────────────────────────────
+
+  #setupToggles() {
+    this.#restoreSidebars();
+
+    for (const btn of this.querySelectorAll('[data-sidebar-toggle]')) {
+      const sidebarName = btn.getAttribute('data-sidebar-toggle');
+      btn.addEventListener('click', () => {
+        const sidebar = this.querySelector(`:is([data-sidebar="${sidebarName}"], aside-ui[slot="${sidebarName}"])`);
+        if (!sidebar) return;
+
+        const isCollapsed = sidebar.getBoundingClientRect().width <= SNAP_THRESHOLD;
+
+        if (isCollapsed) {
+          // Expand: restore previous width
+          const prev = this.#sidebarWidths.get(sidebarName);
+          sidebar.style.width = prev || '';
+          this.#persistSidebar(sidebarName, prev || '');
+        } else {
+          // Collapse: save current width, set to min
+          this.#sidebarWidths.set(sidebarName, sidebar.style.width || getComputedStyle(sidebar).width);
+          const minW = getComputedStyle(sidebar).minWidth;
+          sidebar.style.width = minW;
+          this.#persistSidebar(sidebarName, minW);
+        }
+
+        this.dispatchEvent(new CustomEvent('sidebar-toggle', {
+          bubbles: true,
+          detail: { sidebar: sidebarName, expanded: !isCollapsed },
+        }));
+      });
+    }
+  }
+
+  // ── 2. Sidebar resize handles ──────────────────────────────
+
+  #setupResizeHandles() {
+    for (const handle of this.querySelectorAll(`${AdminShell.#SIDEBAR_SEL} > [data-resize]`)) {
+      const sidebar = handle.parentElement;
+      const sidebarName = this.#sidebarName(sidebar);
+      const isLeading = sidebarName === 'leading';
+
+      const onPointerDown = (e) => {
+        e.preventDefault();
+        handle.setPointerCapture(e.pointerId);
+        const startX = e.clientX;
+        const startW = sidebar.getBoundingClientRect().width;
+        sidebar.setAttribute('data-resizing', '');
+        document.documentElement.style.cursor = 'col-resize';
+
+        const onMove = (e) => {
+          const dx = e.clientX - startX;
+          const max = parseInt(getComputedStyle(sidebar).getPropertyValue('max-width')) || 480;
+          const w = Math.max(48, Math.min(max, startW + (isLeading ? dx : -dx)));
+          sidebar.style.width = `${w}px`;
+        };
+
+        const onUp = () => {
+          sidebar.removeAttribute('data-resizing');
+          document.documentElement.style.cursor = '';
+          handle.removeEventListener('pointermove', onMove);
+          handle.removeEventListener('pointerup', onUp);
+
+          // Snap logic
+          const w = sidebar.getBoundingClientRect().width;
+          if (w <= SNAP_THRESHOLD) {
+            sidebar.style.width = getComputedStyle(sidebar).minWidth;
+          } else if (w < SNAP_MIN_USABLE) {
+            sidebar.style.width = `${SNAP_MIN_USABLE}px`;
+          }
+
+          this.#persistSidebar(sidebarName, sidebar.style.width);
+          this.dispatchEvent(new CustomEvent('sidebar-resize', {
+            bubbles: true,
+            detail: { sidebar: sidebarName, width: sidebar.getBoundingClientRect().width },
+          }));
+        };
+
+        handle.addEventListener('pointermove', onMove);
+        handle.addEventListener('pointerup', onUp);
+      };
+
+      handle.addEventListener('pointerdown', onPointerDown);
+      this.#resizeCleanups.push(() => handle.removeEventListener('pointerdown', onPointerDown));
+    }
+  }
+
+  // ── 3. Command palette ─────────────────────────────────────
+
+  #setupCommandPalette() {
+    const dialog = this.querySelector('dialog[data-command]');
+    if (!dialog) return;
+
+    const cmdEl = dialog.querySelector('command-ui');
+    const nav = this.querySelector('nav-ui');
+
+    const openCmd = () => {
+      dialog.showModal();
+      if (cmdEl) { cmdEl.open = true; cmdEl.value = ''; cmdEl.focus(); }
+    };
+
+    const closeCmd = () => {
+      dialog.close();
+      if (cmdEl) cmdEl.open = false;
+    };
+
+    // Trigger elements
+    for (const trigger of this.querySelectorAll('[data-command-trigger]')) {
+      trigger.addEventListener('click', (e) => {
+        e.stopPropagation();
+        openCmd();
+      });
+    }
+
+    // Backdrop click closes
+    dialog.addEventListener('click', (e) => {
+      if (e.target === dialog) closeCmd();
+    });
+
+    // Command-n events
+    if (cmdEl) {
+      cmdEl.addEventListener('dismiss', closeCmd);
+      cmdEl.addEventListener('select', (e) => {
+        closeCmd();
+        if (nav) {
+          const item = nav.querySelector(`nav-item-ui[value="${e.detail.value}"]`);
+          if (item) nav.select(item);
+        }
+        this.dispatchEvent(new CustomEvent('command-select', {
+          bubbles: true,
+          detail: e.detail,
+        }));
+      });
+    }
+
+    // Cmd+K / Ctrl+K
+    this.#cmdKeyHandler = (e) => {
+      if ((e.metaKey || e.ctrlKey) && e.key === 'k') {
+        e.preventDefault();
+        dialog.open ? closeCmd() : openCmd();
+      }
+    };
+    document.addEventListener('keydown', this.#cmdKeyHandler);
+  }
+
+  // ── 4. ResizeObserver for select placement ─────────────────
+
+  #setupResizeObserver() {
+    this.#sidebarRO = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const sidebar = entry.target;
+        const narrow = entry.contentBoxSize[0].inlineSize <= SNAP_THRESHOLD;
+        for (const sel of sidebar.querySelectorAll('select-ui')) {
+          sel.setAttribute('placement', narrow ? 'right' : 'bottom-start');
+        }
+      }
+    });
+
+    for (const sb of this.querySelectorAll(AdminShell.#SIDEBAR_SEL)) {
+      this.#sidebarRO.observe(sb);
+    }
+  }
+}
+
+customElements.define('admin-shell', AdminShell);
+export { AdminShell };

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

@@ -0,0 +1,89 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdminShell
+tag: admin-shell
+component: AppShell
+category: layout
+version: 1
+description: |
+  Behavior-only application shell. Wires sidebar toggles, resize handles,
+  a Cmd+K command palette, and a ResizeObserver that drives responsive
+  sidebar collapse. Author supplies the DOM (aside[data-sidebar], main,
+  dialog[data-command]); admin-shell binds the interactions.
+
+props:
+  mode:
+    type: string
+    default: ""
+    enum: ["", rounded, borderless]
+    reflect: true
+    description: Layout variant — default is bordered surface; rounded softens edges; borderless removes the outer chrome.
+
+events:
+  sidebar-toggle:
+    description: Fired when a sidebar is collapsed or expanded.
+    detail:
+      sidebar: string
+      expanded: boolean
+  sidebar-resize:
+    description: Fired as a sidebar is dragged; debounced on the trailing edge.
+    detail:
+      sidebar: string
+      width: number
+  command-select:
+    description: Forwarded from the command palette when an option is chosen.
+    detail:
+      value: string
+
+slots:
+  default:
+    description: >-
+      Author-supplied page DOM. Expected structure — aside[data-sidebar] for
+      navigation, main for content, optional dialog[data-command] for Cmd+K.
+  icon:
+    description: >-
+      Leading glyph inside any chrome bar — > main > header / footer and
+      [data-sidebar] > header / footer. Muted color, flex-align.
+  heading:
+    description: >-
+      Primary label inside any chrome bar. Medium-weight + strong fg.
+  description:
+    description: >-
+      Secondary metadata inside any chrome bar. Muted + --a-ui-sm size.
+  action:
+    description: >-
+      Trailing control cluster inside any chrome bar. The first
+      [slot="action"] child pushes itself (and siblings) to the end;
+      subsequent siblings flow with gap. Coexists with legacy
+      <span data-spacer> / <div data-actions> hooks for one release —
+      new code should prefer slots.
+  action-leading:
+    description: >-
+      Leading (inline-start) control cluster inside any chrome bar.
+      Pairs with [slot="action"] for dual-cluster chrome (e.g. back
+      button + breadcrumb on the left, primary actions on the right).
+      Replaces the legacy <span data-spacer> hack.
+
+states:
+  - name: idle
+    description: Default, interactive shell.
+  - name: collapsed-leading
+    attribute: data-sidebar-leading-collapsed
+    description: Leading sidebar is collapsed; content expands.
+  - name: collapsed-trailing
+    attribute: data-sidebar-trailing-collapsed
+    description: Trailing sidebar (inspector) is collapsed.
+
+traits: []
+
+a2ui:
+  rules:
+    - >-
+      admin-shell is a behavior wrapper; its children are native HTML landmarks
+      (aside, main, header). Don't wrap them in col-ui/row-ui — app-shell.css
+      handles grid layout based on [data-sidebar] attributes.
+
+keywords: [app-shell, shell, layout, admin, dashboard, sidebar, nav]
+synonyms:
+  admin:     [dashboard, shell, app-shell]
+  dashboard: [admin, shell, app-shell]
+related: [Nav, NavGroup, NavItem, Command]

package/shell/admin-shell/css/admin-shell.collapsed.css

@@ -0,0 +1,86 @@
+/* ═══════════════════════════════════════════════════════════════
+   admin-shell — Sidebar collapsed state
+
+   @container sidebar (max-width: 96px)
+
+   All collapse behavior is CSS-driven via container queries.
+   JS only handles:
+     - Resize drag with snap (≤96px → 48px, 97-159px → 160px)
+     - Toggle button (sets width to min/restore)
+     - Select placement attribute (bottom-start → right)
+     - Nav-group popover-vs-toggle (checks width at click time)
+   ═══════════════════════════════════════════════════════════════ */
+
+@container sidebar (max-width: 96px) {
+  /* Center header/footer content */
+  :is(header, header-ui, footer, footer-ui) {
+    justify-content: center;
+    padding: var(--page-sidebar-px);
+  }
+
+  /* Center section content */
+  :is(section, section-ui) {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+  }
+
+  /* Select: hide text + caret, keep leading icon/avatar */
+  select-ui [slot="display"],
+  select-ui [slot="caret"] {
+    display: none;
+  }
+
+  select-ui [slot="trigger"] {
+    justify-content: center;
+    padding: 0;
+    min-height: var(--page-header-height);
+  }
+
+  /* Select leading: bump icon/avatar size for collapsed state */
+  select-ui [slot="leading"] {
+    --a-icon-size: var(--page-sidebar-collapsed-icon);
+    font-size: var(--page-sidebar-collapsed-icon);
+  }
+
+  select-ui img[slot="leading"] {
+    width: var(--page-sidebar-collapsed-avatar);
+    height: var(--page-sidebar-collapsed-avatar);
+  }
+
+  /* Nav: hide all text/meta, show only icons */
+  nav-ui [slot="text"],
+  nav-ui [slot="badge"],
+  nav-ui [slot="caret"],
+  nav-ui [slot="trailing"],
+  nav-ui [data-nav-label],
+  nav-ui [data-nav-divider] {
+    display: none !important;
+  }
+
+  /* Nav items/group headers: center icon, ensure square hit area */
+  nav-group-ui [slot="header"] {
+    justify-content: center;
+    padding: 0;
+    min-height: var(--nav-group-row-height);
+    min-width: var(--nav-group-row-height);
+  }
+
+  nav-item-ui {
+    justify-content: center;
+    padding: 0;
+    min-height: var(--nav-item-row-height);
+    min-width: var(--nav-item-row-height);
+  }
+
+  /* Button: icon-only mode */
+  button-ui {
+    --button-px: 0;
+    width: auto !important;
+    justify-content: center;
+  }
+
+  button-ui [slot="trailing"] {
+    display: none;
+  }
+}

package/shell/admin-shell/css/admin-shell.helpers.css

@@ -0,0 +1,42 @@
+/* ═══════════════════════════════════════════════════════════════
+   admin-shell — Layout helpers
+
+   Generic layout utilities used across admin pages.
+   ═══════════════════════════════════════════════════════════════ */
+
+/* Flex spacer — pushes siblings to opposite ends */
+[data-spacer] { flex: 1; }
+
+/* Inline action group (buttons, icons) */
+[data-actions] {
+  display: flex;
+  align-items: center;
+  gap: var(--page-actions-gap);
+}
+
+/* ── Form layout helpers ── */
+
+/* 2-column grid (default), 3-column with data-grid="3" */
+[data-grid] {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: var(--page-grid-gap);
+}
+
+[data-grid="3"] {
+  grid-template-columns: 1fr 1fr 1fr;
+}
+
+/* Vertical stack */
+[data-col] {
+  display: flex;
+  flex-direction: column;
+  gap: var(--page-grid-gap);
+}
+
+/* Horizontal row */
+[data-row] {
+  display: flex;
+  align-items: center;
+  gap: var(--page-grid-gap);
+}