@adia-ai/web-components 0.4.6 → 0.4.8

package/components/modal/modal.js

@@ -1,221 +1,17 @@
 /**
- * <modal-ui> — Centered dialog overlay.
+ * `<modal-ui>` — auto-registers the tag on import.
  *
- * Uses native <dialog> for focus trapping, Escape key, and ::backdrop.
- * Content panel scales in/out with CSS transitions.
- * Exit animation plays before dialog.close() via [data-closing].
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Structure (stamped automatically):
- *   <modal-ui size="md">
- *     <dialog slot="dialog">
- *       <div slot="panel">
- *         <div slot="header">Title × </div>
- *         <div slot="body">...content...</div>
- *         <div slot="footer">...actions...</div>
- *       </div>
- *     </dialog>
- *   </modal-ui>
+ *   import { UIModal } from '@adia-ai/web-components/components/modal/class';
  *
- * Usage:
- *   <modal-ui text="Confirm" size="md">
- *     <section>Modal content here</section>
- *   </modal-ui>
- *
- *   modal.show();
- *   modal.hide();
- *   modal.open = true;
- *
- * Events:
- *   close — fired after the modal finishes closing
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-
-class UIModal extends UIElement {
-  #bound = false;
-  #closing = false;
-  #previousFocus = null;
-  #closeTimer = null;
-  #dialogRef = null;
-
-  static properties = {
-    text:      { type: String,  default: '', reflect: true },
-    size:      { type: String,  default: 'md', reflect: true },
-    permanent: { type: Boolean, default: false, reflect: true },
-    open:      { type: Boolean, default: false, reflect: true },
-  };
-
-  static parts = {
-    dialog: '<dialog slot="dialog"></dialog>',
-    panel:  '<div slot="panel"></div>',
-    header: '<header slot="header"></header>',
-    close:  '<button-ui slot="close" icon="x" variant="ghost" size="sm" aria-label="Close"></button-ui>',
-    body:   '<section slot="body"></section>',
-    footer: '<footer slot="footer"></footer>',
-  };
-
-  // No template — modal composes from authored light-DOM children. An empty
-  // html`` result would trigger stamp() → replaceChildren(), wiping authored
-  // [slot=body|footer] before render() can migrate them into the panel.
-  // (Same rationale as drawer.js — parallel pattern.)
-
-  #onPress = (e) => {
-    if (e.target.closest('[slot="close"]')) this.open = false;
-  };
-
-  #onDialogCancel = (e) => {
-    e.preventDefault();
-    if (!this.permanent) this.open = false;
-  };
-
-  #onDialogClose = () => {
-    this.open = false;
-    this.#previousFocus?.focus();
-    this.#previousFocus = null;
-    this.dispatchEvent(new Event('close', { bubbles: true }));
-  };
-
-  #onDialogClick = (e) => {
-    if (e.target === this.#dialogRef && !this.permanent) this.open = false;
-  };
-
-  connected() {
-    this.addEventListener('press', this.#onPress);
-
-    // Bind dialog listeners as soon as the dialog part is available.
-    const dialog = this.ensure('dialog');
-    if (dialog && !this.#bound) {
-      this.#bound = true;
-      this.#dialogRef = dialog;
-      dialog.addEventListener('cancel', this.#onDialogCancel);
-      dialog.addEventListener('close', this.#onDialogClose);
-      dialog.addEventListener('click', this.#onDialogClick);
-    }
-  }
-
-  disconnected() {
-    this.removeEventListener('press', this.#onPress);
-    if (this.#dialogRef) {
-      this.#dialogRef.removeEventListener('cancel', this.#onDialogCancel);
-      this.#dialogRef.removeEventListener('close', this.#onDialogClose);
-      this.#dialogRef.removeEventListener('click', this.#onDialogClick);
-    }
-    if (this.#closeTimer != null) {
-      clearTimeout(this.#closeTimer);
-      this.#closeTimer = null;
-    }
-    this.#bound = false;
-    this.#dialogRef = null;
-  }
-
-  #getDuration() {
-    const raw = getComputedStyle(this).getPropertyValue('--modal-duration').trim();
-    return parseFloat(raw) || 200;
-  }
-
-  render() {
-    const dialog = this.ensure('dialog');
-
-    if (this.text) {
-      dialog.setAttribute('aria-label', this.text);
-      this.setAttribute('aria-label', this.text);
-    } else {
-      dialog.removeAttribute('aria-label');
-      this.removeAttribute('aria-label');
-    }
-
-    const panel = this.ensure('panel');
-    if (panel.parentElement !== dialog) dialog.appendChild(panel);
-
-    const header = this.ensure('header');
-    if (header.parentElement !== panel) panel.prepend(header);
-    header.setAttribute('text', this.text);
-
-    if (!this.permanent) {
-      const close = this.ensure('close');
-      if (close.parentElement !== header) header.appendChild(close);
-    } else {
-      this.drop('close');
-    }
-
-    // Body — accept bare `<section>` tags, explicit `[slot="body"]`, OR
-    // unslotted light-DOM children (so `<modal-ui><p>…</p></modal-ui>` works
-    // with no markup ceremony). Mirrors drawer-ui's authoring contract.
-    const authorBody = [...this.children].find(c =>
-      c.getAttribute('slot') === 'body' || (!c.getAttribute('slot') && c.localName === 'section')
-    );
-    const looseChildren = [...this.children].filter(c =>
-      !c.getAttribute('slot') && c.localName !== 'section' && c.localName !== 'dialog' && c.localName !== 'footer'
-    );
-
-    let body;
-    if (authorBody) {
-      if (authorBody.getAttribute('slot') !== 'body') authorBody.setAttribute('slot', 'body');
-      if (authorBody.parentElement !== panel) panel.appendChild(authorBody);
-      panel.querySelector(':scope > [slot="body"][data-stamped]')?.remove();
-      body = authorBody;
-    } else {
-      body = this.ensure('body');
-      body.setAttribute('data-stamped', '');
-      if (body.parentElement !== panel) panel.appendChild(body);
-    }
-
-    // Migrate any remaining unslotted light-DOM children into the body so
-    // `<modal-ui><p>…</p></modal-ui>` lands in the visible region.
-    for (const child of looseChildren) {
-      if (child !== body) body.appendChild(child);
-    }
-
-    // Footer — opt-in via [slot="footer"] or bare <footer> tag (card-ui style).
-    const userFooter = [...this.children].find(c =>
-      c.getAttribute('slot') === 'footer' || (!c.getAttribute('slot') && c.localName === 'footer')
-    );
-    if (userFooter) {
-      if (userFooter.getAttribute('slot') !== 'footer') userFooter.setAttribute('slot', 'footer');
-      if (userFooter.parentElement !== panel) panel.appendChild(userFooter);
-      panel.querySelector(':scope > [slot="footer"][data-stamped]')?.remove();
-    } else {
-      const footer = this.ensure('footer');
-      footer.setAttribute('data-stamped', '');
-      if (footer.parentElement !== panel) panel.appendChild(footer);
-    }
-
-    // Sync open state. Synchronous reflow instead of rAF — Safari throttles
-    // requestAnimationFrame when a top-layer dialog is open, sometimes
-    // delaying [data-open] (and the scale-in transition) by tens of seconds.
-    // See docs/BROWSER-COMPAT.md §3a (Flavor C).
-    if (this.open && !dialog.open) {
-      this.#closing = false;
-      this.#previousFocus = document.activeElement;
-      dialog.showModal();
-      void dialog.offsetHeight;
-      dialog.setAttribute('data-open', '');
-    } else if (!this.open && dialog.open && !this.#closing) {
-      this.#animateClose(dialog);
-    }
-  }
-
-  #animateClose(dialog) {
-    this.#closing = true;
-    // Set [data-closing] FIRST (carries the transition spec), force a
-    // reflow, THEN remove [data-open]. If both attribute changes batch
-    // into a single style update, Safari can skip the fade-out animation
-    // entirely.
-    dialog.setAttribute('data-closing', '');
-    void dialog.offsetHeight;
-    dialog.removeAttribute('data-open');
-
-    this.#closeTimer = setTimeout(() => {
-      this.#closeTimer = null;
-      this.#closing = false;
-      dialog.removeAttribute('data-closing');
-      if (dialog.open) dialog.close();
-    }, this.#getDuration());
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UIModal } from './class.js';
 
-  show() { this.open = true; }
-  hide() { this.open = false; }
-}
-customElements.define('modal-ui', UIModal);
+defineIfFree('modal-ui', UIModal);
 
 export { UIModal };

package/components/modal/modal.yaml

@@ -1,5 +1,3 @@
-# Generated by scripts/migrate-yamls-to-v1.mjs — migrated to v1 contract.
-# Edit this file; run `npm run build:components` to regenerate a2ui.json.
 $schema: ../../../../scripts/schemas/component.yaml.schema.json
 name: UIModal
 tag: modal-ui
@@ -22,25 +20,24 @@ props:
     type: string
     default: md
     enum:
-      - sm
-      - md
-      - lg
-      - xl
+    - sm
+    - md
+    - lg
+    - xl
   text:
     description: Aria label applied to the surface element for accessibility
     type: string
-    default: ""
+    default: ''
 events:
   close:
-    description: Fired when the overlay is dismissed via backdrop click, Escape key, popover toggle, or
-      programmatic hide(). Bubbles.
+    description: Fired when the overlay is dismissed via backdrop click, Escape key, popover toggle, or programmatic hide().
+      Bubbles.
 slots:
   default:
-    description: Content placed inside the modal surface. Accepts any elements (card-ui, command-ui,
-      custom markup).
+    description: Content placed inside the modal surface. Accepts any elements (card-ui, command-ui, custom markup).
 states:
-  - name: idle
-    description: Default, ready for interaction.
+- name: idle
+  description: Default, ready for interaction.
 traits: []
 tokens:
   --modal-backdrop:
@@ -63,31 +60,14 @@ a2ui:
   rules: []
 anti_patterns: []
 examples:
-  - name: basic-modal
-    description: Basic Modal usage
-    a2ui: >-
-      [
-        {
-          "id": "root",
-          "component": "Card",
-          "children": [
-            "sec"
-          ]
-        },
-        {
-          "id": "sec",
-          "component": "Section",
-          "children": [
-            "comp"
-          ]
-        },
-        {
-          "id": "comp",
-          "component": "Modal",
-          "text": "Example Modal"
-        }
-      ]
+- name: basic-modal
+  description: Basic Modal usage
+  a2ui: "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\"\n    ]\n  },\n  {\n\
+    \    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"comp\"\n    ]\n  },\n  {\n    \"\
+    id\": \"comp\",\n    \"component\": \"Modal\",\n    \"text\": \"Example Modal\"\n  }\n]"
 keywords:
-  - modal
-synonyms: {}
+- modal
+synonyms:
+  tags:
+  - Dialog
 related: []

package/components/nav/class.js

@@ -0,0 +1,150 @@
+/**
+ * Non-side-effect class export for `<nav-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`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <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';
+
+export 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;
+  }
+}

package/components/nav/nav.a2ui.json

@@ -48,6 +48,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "nav-select": {
         "description": "Bubbles from <nav-item-ui> children when one is selected. Detail: { item, text, value }."

package/components/nav/nav.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `<nav-ui>` — 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.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/nav
+ *
+ * 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 NavSelectEvent = CustomEvent<unknown>;
+
+export class UINav extends UIElement {
+  /** Primary-variant only. Force icon-only collapse regardless of viewport width. */
+  collapsed: boolean;
+  /** Auto-place dividers between adjacent groups + items. */
+  divider: boolean;
+  /** Optional kicker label. Section variant renders it via ::before; primary uses it as aria-label only. */
+  heading: string;
+  /** Visual treatment. primary = app sidebar; section = subnav rail. */
+  variant: 'primary' | 'section';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UINav, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'nav-select', listener: (ev: NavSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/nav/nav.js

@@ -1,140 +1,17 @@
 /**
- * <nav-ui> — Navigation rail (consolidated primary + section variants).
+ * `<nav-ui>` — auto-registers the tag on import.
  *
- * Consolidates the prior `app-nav-ui` + `section-nav-ui` dual-family
- * per ADR-0015 § Nav consolidation. Variant drives visual treatment;
- * behavior is unified.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * 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).
+ *   import { UINav } from '@adia-ai/web-components/components/nav/class';
  *
- * 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 }
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-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 = '';
-    });
-  }
+import { defineIfFree } from '../../core/register.js';
+import { UINav } from './class.js';
 
-  disconnected() {
-    this.removeEventListener('click', this.#onClick);
-    this.#ro?.disconnect();
-    this.#ro = null;
-  }
-}
+defineIfFree('nav-ui', UINav);
 
-customElements.define('nav-ui', UINav);
 export { UINav };