@adia-ai/web-components 0.4.6 → 0.4.8

package/components/menu/menu.js

@@ -1,324 +1,19 @@
 /**
- * <menu-ui>
- *   <button-ui slot="trigger" icon="dots-three-vertical" variant="ghost"></button-ui>
- *   <menu-item-ui icon="pencil" text="Edit" value="edit"></menu-item-ui>
- *   <menu-item-ui icon="copy" text="Duplicate" value="duplicate"></menu-item-ui>
- *   <menu-divider-ui></menu-divider-ui>
- *   <menu-item-ui icon="trash" text="Delete" value="delete" variant="danger"></menu-item-ui>
- * </menu-ui>
+ * `<menu-ui>` — auto-registers the tag on import.
  *
- * Dropdown action menu. Fires `action` events, does not hold a value.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Platform:
- *   • Popover API (popover="manual") → top-layer, escapes overflow/z-index.
- *   • CSS Anchor Positioning (via @core/anchor.js) with JS fallback.
- *   • Roving focus + arrow/Home/End/Enter/Escape keyboard nav.
+ *   import { UIMenu, UIMenuItem, UIMenuDivider } from '@adia-ai/web-components/components/menu/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
-import { anchorPopover } from '../../core/anchor.js';
-
-class UIMenu extends UIElement {
-  static properties = {
-    open:      { type: Boolean, default: false, reflect: true },
-    placement: { type: String,  default: 'bottom-start', reflect: true },
-    gap:       { type: Number,  default: 4, reflect: true },
-  };
-
-  static template = () => null;
-
-  #anchorCleanup = null;
-  #popover = null;
-  #bound = false;
-  #rafId = null;
-  #focusRaf = null;
-
-  connected() {
-    if (!this.#bound) {
-      this.#bound = true;
-      this.addEventListener('click', this.#onTriggerClick);
-      this.addEventListener('keydown', this.#onTriggerKey);
-    }
-  }
-
-  render() {
-    if (this.open) this.#show();
-    else this.#hide();
-  }
-
-  // ── Public API ──
-  show()   { this.open = true; }
-  hide()   { this.open = false; }
-  toggle() { this.open = !this.open; }
-
-  // ── Internal ──
-
-  #ensurePopover() {
-    if (this.#popover) return this.#popover;
-    const el = document.createElement('div');
-    el.setAttribute('data-menu-popover', '');
-    el.setAttribute('popover', 'manual');
-    el.setAttribute('role', 'menu');
-    el.addEventListener('toggle', this.#onToggle);
-    el.addEventListener('click', this.#onItemClick);
-    el.addEventListener('keydown', this.#onMenuKey);
-    this.appendChild(el);
-    this.#popover = el;
-    return el;
-  }
-
-  #show() {
-    const trigger = this.querySelector('[slot="trigger"]');
-    if (!trigger) return;
-    const pop = this.#ensurePopover();
-
-    // Move menu items into popover (so they render in the top layer).
-    const items = this.querySelectorAll(':scope > menu-item-ui, :scope > menu-divider-ui');
-    for (const item of items) pop.appendChild(item);
-
-    if (!pop.matches(':popover-open')) pop.showPopover?.();
-
-    this.#anchorCleanup?.();
-    this.#anchorCleanup = anchorPopover(trigger, pop, {
-      placement: this.placement,
-      gap: this.gap,
-    });
-
-    // Focus first enabled item (only when opened via keyboard).
-    if (this.#openedByKeyboard) {
-      this.#openedByKeyboard = false;
-      this.#focusRaf = requestAnimationFrame(() => {
-        this.#focusRaf = null;
-        this.#focusItem(0);
-      });
-    }
-
-    this.#rafId = requestAnimationFrame(() => {
-      this.#rafId = null;
-      document.addEventListener('pointerdown', this.#onOutside);
-      document.addEventListener('keydown', this.#onDocKey, true);
-    });
-  }
-
-  #hide() {
-    this.#anchorCleanup?.();
-    this.#anchorCleanup = null;
-
-    const pop = this.#popover;
-    if (pop) {
-      if (pop.matches(':popover-open')) pop.hidePopover?.();
-      // Move items back to host (before the popover div) so next open can re-adopt them.
-      const items = pop.querySelectorAll('menu-item-ui, menu-divider-ui');
-      for (const item of items) this.insertBefore(item, pop);
-    }
-
-    if (this.#rafId != null) {
-      cancelAnimationFrame(this.#rafId);
-      this.#rafId = null;
-    }
-    if (this.#focusRaf != null) {
-      cancelAnimationFrame(this.#focusRaf);
-      this.#focusRaf = null;
-    }
-    document.removeEventListener('pointerdown', this.#onOutside);
-    document.removeEventListener('keydown', this.#onDocKey, true);
-  }
-
-  #enabledItems() {
-    return Array.from(this.#popover?.querySelectorAll('menu-item-ui') ?? [])
-      .filter((el) => !el.disabled);
-  }
-
-  #focusItem(index) {
-    const items = this.#enabledItems();
-    if (!items.length) return;
-    const i = (index + items.length) % items.length;
-    const item = items[i];
-    item.setAttribute('tabindex', '-1');
-    item.focus({ preventScroll: true });
-  }
-
-  #focusedIndex() {
-    const items = this.#enabledItems();
-    return items.indexOf(document.activeElement);
-  }
-
-  // ── Events ──
-
-  #openedByKeyboard = false;
-
-  #onTriggerClick = (e) => {
-    const trigger = this.querySelector('[slot="trigger"]');
-    if (!trigger) return;
-    if (e.target === trigger || trigger.contains(e.target)) {
-      this.#openedByKeyboard = false;
-      this.open = !this.open;
-    }
-  };
-
-  #onTriggerKey = (e) => {
-    const trigger = this.querySelector('[slot="trigger"]');
-    if (!trigger || !(e.target === trigger || trigger.contains(e.target))) return;
-    if (e.key === 'ArrowDown' || e.key === 'Enter' || e.key === ' ') {
-      e.preventDefault();
-      this.#openedByKeyboard = true;
-      this.open = true;
-    }
-  };
-
-  #onItemClick = (e) => {
-    const item = e.target.closest('menu-item-ui');
-    if (!item || item.disabled) return;
-    this.dispatchEvent(new CustomEvent('action', {
-      bubbles: true,
-      detail: { value: item.value, text: item.text },
-    }));
-    this.open = false;
-    // Return focus to trigger for continued keyboard flow.
-    this.querySelector('[slot="trigger"]')?.focus?.({ preventScroll: true });
-  };
-
-  #onMenuKey = (e) => {
-    const items = this.#enabledItems();
-    if (!items.length) return;
-    const i = this.#focusedIndex();
-    switch (e.key) {
-      case 'ArrowDown': e.preventDefault(); this.#focusItem(i + 1); break;
-      case 'ArrowUp':   e.preventDefault(); this.#focusItem(i - 1); break;
-      case 'Home':      e.preventDefault(); this.#focusItem(0); break;
-      case 'End':       e.preventDefault(); this.#focusItem(items.length - 1); break;
-      case 'Enter':
-      case ' ': {
-        e.preventDefault();
-        const item = items[i] ?? items[0];
-        item?.click();
-        break;
-      }
-    }
-  };
-
-  #onOutside = (e) => {
-    if (!this.open) return;
-    if (this.contains(e.target)) return;
-    this.open = false;
-  };
-
-  #onDocKey = (e) => {
-    if (e.key === 'Escape' && this.open) {
-      e.stopPropagation();
-      e.preventDefault();
-      this.open = false;
-      this.querySelector('[slot="trigger"]')?.focus?.({ preventScroll: true });
-    } else if (e.key === 'Tab' && this.open) {
-      // Tab dismisses the menu; let focus move naturally.
-      this.open = false;
-    }
-  };
-
-  #onToggle = (e) => {
-    const nowOpen = e.newState === 'open';
-    if (nowOpen !== this.open) this.open = nowOpen;
-  };
-
-  disconnected() {
-    this.#hide();
-    if (this.#popover) {
-      this.#popover.removeEventListener('toggle', this.#onToggle);
-      this.#popover.removeEventListener('click', this.#onItemClick);
-      this.#popover.removeEventListener('keydown', this.#onMenuKey);
-    }
-    this.#popover = null;
-    this.#bound = false;
-  }
-}
-customElements.define('menu-ui', UIMenu);
-
-class UIMenuItem extends UIElement {
-  static properties = {
-    icon:     { type: String,  default: '', reflect: true },
-    text:     { type: String,  default: '', reflect: true },
-    value:    { type: String,  default: '', reflect: true },
-    variant:  { type: String,  default: 'default', reflect: true },
-    disabled: { type: Boolean, default: false, reflect: true },
-  };
-
-  static template = () => null;
-
-  connected() {
-    this.setAttribute('role', 'menuitem');
-    if (!this.hasAttribute('tabindex')) this.setAttribute('tabindex', '-1');
-    this.#stamp();
-    this.#syncAria();
-  }
-
-  // Mark slot elements we create so render() never deletes consumer-provided ones.
-  // See ADR-0010 (slot content is source of truth).
-  #stampMark(el) { el.dataset.menuItemStamped = '1'; return el; }
-  #wasStamped(el) { return el?.dataset?.menuItemStamped === '1'; }
-
-  #ownChild(selector) {
-    for (const ch of this.children) {
-      if (ch.matches(selector)) return ch;
-    }
-    return null;
-  }
-
-  #stamp() {
-    if (this.#ownChild('[slot="text"]')) return;
-
-    if (this.icon && !this.#ownChild('[slot="icon"]')) {
-      const iconEl = this.#stampMark(document.createElement('icon-ui'));
-      iconEl.setAttribute('slot', 'icon');
-      iconEl.setAttribute('name', this.icon);
-      this.appendChild(iconEl);
-    }
-
-    if (this.text) {
-      const span = this.#stampMark(document.createElement('span'));
-      span.setAttribute('slot', 'text');
-      span.textContent = this.text;
-      this.appendChild(span);
-    }
-  }
-
-  #syncAria() {
-    if (this.disabled) this.setAttribute('aria-disabled', 'true');
-    else this.removeAttribute('aria-disabled');
-  }
-
-  render() {
-    // Sync icon — only touch elements we stamped.
-    const iconEl = this.#ownChild('[slot="icon"]');
-    if (this.icon) {
-      if (iconEl) {
-        if (this.#wasStamped(iconEl)) iconEl.setAttribute('name', this.icon);
-      } else {
-        const el = this.#stampMark(document.createElement('icon-ui'));
-        el.setAttribute('slot', 'icon');
-        el.setAttribute('name', this.icon);
-        this.prepend(el);
-      }
-    } else if (this.#wasStamped(iconEl)) {
-      iconEl.remove();
-    }
-
-    // Sync text — only touch elements we stamped.
-    const textEl = this.#ownChild('[slot="text"]');
-    if (this.#wasStamped(textEl)) textEl.textContent = this.text;
-
-    this.#syncAria();
-  }
-}
-customElements.define('menu-item-ui', UIMenuItem);
-
-class UIMenuDivider extends UIElement {
-  static properties = {};
-  static template = () => null;
+import { defineIfFree } from '../../core/register.js';
+import { UIMenu, UIMenuItem, UIMenuDivider } from './class.js';
 
-  connected() {
-    this.setAttribute('role', 'separator');
-  }
-}
-customElements.define('menu-divider-ui', UIMenuDivider);
+defineIfFree('menu-ui', UIMenu);
+defineIfFree('menu-item-ui', UIMenuItem);
+defineIfFree('menu-divider-ui', UIMenuDivider);
 
 export { UIMenu, UIMenuItem, UIMenuDivider };

package/components/menu/menu.yaml

@@ -7,6 +7,10 @@ component: Menu
 category: container
 version: 1
 description: Dropdown action menu with roving focus and keyboard navigation. Uses Popover API.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui  # leading affordances on menu items (created in render)
 props:
   gap:
     description: Gap in px

package/components/modal/class.js

@@ -0,0 +1,231 @@
+/**
+ * Non-side-effect class export for `<modal-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/modal`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <modal-ui> — Centered dialog overlay.
+ *
+ * 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].
+ *
+ * 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>
+ *
+ * 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
+ */
+
+import { UIElement } from '../../core/element.js';
+
+export 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());
+  }
+
+  show() { this.open = true; }
+  hide() { this.open = false; }
+}

package/components/modal/modal.a2ui.json

@@ -50,6 +50,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "close": {
         "description": "Fired when the overlay is dismissed via backdrop click, Escape key, popover toggle, or programmatic hide(). Bubbles."
@@ -78,7 +79,11 @@
         "name": "idle"
       }
     ],
-    "synonyms": {},
+    "synonyms": {
+      "tags": [
+        "Dialog"
+      ]
+    },
     "tag": "modal-ui",
     "tokens": {
       "--modal-backdrop": {

package/components/modal/modal.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `<modal-ui>` — Centered dialog overlay using native <dialog>. Focus trapping, Escape key, backdrop.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/modal
+ *
+ * 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 ModalCloseEvent = CustomEvent<unknown>;
+
+export class UIModal extends UIElement {
+  /** Controls overlay visibility. Setting to true opens the surface with entry animation. */
+  open: boolean;
+  /** When true, suppress backdrop click and Escape key dismissal of the overlay */
+  permanent: boolean;
+  /** Width preset. sm=24rem, md=32rem, lg=48rem, full=95vw. */
+  size: 'sm' | 'md' | 'lg' | 'xl';
+  /** Aria label applied to the surface element for accessibility */
+  text: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIModal, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'close', listener: (ev: ModalCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}