@adia-ai/web-components 0.0.1

package/patterns/app-nav-item/app-nav-item.js

@@ -0,0 +1,42 @@
+/**
+ * <app-nav-item-ui> — Single navigation link in app-nav-ui (optionally
+ * nested under app-nav-group-ui). Supports icon, label, and optional badge.
+ *
+ * Selection is managed by the parent app-nav-ui; setting `selected` is
+ * a side-effect of calling nav.select(item) or user click.
+ */
+
+import { AdiaElement } from '@core/element.js';
+
+class AdiaAppNavItem extends AdiaElement {
+  static properties = {
+    text:     { type: String,  default: '', reflect: true },
+    icon:     { type: String,  default: '', reflect: true },
+    value:    { type: String,  default: '', reflect: true },
+    badge:    { type: String,  default: '', reflect: true },
+    selected: { type: Boolean, default: false, reflect: true },
+  };
+
+  static template = () => null;
+
+  connected() {
+    this.setAttribute('role', 'link');
+    this.setAttribute('tabindex', '0');
+
+    if (!this.querySelector('[slot="text"]')) {
+      this.innerHTML = `
+        <span slot="icon">${this.icon ? `<icon-ui name="${this.icon}"></icon-ui>` : ''}</span>
+        <span slot="text">${this.text}</span>
+        ${this.badge ? `<span slot="badge">${this.badge}</span>` : ''}
+      `;
+    }
+  }
+
+  render() {
+    const textEl = this.querySelector('[slot="text"]');
+    if (textEl) textEl.textContent = this.text;
+  }
+}
+customElements.define('app-nav-item-ui', AdiaAppNavItem);
+
+export { AdiaAppNavItem };

package/patterns/app-nav-item/app-nav-item.yaml

@@ -0,0 +1,62 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdiaAppNavItem
+tag: app-nav-item-ui
+component: AppNavItem
+category: nav
+version: 1
+description: |
+  Single navigation link in app-nav-ui, optionally nested inside
+  app-nav-group-ui. Icon + label + optional badge. Selection is managed
+  by the parent app-nav-ui — set via clicking or nav.select(item).
+
+props:
+  text:
+    type: string
+    default: ""
+    reflect: true
+    description: Item label.
+
+  icon:
+    type: string
+    default: ""
+    reflect: true
+    description: Phosphor icon name (leading).
+
+  value:
+    type: string
+    default: ""
+    reflect: true
+    description: Unique identifier for selection tracking (also the route / target id).
+
+  badge:
+    type: string
+    default: ""
+    reflect: true
+    description: Optional trailing badge text (count, "New", etc.).
+
+  selected:
+    type: boolean
+    default: false
+    reflect: true
+    description: Current selection. Managed by parent app-nav-ui — don't set multiple siblings.
+
+events: {}
+
+slots: {}
+
+states:
+  - name: idle
+    description: Default.
+  - name: selected
+    attribute: selected
+    description: Currently selected nav destination.
+
+traits: []
+
+a2ui:
+  rules:
+    - Must be a descendant of app-nav-ui (direct child or via app-nav-group-ui).
+    - Only one sibling may have selected=true at a time; prefer calling nav.select() over setting the attribute manually.
+
+keywords: [app-nav-item, nav, link, menu-item]
+related: [AppNav, AppNavGroup]

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

@@ -0,0 +1,114 @@
+{
+  "$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]); app-shell-ui 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": "AdiaAppShell",
+    "related": [
+      "AppNav",
+      "AppNavGroup",
+      "AppNavItem",
+      "Command"
+    ],
+    "slots": {
+      "default": {
+        "description": "Author-supplied page DOM. Expected structure — aside[data-sidebar] for navigation, main for content, optional dialog[data-command] for Cmd+K."
+      }
+    },
+    "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": "app-shell-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

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

@@ -0,0 +1,14 @@
+/* ═══════════════════════════════════════════════════════════════
+   App Shell — <app-shell-ui> pattern component CSS
+
+   Split into constituent parts for maintainability.
+   Import order matters: tokens first, then structure, then overrides.
+   ═══════════════════════════════════════════════════════════════ */
+
+@import "./css/app-shell.tokens.css";
+@import "./css/app-shell.shell.css";
+@import "./css/app-shell.main.css";
+@import "./css/app-shell.sidebar.css";
+@import "./css/app-shell.collapsed.css";
+@import "./css/app-shell.templates.css";
+@import "./css/app-shell.helpers.css";

package/patterns/app-shell/app-shell.js

@@ -0,0 +1,251 @@
+/**
+ * <app-shell-ui mode="rounded borderless">
+ *   <aside data-sidebar="leading">...</aside>
+ *   <main>...</main>
+ *   <aside data-sidebar="trailing">...</aside>
+ *   <dialog data-command>...</dialog>
+ * </app-shell-ui>
+ *
+ * Behavior-only app shell. Stamps no HTML — the page author writes the
+ * structure using semantic elements + data attributes. 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 { AdiaElement } from '@core/element.js';
+
+const SNAP_THRESHOLD = 96;
+const SNAP_MIN_USABLE = 160;
+
+class AdiaAppShell extends AdiaElement {
+  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 ────────────────────────────────────
+
+  #persistSidebar(sidebarName, width) {
+    try { localStorage.setItem(`adia-sidebar-${sidebarName}`, width); } catch {}
+  }
+
+  #restoreSidebars() {
+    for (const sidebar of this.querySelectorAll('[data-sidebar]')) {
+      const name = sidebar.getAttribute('data-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(`[data-sidebar="${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('[data-sidebar] > [data-resize]')) {
+      const sidebar = handle.parentElement;
+      const sidebarName = sidebar.getAttribute('data-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('app-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(`app-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('[data-sidebar]')) {
+      this.#sidebarRO.observe(sb);
+    }
+  }
+}
+
+customElements.define('app-shell-ui', AdiaAppShell);
+export { AdiaAppShell };

package/patterns/app-shell/app-shell.yaml

@@ -0,0 +1,66 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdiaAppShell
+tag: app-shell-ui
+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]); app-shell-ui 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.
+
+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:
+    - >-
+      app-shell-ui 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: [AppNav, AppNavGroup, AppNavItem, Command]

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

@@ -0,0 +1,86 @@
+/* ═══════════════════════════════════════════════════════════════
+   App 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 */
+  header, footer {
+    justify-content: center;
+    padding: var(--page-sidebar-px);
+  }
+
+  /* Center section content */
+  section {
+    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 */
+  app-nav-ui [slot="text"],
+  app-nav-ui [slot="badge"],
+  app-nav-ui [slot="caret"],
+  app-nav-ui [slot="trailing"],
+  app-nav-ui [data-nav-label],
+  app-nav-ui [data-nav-divider] {
+    display: none !important;
+  }
+
+  /* Nav items/group headers: center icon, ensure square hit area */
+  app-nav-group-ui [slot="header"] {
+    justify-content: center;
+    padding: 0;
+    min-height: var(--nav-group-row-height);
+    min-width: var(--nav-group-row-height);
+  }
+
+  app-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/patterns/app-shell/css/app-shell.helpers.css

@@ -0,0 +1,42 @@
+/* ═══════════════════════════════════════════════════════════════
+   App 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);
+}