@adia-ai/web-modules 0.3.3 → 0.3.5

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

@@ -0,0 +1,227 @@
+/**
+ * <admin-sidebar slot="leading|trailing" resizable collapsible>
+ *   <admin-topbar slot="header">…</admin-topbar>     (or any chrome bar)
+ *   …default content (nav, list, etc.)…
+ *   <admin-statusbar slot="footer">…</admin-statusbar>
+ * </admin-sidebar>
+ *
+ * Module-tier sidebar — owns resize, snap-to-collapsed, persistence,
+ * and the [collapsed] reflected attribute. Sits inside <admin-shell>
+ * but doesn't reach into it; the shell coordinates without orchestrating
+ * child internals.
+ *
+ * Reflected attributes (the consumer-queryable state):
+ *   [collapsed]   — set when sidebar width is at or below SNAP_THRESHOLD
+ *   [resizing]    — set during an active pointer-drag
+ *
+ * Author-supplied attributes (read once at connect, never overwritten):
+ *   [slot="leading"|"trailing"]  — required, drives drag direction +
+ *                                  localStorage namespacing
+ *   [resizable]                  — opts in to drag handle wiring
+ *   [collapsible]                — opts in to programmatic collapse
+ *                                  (toggle button + window.toggle())
+ *   [name="<id>"]                — optional override for the localStorage
+ *                                  key. Defaults to slot value.
+ *   [min-width="48px"]           — optional override for the snap-floor
+ *                                  width (otherwise reads CSS min-width)
+ *
+ * Events:
+ *   sidebar-toggle  — bubbles. detail: { name, expanded }
+ *   sidebar-resize  — bubbles. detail: { name, width }
+ *
+ * The drag handle is conventional: a child `[data-resize]` element.
+ * Authors may provide a custom one, or omit (no resize affordance).
+ *
+ * Backwards compat: <admin-shell> still recognizes the legacy
+ * `<aside data-sidebar="leading">` shape via :is() selector. New
+ * code should prefer <admin-sidebar>.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+const SNAP_THRESHOLD = 96;
+const SNAP_MIN_USABLE = 160;
+
+class AdminSidebar extends UIElement {
+  static properties = {
+    collapsed: { type: Boolean, default: false, reflect: true },
+    resizing: { type: Boolean, default: false, reflect: true },
+    resizable: { type: Boolean, default: false, reflect: true },
+    collapsible: { type: Boolean, default: false, reflect: true },
+    name: { type: String, default: '', reflect: true },
+    minWidth: { type: String, default: '', reflect: true, attribute: 'min-width' },
+  };
+
+  static template = () => null;
+
+  // The width the sidebar had before being collapsed — used for restore.
+  // Map keyed by sidebar name allows multiple sidebars on one host.
+  #previousExpandedWidth = '';
+  #resizeCleanups = [];
+  #childRO = null;
+
+  connected() {
+    this.#restoreFromStorage();
+    if (this.resizable) this.#setupResizeHandle();
+    this.#setupChildResizeObserver();
+    this.#syncCollapsedFromWidth();
+  }
+
+  disconnected() {
+    for (const cleanup of this.#resizeCleanups) cleanup();
+    this.#resizeCleanups = [];
+    this.#childRO?.disconnect();
+    this.#childRO = null;
+  }
+
+  // ── Public API (callable from <admin-shell> or external code) ──
+
+  /**
+   * Toggle collapsed state. Collapses if expanded, restores if collapsed.
+   * Returns the new collapsed value.
+   */
+  toggle() {
+    if (this.collapsed) {
+      this.expand();
+    } else {
+      this.collapse();
+    }
+    return this.collapsed;
+  }
+
+  /** Collapse to the snap-floor width. Persists to localStorage. */
+  collapse() {
+    if (this.collapsed) return;
+    // Remember current expanded width before collapsing
+    const currentWidth = this.style.width || getComputedStyle(this).width;
+    if (parseFloat(currentWidth) > SNAP_THRESHOLD) {
+      this.#previousExpandedWidth = currentWidth;
+    }
+    const minW = this.minWidth || getComputedStyle(this).minWidth;
+    this.style.width = minW;
+    this.#persist(minW);
+    this.collapsed = true;
+    this.#dispatchToggle(false);
+  }
+
+  /** Restore to the previous expanded width (or default if none). */
+  expand() {
+    if (!this.collapsed) return;
+    const restoreWidth = this.#previousExpandedWidth || '';
+    this.style.width = restoreWidth;
+    this.#persist(restoreWidth);
+    this.collapsed = false;
+    this.#dispatchToggle(true);
+  }
+
+  // ── Persistence ──
+
+  #storageKey() {
+    const id = this.name || this.getAttribute('slot') || 'default';
+    return `adia-sidebar-${id}`;
+  }
+
+  #persist(width) {
+    try { localStorage.setItem(this.#storageKey(), width); } catch {}
+  }
+
+  #restoreFromStorage() {
+    try {
+      const saved = localStorage.getItem(this.#storageKey());
+      if (!saved) return;
+      this.style.width = saved;
+      // Only treat as "previous expanded" if actually expanded
+      const w = parseFloat(saved);
+      if (!isNaN(w) && w > SNAP_THRESHOLD) {
+        this.#previousExpandedWidth = saved;
+      }
+    } catch {}
+  }
+
+  // ── Reflect [collapsed] from current measured width ──
+
+  #syncCollapsedFromWidth() {
+    const w = this.getBoundingClientRect().width;
+    this.collapsed = w <= SNAP_THRESHOLD;
+  }
+
+  // ── Resize drag handle ──
+
+  #setupResizeHandle() {
+    const handle = this.querySelector(':scope > [data-resize]');
+    if (!handle) return;
+
+    const slot = this.getAttribute('slot');
+    const isLeading = slot === 'leading';
+
+    const onPointerDown = (e) => {
+      e.preventDefault();
+      handle.setPointerCapture(e.pointerId);
+      const startX = e.clientX;
+      const startW = this.getBoundingClientRect().width;
+      this.resizing = true;
+      document.documentElement.style.cursor = 'col-resize';
+
+      const onMove = (e) => {
+        const dx = e.clientX - startX;
+        const max = parseInt(getComputedStyle(this).getPropertyValue('max-width')) || 480;
+        const w = Math.max(48, Math.min(max, startW + (isLeading ? dx : -dx)));
+        this.style.width = `${w}px`;
+      };
+
+      const onUp = () => {
+        this.resizing = false;
+        document.documentElement.style.cursor = '';
+        handle.removeEventListener('pointermove', onMove);
+        handle.removeEventListener('pointerup', onUp);
+
+        // Snap logic
+        const w = this.getBoundingClientRect().width;
+        if (w <= SNAP_THRESHOLD) {
+          this.style.width = this.minWidth || getComputedStyle(this).minWidth;
+        } else if (w < SNAP_MIN_USABLE) {
+          this.style.width = `${SNAP_MIN_USABLE}px`;
+        }
+
+        this.#persist(this.style.width);
+        this.#syncCollapsedFromWidth();
+        this.dispatchEvent(new CustomEvent('sidebar-resize', {
+          bubbles: true,
+          detail: { name: this.name || slot, width: this.getBoundingClientRect().width },
+        }));
+      };
+
+      handle.addEventListener('pointermove', onMove);
+      handle.addEventListener('pointerup', onUp);
+    };
+
+    handle.addEventListener('pointerdown', onPointerDown);
+    this.#resizeCleanups.push(() => handle.removeEventListener('pointerdown', onPointerDown));
+  }
+
+  // ── Child ResizeObserver — flips select-ui placement in narrow mode ──
+
+  #setupChildResizeObserver() {
+    this.#childRO = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        const narrow = entry.contentBoxSize[0].inlineSize <= SNAP_THRESHOLD;
+        for (const sel of this.querySelectorAll('select-ui')) {
+          sel.setAttribute('placement', narrow ? 'right' : 'bottom-start');
+        }
+      }
+    });
+    this.#childRO.observe(this);
+  }
+
+  // ── Internal — dispatch the toggle event in a consistent shape ──
+
+  #dispatchToggle(expanded) {
+    this.dispatchEvent(new CustomEvent('sidebar-toggle', {
+      bubbles: true,
+      detail: { name: this.name || this.getAttribute('slot') || 'default', expanded },
+    }));
+  }
+}
+
+customElements.define('admin-sidebar', AdminSidebar);
+export { AdminSidebar };

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

