@adia-ai/web-components 0.0.28 → 0.0.33

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 };

package/components/nav/nav.test.js

@@ -0,0 +1,428 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import '../../core/element.js';
+import './nav.js';
+import '../nav-group/nav-group.js';
+import '../nav-item/nav-item.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;
+}
+
+describe('nav-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('registers nav-ui, nav-group-ui, and nav-item-ui as custom elements', () => {
+    expect(customElements.get('nav-ui')).toBeDefined();
+    expect(customElements.get('nav-group-ui')).toBeDefined();
+    expect(customElements.get('nav-item-ui')).toBeDefined();
+  });
+
+  it('defaults to variant="primary" with role=navigation', () => {
+    const nav = mount('<nav-ui></nav-ui>');
+    expect(nav.variant).toBe('primary');
+    expect(nav.getAttribute('role')).toBe('navigation');
+  });
+
+  it('reflects [variant="section"] from the property', () => {
+    const nav = mount('<nav-ui variant="section"></nav-ui>');
+    expect(nav.variant).toBe('section');
+    expect(nav.getAttribute('variant')).toBe('section');
+  });
+
+  it('uses [heading] as aria-label and removes it when cleared', async () => {
+    const nav = mount('<nav-ui heading="On this page"></nav-ui>');
+    expect(nav.getAttribute('aria-label')).toBe('On this page');
+    nav.heading = '';
+    await tick();
+    expect(nav.hasAttribute('aria-label')).toBe(false);
+  });
+
+  it('section variant skips the ResizeObserver wiring', () => {
+    const primary = mount('<nav-ui></nav-ui>');
+    const section = mount('<nav-ui variant="section"></nav-ui>');
+    // The internal ResizeObserver is private (`#ro`); verify by the
+    // observable surface — toggle() is a no-op on section, but the
+    // primary nav can be flipped collapsed/uncollapsed.
+    section.toggle();
+    expect(section.collapsed).toBe(false);
+    primary.toggle();
+    expect(primary.collapsed).toBe(true);
+  });
+
+  it('select(item) sets [selected], clears prior selection, and bubbles nav-select', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-item-ui id="a" text="Alpha" value="/a"></nav-item-ui>
+        <nav-item-ui id="b" text="Bravo" value="/b" selected></nav-item-ui>
+      </nav-ui>
+    `);
+    const a = nav.querySelector('#a');
+    const b = nav.querySelector('#b');
+
+    const events = [];
+    nav.addEventListener('nav-select', (e) => events.push(e.detail));
+
+    nav.select(a);
+
+    expect(a.hasAttribute('selected')).toBe(true);
+    expect(b.hasAttribute('selected')).toBe(false);
+    expect(nav.selectedItem).toBe(a);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ item: a, text: 'Alpha', value: '/a' });
+  });
+
+  it('selectedItem getter returns null when no item is selected', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-item-ui text="Alpha" value="/a"></nav-item-ui>
+      </nav-ui>
+    `);
+    expect(nav.selectedItem).toBeNull();
+  });
+
+  it('toggle() is a no-op on variant="section"', () => {
+    const nav = mount('<nav-ui variant="section"></nav-ui>');
+    nav.toggle();
+    expect(nav.collapsed).toBe(false);
+    nav.toggle();
+    expect(nav.collapsed).toBe(false);
+  });
+
+  it('survives disconnect without throwing', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-item-ui text="Alpha"></nav-item-ui>
+      </nav-ui>
+    `);
+    expect(() => nav.remove()).not.toThrow();
+  });
+});
+
+describe('nav-item-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('sets role=link and tabindex=0 by default', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-item-ui text="Alpha"></nav-item-ui>
+      </nav-ui>
+    `);
+    const item = nav.querySelector('nav-item-ui');
+    expect(item.getAttribute('role')).toBe('link');
+    expect(item.getAttribute('tabindex')).toBe('0');
+  });
+
+  it('switches tabindex to -1 when [disabled]', async () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-item-ui text="Alpha"></nav-item-ui>
+      </nav-ui>
+    `);
+    const item = nav.querySelector('nav-item-ui');
+    item.disabled = true;
+    await tick();
+    expect(item.getAttribute('tabindex')).toBe('-1');
+  });
+
+  it('click on the item calls parent nav-ui.select(this)', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-item-ui id="a" text="Alpha" value="/a"></nav-item-ui>
+      </nav-ui>
+    `);
+    const item = nav.querySelector('#a');
+    const spy = vi.spyOn(nav, 'select');
+
+    item.click();
+
+    expect(spy).toHaveBeenCalledWith(item);
+  });
+
+  it('Enter key activates a nav-item-ui (same as click)', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-item-ui id="a" text="Alpha" value="/a"></nav-item-ui>
+      </nav-ui>
+    `);
+    const item = nav.querySelector('#a');
+    const spy = vi.spyOn(nav, 'select');
+
+    item.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+
+    expect(spy).toHaveBeenCalledWith(item);
+  });
+
+  it('Space key activates a nav-item-ui', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-item-ui id="a" text="Alpha"></nav-item-ui>
+      </nav-ui>
+    `);
+    const item = nav.querySelector('#a');
+    const spy = vi.spyOn(nav, 'select');
+
+    item.dispatchEvent(new KeyboardEvent('keydown', { key: ' ', bubbles: true }));
+
+    expect(spy).toHaveBeenCalledWith(item);
+  });
+
+  it('disabled nav-item-ui does not activate on click or keyboard', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-item-ui id="a" text="Alpha" disabled></nav-item-ui>
+      </nav-ui>
+    `);
+    const item = nav.querySelector('#a');
+    const spy = vi.spyOn(nav, 'select');
+
+    item.click();
+    item.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+
+    expect(spy).not.toHaveBeenCalled();
+  });
+
+  it('selected item carries aria-current="page"', async () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-item-ui id="a" text="Alpha"></nav-item-ui>
+      </nav-ui>
+    `);
+    const item = nav.querySelector('#a');
+    nav.select(item);
+    await tick();
+    expect(item.getAttribute('aria-current')).toBe('page');
+  });
+
+  it('clearing selected removes aria-current', async () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-item-ui id="a" text="Alpha"></nav-item-ui>
+        <nav-item-ui id="b" text="Bravo"></nav-item-ui>
+      </nav-ui>
+    `);
+    const a = nav.querySelector('#a');
+    const b = nav.querySelector('#b');
+    nav.select(a);
+    await tick();
+    expect(a.getAttribute('aria-current')).toBe('page');
+    nav.select(b);
+    await tick();
+    expect(a.hasAttribute('aria-current')).toBe(false);
+    expect(b.getAttribute('aria-current')).toBe('page');
+  });
+});
+
+describe('nav-group-ui', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('auto-mints a header div with icon/text/caret slots', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-group-ui text="Settings" icon="gear">
+          <nav-item-ui text="General"></nav-item-ui>
+        </nav-group-ui>
+      </nav-ui>
+    `);
+    const group = nav.querySelector('nav-group-ui');
+    const header = group.querySelector(':scope > [slot="header"]');
+    expect(header).not.toBeNull();
+    expect(header.querySelector('[slot="text"]').textContent).toBe('Settings');
+    expect(header.querySelector('icon-ui[slot="caret"]')).not.toBeNull();
+  });
+
+  it('renders [badge] in the header when set', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-group-ui text="Settings" badge="3"></nav-group-ui>
+      </nav-ui>
+    `);
+    const group = nav.querySelector('nav-group-ui');
+    const badge = group.querySelector('[slot="header"] [slot="badge"]');
+    expect(badge).not.toBeNull();
+    expect(badge.textContent).toBe('3');
+  });
+
+  it('header click toggles [open] when not collapsed (delegated through nav-ui)', async () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-group-ui text="Settings"></nav-group-ui>
+      </nav-ui>
+    `);
+    // happy-dom returns 0 for getBoundingClientRect width, which makes the
+    // nav-ui treat itself as collapsed and route clicks to popover instead
+    // of inline expand. Stub the rect so the inline-expand path fires.
+    nav.getBoundingClientRect = () => ({ width: 240, height: 600, top: 0, left: 0, right: 240, bottom: 600, x: 0, y: 0 });
+
+    const group = nav.querySelector('nav-group-ui');
+    const header = group.querySelector(':scope > [slot="header"]');
+    expect(group.open).toBe(false);
+
+    header.click();
+    await tick();
+
+    expect(group.open).toBe(true);
+  });
+
+  it('keydown Enter on header is ignored when collapsible=false', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-group-ui text="Settings" open></nav-group-ui>
+      </nav-ui>
+    `);
+    const group = nav.querySelector('nav-group-ui');
+    group.collapsible = false;
+
+    const header = group.querySelector(':scope > [slot="header"]');
+    const events = [];
+    group.addEventListener('group-toggle', (e) => events.push(e.detail));
+
+    header.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+
+    expect(events).toHaveLength(0);
+    expect(group.open).toBe(true);
+  });
+
+  it('aria-expanded reflects the open state', async () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-group-ui text="Settings"></nav-group-ui>
+      </nav-ui>
+    `);
+    const group = nav.querySelector('nav-group-ui');
+    expect(group.getAttribute('aria-expanded')).toBe('false');
+    group.open = true;
+    await tick();
+    expect(group.getAttribute('aria-expanded')).toBe('true');
+  });
+
+  it('Enter on the header dispatches group-toggle when collapsible', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-group-ui text="Settings"></nav-group-ui>
+      </nav-ui>
+    `);
+    const group = nav.querySelector('nav-group-ui');
+    const header = group.querySelector(':scope > [slot="header"]');
+
+    const events = [];
+    group.addEventListener('group-toggle', (e) => events.push(e.detail));
+
+    header.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
+
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({ text: 'Settings', open: true });
+  });
+
+  it('respects an existing [slot="header"] instead of auto-minting one', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-group-ui text="Settings">
+          <div slot="header" data-custom>my header</div>
+        </nav-group-ui>
+      </nav-ui>
+    `);
+    const group = nav.querySelector('nav-group-ui');
+    const headers = group.querySelectorAll(':scope > [slot="header"]');
+    expect(headers.length).toBe(1);
+    expect(headers[0].dataset.custom).toBe('');
+  });
+
+  it('survives disconnect without throwing', () => {
+    const nav = mount(`
+      <nav-ui>
+        <nav-group-ui text="Settings">
+          <nav-item-ui text="General"></nav-item-ui>
+        </nav-group-ui>
+      </nav-ui>
+    `);
+    expect(() => nav.remove()).not.toThrow();
+  });
+
+  it('section-variant subnav stamps groups + items per the docs site pattern', () => {
+    // Mirrors site/site.js subnav stamping for `subnav: true` sections:
+    // dividers in the sitemap become nav-group-ui kickers; following items
+    // become nav-item-ui children of the most recent group.
+    const nav = mount(`
+      <nav-ui variant="section" aria-label="Authentication">
+        <nav-group-ui text="Sign in">
+          <nav-item-ui text="Sign In" value="/auth/sign-in"></nav-item-ui>
+          <nav-item-ui text="Password" value="/auth/sign-in/password"></nav-item-ui>
+        </nav-group-ui>
+        <nav-group-ui text="Sign up">
+          <nav-item-ui text="Sign Up" value="/auth/sign-up"></nav-item-ui>
+        </nav-group-ui>
+      </nav-ui>
+    `);
+    const groups = nav.querySelectorAll(':scope > nav-group-ui');
+    expect(groups.length).toBe(2);
+    // Each group has its expected children attached (not stripped at mount).
+    expect(groups[0].querySelectorAll('nav-item-ui').length).toBe(2);
+    expect(groups[1].querySelectorAll('nav-item-ui').length).toBe(1);
+    // Group headers are auto-minted with the kicker text.
+    expect(groups[0].querySelector('[slot="header"] [slot="text"]').textContent).toBe('Sign in');
+    expect(groups[1].querySelector('[slot="header"] [slot="text"]').textContent).toBe('Sign up');
+  });
+});
+
+describe('section variant — explicit + cascade', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('nav-group-ui[variant="section"] reflects the property', () => {
+    const group = mount('<nav-group-ui variant="section" text="Settings"></nav-group-ui>');
+    expect(group.variant).toBe('section');
+    expect(group.getAttribute('variant')).toBe('section');
+  });
+
+  it('nav-item-ui[variant="section"] reflects the property', () => {
+    const item = mount('<nav-item-ui variant="section" text="General"></nav-item-ui>');
+    expect(item.variant).toBe('section');
+    expect(item.getAttribute('variant')).toBe('section');
+  });
+
+  it('nav-group-ui defaults to variant="" (empty) when not set', () => {
+    const group = mount('<nav-group-ui text="Settings"></nav-group-ui>');
+    expect(group.variant).toBe('');
+  });
+
+  it('nav-item-ui defaults to variant="" (empty) when not set', () => {
+    const item = mount('<nav-item-ui text="General"></nav-item-ui>');
+    expect(item.variant).toBe('');
+  });
+
+  it('cascade: nav-ui[variant="section"] does NOT mutate the child variant prop', () => {
+    // The cascade is CSS-only — children keep their own (empty) variant.
+    // CSS rules target `nav-ui[variant="section"] > x:not([variant])` so
+    // the parent's variant only governs styling, not the JS state.
+    const nav = mount(`
+      <nav-ui variant="section">
+        <nav-group-ui text="Settings">
+          <nav-item-ui text="General"></nav-item-ui>
+        </nav-group-ui>
+      </nav-ui>
+    `);
+    const group = nav.querySelector('nav-group-ui');
+    const item = nav.querySelector('nav-item-ui');
+    expect(group.variant).toBe('');
+    expect(item.variant).toBe('');
+  });
+
+  it('explicit variant on a child wins over the parent cascade', () => {
+    // A child can opt out of the section cascade by setting its own
+    // variant. The CSS rules use `:not([variant])` for the cascade path,
+    // so an explicit non-section variant on the child suppresses kicker
+    // styling and the child renders primary-style.
+    const nav = mount(`
+      <nav-ui variant="section">
+        <nav-group-ui text="Override" variant="primary"></nav-group-ui>
+      </nav-ui>
+    `);
+    const group = nav.querySelector('nav-group-ui');
+    expect(group.variant).toBe('primary');
+    expect(group.matches('[variant]')).toBe(true);
+  });
+});