@adia-ai/web-modules 0.3.2 → 0.3.4

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

@@ -0,0 +1,198 @@
+/* ═══════════════════════════════════════════════════════════════
+   admin-shell — Bespoke shell-tier children (Phase 2 of ADR-0023)
+
+   The admin-* CSS-only structural children are styled by SHARING the
+   same CSS rules as their legacy raw-HTML counterparts. This file
+   re-applies the existing selectors (main / section / header / footer)
+   to the new bespoke tags via display + structural mappings.
+
+   Rather than duplicate every rule in main.css / sidebar.css /
+   templates.css, we declare the bespoke tags as `display: contents` or
+   the relevant layout box, then let the existing selectors (which
+   already use :is() lifts for legacy + slot-vocabulary) match.
+
+   For Phase 2, the simplest map: each bespoke tag mimics its legacy
+   counterpart's display behavior. The host shell.css already handles
+   admin-shell flex layout; main.css handles main-as-column; sidebar.css
+   handles sidebar geometry.
+   ═══════════════════════════════════════════════════════════════ */
+
+/* ── admin-content ≡ <main> ── */
+admin-shell > admin-content {
+  display: flex;
+  flex-direction: column;
+  flex: 1;
+  min-width: 0;
+  min-height: 0;
+  border-inline: var(--page-main-border);
+}
+
+/* ── admin-topbar ≡ <header-ui> at shell tier ── */
+admin-content > admin-topbar,
+admin-shell > admin-topbar,
+:is([data-sidebar], aside-ui[slot="leading"], aside-ui[slot="trailing"], admin-sidebar) > admin-topbar {
+  display: flex;
+  align-items: center;
+  gap: var(--page-header-gap);
+  padding: 0 var(--page-header-px);
+  height: var(--page-header-height);
+  font-size: var(--page-header-font);
+  border-bottom: var(--page-border);
+  flex-shrink: 0;
+}
+
+/* ── admin-statusbar ≡ <footer-ui> at shell tier ── */
+admin-content > admin-statusbar,
+admin-shell > admin-statusbar,
+:is([data-sidebar], aside-ui[slot="leading"], aside-ui[slot="trailing"], admin-sidebar) > admin-statusbar {
+  display: flex;
+  align-items: center;
+  gap: var(--page-header-gap);
+  padding: 0 var(--page-header-px);
+  height: var(--page-header-height);
+  font-size: var(--page-header-font);
+  color: var(--page-header-fg-muted);
+  border-top: var(--page-border);
+  flex-shrink: 0;
+}
+
+/* ── admin-scroll ≡ <section> child of <main> ── */
+admin-content > admin-scroll {
+  flex: 1;
+  min-height: 0;
+  overflow-y: auto;
+  overscroll-behavior: contain;
+  background: var(--page-content-bg);
+  border-inline: var(--page-content-border);
+  box-shadow: var(--page-content-shadow);
+}
+
+admin-shell[mode~="rounded"] > admin-content > admin-scroll {
+  border-radius: var(--page-content-radius);
+}
+
+/* ── admin-page ≡ <article data-content-root> ── */
+admin-scroll > admin-page,
+admin-content > admin-page {
+  display: flex;
+  flex-direction: column;
+  min-height: 100%;
+  container-type: inline-size;
+  container-name: page-content;
+}
+
+/* ── admin-page-header ≡ <[data-content-header]> sticky band ── */
+admin-page > admin-page-header {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  background: var(--page-content-bg);
+  border-bottom: var(--page-content-border);
+  flex-shrink: 0;
+}
+
+/* ── admin-page-body ≡ <[data-content-body]> centered body ── */
+admin-page > admin-page-body {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+}
+
+/* ── admin-sidebar — bridge to existing sidebar.css selectors ──
+   Rather than expand every :is([data-sidebar], aside-ui[slot=…], …)
+   selector in sidebar.css with `, admin-sidebar[slot=…]`, we apply the
+   core sidebar geometry + container query rules here. The remaining
+   slot-routing rules in sidebar.css (header/footer chrome, section,
+   nav-ui colors) match by descendant selector rather than parent
+   tag, so they pick up admin-sidebar children automatically. */
+
+:is(admin-sidebar[slot="leading"], admin-sidebar[slot="trailing"]) {
+  display: flex;
+  flex-direction: column;
+  flex-shrink: 0;
+  min-width: var(--page-sidebar-min-width);
+  max-width: var(--page-sidebar-max-width);
+  min-height: 0;
+  font-size: var(--page-sidebar-font);
+  position: relative;
+  container-type: inline-size;
+  container-name: sidebar;
+  transition: width var(--page-duration) var(--page-easing);
+  background: var(--page-bg);
+}
+
+admin-sidebar[slot="leading"] {
+  width: var(--page-sidebar-width-leading);
+  border-right: var(--page-border);
+}
+
+admin-sidebar[slot="trailing"] {
+  width: var(--page-sidebar-width-trailing);
+  border-left: var(--page-border);
+}
+
+/* Resize handle — same shape as legacy [data-sidebar] > [data-resize] */
+:is(admin-sidebar[slot="leading"], admin-sidebar[slot="trailing"]) > [data-resize] {
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  width: 6px;
+  cursor: col-resize;
+  z-index: 1;
+  user-select: none;
+}
+
+admin-sidebar[slot="leading"] > [data-resize] { right: -3px; }
+admin-sidebar[slot="trailing"] > [data-resize] { left: -3px; }
+
+:is(admin-sidebar[slot="leading"], admin-sidebar[slot="trailing"]) > [data-resize]:hover {
+  background: var(--page-sidebar-resize-accent);
+  opacity: 0.5;
+}
+
+admin-sidebar[resizing] {
+  transition: none;
+}
+
+admin-sidebar[resizing] > [data-resize] {
+  background: var(--page-sidebar-resize-accent);
+  opacity: 0.8;
+}
+
+/* When collapsed, suppress text labels in slot vocabulary children
+   inside the sidebar via the bespoke [collapsed] reflected attribute */
+admin-sidebar[collapsed] {
+  /* Container query in collapsed.css already handles narrow-mode children;
+     this rule is a backup for browsers without container query support. */
+}
+
+/* ── Slot vocabulary inside topbar/statusbar ──
+   Uniform action-cluster routing — same shape used inside
+   header-ui, footer-ui, and now admin-topbar/admin-statusbar. */
+
+:is(admin-topbar, admin-statusbar) {
+  /* Default: action cluster pushes itself + siblings to the end */
+}
+
+:is(admin-topbar, admin-statusbar) > [slot="action"]:first-of-type {
+  margin-inline-start: auto;
+}
+
+:is(admin-topbar, admin-statusbar) > [slot="action-leading"] {
+  margin-inline-end: var(--page-actions-gap);
+}
+
+:is(admin-topbar, admin-statusbar) > [slot="icon"] {
+  color: var(--page-header-fg-muted);
+  flex-shrink: 0;
+}
+
+:is(admin-topbar, admin-statusbar) > [slot="heading"] {
+  font-weight: var(--a-weight-medium, 500);
+  color: var(--a-fg);
+}
+
+:is(admin-topbar, admin-statusbar) > [slot="description"] {
+  color: var(--page-header-fg-muted);
+  font-size: var(--a-ui-sm);
+}

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

