@adia-ai/web-components 0.4.6 → 0.4.8

package/components/list/list.js

@@ -1,240 +1,18 @@
 /**
- * <list-ui divider>
- *   <list-item-ui icon="check" text="Item one"></list-item-ui>
- *   <list-item-ui icon="check" text="Item two"></list-item-ui>
- * </list-ui>
+ * `<list-ui>` — auto-registers the tag on import.
  *
- * Styled list with optional icons and dividers.
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
  *
- * Selection (mirrors table-ui):
- *   <list-ui selectable selected-key="row-2">
- *     <list-item-ui id="row-1" text="One"></list-item-ui>
- *     <list-item-ui id="row-2" text="Two"></list-item-ui>
- *   </list-ui>
+ *   import { UIList, UIListItem } from '@adia-ai/web-components/components/list/class';
  *
- * When `selectable`:
- *   - Children (role="listitem") become keyboard-focusable via roving tabindex.
- *   - Click selects the child; key is its id or data-key.
- *   - aria-selected is set on all children.
- *   - Fires `selection-change` with { key, previousKey }.
+ * @see ../../USAGE.md#registration--auto-vs-explicit
  */
 
-import { UIElement } from '../../core/element.js';
+import { defineIfFree } from '../../core/register.js';
+import { UIList, UIListItem } from './class.js';
 