@@ -0,0 +1,123 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import '../../../web-components/core/element.js';
+import './admin-sidebar.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 doesn't ship a working ResizeObserver out-of-the-box, and
+// returns zero from getBoundingClientRect (no layout engine). Patch both
+// in beforeEach so connected() doesn't immediately mark every sidebar as
+// collapsed (width <= 96).
+let originalRect;
+beforeEach(() => {
+  document.body.innerHTML = '';
+  try { localStorage.clear(); } catch {}
+  globalThis.ResizeObserver = class {
+    observe() {}
+    unobserve() {}
+    disconnect() {}
+  };
+  // Mock getBoundingClientRect to derive width from inline style (or 240 default)
+  originalRect = HTMLElement.prototype.getBoundingClientRect;
+  HTMLElement.prototype.getBoundingClientRect = function () {
+    const inline = this.style?.width || '';
+    const w = parseFloat(inline) || 240;
+    return { width: w, height: 600, top: 0, left: 0, right: w, bottom: 600, x: 0, y: 0 };
+  };
+});
+
+afterEach(() => {
+  if (originalRect) HTMLElement.prototype.getBoundingClientRect = originalRect;
+});
+
+describe('admin-sidebar', () => {
+  it('registers admin-sidebar as a custom element', () => {
+    expect(customElements.get('admin-sidebar')).toBeDefined();
+  });
+
+  it('defaults to collapsed=false on connect', () => {
+    const sb = mount('<admin-sidebar slot="leading"></admin-sidebar>');
+    expect(sb.collapsed).toBe(false);
+  });
+
+  it('reflects [collapsed] via property assignment', async () => {
+    const sb = mount('<admin-sidebar slot="leading"></admin-sidebar>');
+    sb.collapsed = true;
+    await tick();
+    expect(sb.hasAttribute('collapsed')).toBe(true);
+  });
+
+  it('reflects [resizing] via property assignment', async () => {
+    const sb = mount('<admin-sidebar slot="leading"></admin-sidebar>');
+    sb.resizing = true;
+    await tick();
+    expect(sb.hasAttribute('resizing')).toBe(true);
+  });
+
+  it('exposes .toggle() / .collapse() / .expand() public methods', () => {
+    const sb = mount('<admin-sidebar slot="leading" collapsible></admin-sidebar>');
+    expect(typeof sb.toggle).toBe('function');
+    expect(typeof sb.collapse).toBe('function');
+    expect(typeof sb.expand).toBe('function');
+  });
+
+  it('persists width to localStorage on collapse, restores on connect', async () => {
+    // First mount: set a width, collapse, persisted to localStorage
+    const sb1 = mount('<admin-sidebar slot="leading" collapsible></admin-sidebar>');
+    sb1.style.width = '240px';
+    // happy-dom doesn't compute layout; mock getBoundingClientRect to return our set width
+    sb1.getBoundingClientRect = () => ({ width: 240 });
+    sb1.collapse();
+    expect(sb1.collapsed).toBe(true);
+    // localStorage should hold either the floor or the previous width
+    const stored = localStorage.getItem('adia-sidebar-leading');
+    expect(stored).not.toBeNull();
+  });
+
+  it('uses [name] override for the localStorage key', () => {
+    const sb = mount('<admin-sidebar slot="leading" name="custom-id" collapsible></admin-sidebar>');
+    sb.getBoundingClientRect = () => ({ width: 200 });
+    sb.style.width = '200px';
+    sb.collapse();
+    expect(localStorage.getItem('adia-sidebar-custom-id')).not.toBeNull();
+    expect(localStorage.getItem('adia-sidebar-leading')).toBeNull();
+  });
+
+  it('toggle() returns the new collapsed value', () => {
+    const sb = mount('<admin-sidebar slot="leading" collapsible></admin-sidebar>');
+    sb.getBoundingClientRect = () => ({ width: 200 });
+    sb.style.width = '200px';
+    const result = sb.toggle();
+    expect(result).toBe(sb.collapsed);
+  });
+
+  it('dispatches sidebar-toggle event on toggle()', () => {
+    const sb = mount('<admin-sidebar slot="leading" collapsible></admin-sidebar>');
+    sb.getBoundingClientRect = () => ({ width: 200 });
+    sb.style.width = '200px';
+    const onToggle = vi.fn();
+    sb.addEventListener('sidebar-toggle', onToggle);
+    sb.toggle();
+    expect(onToggle).toHaveBeenCalledTimes(1);
+    expect(onToggle.mock.calls[0][0].detail).toEqual(
+      expect.objectContaining({ name: expect.any(String), expanded: expect.any(Boolean) })
+    );
+  });
+
+  it('cleans up resize handlers on disconnect (no zombie listeners)', () => {
+    const sb = mount('<admin-sidebar slot="leading" resizable><div data-resize></div></admin-sidebar>');
+    const handle = sb.querySelector('[data-resize]');
+    const removeSpy = vi.spyOn(handle, 'removeEventListener');
+    sb.remove();
+    // disconnected() runs cleanup; pointerdown listener should have been removed
+    const removedTypes = removeSpy.mock.calls.map((args) => args[0]);
+    expect(removedTypes).toContain('pointerdown');
+  });
+});

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