@@ -89,6 +89,16 @@
   --page-font-family:         var(--a-font-family);
   --page-body-size:           var(--a-body-size);
 
+  /* ── Nav tokens — shell-context overrides ──
+     These are NOT the canonical nav tokens. The canonical tokens live in
+     each nav primitive's @scope :where():
+       packages/web-components/components/nav/nav.css
+       packages/web-components/components/nav-group/nav-group.css
+       packages/web-components/components/nav-item/nav-item.css
+     The overrides below adjust nav presentation specifically when nested
+     inside <admin-shell>. Outside the shell, nav primitives fall back to
+     their own :where() declarations. */
+
   /* Nav — root container tokens */
   --nav-duration:             var(--a-duration);
   --nav-duration-fast:        var(--a-duration-fast);

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

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AdminSidebar.json",
+  "title": "AdminSidebar",
+  "description": "Module-tier shell sidebar — owns resize, snap-to-collapsed, persistence,\nand the [collapsed] reflected attribute. Sits inside <admin-shell> as\nslot=\"leading\" or slot=\"trailing\". Authors compose chrome bars + content\ninside via slot vocabulary.\n\nThis is the bespoke web-component replacement for the legacy\n<aside data-sidebar> shape. <admin-shell> still recognizes the legacy\nshape via :is() selector for backwards compat. New code should prefer\n<admin-sidebar>.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "collapsed": {
+      "description": "Reflected — set when the sidebar's measured width is at or below\n96px. Consumers query this to style \"collapsed mode\" without\nduplicating threshold math.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "collapsible": {
+      "description": "Opts in to programmatic collapse — toggle button wiring + the\n.toggle() / .collapse() / .expand() public methods.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "component": {
+      "const": "AdminSidebar"
+    },
+    "min-width": {
+      "description": "Optional override for the snap-floor width. Defaults to reading\nCSS min-width via getComputedStyle.\n",
+      "type": "string",
+      "default": ""
+    },
+    "name": {
+      "description": "Identifier for localStorage namespacing. Defaults to slot value\n(\"leading\" or \"trailing\"). Override when running multiple sidebars\nwith the same slot.\n",
+      "type": "string",
+      "default": ""
+    },
+    "resizable": {
+      "description": "Opts in to drag-to-resize behavior. Author supplies a child\n[data-resize] element as the drag handle.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "resizing": {
+      "description": "Reflected — set during an active pointer-drag on the resize handle.\nUseful for suppressing transitions while dragging.\n",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "events": {
+      "sidebar-resize": {
+        "description": "Bubbles when an active pointer-drag releases.",
+        "detail": {
+          "name": "string",
+          "width": "number"
+        }
+      },
+      "sidebar-toggle": {
+        "description": "Bubbles when sidebar collapses or expands.",
+        "detail": {
+          "expanded": "boolean",
+          "name": "string"
+        }
+      }
+    },
+    "examples": [],
+    "keywords": [
+      "admin-sidebar",
+      "sidebar",
+      "aside",
+      "rail",
+      "panel",
+      "leading",
+      "trailing",
+      "inspector",
+      "nav"
+    ],
+    "name": "AdminSidebar",
+    "related": [
+      "AdminShell",
+      "AdminCommand",
+      "Aside",
+      "Nav",
+      "NavGroup",
+      "NavItem"
+    ],
+    "slots": {
+      "default": {
+        "description": "Default content — typically a <nav-ui> for navigation, or a list / tree for the trailing inspector pattern."
+      },
+      "footer": {
+        "description": "Bottom chrome bar (user select, status indicator, etc.)."
+      },
+      "header": {
+        "description": "Top chrome bar (workspace select, breadcrumb, etc.)."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, expanded.",
+        "name": "idle"
+      },
+      {
+        "description": "Sidebar width is at or below the snap threshold; CSS container queries flip child layout to icon-only mode.",
+        "attribute": "collapsed",
+        "name": "collapsed"
+      },
+      {
+        "description": "Active pointer-drag in progress.",
+        "attribute": "resizing",
+        "name": "resizing"
+      }
+    ],
+    "synonyms": {
+      "collapsed": [
+        "minimized",
+        "narrow",
+        "icon-only"
+      ],
+      "sidebar": [
+        "aside",
+        "rail",
+        "panel"
+      ]
+    },
+    "tag": "admin-sidebar",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

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

@@ -0,0 +1,76 @@
+<header>
+    <div>
+      <h1>Admin Sidebar</h1>
+      <div data-actions>
+        <tag-ui size="sm">admin-sidebar</tag-ui>
+      </div>
+    </div>
+    <p>Module-tier shell sidebar — owns resize, snap-to-collapsed, persistence, and the <code>[collapsed]</code> reflected attribute. Sits inside <code>&lt;admin-shell&gt;</code> as <code>slot="leading"</code> or <code>slot="trailing"</code>. Authors compose chrome bars + content inside via slot vocabulary.</p>
+  </header>
+
+<section data-section>
+  <h2 variant="section">Basic shape</h2>
+  <p data-note>Drop into <code>&lt;admin-shell&gt;</code> as a slotted child. Add <code>resizable</code> to wire the drag handle, <code>collapsible</code> to wire programmatic collapse.</p>
+  <code-ui language="html">&lt;admin-sidebar slot="leading" resizable collapsible&gt;
+  &lt;admin-topbar slot="header"&gt;…&lt;/admin-topbar&gt;
+  &lt;nav-ui&gt;…&lt;/nav-ui&gt;
+  &lt;admin-statusbar slot="footer"&gt;…&lt;/admin-statusbar&gt;
+  &lt;div data-resize&gt;&lt;/div&gt;
+&lt;/admin-sidebar&gt;</code-ui>
+</section>
+
+<section data-section>
+  <h2 variant="section">State as attribute</h2>
+  <p>The sidebar reflects its state on the element itself — no <code>data-*</code> proxy attributes, no threshold math from the outside.</p>
+  <table>
+    <thead><tr><th>Attribute</th><th>When set</th><th>Use for</th></tr></thead>
+    <tbody>
+      <tr><td><code>collapsed</code></td><td>Width is at or below 96px (snap floor)</td><td>CSS <code>:has(admin-sidebar[collapsed])</code> selectors; JS <code>.hasAttribute('collapsed')</code></td></tr>
+      <tr><td><code>resizing</code></td><td>Active pointer-drag</td><td>Suppress transitions during drag</td></tr>
+    </tbody>
+  </table>
+  <p data-note>The reflection is round-tripped — set <code>collapsed</code> programmatically and the sidebar will width-snap; release the attribute and it expands to the previously-saved width.</p>
+</section>
+
+<section data-section>
+  <h2 variant="section">Public methods</h2>
+  <table>
+    <thead><tr><th>Method</th><th>Effect</th></tr></thead>
+    <tbody>
+      <tr><td><code>.toggle()</code></td><td>Flip collapsed state. Returns the new <code>collapsed</code> value.</td></tr>
+      <tr><td><code>.collapse()</code></td><td>Force collapsed (idempotent if already collapsed).</td></tr>
+      <tr><td><code>.expand()</code></td><td>Restore the previous expanded width.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Events</h2>
+  <table>
+    <thead><tr><th>Event</th><th>Detail</th></tr></thead>
+    <tbody>
+      <tr><td><code>sidebar-toggle</code></td><td><code>{ name, expanded }</code> — bubbles when collapsed/expanded</td></tr>
+      <tr><td><code>sidebar-resize</code></td><td><code>{ name, width }</code> — bubbles after a pointer-drag releases</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Properties</h2>
+  <table>
+    <thead><tr><th>Prop</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
+    <tbody>
+      <tr><td><code>resizable</code></td><td>boolean</td><td><code>false</code></td><td>Opts in to drag-to-resize. Author supplies a child <code>[data-resize]</code> element.</td></tr>
+      <tr><td><code>collapsible</code></td><td>boolean</td><td><code>false</code></td><td>Opts in to <code>.toggle()</code>/<code>.collapse()</code>/<code>.expand()</code>.</td></tr>
+      <tr><td><code>name</code></td><td>string</td><td>(slot value)</td><td>localStorage namespace override.</td></tr>
+      <tr><td><code>min-width</code></td><td>string</td><td>(CSS min-width)</td><td>Override for the snap-floor width.</td></tr>
+      <tr><td><code>collapsed</code></td><td>boolean</td><td>—</td><td>Reflected — set when width ≤ 96px.</td></tr>
+      <tr><td><code>resizing</code></td><td>boolean</td><td>—</td><td>Reflected — set during active drag.</td></tr>
+    </tbody>
+  </table>
+</section>
+
+<section data-section>
+  <h2 variant="section">Persistence</h2>
+  <p>Width is saved to <code>localStorage</code> on every drag release + every toggle, under the key <code>adia-sidebar-{name}</code> (where <code>name</code> defaults to the slot value). On reconnect, the saved width is restored — the &ldquo;previous expanded width&rdquo; tracker preserves the user's preferred expanded size across collapse cycles.</p>
+</section>

package/shell/admin-sidebar/admin-sidebar.html

@@ -0,0 +1,47 @@
+<!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 Sidebar — AdiaUI</title>
+
+  <!-- Token base -->
+  <link rel="stylesheet" href="../../../web-components/styles/resets.css">
+  <link rel="stylesheet" href="../../../web-components/styles/tokens.css">
+
+  <!-- Component CSS — admin-sidebar inherits from admin-shell tokens
+       when nested inside one; standalone styling below for the demo. -->
+  <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">
+
+  <!-- Component JS -->
+  <script type="module" src="./admin-sidebar.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-sidebar.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-sidebar.examples.html — ${err.message}</p>`;
+      console.error('[admin-sidebar.html]', err);
+    }
+  </script>
+
+</body>
+</html>