@adia-ai/web-modules 0.6.20 → 0.6.22

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

@@ -5,10 +5,20 @@ 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.
+  Behavior-only application shell. Canonical authoring shape uses
+  cluster-namespaced bespoke children — <admin-topbar> at the top,
+  <admin-sidebar slot="leading|trailing"> rails, <admin-content> for
+  the main content region, <admin-command> for the Cmd+K palette, and
+  optional <admin-statusbar> at the bottom. The shell wires sidebar
+  toggle forwarding, command-palette triggers, and the ResizeObserver
+  that drives responsive sidebar collapse; each bespoke child owns
+  its own resize / collapse / open state-as-attribute semantics per
+  ADR-0023.
+
+  Legacy data-attribute shapes (<aside data-sidebar>, <dialog
+  data-command>, [data-resize], <aside-ui slot=>, <span data-spacer>,
+  <div data-actions>) were RETIRED in v0.4.0 per ADR-0024 and are no
+  longer recognized. Consumers must use the bespoke vocabulary.
 
 props:
   mode:
@@ -46,12 +56,17 @@ events:
 slots:
   default:
     description: >-
-      Author-supplied page DOM. Expected structure — aside[data-sidebar] for
-      navigation, main for content, optional dialog[data-command] for Cmd+K.
+      Bespoke children compose here in document order — <admin-topbar>,
+      <admin-sidebar slot="leading">, <admin-content> (containing
+      <admin-page> / <admin-page-header> / <admin-page-body>),
+      <admin-sidebar slot="trailing">, <admin-command>, optional
+      <admin-statusbar>. The shell's grid layout reads child tag
+      selectors to place them.
   icon:
     description: >-
-      Leading glyph inside any chrome bar — > main > header / footer and
-      [data-sidebar] > header / footer. Muted color, flex-align.
+      Leading glyph inside any chrome bar (<admin-topbar>,
+      <admin-statusbar>, <admin-sidebar> header/footer). Muted color,
+      flex-align.
   heading:
     description: >-
       Primary label inside any chrome bar. Medium-weight + strong fg.
@@ -62,15 +77,12 @@ slots:
     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.
+      subsequent siblings flow with gap.
   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
@@ -87,9 +99,27 @@ 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.
+      admin-shell takes bespoke admin-* children only. The canonical
+      composition is <admin-topbar> + <admin-sidebar slot="leading">
+      + <admin-content> + <admin-sidebar slot="trailing"> +
+      <admin-command> + optional <admin-statusbar>. The shell's CSS
+      grid reads child tag selectors to place them.
+    - >-
+      Don't nest col-ui / row-ui or generic layout primitives directly
+      inside admin-shell — app-shell.css handles grid layout based on
+      bespoke child tags. Generic layout goes inside <admin-content>
+      or inside <admin-page-body>.
+    - >-
+      Click forwarding patterns — [data-sidebar-toggle="<name>"] on a
+      button forwards to <admin-sidebar[slot="<name>"]>.toggle();
+      [data-command-trigger] on a button forwards to
+      <admin-command>.show(). The shell doesn't need to know about
+      the buttons; the bespoke children own the behavior.
+    - >-
+      Legacy data-attribute shapes were retired in v0.4.0 per ADR-0024.
+      Do not author <aside data-sidebar>, <dialog data-command>,
+      [data-resize], <aside-ui slot=>, <span data-spacer>, or
+      <div data-actions> inside admin-shell.
 
 keywords: [app-shell, shell, layout, admin, dashboard, sidebar, nav]
 synonyms:

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