-class UIList extends UIElement {
-  static properties = {
-    divider:     { type: Boolean, default: false, reflect: true },
-    spacing:     { type: String,  default: 'md',  reflect: true },
-    selectable:  { type: Boolean, default: false, reflect: true },
-    selectedKey: { type: String,  default: '',    reflect: true, attribute: 'selected-key' },
-  };
-
-  static template = () => null;
-
-  #bound = false;
-
-  connected() {
-    this.setAttribute('role', 'list');
-    if (!this.#bound) {
-      this.#bound = true;
-      this.addEventListener('click', this.#onClick);
-      this.addEventListener('keydown', this.#onKeydown);
-    }
-  }
-
-  disconnected() {
-    this.removeEventListener('click', this.#onClick);
-    this.removeEventListener('keydown', this.#onKeydown);
-    this.#bound = false;
-  }
-
-  render() {
-    if (!this.selectable) {
-      // Clear selection chrome from children
-      for (const ch of this.#items()) {
-        ch.removeAttribute('aria-selected');
-        ch.removeAttribute('tabindex');
-      }
-      return;
-    }
-    const key = this.selectedKey || '';
-    const items = this.#items();
-    let focusTarget = null;
-    for (const ch of items) {
-      const k = this.#keyOf(ch);
-      const selected = k && k === key;
-      ch.setAttribute('aria-selected', selected ? 'true' : 'false');
-      ch.setAttribute('tabindex', selected ? '0' : '-1');
-      if (selected) focusTarget = ch;
-    }
-    // Ensure at least one item is focusable (first) when nothing selected.
-    if (!focusTarget && items.length) {
-      items[0].setAttribute('tabindex', '0');
-    }
-  }
-
-  #items() {
-    return [...this.children].filter(
-      (el) => el.getAttribute && el.getAttribute('role') === 'listitem',
-    );
-  }
-
-  #keyOf(el) {
-    return el.id || el.getAttribute('data-key') || '';
-  }
-
-  #selectKey(newKey, { focus = false } = {}) {
-    if (!this.selectable) return;
-    if (!newKey) return;
-    const previousKey = this.selectedKey || '';
-    if (newKey === previousKey) return;
-    this.selectedKey = newKey;
-    this.dispatchEvent(new CustomEvent('selection-change', {
-      detail: { key: newKey, previousKey },
-      bubbles: true,
-    }));
-    if (focus) {
-      const el = [...this.#items()].find((i) => this.#keyOf(i) === newKey);
-      el?.focus?.();
-    }
-  }
-
-  #onClick = (e) => {
-    if (!this.selectable) return;
-    const item = e.target.closest?.('[role="listitem"]');
-    if (!item || item.parentElement !== this) return;
-    const key = this.#keyOf(item);
-    if (key) this.#selectKey(key);
-  };
-
-  #onKeydown = (e) => {
-    if (!this.selectable) return;
-    const items = this.#items();
-    if (!items.length) return;
-    const current = document.activeElement;
-    const idx = items.indexOf(current);
-    if (idx < 0) return;
-    let next = idx;
-    switch (e.key) {
-      case 'ArrowDown': next = Math.min(items.length - 1, idx + 1); break;
-      case 'ArrowUp':   next = Math.max(0, idx - 1); break;
-      case 'Home':      next = 0; break;
-      case 'End':       next = items.length - 1; break;
-      case 'Enter':
-      case ' ': {
-        e.preventDefault();
-        const key = this.#keyOf(items[idx]);
-        if (key) this.#selectKey(key);
-        return;
-      }
-      default: return;
-    }
-    if (next !== idx) {
-      e.preventDefault();
-      items[next]?.focus?.();
-    }
-  };
-}
-customElements.define('list-ui', UIList);
-
-class UIListItem extends UIElement {
-  static properties = {
-    icon:        { type: String, default: '', reflect: true },
-    text:        { type: String, default: '', reflect: true },
-    description: { type: String, default: '', reflect: true },
-  };
-
-  static template = () => null;
-
-  connected() {
-    this.setAttribute('role', 'listitem');
-    this.#stamp();
-  }
-
-  // Scoped to direct children — never reach into nested custom elements,
-  // otherwise we'd accidentally remove e.g. a <span slot="icon"> inside a
-  // child <card-ui> when list-item-ui has no `icon` prop.
-  #ownChild(selector) {
-    for (const ch of this.children) {
-      if (ch.matches(selector)) return ch;
-    }
-    return null;
-  }
-
-  // Mark slot elements we create so render() never deletes consumer-provided ones.
-  #stampMark(el) { el.dataset.listStamped = '1'; return el; }
-  #wasStamped(el) { return el?.dataset?.listStamped === '1'; }
-
-  #stamp() {
-    if (this.#ownChild('[slot="content"]')) return;
-
-    if (this.icon) {
-      let iconEl = this.#ownChild('[slot="icon"]') || this.#ownChild('icon-ui');
-      if (!iconEl) {
-        iconEl = this.#stampMark(document.createElement('icon-ui'));
-        iconEl.setAttribute('slot', 'icon');
-        this.prepend(iconEl);
-      }
-      iconEl.setAttribute('name', this.icon);
-    }
-
-    if (this.text) {
-      let span = this.#ownChild('[slot="text"]');
-      if (!span) {
-        span = this.#stampMark(document.createElement('span'));
-        span.setAttribute('slot', 'text');
-        this.appendChild(span);
-      }
-      if (this.#wasStamped(span)) span.textContent = this.text;
-    }
-
-    if (this.description) {
-      let desc = this.#ownChild('[slot="description"]');
-      if (!desc) {
-        desc = this.#stampMark(document.createElement('span'));
-        desc.setAttribute('slot', 'description');
-        this.appendChild(desc);
-      }
-      if (this.#wasStamped(desc)) desc.textContent = this.description;
-    }
-  }
-
-  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;
-
-    // Sync description — only touch elements we stamped.
-    const descEl = this.#ownChild('[slot="description"]');
-    if (this.description) {
-      if (descEl) {
-        if (this.#wasStamped(descEl)) descEl.textContent = this.description;
-      } else {
-        const el = this.#stampMark(document.createElement('span'));
-        el.setAttribute('slot', 'description');
-        el.textContent = this.description;
-        this.appendChild(el);
-      }
-    } else if (this.#wasStamped(descEl)) {
-      descEl.remove();
-    }
-  }
-}
-customElements.define('list-item-ui', UIListItem);
+defineIfFree('list-ui', UIList);
+defineIfFree('list-item-ui', UIListItem);
 
 export { UIList, UIListItem };

package/components/list/list.yaml

@@ -7,6 +7,10 @@ component: List
 category: layout
 version: 1
 description: Styled list with optional icons and dividers.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
 props:
   divider:
     description: Show dividers between items

package/components/menu/class.js

@@ -0,0 +1,332 @@
+/**
+ * Non-side-effect class export for `<menu-ui>` (+ co-located primitives).
+ *
+ * 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/menu`
+ * (which imports this file + calls `defineIfFree()`).
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * <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>
+ *
+ * Dropdown action menu. Fires `action` events, does not hold a value.
+ *
+ * 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 { UIElement } from '../../core/element.js';
+import { anchorPopover } from '../../core/anchor.js';
+
+export 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;
+  }
+}
+
+export 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();
+  }
+}
+
+export class UIMenuDivider extends UIElement {
+  static properties = {};
+  static template = () => null;
+
+  connected() {
+    this.setAttribute('role', 'separator');
+  }
+}

package/components/menu/menu.a2ui.json

@@ -45,6 +45,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "action": {
         "description": "Fired when a menu item is activated. Detail contains the triggering element."

package/components/menu/menu.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `<menu-ui>` — Dropdown action menu with roving focus and keyboard navigation. Uses Popover API.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/menu
+ *
+ * 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 MenuActionEvent = CustomEvent<unknown>;
+
+export class UIMenu extends UIElement {
+  /** Gap in px */
+  gap: number;
+  /** Controls visibility via popover API */
+  open: boolean;
+  /** Preferred position relative to the anchor element */
+  placement: 'bottom-start' | 'bottom-end' | 'top-start' | 'top-end';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIMenu, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'action', listener: (ev: MenuActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}