@adia-ai/web-components 0.4.6 → 0.4.8

package/components/nav-group/class.js

@@ -0,0 +1,152 @@
+/**
+ * Non-side-effect class export for `<nav-group-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/nav-group`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <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 <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 { UIElement } from '../../core/element.js';
+import { anchorPopover } from '../../core/anchor.js';
+
+export 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 },
+    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"]')) {
+      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(this.#headerEl);
+    } else {
+      this.#headerEl = this.querySelector(':scope > [slot="header"]');
+    }
+
+    this.#headerEl?.addEventListener('keydown', this.#onHeaderKey);
+  }
+
+  render() {
+    const textEl = this.querySelector('[slot="header"] [slot="text"]');
+    if (textEl) textEl.textContent = this.text;
+
+    const badgeEl = this.querySelector('[slot="header"] [slot="badge"]');
+    if (badgeEl) badgeEl.textContent = this.badge;
+
+    this.setAttribute('aria-expanded', String(this.open));
+  }
+
+  showPopover() {
+    if (!this.#popover) {
+      this.#popover = document.createElement('div');
+      this.#popover.setAttribute('slot', 'popover');
+      this.#popover.setAttribute('popover', 'auto');
+
+      const label = document.createElement('div');
+      label.setAttribute('slot', 'popover-label');
+      label.textContent = this.text;
+      this.#popover.appendChild(label);
+
+      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(opt);
+      }
+
+      this.appendChild(this.#popover);
+
+      this.#popover.addEventListener('toggle', (e) => {
+        if (e.newState === 'closed') {
+          this.#anchorCleanup?.();
+          this.#anchorCleanup = null;
+        }
+      });
+    }
+
+    for (const opt of this.#popover.querySelectorAll('[role="option"]')) {
+      const srcValue = opt.dataset.sourceValue;
+      const src = srcValue
+        ? this.querySelector(`:scope > nav-item-ui[value="${srcValue}"]`)
+        : null;
+      if (src?.hasAttribute('selected')) {
+        opt.setAttribute('aria-current', 'page');
+        opt.setAttribute('aria-selected', 'true');
+      } else {
+        opt.removeAttribute('aria-current');
+        opt.removeAttribute('aria-selected');
+      }
+    }
+
+    this.#popover.showPopover();
+
+    this.#anchorCleanup?.();
+    this.#anchorCleanup = anchorPopover(this, this.#popover, {
+      placement: 'right', gap: 4,
+    });
+  }
+
+  disconnected() {
+    this.#headerEl?.removeEventListener('keydown', this.#onHeaderKey);
+    this.#anchorCleanup?.();
+    this.#anchorCleanup = null;
+    this.#popover?.hidePopover?.();
+  }
+}

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

@@ -58,6 +58,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "group-toggle": {
         "description": "Fired when the header toggles via click/keyboard. Detail: { text, open }."

package/components/nav-group/nav-group.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `<nav-group-ui>` — 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).
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/nav-group
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export type NavGroupGroupToggleEvent = CustomEvent<unknown>;
+
+export class UINavGroup extends UIElement {
+  /** Optional trailing badge (count, label). */
+  badge: string;
+  /** When true, the header row toggles the open state on click/keyboard. */
+  collapsible: boolean;
+  /** Optional leading icon name (resolved via <icon-ui>). */
+  icon: string;
+  /** Inline-expanded state. Toggled by header click when [collapsible]. */
+  open: boolean;
+  /** Visible group label. */
+  text: string;
+  /** 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. When the parent <nav-ui> carries variant="section", this group inherits it via CSS cascade unless an explicit variant is set on the group. */
+  variant: '' | 'section';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UINavGroup, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'group-toggle', listener: (ev: NavGroupGroupToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/nav-group/nav-group.js

@@ -1,142 +1,17 @@
 /**
- * <nav-group-ui> — Collapsible labeled group of nav items inside <nav-ui>.
+ * `<nav-group-ui>` — auto-registers the tag on import.
  *
- * 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.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Has icon, label, optional badge, and a caret indicating open/closed.
- * 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 { UINavGroup } from '@adia-ai/web-components/components/nav-group/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-import { anchorPopover } from '../../core/anchor.js';
-
-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 },
-    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"]')) {
-      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(this.#headerEl);
-    } else {
-      this.#headerEl = this.querySelector(':scope > [slot="header"]');
-    }
-
-    this.#headerEl?.addEventListener('keydown', this.#onHeaderKey);
-  }
-
-  render() {
-    const textEl = this.querySelector('[slot="header"] [slot="text"]');
-    if (textEl) textEl.textContent = this.text;
-
-    const badgeEl = this.querySelector('[slot="header"] [slot="badge"]');
-    if (badgeEl) badgeEl.textContent = this.badge;
-
-    this.setAttribute('aria-expanded', String(this.open));
-  }
-
-  showPopover() {
-    if (!this.#popover) {
-      this.#popover = document.createElement('div');
-      this.#popover.setAttribute('slot', 'popover');
-      this.#popover.setAttribute('popover', 'auto');
-
-      const label = document.createElement('div');
-      label.setAttribute('slot', 'popover-label');
-      label.textContent = this.text;
-      this.#popover.appendChild(label);
-
-      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(opt);
-      }
-
-      this.appendChild(this.#popover);
-
-      this.#popover.addEventListener('toggle', (e) => {
-        if (e.newState === 'closed') {
-          this.#anchorCleanup?.();
-          this.#anchorCleanup = null;
-        }
-      });
-    }
-
-    for (const opt of this.#popover.querySelectorAll('[role="option"]')) {
-      const srcValue = opt.dataset.sourceValue;
-      const src = srcValue
-        ? this.querySelector(`:scope > nav-item-ui[value="${srcValue}"]`)
-        : null;
-      if (src?.hasAttribute('selected')) {
-        opt.setAttribute('aria-current', 'page');
-        opt.setAttribute('aria-selected', 'true');
-      } else {
-        opt.removeAttribute('aria-current');
-        opt.removeAttribute('aria-selected');
-      }
-    }
-
-    this.#popover.showPopover();
-
-    this.#anchorCleanup?.();
-    this.#anchorCleanup = anchorPopover(this, this.#popover, {
-      placement: 'right', gap: 4,
-    });
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UINavGroup } from './class.js';
 
-  disconnected() {
-    this.#headerEl?.removeEventListener('keydown', this.#onHeaderKey);
-    this.#anchorCleanup?.();
-    this.#anchorCleanup = null;
-    this.#popover?.hidePopover?.();
-  }
-}
+defineIfFree('nav-group-ui', UINavGroup);
 
-customElements.define('nav-group-ui', UINavGroup);
 export { UINavGroup };

package/components/nav-item/class.js

@@ -0,0 +1,86 @@
+/**
+ * Non-side-effect class export for `<nav-item-ui>`.
+ *
+ * Importing this file gives you the class(es) without auto-registering the tag.
+ * Useful for test isolation, subclassing with tag-name override, or selective
+ * composition.
+ *
+ * The auto-register path stays at `@adia-ai/web-components/components/nav-item`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <nav-item-ui> — Single navigation link inside <nav-ui> (optionally
+ * nested under <nav-group-ui>). Consolidates the prior
+ * `app-nav-item-ui` + `section-nav-item-ui` per ADR-0015 § Nav consolidation.
+ *
+ * Supports icon, label, optional badge, selected/disabled state, and
+ * keyboard activation (Enter/Space). Selection is managed by the parent
+ * <nav-ui>; clicking or keyboard-activating an item calls nav.select(this)
+ * and dispatches `nav-select` (bubbles, detail: { item, text, value }).
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export class UINavItem extends UIElement {
+  static properties = {
+    text:     { type: String,  default: '', reflect: true },
+    icon:     { type: String,  default: '', reflect: true },
+    value:    { type: String,  default: '', reflect: true },
+    badge:    { type: String,  default: '', reflect: true },
+    selected: { type: Boolean, default: false, reflect: true },
+    disabled: { type: Boolean, default: false, reflect: true },
+    variant:  { type: String,  default: '', reflect: true },
+  };
+
+  static template = () => null;
+
+  #onClick = (e) => {
+    if (this.disabled) { e.preventDefault(); return; }
+    const parent = this.closest('nav-ui');
+    parent?.select?.(this);
+    this.dispatchEvent(new CustomEvent('nav-select', {
+      bubbles: true,
+      detail: { item: this, text: this.text, value: this.value },
+    }));
+  };
+
+  #onKey = (e) => {
+    if (this.disabled) return;
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      this.#onClick(e);
+    }
+  };
+
+  connected() {
+    this.setAttribute('role', 'link');
+    this.setAttribute('tabindex', this.disabled ? '-1' : '0');
+
+    if (!this.querySelector('[slot="text"]')) {
+      this.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>` : ''}
+      `;
+    }
+
+    this.addEventListener('click', this.#onClick);
+    this.addEventListener('keydown', this.#onKey);
+  }
+
+  render() {
+    const textEl = this.querySelector('[slot="text"]');
+    if (textEl) textEl.textContent = this.text;
+    this.setAttribute('tabindex', this.disabled ? '-1' : '0');
+    if (this.selected) this.setAttribute('aria-current', 'page');
+    else this.removeAttribute('aria-current');
+  }
+
+  disconnected() {
+    this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('keydown', this.#onKey);
+  }
+}

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

@@ -63,6 +63,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "nav-select": {
         "description": "Bubbles when the item is activated. Detail: { item, text, value }."

package/components/nav-item/nav-item.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `<nav-item-ui>` — Single navigation link inside <nav-ui> (optionally nested under
+<nav-group-ui>). Consolidates the prior `app-nav-item-ui` +
+`section-nav-item-ui` per ADR-0015 § Nav consolidation.
+
+Supports icon, label, optional badge, selected/disabled state, and
+keyboard activation (Enter/Space). Selection is managed by the parent
+<nav-ui>; clicking or activating an item calls nav.select(this) and
+bubbles a `nav-select` event.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/nav-item
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export type NavItemNavSelectEvent = CustomEvent<unknown>;
+
+export class UINavItem extends UIElement {
+  /** Optional trailing badge. */
+  badge: string;
+  /** Suppresses click/keyboard activation; greyed visually. */
+  disabled: boolean;
+  /** Optional leading icon name. */
+  icon: string;
+  /** Set by the parent <nav-ui>'s select() method. */
+  selected: boolean;
+  /** Visible item label. */
+  text: string;
+  /** Identifier — typically a route or anchor. */
+  value: string;
+  /** 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. When the parent <nav-ui> carries variant="section", this item inherits it via CSS cascade unless an explicit variant is set. */
+  variant: '' | 'section';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UINavItem, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'nav-select', listener: (ev: NavItemNavSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/nav-item/nav-item.js

@@ -1,76 +1,17 @@
 /**
- * <nav-item-ui> — Single navigation link inside <nav-ui> (optionally
- * nested under <nav-group-ui>). Consolidates the prior
- * `app-nav-item-ui` + `section-nav-item-ui` per ADR-0015 § Nav consolidation.
+ * `<nav-item-ui>` — auto-registers the tag on import.
  *
- * Supports icon, label, optional badge, selected/disabled state, and
- * keyboard activation (Enter/Space). Selection is managed by the parent
- * <nav-ui>; clicking or keyboard-activating an item calls nav.select(this)
- * and dispatches `nav-select` (bubbles, detail: { item, text, value }).
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UINavItem } from '@adia-ai/web-components/components/nav-item/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UINavItem extends UIElement {
-  static properties = {
-    text:     { type: String,  default: '', reflect: true },
-    icon:     { type: String,  default: '', reflect: true },
-    value:    { type: String,  default: '', reflect: true },
-    badge:    { type: String,  default: '', reflect: true },
-    selected: { type: Boolean, default: false, reflect: true },
-    disabled: { type: Boolean, default: false, reflect: true },
-    variant:  { type: String,  default: '', reflect: true },
-  };
-
-  static template = () => null;
-
-  #onClick = (e) => {
-    if (this.disabled) { e.preventDefault(); return; }
-    const parent = this.closest('nav-ui');
-    parent?.select?.(this);
-    this.dispatchEvent(new CustomEvent('nav-select', {
-      bubbles: true,
-      detail: { item: this, text: this.text, value: this.value },
-    }));
-  };
-
-  #onKey = (e) => {
-    if (this.disabled) return;
-    if (e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault();
-      this.#onClick(e);
-    }
-  };
-
-  connected() {
-    this.setAttribute('role', 'link');
-    this.setAttribute('tabindex', this.disabled ? '-1' : '0');
-
-    if (!this.querySelector('[slot="text"]')) {
-      this.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>` : ''}
-      `;
-    }
-
-    this.addEventListener('click', this.#onClick);
-    this.addEventListener('keydown', this.#onKey);
-  }
-
-  render() {
-    const textEl = this.querySelector('[slot="text"]');
-    if (textEl) textEl.textContent = this.text;
-    this.setAttribute('tabindex', this.disabled ? '-1' : '0');
-    if (this.selected) this.setAttribute('aria-current', 'page');
-    else this.removeAttribute('aria-current');
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UINavItem } from './class.js';
 
-  disconnected() {
-    this.removeEventListener('click', this.#onClick);
-    this.removeEventListener('keydown', this.#onKey);
-  }
-}
+defineIfFree('nav-item-ui', UINavItem);
 
-customElements.define('nav-item-ui', UINavItem);
 export { UINavItem };