@@ -34,7 +34,7 @@ admin-sidebar > admin-topbar {
   display: flex;
   align-items: center;
   gap: var(--page-header-gap);
-  padding: 0 var(--page-content-inset);
+  padding: 0 var(--a-space-3);
   height: var(--page-header-height);
   font-size: var(--page-header-font);
   border-bottom: var(--page-border);
@@ -48,7 +48,7 @@ admin-sidebar > admin-statusbar {
   display: flex;
   align-items: center;
   gap: var(--page-header-gap);
-  padding: 0 var(--page-content-inset);
+  padding: 0 var(--a-space-3);
   height: var(--page-header-height);
   font-size: var(--page-header-font);
   color: var(--page-header-fg-muted);

package/shell/admin-shell/css/admin-shell.entity-item.css

@@ -22,8 +22,13 @@
    ═══════════════════════════════════════════════════════════════ */
 
 admin-entity-item {
-  /* ── tunable tokens ── */
-  --entity-item-gap:         var(--a-space-2);
+  /* ── tunable tokens ──
+     Gap + horizontal padding match <select-ui>'s trigger row and
+     <nav-item-ui>'s row (shared convention: --a-space-1 between
+     slots, --a-ui-px on each inline edge). Consumers can opt out
+     by setting --entity-item-px: 0 on a per-use basis. */
+  --entity-item-gap:         var(--a-space-1);
+  --entity-item-px:          var(--a-ui-px);
   --entity-item-icon-size:   1rem;
   --entity-item-icon-color:  var(--a-fg-muted);
   --entity-item-avatar-size: 1.5rem;
@@ -31,6 +36,7 @@ admin-entity-item {
   display: inline-flex;
   align-items: center;
   gap: var(--entity-item-gap);
+  padding: 0 var(--entity-item-px);
   min-width: 0;
   overflow: hidden;
 }

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

@@ -83,8 +83,14 @@ admin-page-header > :is(header, header-ui)[data-compact] {
   padding-block: var(--page-header-px);
 }
 
-/* Title row: h1 left, actions right */
-admin-page-header > :is(header, header-ui) > div:first-child {
+/* Title row: h1 left, actions right.
+   `:first-of-type` (not `:first-child`) so the row still matches when a
+   non-<div> element is prepended ahead of it — e.g. the
+   `<span data-chunk-marker>` the `?chunks` dev overlay (site/dev-chunks.js)
+   injects as the first child of every `[data-chunk]` element. With
+   `:first-child` the prepended span won the match and the title + actions
+   stacked instead of sitting on one row. */
+admin-page-header > :is(header, header-ui) > div:first-of-type {
   display: flex;
   align-items: center;
   justify-content: space-between;
@@ -176,13 +182,24 @@ admin-page-body > iframe {
   }
 }
 
-/* Tighten the content gutter when the article is genuinely narrow. */
+/* Tighten the content gutter at medium width (tablet / narrow desktop). */
+@container page-content (max-width: 768px) {
+  admin-page-header > :is(header, header-ui),
+  admin-page-body > :is(section, section-ui) {
+    padding-inline: var(--a-space-8);
+  }
+  admin-page-body > :is(section, section-ui) {
+    padding-block: var(--a-space-8);
+  }
+}
+
+/* Tighten further when the article is genuinely narrow (phone). */
 @container page-content (max-width: 480px) {
   admin-page-header > :is(header, header-ui),
   admin-page-body > :is(section, section-ui) {
-    padding-inline: var(--a-space-4);
+    padding-inline: var(--a-space-6);
   }
   admin-page-body > :is(section, section-ui) {
-    padding-block: var(--a-space-4);
+    padding-block: var(--a-space-6);
   }
 }

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

@@ -2,7 +2,7 @@
   "$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",
+  "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 per ADR-0023. The legacy shape was\nretired in v0.4.0 per ADR-0024 and is no longer recognized.\n",
   "type": "object",
   "allOf": [
     {

package/shell/admin-sidebar/admin-sidebar.d.ts

@@ -5,9 +5,8 @@ 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>.
+<aside data-sidebar> shape per ADR-0023. The legacy shape was
+retired in v0.4.0 per ADR-0024 and is no longer recognized.
 
  *
  * @see https://ui-kit.exe.xyz/site/components/admin-sidebar

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

@@ -12,9 +12,8 @@ description: |
   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>.
+  <aside data-sidebar> shape per ADR-0023. The legacy shape was
+  retired in v0.4.0 per ADR-0024 and is no longer recognized.
 
 props:
   collapsed:
@@ -115,6 +114,10 @@ a2ui:
       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.
+    - rule: '[resizable] attribute enables drag-resize via internal <pane-ui resizable>; persists collapsed/width to localStorage under adia-sidebar-* keys.'
+      reason: 'Resize + persistence behavior.'
+    - rule: 'For non-resizable static rails (fixed-width nav), omit [resizable]; the same primitive serves both modes.'
+      reason: 'Single primitive, two modes.'
 
 keywords:
   - admin-sidebar

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

@@ -2,7 +2,7 @@
   "$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",
+  "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 per ADR-0023. The\nlegacy shape was retired in v0.4.0 per ADR-0024 and is no longer\nrecognized; new code uses <admin-statusbar> for shell-tier chrome\n(use <footer-ui> for primitive containers like Card / Drawer /\nModal).\n",
   "type": "object",
   "allOf": [
     {

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

@@ -11,8 +11,11 @@ description: |
   clusters via slot vocabulary), conventionally used for read-only
   status — connection state, sync indicator, footer metadata.
 
-  Replaces legacy <footer-ui> usage at shell-tier. Both still work per
-  ADR-0023 backwards-compat.
+  Replaces legacy <footer-ui> usage at shell-tier per ADR-0023. The
+  legacy shape was retired in v0.4.0 per ADR-0024 and is no longer
+  recognized; new code uses <admin-statusbar> for shell-tier chrome
+  (use <footer-ui> for primitive containers like Card / Drawer /
+  Modal).
 
 props: {}
 
@@ -50,17 +53,15 @@ a2ui:
       admin-statusbar replaces <footer-ui> at shell-tier. Same slot
       vocabulary as <admin-topbar>; visual treatment differs (the
       shell css applies a top-border instead of bottom).
-    - >-
-      When placed inside <admin-sidebar> or <admin-content>, admin-statusbar
-      MUST carry slot="footer". Without it the statusbar lands in the
-      default body slot instead of the chrome footer band. Canonical:
-      <admin-statusbar slot="footer">…</admin-statusbar>. admin-shell logs
-      a one-shot console.warn when the slot is missing.
     - >-
       For a user-identity row (avatar + name + role badge), slot a single
       <admin-entity-item slot="heading"> rather than separate slot="icon" +
       slot="heading" children — the wrapper collapses the name + badge
       together inside a collapsible <admin-sidebar>, keeping the avatar.
+    - rule: 'All slots optional; common pattern is [slot="heading"] + [slot="action"] only. Empty admin-statusbar renders zero-height (no visual chrome).'
+      reason: 'Cardinality — fully optional content.'
+    - rule: 'Sits at slot="footer" of <admin-shell>, <admin-content>, or <admin-sidebar>; do not place inside <admin-page slot="footer"> (use raw <footer-ui> there).'
+      reason: 'Shell-tier vs page-tier boundary.'
 
 keywords:
   - admin-statusbar

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

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/AdminTopbar.json",
   "title": "AdminTopbar",
-  "description": "Module-tier shell top chrome bar. CSS-only — no behavior, no JS.\nSits at the top of <admin-content>, <admin-sidebar>, or any chrome\nregion. Provides the canonical icon + heading + description +\naction-clusters layout via slot vocabulary.\n\nReplaces the legacy <header-ui> usage at shell-tier. Both still work\nper ADR-0023 backwards-compat; new code should prefer <admin-topbar>\nfor shell-tier chrome bars (use <header-ui> for primitive containers\nlike Card / Drawer / Modal).\n",
+  "description": "Module-tier shell top chrome bar. CSS-only — no behavior, no JS.\nSits at the top of <admin-content>, <admin-sidebar>, or any chrome\nregion. Provides the canonical icon + heading + description +\naction-clusters layout via slot vocabulary.\n\nReplaces the legacy <header-ui> usage at shell-tier per ADR-0023.\nThe legacy shape was retired in v0.4.0 per ADR-0024 and is no\nlonger recognized; new code uses <admin-topbar> for shell-tier\nchrome bars (use <header-ui> for primitive containers like Card /\nDrawer / Modal).\n",
   "type": "object",
   "allOf": [
     {

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

@@ -11,10 +11,11 @@ description: |
   region. Provides the canonical icon + heading + description +
   action-clusters layout via slot vocabulary.
 
-  Replaces the legacy <header-ui> usage at shell-tier. Both still work
-  per ADR-0023 backwards-compat; new code should prefer <admin-topbar>
-  for shell-tier chrome bars (use <header-ui> for primitive containers
-  like Card / Drawer / Modal).
+  Replaces the legacy <header-ui> usage at shell-tier per ADR-0023.
+  The legacy shape was retired in v0.4.0 per ADR-0024 and is no
+  longer recognized; new code uses <admin-topbar> for shell-tier
+  chrome bars (use <header-ui> for primitive containers like Card /
+  Drawer / Modal).
 
 props: {}
 
@@ -56,18 +57,16 @@ a2ui:
       admin-topbar replaces <header-ui> at shell-tier — use it for
       chrome bars inside admin-shell, admin-content, admin-sidebar.
       Use <header-ui> for primitive containers (Card / Drawer / Modal).
-    - >-
-      When placed inside <admin-sidebar> or <admin-content>, admin-topbar
-      MUST carry slot="header". Without it the topbar lands in the default
-      body slot and renders below the content instead of as the chrome
-      header band. Canonical: <admin-topbar slot="header">…</admin-topbar>.
-      admin-shell logs a one-shot console.warn when the slot is missing.
     - >-
       For an icon + label (+ optional badge) identity row — workspace or
       product identity — slot a single <admin-entity-item slot="heading">
       rather than separate slot="icon" + slot="heading" children. The
       wrapper keeps the icon and label as one unit so they truncate and
       collapse together inside a collapsible <admin-sidebar>.
+    - rule: 'All slots optional; common pattern is [slot="heading"] + [slot="action"] only. Empty admin-topbar renders zero-height (no visual chrome).'
+      reason: 'Cardinality — fully optional content.'
+    - rule: 'Sits at slot="header" of <admin-shell>, <admin-content>, or <admin-sidebar>; do not place inside <admin-page slot="header"> (use <admin-page-header> there).'
+      reason: 'Shell-tier vs page-tier boundary.'
 
 keywords:
   - admin-topbar

package/simple/simple-content/simple-content.yaml

@@ -36,6 +36,10 @@ a2ui:
     - >-
       simple-content is the article surface inside simple-shell. Use
       for primary page body. Sibling to <simple-hero> (optional).
+    - rule: 'CSS-only — do not import its JS module (there isn''t one); does not need an `import` in shell HTML.'
+      reason: 'CSS-only primitives don''t need JS-side registration.'
+    - rule: 'For multi-page apps with chrome (nav, topbar, command palette) use <admin-shell-ui> with <admin-content> instead.'
+      reason: 'Surface decision rule — simple vs admin.'
 
 keywords:
   - simple-content

package/simple/simple-hero/simple-hero.yaml

@@ -39,6 +39,10 @@ a2ui:
       simple-hero is the optional top strip inside simple-shell. Use
       for marketing splashes, error-page reassurance text, or single-
       flow page intros. Always followed by <simple-content> for body.
+    - rule: 'Three named slots: heading (large title), lede (supporting subtitle), actions (button cluster). All optional but order is fixed.'
+      reason: 'Slot contract.'
+    - rule: 'CSS-only — sibling to <simple-content> inside <simple-shell>. Do not nest hero inside content or vice versa.'
+      reason: 'Composition discipline.'
 
 keywords:
   - simple-hero

package/simple/simple-shell/simple-shell.yaml

@@ -59,6 +59,10 @@ a2ui:
       Compose with <simple-hero> (optional top hero strip) and
       <simple-content> (main article body). Both are CSS-only structural
       children — no JS, no state.
+    - rule: '[centered] reflected attribute centers content vertically; [full-bleed] drops the max-width constraint on <simple-content> children. Both optional, default unset.'
+      reason: 'Layout-mode knobs.'
+    - rule: 'For multi-page apps with chrome (nav, topbar, command palette) use <admin-shell> instead; simple-shell has zero chrome.'
+      reason: 'Simple vs admin decision rule.'
 
 keywords:
   - simple-shell