@adia-ai/web-components 0.0.29 → 0.0.34

package/components/nav/nav.a2ui.json

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

package/components/nav/nav.css

@@ -0,0 +1,133 @@
+/* ═══════════════════════════════════════════
+   nav-ui — Consolidated navigation rail
+   Variants: primary (default, app sidebar) / section (subnav rail)
+   ═══════════════════════════════════════════ */
+
+@scope (nav-ui) {
+  :where(:scope) {
+    /* Shared */
+    --nav-gap:       var(--a-space-1);
+    --nav-px:        var(--a-space-2);
+    --nav-py:        var(--a-space-2);
+    --nav-font-size: var(--a-ui-size);
+    --nav-bg:        transparent;
+    --nav-divider-bg: var(--a-border-subtle);
+    --nav-divider-my: var(--a-space-1);
+
+    /* Primary-variant collapse */
+    --nav-width:           auto;
+    --nav-width-collapsed: 48px;
+    --nav-duration: var(--a-duration-base, 200ms);
+    --nav-easing:   var(--a-easing, ease);
+
+    /* Group-heading kicker */
+    --nav-label-fg:        var(--a-fg-muted);
+    --nav-label-font-size: var(--a-kicker-sm);
+    --nav-label-weight:    var(--a-weight-medium);
+    --nav-label-px:        var(--a-space-2);
+    --nav-label-py:        var(--a-space-3) var(--a-space-1);
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: flex;
+    flex-direction: column;
+    gap: var(--nav-gap);
+    padding: var(--nav-py) var(--nav-px);
+    background: var(--nav-bg);
+    font-size: var(--nav-font-size);
+    min-width: 0;
+    overflow-y: auto;
+    overflow-x: hidden;
+    scrollbar-width: none;
+  }
+
+  :scope::-webkit-scrollbar { display: none; }
+
+  /* ── Primary variant (default) ── */
+
+  :scope:not([variant="section"]) {
+    width: var(--nav-width);
+    transition: width var(--nav-duration) var(--nav-easing);
+  }
+
+  :scope:not([variant="section"])[collapsed] {
+    width: var(--nav-width-collapsed);
+    --nav-px: var(--a-space-1);
+  }
+
+  /* Container-query collapse — when nav lives in a sidebar that goes
+     narrow, behave as if [collapsed] regardless of attribute. */
+  @container sidebar (max-width: 96px) {
+    :scope:not([variant="section"]) {
+      --nav-px: var(--a-space-1);
+    }
+  }
+
+  /* Group label kicker (group header text inside nav-group) */
+  [data-nav-label] {
+    display: block;
+    padding: var(--nav-label-py) var(--nav-label-px);
+    font-size: var(--nav-label-font-size);
+    font-weight: var(--nav-label-weight);
+    color: var(--nav-label-fg);
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    white-space: nowrap;
+    overflow: hidden;
+  }
+
+  /* Hand-placed dividers */
+  [data-nav-divider] {
+    border: none;
+    height: 1px;
+    background: var(--nav-divider-bg);
+    margin: var(--nav-divider-my) 0;
+  }
+
+  /* Auto-dividers between groups when [divider] set */
+  :scope[divider] > nav-group-ui + nav-group-ui,
+  :scope[divider] > nav-item-ui + nav-group-ui,
+  :scope[divider] > nav-group-ui + nav-item-ui {
+    border-top: 1px solid var(--nav-divider-bg);
+    margin-top: var(--nav-divider-my);
+    padding-top: var(--nav-divider-my);
+  }
+
+  /* Spacer — pushes items below to bottom */
+  [data-nav-spacer] { flex: 1; }
+
+  /* Collapsed (primary): hide labels + dividers */
+  :scope:not([variant="section"])[collapsed] [data-nav-label],
+  :scope:not([variant="section"])[collapsed] [data-nav-divider] {
+    display: none;
+  }
+
+  @container sidebar (max-width: 96px) {
+    :scope:not([variant="section"]) [data-nav-label],
+    :scope:not([variant="section"]) [data-nav-divider] {
+      display: none;
+    }
+  }
+
+  /* ── Section variant ── */
+
+  :scope[variant="section"] {
+    --nav-px: 0;
+    --nav-py: 0;
+  }
+
+  /* Heading rendered from [heading] attribute on section variant. */
+  :scope[variant="section"][heading]:not([heading=""])::before {
+    content: attr(heading);
+    display: block;
+    padding: var(--nav-label-py) var(--nav-label-px);
+    font-size: var(--nav-label-font-size);
+    font-weight: var(--nav-label-weight);
+    color: var(--nav-label-fg);
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    white-space: nowrap;
+    overflow: hidden;
+  }
+}

package/components/nav/nav.js

