@adia-ai/web-components 0.0.28 → 0.0.33

package/components/nav/nav.yaml

@@ -0,0 +1,114 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UINav
+tag: nav-ui
+component: Nav
+category: layout
+version: 1
+description: |
+  Navigation rail. Consolidates the prior `app-nav-ui` + `section-nav-ui`
+  pair per ADR-0015 § Nav consolidation. [variant] drives visual
+  treatment; behavior is unified.
+
+  Default variant ("primary") is the app-sidebar nav: ResizeObserver
+  collapses to icon-only below 96px, groups open a popover when
+  collapsed. [variant="section"] is a subnav rail with quieter chrome
+  and a [heading] kicker rendered via CSS.
+
+props:
+  variant:
+    type: string
+    default: primary
+    enum: [primary, section]
+    description: "Visual treatment. primary = app sidebar; section = subnav rail."
+  collapsed:
+    type: boolean
+    default: false
+    description: "Primary-variant only. Force icon-only collapse regardless of viewport width."
+  divider:
+    type: boolean
+    default: false
+    description: "Auto-place dividers between adjacent groups + items."
+  heading:
+    type: string
+    default: ''
+    description: "Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only."
+
+events:
+  nav-select:
+    description: "Bubbles from <nav-item-ui> children when one is selected. Detail: { item, text, value }."
+
+slots:
+  default:
+    description: "Primary slot — accepts <nav-group-ui> + <nav-item-ui> children, plus <hr data-nav-divider> for hand-placed dividers."
+
+states:
+  - name: idle
+    description: Default, not collapsed.
+  - name: collapsed
+    description: Primary variant when [collapsed] or container width <= 96px.
+
+traits: []
+tokens: {}
+a2ui:
+  rules: []
+anti_patterns: []
+
+examples:
+  - name: primary
+    description: App sidebar nav with groups + items.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Nav",
+          "children": ["g1", "i1"]
+        },
+        {
+          "id": "g1",
+          "component": "NavGroup",
+          "text": "Settings",
+          "icon": "gear",
+          "children": ["g1i1"]
+        },
+        {
+          "id": "g1i1",
+          "component": "NavItem",
+          "text": "General",
+          "value": "/settings/general"
+        },
+        {
+          "id": "i1",
+          "component": "NavItem",
+          "text": "Profile",
+          "icon": "user",
+          "value": "/profile"
+        }
+      ]
+  - name: section
+    description: Subnav rail with heading.
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Nav",
+          "variant": "section",
+          "heading": "On this page",
+          "children": ["i1", "i2"]
+        },
+        {
+          "id": "i1",
+          "component": "NavItem",
+          "text": "Overview",
+          "value": "#overview"
+        },
+        {
+          "id": "i2",
+          "component": "NavItem",
+          "text": "API",
+          "value": "#api"
+        }
+      ]
+
+keywords: [nav, navigation, sidebar, menu, links]
+synonyms: {}
+related: []

package/components/nav-group/nav-group.a2ui.json

