@adia-ai/web-components 0.0.1

package/components/menu/menu.a2ui.json

@@ -0,0 +1,146 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/Menu.json",
+  "title": "Menu",
+  "description": "Dropdown action menu with roving focus and keyboard navigation. Uses Popover API.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "anchor": {
+      "description": "ID of the anchor element the menu positions relative to",
+      "type": "string",
+      "default": ""
+    },
+    "component": {
+      "const": "Menu"
+    },
+    "gap": {
+      "description": "Gap in px",
+      "type": "number",
+      "default": 4
+    },
+    "open": {
+      "description": "Controls visibility via popover API",
+      "type": "boolean",
+      "default": false
+    },
+    "placement": {
+      "description": "Preferred position relative to the anchor element",
+      "type": "string",
+      "enum": [
+        "bottom-start",
+        "bottom-end",
+        "top-start",
+        "top-end"
+      ],
+      "default": "bottom-start"
+    },
+    "trigger": {
+      "description": "ID of the element that opens this menu (click handler + aria-controls).",
+      "type": "string",
+      "default": ""
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "container",
+    "events": {
+      "action": {
+        "description": "Fired when a menu item is activated. Detail contains the triggering element."
+      }
+    },
+    "examples": [
+      {
+        "description": "Basic Menu 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\": \"Menu\"\n  }\n]",
+        "name": "basic-menu"
+      }
+    ],
+    "keywords": [
+      "menu",
+      "navigation",
+      "navbar",
+      "hamburger",
+      "dropdown",
+      "popover",
+      "context-menu",
+      "right-click"
+    ],
+    "name": "AdiaMenu",
+    "related": [],
+    "slots": {
+      "default": {
+        "description": "Menu items with role=\"menuitem\" and optional <hr> dividers"
+      }
+    },
+    "states": [
+      {
+        "description": "Default, ready for interaction.",
+        "name": "idle"
+      }
+    ],
+    "synonyms": {
+      "context-menu": [
+        "popover",
+        "menu"
+      ],
+      "dropdown": [
+        "popover",
+        "menu",
+        "select",
+        "form"
+      ],
+      "hamburger": [
+        "nav",
+        "menu",
+        "sidebar",
+        "drawer"
+      ],
+      "menu": [
+        "nav",
+        "sidebar",
+        "popover",
+        "menu",
+        "command"
+      ],
+      "navbar": [
+        "nav",
+        "menu",
+        "sidebar",
+        "breadcrumb"
+      ],
+      "navigation": [
+        "nav",
+        "sidebar",
+        "breadcrumb",
+        "tabs",
+        "menu",
+        "pagination"
+      ],
+      "popover": [
+        "popover",
+        "menu",
+        "tooltip"
+      ],
+      "right-click": [
+        "popover",
+        "menu"
+      ]
+    },
+    "tag": "menu-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/menu/menu.css

@@ -0,0 +1,146 @@
+@scope (menu-ui) {
+  :scope {
+    box-sizing: border-box;
+    display: inline-flex;
+    position: relative;
+  }
+}
+
+/* Items/dividers in Light DOM are hidden unless they've been adopted
+   into the popover on open. Popover API also hides the popover itself when closed. */
+menu-ui > menu-item-ui,
+menu-ui > menu-divider-ui {
+  display: none !important;
+}
+
+/* ── Top-layer: cannot inherit component tokens ── */
+
+menu-ui [data-menu-popover] {
+  margin: 0;
+  padding: var(--a-space-1);
+  border: 1px solid var(--a-border-subtle);
+  border-radius: var(--a-radius-lg);
+  background: var(--a-bg-subtle);
+  box-shadow: var(--a-shadow-lg);
+  min-width: 10rem;
+  font-family: inherit;
+  font-size: var(--a-ui-size);
+  color: var(--a-fg);
+}
+
+@scope (menu-item-ui) {
+  :where(:scope) {
+    /* ── Layout ── */
+    --menu-item-gap:            var(--a-space-2);
+    --menu-item-px:             var(--a-space-2);
+    --menu-item-py:             var(--a-space-1-5);
+    --menu-item-radius:         var(--a-radius-md);
+
+    /* ── Colors ── */
+    --menu-item-bg:             transparent;
+    --menu-item-fg:             var(--a-fg-subtle);
+    --menu-item-fg-hover:       var(--a-fg);
+    --menu-item-bg-hover:       var(--a-bg-muted);
+    --menu-item-fg-disabled:    var(--a-fg-disabled, var(--a-fg-muted));
+    --menu-item-icon-fg:        var(--a-fg-muted);
+    --menu-item-icon-fg-hover:  var(--a-fg);
+    --menu-item-icon-disabled:  var(--a-fg-disabled, var(--a-fg-muted));
+    --menu-item-danger-fg:      var(--a-danger-bg);
+    --menu-item-danger-bg:      var(--a-danger-muted);
+
+    /* ── Typography ── */
+    --menu-item-font-size:      var(--a-ui-size);
+
+    /* ── Transition ── */
+    --menu-item-duration:       var(--a-duration-fast);
+    --menu-item-easing:         var(--a-easing);
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    gap: var(--menu-item-gap);
+    padding: var(--menu-item-py) var(--menu-item-px);
+    border-radius: var(--menu-item-radius);
+    font-size: var(--menu-item-font-size);
+    background: var(--menu-item-bg);
+    color: var(--menu-item-fg);
+    cursor: pointer;
+    transition:
+      background var(--menu-item-duration) var(--menu-item-easing),
+      color var(--menu-item-duration) var(--menu-item-easing);
+  }
+
+  :scope:hover,
+  :scope:focus-visible {
+    --menu-item-bg: var(--menu-item-bg-hover);
+    --menu-item-fg: var(--menu-item-fg-hover);
+    outline: none;
+  }
+
+  /* Icon */
+  [slot="icon"] {
+    flex-shrink: 0;
+    --a-icon-size: var(--menu-item-font-size);
+    color: var(--menu-item-icon-fg);
+    transition: color var(--menu-item-duration) var(--menu-item-easing);
+  }
+  :scope:hover [slot="icon"] {
+    color: var(--menu-item-icon-fg-hover);
+  }
+
+  /* Text */
+  [slot="text"] {
+    flex: 1;
+    white-space: nowrap;
+  }
+
+  /* ── Variant: danger ── */
+  :scope[variant="danger"] {
+    --menu-item-fg: var(--a-danger-bg);
+  }
+  :scope[variant="danger"]:hover {
+    --menu-item-bg: var(--menu-item-danger-bg);
+    --menu-item-fg: var(--menu-item-danger-fg);
+  }
+  :scope[variant="danger"] [slot="icon"] {
+    color: var(--menu-item-danger-fg);
+  }
+  :scope[variant="danger"]:hover [slot="icon"] {
+    color: var(--menu-item-danger-fg);
+  }
+
+  /* ── Disabled ── */
+  :scope[disabled] {
+    --menu-item-fg: var(--menu-item-fg-disabled);
+    pointer-events: none;
+    cursor: not-allowed;
+  }
+  :scope[disabled] [slot="icon"] {
+    color: var(--menu-item-icon-disabled);
+  }
+  :scope[disabled]:hover {
+    --menu-item-bg: transparent;
+    --menu-item-fg: var(--menu-item-fg-disabled);
+  }
+}
+
+@scope (menu-divider-ui) {
+  :where(:scope) {
+    /* ── Layout ── */
+    --menu-divider-my: var(--a-space-1);
+
+    /* ── Colors ── */
+    --menu-divider-color: var(--a-border-subtle);
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: block;
+    height: 1px;
+    background: var(--menu-divider-color);
+    margin: var(--menu-divider-my) 0;
+    border: none;
+  }
+}

package/components/menu/menu.js

@@ -0,0 +1,296 @@
+/**
+ * <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 { AdiaElement } from '@core/element.js';
+import { anchorPopover } from '@core/anchor.js';
+
+class AdiaMenu extends AdiaElement {
+  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;
+
+  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;
+      requestAnimationFrame(() => this.#focusItem(0));
+    }
+
+    requestAnimationFrame(() => {
+      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);
+    }
+
+    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', AdiaMenu);
+
+class AdiaMenuItem extends AdiaElement {
+  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();
+  }
+
+  #stamp() {
+    if (this.querySelector('[slot="text"]')) return;
+
+    if (this.icon) {
+      const iconEl = document.createElement('icon-ui');
+      iconEl.setAttribute('slot', 'icon');
+      iconEl.setAttribute('name', this.icon);
+      this.appendChild(iconEl);
+    }
+
+    if (this.text) {
+      const span = 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() {
+    const iconEl = this.querySelector('[slot="icon"]');
+    if (this.icon) {
+      if (iconEl) {
+        iconEl.setAttribute('name', this.icon);
+      } else {
+        const el = document.createElement('icon-ui');
+        el.setAttribute('slot', 'icon');
+        el.setAttribute('name', this.icon);
+        this.prepend(el);
+      }
+    } else if (iconEl) {
+      iconEl.remove();
+    }
+
+    const textEl = this.querySelector('[slot="text"]');
+    if (textEl) textEl.textContent = this.text;
+
+    this.#syncAria();
+  }
+}
+customElements.define('menu-item-ui', AdiaMenuItem);
+
+class AdiaMenuDivider extends AdiaElement {
+  static properties = {};
+  static template = () => null;
+
+  connected() {
+    this.setAttribute('role', 'separator');
+  }
+}
+customElements.define('menu-divider-ui', AdiaMenuDivider);
+
+export { AdiaMenu, AdiaMenuItem, AdiaMenuDivider };

package/components/menu/menu.yaml

@@ -0,0 +1,123 @@
+# 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: AdiaMenu
+tag: menu-ui
+component: Menu
+category: container
+version: 1
+description: Dropdown action menu with roving focus and keyboard navigation. Uses Popover API.
+props:
+  anchor:
+    description: ID of the anchor element the menu positions relative to
+    type: string
+    default: ""
+  trigger:
+    description: ID of the element that opens this menu (click handler + aria-controls).
+    type: string
+    default: ""
+  gap:
+    description: Gap in px
+    type: number
+    default: 4
+  open:
+    description: Controls visibility via popover API
+    type: boolean
+    default: false
+    reflect: true
+  placement:
+    description: Preferred position relative to the anchor element
+    type: string
+    default: bottom-start
+    enum:
+      - bottom-start
+      - bottom-end
+      - top-start
+      - top-end
+events:
+  action:
+    description: Fired when a menu item is activated. Detail contains the triggering element.
+slots:
+  default:
+    description: Menu items with role="menuitem" and optional <hr> dividers
+states:
+  - name: idle
+    description: Default, ready for interaction.
+traits: []
+tokens: {}
+a2ui:
+  rules: []
+anti_patterns: []
+examples:
+  - name: basic-menu
+    description: Basic Menu usage
+    a2ui: >-
+      [
+        {
+          "id": "root",
+          "component": "Card",
+          "children": [
+            "sec"
+          ]
+        },
+        {
+          "id": "sec",
+          "component": "Section",
+          "children": [
+            "comp"
+          ]
+        },
+        {
+          "id": "comp",
+          "component": "Menu"
+        }
+      ]
+keywords:
+  - menu
+  - navigation
+  - navbar
+  - hamburger
+  - dropdown
+  - popover
+  - context-menu
+  - right-click
+synonyms:
+  context-menu:
+    - popover
+    - menu
+  dropdown:
+    - popover
+    - menu
+    - select
+    - form
+  hamburger:
+    - nav
+    - menu
+    - sidebar
+    - drawer
+  menu:
+    - nav
+    - sidebar
+    - popover
+    - menu
+    - command
+  navbar:
+    - nav
+    - menu
+    - sidebar
+    - breadcrumb
+  navigation:
+    - nav
+    - sidebar
+    - breadcrumb
+    - tabs
+    - menu
+    - pagination
+  popover:
+    - popover
+    - menu
+    - tooltip
+  right-click:
+    - popover
+    - menu
+related: []