@@ -0,0 +1,140 @@
+/**
+ * <nav-ui> — Navigation rail (consolidated primary + section variants).
+ *
+ * Consolidates the prior `app-nav-ui` + `section-nav-ui` dual-family
+ * per ADR-0015 § Nav consolidation. Variant drives visual treatment;
+ * behavior is unified.
+ *
+ * Variants:
+ *   primary  — default. App sidebar. ResizeObserver collapses to icon-only
+ *              below 96px container width or when [collapsed] set; groups
+ *              open a popover with their children when collapsed.
+ *   section  — subnav rail. Quieter chrome; no collapse behavior.
+ *              Optional [heading] attribute renders an uppercase label
+ *              via ::before pseudo (CSS-only).
+ *
+ * Structure:
+ *   <nav-ui>
+ *     <nav-group-ui icon="gear" text="Settings" badge="3">
+ *       <nav-item-ui text="General" value="/settings/general"></nav-item-ui>
+ *     </nav-group-ui>
+ *     <nav-item-ui icon="user" text="Profile" value="/profile"></nav-item-ui>
+ *   </nav-ui>
+ *
+ *   <nav-ui variant="section" heading="On this page">
+ *     <nav-item-ui text="Overview" value="#overview"></nav-item-ui>
+ *   </nav-ui>
+ *
+ * Event: nav-select (bubbles from nav-item-ui). detail: { item, text, value }
+ */
+
+import { UIElement } from '../../core/element.js';
+
+class UINav extends UIElement {
+  static properties = {
+    variant:   { type: String,  default: 'primary', reflect: true },
+    collapsed: { type: Boolean, default: false,     reflect: true },
+    divider:   { type: Boolean, default: false,     reflect: true },
+    heading:   { type: String,  default: '',        reflect: true },
+  };
+
+  static template = () => null;
+
+  #ro = null;
+
+  connected() {
+    this.setAttribute('role', 'navigation');
+    if (this.heading) this.setAttribute('aria-label', this.heading);
+    this.addEventListener('click', this.#onClick);
+
+    // ResizeObserver only meaningful for primary variant — section is static.
+    if (this.variant !== 'section') {
+      this.#ro = new ResizeObserver(() => this.#updateTooltips());
+      this.#ro.observe(this);
+    }
+  }
+
+  render() {
+    if (this.heading) this.setAttribute('aria-label', this.heading);
+    else this.removeAttribute('aria-label');
+    if (this.variant !== 'section') this.#updateTooltips();
+  }
+
+  #updateTooltips() {
+    const isCollapsed = this.collapsed || this.getBoundingClientRect().width <= 96;
+    for (const group of this.querySelectorAll(':scope > nav-group-ui')) {
+      const header = group.querySelector(':scope > [slot="header"]');
+      if (header) header.title = isCollapsed ? group.text : '';
+    }
+    for (const item of this.querySelectorAll(':scope > nav-item-ui')) {
+      item.title = isCollapsed ? item.text : '';
+    }
+  }
+
+  get selectedItem() {
+    return this.querySelector('nav-item-ui[selected]');
+  }
+
+  select(item) {
+    const prev = this.selectedItem;
+    if (prev && prev !== item) prev.removeAttribute('selected');
+    if (item) {
+      item.setAttribute('selected', '');
+      this.dispatchEvent(new CustomEvent('nav-select', {
+        bubbles: true,
+        detail: { item, text: item.text, value: item.value },
+      }));
+    }
+  }
+
+  toggle() {
+    if (this.variant === 'section') return; // no-op for section variant
+    this.collapsed = !this.collapsed;
+  }
+
+  #onClick = (e) => {
+    const item = e.target.closest('nav-item-ui');
+    if (item && this.contains(item)) {
+      if (item.disabled) return;
+      this.select(item);
+      this.#flushHoverState();
+      return;
+    }
+
+    // Group expand/popover — primary variant only.
+    if (this.variant === 'section') return;
+
+    const group = e.target.closest('nav-group-ui');
+    if (group && this.contains(group)) {
+      const isCollapsed = this.collapsed || this.getBoundingClientRect().width <= 96;
+      if (isCollapsed) {
+        group.showPopover?.();
+      } else {
+        const header = group.querySelector(':scope > [slot="header"]');
+        if (header && (e.target === header || header.contains(e.target))) {
+          group.open = !group.open;
+        }
+      }
+    }
+  };
+
+  // Safari macOS leaves :hover stuck on items the cursor passed through
+  // when the DOM mutates during click+route navigation. Toggling pointer-
+  // events forces re-evaluation of hover state on next paint.
+  // See docs/BROWSER-COMPAT.md §3a.
+  #flushHoverState() {
+    this.style.pointerEvents = 'none';
+    requestAnimationFrame(() => {
+      this.style.pointerEvents = '';
+    });
+  }
+
+  disconnected() {
+    this.removeEventListener('click', this.#onClick);
+    this.#ro?.disconnect();
+    this.#ro = null;
+  }
+}
+
+customElements.define('nav-ui', UINav);
+export { UINav };