@@ -0,0 +1,100 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/NavGroup.json",
+  "title": "NavGroup",
+  "description": "Collapsible labeled group of <nav-item-ui> children inside <nav-ui>.\nConsolidates the prior `app-nav-group-ui` + `section-nav-group-ui`\nper ADR-0015 § Nav consolidation.\n\nWhen the parent <nav-ui> is collapsed (primary variant), clicking the\ngroup opens a popover with its children instead of toggling inline\nexpansion. Inline click + keyboard (Enter/Space) toggle is supported\nwhen [collapsible] (default true).\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "badge": {
+      "description": "Optional trailing badge (count, label).",
+      "type": "string",
+      "default": ""
+    },
+    "collapsible": {
+      "description": "When true, the header row toggles the open state on click/keyboard.",
+      "type": "boolean",
+      "default": true
+    },
+    "component": {
+      "const": "NavGroup"
+    },
+    "icon": {
+      "description": "Optional leading icon name (resolved via <icon-ui>).",
+      "type": "string",
+      "default": ""
+    },
+    "open": {
+      "description": "Inline-expanded state. Toggled by header click when [collapsible].",
+      "type": "boolean",
+      "default": false
+    },
+    "text": {
+      "description": "Visible group label.",
+      "type": "string",
+      "default": ""
+    },
+    "variant": {
+      "description": "Visual treatment. Default ('') renders as a primary-rail group (icon row, caret, collapsible). 'section' renders the header as a static kicker label with always-visible children — matches the prior <section-nav-group-ui>. When the parent <nav-ui> carries variant=\"section\", this group inherits it via CSS cascade unless an explicit variant is set on the group.",
+      "type": "string",
+      "enum": [
+        "",
+        "section"
+      ],
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "events": {
+      "group-toggle": {
+        "description": "Fired when the header toggles via click/keyboard. Detail: { text, open }."
+      }
+    },
+    "examples": [],
+    "keywords": [
+      "nav",
+      "navigation",
+      "group",
+      "sidebar",
+      "menu"
+    ],
+    "name": "UINavGroup",
+    "related": [],
+    "slots": {
+      "default": {
+        "description": "Children — typically <nav-item-ui> rows."
+      },
+      "header": {
+        "description": "Optional custom header. Auto-generated when missing."
+      }
+    },
+    "states": [
+      {
+        "description": "Default. Children hidden.",
+        "name": "closed"
+      },
+      {
+        "description": "Children visible inline.",
+        "name": "open"
+      }
+    ],
+    "synonyms": {},
+    "tag": "nav-group-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/{patterns/app-nav-group/app-nav-group.css → components/nav-group/nav-group.css}

@@ -1,4 +1,4 @@
-@scope (app-nav-group-ui) {
+@scope (nav-group-ui) {
   :where(:scope) {
     --nav-group-row-height:    var(--a-size);
     --nav-group-row-height-sm: var(--a-size-sm);
@@ -133,33 +133,33 @@
   }
 
   /* Children — hidden when collapsed */
-  :scope:not([open]) > app-nav-item-ui {
+  :scope:not([open]) > nav-item-ui {
     display: none;
   }
 
   /* Child items default to sm for visual hierarchy */
-  :scope > app-nav-item-ui:not([size]) {
+  :scope > nav-item-ui:not([size]) {
     height: var(--nav-item-child-height);
     font-size: var(--nav-item-child-font);
   }
 
   /* ── Collapsed nav: hide text, badge, caret ── */
-  app-nav-ui[collapsed] & [slot="text"],
-  app-nav-ui[collapsed] & [slot="badge"],
-  app-nav-ui[collapsed] & [slot="caret"] {
+  nav-ui[collapsed] & [slot="text"],
+  nav-ui[collapsed] & [slot="badge"],
+  nav-ui[collapsed] & [slot="caret"] {
     display: none;
   }
 
-  app-nav-ui[collapsed] & [slot="header"] {
+  nav-ui[collapsed] & [slot="header"] {
     justify-content: center;
     padding: 0;
   }
 
-  app-nav-ui[collapsed] & {
+  nav-ui[collapsed] & {
     align-self: stretch;
   }
 
-  app-nav-ui[collapsed] &::after {
+  nav-ui[collapsed] &::after {
     display: none;
   }
 
@@ -167,7 +167,7 @@
     [slot="text"], [slot="badge"], [slot="caret"] {
       display: none !important;
     }
-    app-nav-item-ui {
+    nav-item-ui {
       display: none !important;
     }
     [slot="header"] {
@@ -204,7 +204,7 @@
    Popovers are promoted to the top layer and cannot inherit
    pattern-level custom properties, so raw --a-* tokens are
    used intentionally here. */
-app-nav-group-ui [slot="popover"] {
+nav-group-ui [slot="popover"] {
   margin: 0;
   padding: var(--a-space-1);
   border: 1px solid var(--a-border-subtle);
@@ -217,7 +217,7 @@ app-nav-group-ui [slot="popover"] {
   font-size: var(--a-ui-size);
 }
 
-app-nav-group-ui [slot="popover-label"] {
+nav-group-ui [slot="popover-label"] {
   padding: var(--a-space-1) var(--a-space-2);
   font-weight: var(--a-weight-medium);
   color: var(--a-fg-muted);
@@ -226,7 +226,7 @@ app-nav-group-ui [slot="popover-label"] {
   letter-spacing: 0.06em;
 }
 
-app-nav-group-ui [slot="popover"] [role="option"] {
+nav-group-ui [slot="popover"] [role="option"] {
   padding: var(--a-space-1) var(--a-space-2);
   border-radius: var(--a-radius);
   color: var(--a-fg-subtle);
@@ -237,23 +237,23 @@ app-nav-group-ui [slot="popover"] [role="option"] {
     color var(--a-duration-fast) var(--a-easing);
 }
 
-app-nav-group-ui [slot="popover"] [role="option"]:hover {
+nav-group-ui [slot="popover"] [role="option"]:hover {
   background: var(--a-bg-hover);
   color: var(--a-fg-strong);
 }
 
 /* Selected / current option — mirrors the main rail's nav-item selection:
    muted fill + leading 2px accent bar. */
-app-nav-group-ui [slot="popover"] [role="option"][aria-current="page"],
-app-nav-group-ui [slot="popover"] [role="option"][aria-selected="true"] {
+nav-group-ui [slot="popover"] [role="option"][aria-current="page"],
+nav-group-ui [slot="popover"] [role="option"][aria-selected="true"] {
   position: relative;
   background: var(--a-bg-hover);
   color: var(--a-fg-strong);
   font-weight: var(--a-weight-medium);
 }
 
-app-nav-group-ui [slot="popover"] [role="option"][aria-current="page"]::before,
-app-nav-group-ui [slot="popover"] [role="option"][aria-selected="true"]::before {
+nav-group-ui [slot="popover"] [role="option"][aria-current="page"]::before,
+nav-group-ui [slot="popover"] [role="option"][aria-selected="true"]::before {
   content: '';
   position: absolute;
   inset-inline-start: calc(var(--a-space-2) * -0.5);
@@ -262,3 +262,56 @@ app-nav-group-ui [slot="popover"] [role="option"][aria-selected="true"]::before
   border-radius: 1px;
   background: var(--a-accent);
 }
+
+/* ── Section variant — groups render as kicker labels ──
+   The prior <section-nav-group-ui> defaulted to collapsible:false
+   (header was a label, children always visible). The consolidated
+   nav-group-ui defaults collapsible:true (the primary-variant default).
+   Section variant restores the old kicker rendering so subnav rails
+   show all children without an explicit [open] toggle.
+
+   Two ways to enable: either
+     (a) `<nav-group-ui variant="section">` directly, or
+     (b) `<nav-ui variant="section"> > nav-group-ui`  (cascade from parent).
+   Both selectors apply the same kicker styles. */
+
+nav-group-ui[variant="section"] > [slot="header"],
+nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"] {
+  height: auto;
+  padding: var(--a-space-3) var(--a-space-2) var(--a-space-1);
+  font-size: var(--a-kicker-sm, var(--a-ui-tiny));
+  font-weight: var(--a-weight-medium);
+  color: var(--a-fg-muted);
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  cursor: default;
+  border-radius: 0;
+}
+
+nav-group-ui[variant="section"] > [slot="header"]:hover,
+nav-group-ui[variant="section"] > [slot="header"]:focus-visible,
+nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"]:hover,
+nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"]:focus-visible {
+  background: transparent;
+  color: var(--a-fg-muted);
+}
+
+nav-group-ui[variant="section"] > [slot="header"] [slot="caret"],
+nav-group-ui[variant="section"] > [slot="header"] [slot="icon"]:empty,
+nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"] [slot="caret"],
+nav-ui[variant="section"] > nav-group-ui:not([variant]) > [slot="header"] [slot="icon"]:empty {
+  display: none;
+}
+
+/* Children always visible in section variant (override the
+   :scope:not([open]) > nav-item-ui hide rule from inside @scope). */
+nav-group-ui[variant="section"]:not([open]) > nav-item-ui,
+nav-ui[variant="section"] > nav-group-ui:not([variant]):not([open]) > nav-item-ui {
+  display: flex;
+}
+
+/* No indent rail in section variant — kicker layout doesn't carry it. */
+nav-group-ui[variant="section"]::after,
+nav-ui[variant="section"] > nav-group-ui:not([variant])::after {
+  display: none;
+}

package/{patterns/app-nav-group/app-nav-group.js → components/nav-group/nav-group.js}

@@ -1,42 +1,67 @@
 /**
- * <app-nav-group-ui> — Collapsible group of nav items inside app-nav-ui.
+ * <nav-group-ui> — Collapsible labeled group of nav items inside <nav-ui>.
+ *
+ * Consolidates the prior `app-nav-group-ui` + `section-nav-group-ui`
+ * per ADR-0015 § Nav consolidation. Behavior is unified; the parent
+ * <nav-ui>'s [variant] drives the visual treatment.
  *
  * Has icon, label, optional badge, and a caret indicating open/closed.
- * When the parent app-nav-ui is collapsed, clicking the group opens a
- * popover with its children instead of toggling inline expansion.
+ * When the parent <nav-ui> is collapsed (primary variant), clicking the
+ * group opens a popover with its children instead of toggling inline
+ * expansion. When [collapsible] (or always for primary variant), inline
+ * click + keyboard toggle is supported.
  */
 
-import { AdiaElement } from '../../core/element.js';
+import { UIElement } from '../../core/element.js';
 import { anchorPopover } from '../../core/anchor.js';
 
-class AdiaAppNavGroup extends AdiaElement {
+class UINavGroup extends UIElement {
   static properties = {
-    text:  { type: String,  default: '', reflect: true },
-    icon:  { type: String,  default: '', reflect: true },
-    badge: { type: String,  default: '', reflect: true },
-    open:  { type: Boolean, default: false, reflect: true },
+    text:        { type: String,  default: '',    reflect: true },
+    icon:        { type: String,  default: '',    reflect: true },
+    badge:       { type: String,  default: '',    reflect: true },
+    open:        { type: Boolean, default: false, reflect: true },
+    collapsible: { type: Boolean, default: true,  reflect: true },
+    variant:     { type: String,  default: '',    reflect: true },
   };
 
   static template = () => null;
 
   #popover = null;
   #anchorCleanup = null;
+  #headerEl = null;
+
+  #onHeaderKey = (e) => {
+    if (!this.collapsible) return;
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      this.open = !this.open;
+      this.dispatchEvent(new CustomEvent('group-toggle', {
+        bubbles: true,
+        detail: { text: this.text, open: this.open },
+      }));
+    }
+  };
 
   connected() {
     this.setAttribute('role', 'group');
 
     if (!this.querySelector(':scope > [slot="header"]')) {
-      const header = document.createElement('div');
-      header.setAttribute('slot', 'header');
-      header.setAttribute('tabindex', '0');
-      header.innerHTML = `
+      this.#headerEl = document.createElement('div');
+      this.#headerEl.setAttribute('slot', 'header');
+      this.#headerEl.setAttribute('tabindex', '0');
+      this.#headerEl.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>` : ''}
         <icon-ui slot="caret" name="caret-right"></icon-ui>
       `;
-      this.prepend(header);
+      this.prepend(this.#headerEl);
+    } else {
+      this.#headerEl = this.querySelector(':scope > [slot="header"]');
     }
+
+    this.#headerEl?.addEventListener('keydown', this.#onHeaderKey);
   }
 
   render() {
@@ -60,17 +85,17 @@ class AdiaAppNavGroup extends AdiaElement {
       label.textContent = this.text;
       this.#popover.appendChild(label);
 
-      for (const child of this.querySelectorAll(':scope > app-nav-item-ui')) {
-        const clone = document.createElement('div');
-        clone.setAttribute('role', 'option');
-        clone.dataset.sourceValue = child.getAttribute('value') || '';
-        clone.textContent = child.text;
-        clone.addEventListener('click', () => {
-          const nav = this.closest('app-nav-ui');
+      for (const child of this.querySelectorAll(':scope > nav-item-ui')) {
+        const opt = document.createElement('div');
+        opt.setAttribute('role', 'option');
+        opt.dataset.sourceValue = child.getAttribute('value') || '';
+        opt.textContent = child.text;
+        opt.addEventListener('click', () => {
+          const nav = this.closest('nav-ui');
           if (nav) nav.select(child);
           this.#popover.hidePopover();
         });
-        this.#popover.appendChild(clone);
+        this.#popover.appendChild(opt);
       }
 
       this.appendChild(this.#popover);
@@ -86,7 +111,7 @@ class AdiaAppNavGroup extends AdiaElement {
     for (const opt of this.#popover.querySelectorAll('[role="option"]')) {
       const srcValue = opt.dataset.sourceValue;
       const src = srcValue
-        ? this.querySelector(`:scope > app-nav-item-ui[value="${srcValue}"]`)
+        ? this.querySelector(`:scope > nav-item-ui[value="${srcValue}"]`)
         : null;
       if (src?.hasAttribute('selected')) {
         opt.setAttribute('aria-current', 'page');
@@ -106,11 +131,12 @@ class AdiaAppNavGroup extends AdiaElement {
   }
 
   disconnected() {
+    this.#headerEl?.removeEventListener('keydown', this.#onHeaderKey);
     this.#anchorCleanup?.();
     this.#anchorCleanup = null;
     this.#popover?.hidePopover?.();
   }
 }
-customElements.define('app-nav-group-ui', AdiaAppNavGroup);
 
-export { AdiaAppNavGroup };
+customElements.define('nav-group-ui', UINavGroup);
+export { UINavGroup };

package/components/nav-group/nav-group.yaml

@@ -0,0 +1,69 @@
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UINavGroup
+tag: nav-group-ui
+component: NavGroup
+category: layout
+version: 1
+description: |
+  Collapsible labeled group of <nav-item-ui> children inside <nav-ui>.
+  Consolidates the prior `app-nav-group-ui` + `section-nav-group-ui`
+  per ADR-0015 § Nav consolidation.
+
+  When the parent <nav-ui> is collapsed (primary variant), clicking the
+  group opens a popover with its children instead of toggling inline
+  expansion. Inline click + keyboard (Enter/Space) toggle is supported
+  when [collapsible] (default true).
+
+props:
+  text:
+    type: string
+    default: ''
+    description: "Visible group label."
+  icon:
+    type: string
+    default: ''
+    description: "Optional leading icon name (resolved via <icon-ui>)."
+  badge:
+    type: string
+    default: ''
+    description: "Optional trailing badge (count, label)."
+  open:
+    type: boolean
+    default: false
+    description: "Inline-expanded state. Toggled by header click when [collapsible]."
+  collapsible:
+    type: boolean
+    default: true
+    description: "When true, the header row toggles the open state on click/keyboard."
+  variant:
+    type: string
+    default: ''
+    enum: ['', section]
+    description: "Visual treatment. Default ('') renders as a primary-rail group (icon row, caret, collapsible). 'section' renders the header as a static kicker label with always-visible children — matches the prior <section-nav-group-ui>. When the parent <nav-ui> carries variant=\"section\", this group inherits it via CSS cascade unless an explicit variant is set on the group."
+
+events:
+  group-toggle:
+    description: "Fired when the header toggles via click/keyboard. Detail: { text, open }."
+
+slots:
+  default:
+    description: "Children — typically <nav-item-ui> rows."
+  header:
+    description: "Optional custom header. Auto-generated when missing."
+
+states:
+  - name: closed
+    description: Default. Children hidden.
+  - name: open
+    description: Children visible inline.
+
+traits: []
+tokens: {}
+a2ui:
+  rules: []
+anti_patterns: []
+examples: []
+
+keywords: [nav, navigation, group, sidebar, menu]
+synonyms: {}
+related: []

package/components/nav-item/nav-item.a2ui.json

@@ -0,0 +1,106 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/NavItem.json",
+  "title": "NavItem",
+  "description": "Single navigation link inside <nav-ui> (optionally nested under\n<nav-group-ui>). Consolidates the prior `app-nav-item-ui` +\n`section-nav-item-ui` per ADR-0015 § Nav consolidation.\n\nSupports icon, label, optional badge, selected/disabled state, and\nkeyboard activation (Enter/Space). Selection is managed by the parent\n<nav-ui>; clicking or activating an item calls nav.select(this) and\nbubbles a `nav-select` event.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "badge": {
+      "description": "Optional trailing badge.",
+      "type": "string",
+      "default": ""
+    },
+    "component": {
+      "const": "NavItem"
+    },
+    "disabled": {
+      "description": "Suppresses click/keyboard activation; greyed visually.",
+      "type": "boolean",
+      "default": false
+    },
+    "icon": {
+      "description": "Optional leading icon name.",
+      "type": "string",
+      "default": ""
+    },
+    "selected": {
+      "description": "Set by the parent <nav-ui>'s select() method.",
+      "type": "boolean",
+      "default": false
+    },
+    "text": {
+      "description": "Visible item label.",
+      "type": "string",
+      "default": ""
+    },
+    "value": {
+      "description": "Identifier — typically a route or anchor.",
+      "type": "string",
+      "default": ""
+    },
+    "variant": {
+      "description": "Visual treatment. Default ('') renders as a primary-rail item (reserved icon space, in-icon selected accent). 'section' renders flat — no icon space when absent, left-edge accent bar for selected — matching the prior <section-nav-item-ui>. When the parent <nav-ui> carries variant=\"section\", this item inherits it via CSS cascade unless an explicit variant is set.",
+      "type": "string",
+      "enum": [
+        "",
+        "section"
+      ],
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "events": {
+      "nav-select": {
+        "description": "Bubbles when the item is activated. Detail: { item, text, value }."
+      }
+    },
+    "examples": [],
+    "keywords": [
+      "nav",
+      "navigation",
+      "item",
+      "link",
+      "sidebar"
+    ],
+    "name": "UINavItem",
+    "related": [],
+    "slots": {
+      "default": {
+        "description": "Optional override of the default icon + text + badge stamping."
+      }
+    },
+    "states": [
+      {
+        "description": "Default.",
+        "name": "idle"
+      },
+      {
+        "description": "aria-current=page.",
+        "name": "selected"
+      },
+      {
+        "description": "Suppressed activation.",
+        "name": "disabled"
+      }
+    ],
+    "synonyms": {},
+    "tag": "nav-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}