@@ -0,0 +1,140 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: AdminSidebar
+tag: admin-sidebar
+component: AdminSidebar
+category: layout
+version: 1
+description: |
+  Module-tier shell sidebar — owns resize, snap-to-collapsed, persistence,
+  and the [collapsed] reflected attribute. Sits inside <admin-shell> as
+  slot="leading" or slot="trailing". Authors compose chrome bars + content
+  inside via slot vocabulary.
+
+  This is the bespoke web-component replacement for the legacy
+  <aside data-sidebar> shape. <admin-shell> still recognizes the legacy
+  shape via :is() selector for backwards compat. New code should prefer
+  <admin-sidebar>.
+
+props:
+  collapsed:
+    description: |
+      Reflected — set when the sidebar's measured width is at or below
+      96px. Consumers query this to style "collapsed mode" without
+      duplicating threshold math.
+    type: boolean
+    default: false
+    reflect: true
+
+  resizing:
+    description: |
+      Reflected — set during an active pointer-drag on the resize handle.
+      Useful for suppressing transitions while dragging.
+    type: boolean
+    default: false
+    reflect: true
+
+  resizable:
+    description: |
+      Opts in to drag-to-resize behavior. Author supplies a child
+      [data-resize] element as the drag handle.
+    type: boolean
+    default: false
+    reflect: true
+
+  collapsible:
+    description: |
+      Opts in to programmatic collapse — toggle button wiring + the
+      .toggle() / .collapse() / .expand() public methods.
+    type: boolean
+    default: false
+    reflect: true
+
+  name:
+    description: |
+      Identifier for localStorage namespacing. Defaults to slot value
+      ("leading" or "trailing"). Override when running multiple sidebars
+      with the same slot.
+    type: string
+    default: ""
+    reflect: true
+
+  min-width:
+    description: |
+      Optional override for the snap-floor width. Defaults to reading
+      CSS min-width via getComputedStyle.
+    type: string
+    default: ""
+    reflect: true
+
+events:
+  sidebar-toggle:
+    description: Bubbles when sidebar collapses or expands.
+    detail:
+      name: string
+      expanded: boolean
+  sidebar-resize:
+    description: Bubbles when an active pointer-drag releases.
+    detail:
+      name: string
+      width: number
+
+slots:
+  default:
+    description: >-
+      Default content — typically a <nav-ui> for navigation, or a list
+      / tree for the trailing inspector pattern.
+  header:
+    description: >-
+      Top chrome bar (workspace select, breadcrumb, etc.).
+  footer:
+    description: >-
+      Bottom chrome bar (user select, status indicator, etc.).
+
+states:
+  - name: idle
+    description: Default, expanded.
+  - name: collapsed
+    attribute: collapsed
+    description: Sidebar width is at or below the snap threshold; CSS
+      container queries flip child layout to icon-only mode.
+  - name: resizing
+    attribute: resizing
+    description: Active pointer-drag in progress.
+
+traits: []
+
+a2ui:
+  rules:
+    - >-
+      admin-sidebar is the bespoke replacement for legacy
+      <aside data-sidebar>. Use slot="leading" or slot="trailing"
+      to position. Add resizable + collapsible attributes to opt in
+      to interactive behaviors.
+    - >-
+      For chrome bars inside the sidebar, prefer <admin-topbar
+      slot="header"> and <admin-statusbar slot="footer"> over raw
+      <header-ui> / <footer-ui> when authoring shell-tier markup.
+
+keywords:
+  - admin-sidebar
+  - sidebar
+  - aside
+  - rail
+  - panel
+  - leading
+  - trailing
+  - inspector
+  - nav
+
+synonyms:
+  sidebar: [aside, rail, panel]
+  collapsed: [minimized, narrow, icon-only]
+
+related:
+  - AdminShell
+  - AdminCommand
+  - Aside
+  - Nav
+  - NavGroup
+  - NavItem

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

@@ -0,0 +1,81 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AdminStatusbar.json",
+  "title": "AdminStatusbar",
+  "description": "Module-tier shell bottom chrome bar. CSS-only — no behavior, no JS.\nSame shape as <admin-topbar> (icon + heading + description + action\nclusters via slot vocabulary), conventionally used for read-only\nstatus — connection state, sync indicator, footer metadata.\n\nReplaces legacy <footer-ui> usage at shell-tier. Both still work per\nADR-0023 backwards-compat.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "AdminStatusbar"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "events": {},
+    "examples": [],
+    "keywords": [
+      "admin-statusbar",
+      "statusbar",
+      "footer-bar",
+      "app-footer",
+      "status-line"
+    ],
+    "name": "AdminStatusbar",
+    "related": [
+      "AdminShell",
+      "AdminContent",
+      "AdminTopbar",
+      "Footer"
+    ],
+    "slots": {
+      "description": {
+        "description": "Secondary metadata."
+      },
+      "default": {
+        "description": "Default content — status text or inline children."
+      },
+      "action": {
+        "description": "Trailing control cluster."
+      },
+      "action-leading": {
+        "description": "Leading control cluster."
+      },
+      "heading": {
+        "description": "Primary label."
+      },
+      "icon": {
+        "description": "Leading glyph (icon-ui or img)."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, the only state.",
+        "name": "idle"
+      }
+    ],
+    "synonyms": {
+      "statusbar": [
+        "status-line",
+        "footer-bar",
+        "app-footer"
+      ]
+    },
+    "tag": "admin-statusbar",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

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

@@ -0,0 +1,29 @@
+<header>
+    <div>
+      <h1>Admin Statusbar</h1>
+      <div data-actions>
+        <tag-ui size="sm">admin-statusbar</tag-ui>
+        <tag-ui size="sm" variant="ghost">CSS-only</tag-ui>
+      </div>
+    </div>
+    <p>Module-tier shell bottom chrome bar. Same shape as admin-topbar; conventionally read-only status.</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-statusbar&gt;
+  &lt;icon-ui slot="icon" name="check-circle"&gt;&lt;/icon-ui&gt;
+  &lt;span&gt;Synced just now · 12 changes&lt;/span&gt;
+&lt;/admin-statusbar&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-statusbar/admin-statusbar.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 Statusbar — 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-statusbar.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-statusbar.examples.html — ${err.message}</p>`;
+      console.error('[admin-statusbar.html]', err);
+    }
+  </script>
+
+</body>
+</html>