@adia-ai/web-components 0.6.36 → 0.6.37

package/components/calendar-picker/calendar-picker.yaml

@@ -59,6 +59,20 @@ props:
     description: Selected date (ISO string)
     type: string
     default: ''
+  placement:
+    description: Popover placement relative to the trigger. Default `bottom` centers the calendar panel under the trigger (ADR-0034 Rule 2 — calendar panel wider than trigger).
+    type: string
+    default: bottom
+    reflect: true
+    enum:
+      - top
+      - bottom
+      - left
+      - right
+      - top-start
+      - top-end
+      - bottom-start
+      - bottom-end
 events:
   change:
     description: Fired when a date is selected

package/components/color-input/color-input.a2ui.json

@@ -66,7 +66,7 @@
       "default": false
     },
     "placement": {
-      "description": "Popover placement relative to the trigger.",
+      "description": "Popover placement relative to the trigger. Default `bottom` centers the color-picker panel under the swatch button (ADR-0034 Rule 2 — panel wider than trigger).",
       "type": "string",
       "enum": [
         "top",
@@ -78,7 +78,7 @@
         "bottom-start",
         "bottom-end"
       ],
-      "default": "bottom-start"
+      "default": "bottom"
     },
     "value": {
       "description": "Current color as a string in the active [format].",

package/components/color-input/color-input.class.js

@@ -42,7 +42,7 @@ export class UIColorInput extends UIFormElement {
       ...UIFormElement.properties,
       value:       { type: String,  default: '#3b82f6', reflect: true },
       format:      { type: String,  default: 'hex', reflect: true },
-      placement:   { type: String,  default: 'bottom-start', reflect: true },
+      placement:   { type: String,  default: 'bottom', reflect: true }, // ADR-0034 Rule 2: color picker panel >> swatch trigger
       open:        { type: Boolean, default: false, reflect: true },
       // Generation-constraint props forwarded to the inner <color-picker-ui>.
       // v0.5.13 §-TBD (FB-33 §1) — full parity with color-picker's 5 constraint
@@ -63,6 +63,7 @@ export class UIColorInput extends UIFormElement {
   #swatch = null;
   #valueLabel = null;
   #wired = false;
+  #popoverObserver = null;
 
   connected() {
     this.#mount();
@@ -165,7 +166,11 @@ export class UIColorInput extends UIFormElement {
       if (this.open !== open) this.open = open;
     };
     this.#popover.addEventListener('toggle', sync);
-    new MutationObserver(sync).observe(this.#popover, {
+    // Store the observer in a #field so disconnected() can clean it up
+    // — without the explicit reference, the observer survives the host
+    // element across mount/unmount cycles (audit-lifecycle-leak).
+    this.#popoverObserver = new MutationObserver(sync);
+    this.#popoverObserver.observe(this.#popover, {
       attributes: true,
       attributeFilter: ['open'],
     });
@@ -216,6 +221,8 @@ export class UIColorInput extends UIFormElement {
   disconnected() {
     this.#picker?.removeEventListener('change', this.#onPickerChange);
     this.#picker?.removeEventListener('input', this.#onPickerInput);
+    this.#popoverObserver?.disconnect();
+    this.#popoverObserver = null;
     this.#wired = false;
   }
 }

package/components/color-input/color-input.yaml

@@ -44,9 +44,9 @@ props:
     default: false
     reflect: true
   placement:
-    description: Popover placement relative to the trigger.
+    description: Popover placement relative to the trigger. Default `bottom` centers the color-picker panel under the swatch button (ADR-0034 Rule 2 — panel wider than trigger).
     type: string
-    default: bottom-start
+    default: bottom
     reflect: true
     enum:
       - top

package/components/combobox/combobox.class.js

@@ -63,6 +63,10 @@ export class UICombobox extends UIFormElement {
     ...UIFormElement.properties,
     placeholder:     { type: String,  default: 'Select...', reflect: true },
     label:           { type: String,  default: '',          reflect: true },
+    // Universal [size] system — sm/md/lg → 24/30/36 px (with density).
+    // yaml documented this as reflect:true since v1; closing the
+    // static-properties gap so el.size = 'lg' actually updates.
+    size:            { type: String,  default: 'md',        reflect: true },
     open:            { type: Boolean, default: false,       reflect: true },
     freeText:        { type: Boolean, default: false,       reflect: true, attribute: 'free-text' },
     creatable:       { type: Boolean, default: false,       reflect: true },

package/components/context-menu/context-menu.a2ui.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ContextMenu.json",
+  "title": "ContextMenu",
+  "description": "Right-click activated menu — the OS-native context-menu pattern as a\nweb component. Distinct from `menu-ui` (which is button-triggered):\nsame item shape (`menu-item-ui` children), different trigger surface\n(`contextmenu` event), and pointer-anchored positioning instead of\nelement-anchored. Pattern: WAI-APG Menu.\n\nTwo binding modes:\n **A. Wrap.** Default-slot child becomes the target:\n `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.\n **B. Selector.** Point at one or more existing elements via [for]:\n `<context-menu-ui for=\"#my-table\">...items</context-menu-ui>`.\n\nOn `contextmenu` event on a target: `preventDefault()`, position the\nmenu at the pointer coords, show via Popover API. Touch long-press\n(configurable via [long-press-ms]) does the same. Shift+F10 / Menu\nkey opens at the focused target's center for keyboard users.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "ContextMenu"
+    },
+    "for": {
+      "description": "CSS selector(s) for target element(s). Empty = use default-slot child.",
+      "type": "string",
+      "default": ""
+    },
+    "long-press-ms": {
+      "description": "Long-press duration (ms) on touch devices to open the menu.",
+      "type": "number",
+      "default": 500
+    },
+    "open": {
+      "description": "Programmatic open state. Set true to open at target center.",
+      "type": "boolean",
+      "default": false
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "Wrap a target: `<context-menu-ui><my-target></my-target>...items</context-menu-ui>` OR point at one: `<context-menu-ui for=\"#my-target\">...items</context-menu-ui>`.",
+        "why": "No target binding — the menu never opens.",
+        "wrong": "<context-menu-ui>...just items...</context-menu-ui>"
+      }
+    ],
+    "category": "container",
+    "composes": [
+      "menu-item-ui"
+    ],
+    "events": {
+      "context-menu-close": {
+        "description": "Fired when the menu closes (item-select / outside-click / Escape).",
+        "detail": {
+          "reason": {
+            "description": "\"select\" | \"outside\" | \"escape\"",
+            "type": "string"
+          }
+        }
+      },
+      "context-menu-open": {
+        "description": "Fired when the menu opens (right-click / long-press / keyboard).",
+        "detail": {
+          "target": {
+            "description": "The target element the menu was opened on.",
+            "type": "Element"
+          },
+          "x": {
+            "description": "Pointer x coord (viewport-relative); null for keyboard activation.",
+            "type": "number"
+          },
+          "y": {
+            "description": "Pointer y coord; null for keyboard activation.",
+            "type": "number"
+          }
+        }
+      },
+      "context-menu-select": {
+        "description": "Fired when an item is activated. Same shape as menu-ui's `action` event.",
+        "detail": {
+          "text": {
+            "description": "Selected item's text.",
+            "type": "string"
+          },
+          "value": {
+            "description": "Selected item's value.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Right-click a file row for Open / Rename / Delete.",
+        "a2ui": "[\n  { \"id\": \"root\", \"component\": \"ContextMenu\", \"children\": [\"target\", \"item-open\", \"item-rename\", \"div\", \"item-delete\"] },\n  { \"id\": \"target\", \"component\": \"Text\", \"textContent\": \"Right-click me\" },\n  { \"id\": \"item-open\",   \"component\": \"MenuItem\", \"value\": \"open\",   \"text\": \"Open\" },\n  { \"id\": \"item-rename\", \"component\": \"MenuItem\", \"value\": \"rename\", \"text\": \"Rename\" },\n  { \"id\": \"div\",         \"component\": \"MenuDivider\" },\n  { \"id\": \"item-delete\", \"component\": \"MenuItem\", \"value\": \"delete\", \"text\": \"Delete\", \"variant\": \"danger\" }\n]\n",
+        "name": "file-actions"
+      }
+    ],
+    "keywords": [
+      "context-menu",
+      "right-click",
+      "menu",
+      "popup-menu"
+    ],
+    "name": "UIContextMenu",
+    "related": [
+      "menu",
+      "menu-item",
+      "popover"
+    ],
+    "slots": {
+      "default": {
+        "description": "Two-purpose slot: the wrapped target element (mode A — first\nnon-menu-item-ui child) AND the menu-item-ui items. Items are\npromoted to the popover surface on open.\n"
+      }
+    },
+    "states": [
+      {
+        "description": "Default. Menu closed; trigger listeners attached.",
+        "name": "idle"
+      },
+      {
+        "description": "Menu visible at pointer position; focus inside.",
+        "attribute": "open",
+        "name": "open"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "popup-menu": [
+        "menu",
+        "context-menu"
+      ],
+      "right-click": [
+        "context-menu"
+      ]
+    },
+    "tag": "context-menu-ui",
+    "tokens": {
+      "--context-menu-bg": {
+        "description": "Menu surface background color.",
+        "default": "var(--a-bg-subtle)"
+      },
+      "--context-menu-border": {
+        "description": "Menu surface border color.",
+        "default": "var(--a-border-subtle)"
+      },
+      "--context-menu-radius": {
+        "description": "Menu surface border radius.",
+        "default": "var(--a-radius-md)"
+      },
+      "--context-menu-shadow": {
+        "description": "Menu surface shadow.",
+        "default": "var(--a-shadow-lg)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/components/context-menu/context-menu.class.js

@@ -0,0 +1,275 @@
+/**
+ * `<context-menu-ui>` — right-click activated menu (OS context-menu pattern).
+ *
+ * Two binding shapes:
+ *   A. Wrap a target — first non-menu-item-ui default-slot child becomes
+ *      the contextmenu host.
+ *   B. Point at targets via [for="<selector>"] — useful for whole-table
+ *      / whole-canvas menus where wrapping isn't practical.
+ *
+ * Architecture: reuses the existing anchor pattern (core/anchor.js) by
+ * creating a virtual 1×1 anchor element at the pointer coords on each
+ * open. anchorPopover() does the rest — handles native CSS anchor-
+ * positioning + JS fallback + viewport clamping + scroll/resize updates.
+ * This keeps coord-anchored popovers using the same code path as every
+ * other popover surface in the system (menu-ui, popover-ui, etc.).
+ *
+ * @see ../../core/anchor.js
+ * @see ../menu/menu.class.js — peer button-triggered menu primitive.
+ */
+
+import { UIElement } from '../../core/element.js';
+import { anchorPopover } from '../../core/anchor.js';
+
+const LONG_PRESS_DEFAULT = 500;
+
+export class UIContextMenu extends UIElement {
+  static properties = {
+    for:         { type: String,  default: '',                 reflect: true },
+    open:        { type: Boolean, default: false,              reflect: true },
+    longPressMs: { type: Number,  default: LONG_PRESS_DEFAULT, reflect: false, attribute: 'long-press-ms' },
+  };
+
+  static template = () => null;
+
+  #surface = null;
+  #virtualAnchor = null;
+  #anchorCleanup = null;
+  #targets = [];
+  #touchTimer = null;
+  #lastTarget = null;
+  #outsideHandler = null;
+  #keyHandler = null;
+
+  connected() {
+    super.connected();
+    this.#bindTargets();
+  }
+
+  disconnected() {
+    super.disconnected();
+    this.#unbindTargets();
+    this.#teardown();
+    this.#surface?.remove();
+    this.#surface = null;
+  }
+
+  /* ── Public API ──────────────────────────────────────────────────── */
+
+  openAt(x, y, target = null) {
+    target ??= this.#targets[0] ?? null;
+    if (!target) return;
+    this.#lastTarget = target;
+    if (x == null || y == null) {
+      const r = target.getBoundingClientRect();
+      x = r.left + r.width / 2;
+      y = r.top + r.height / 2;
+    }
+    this.#show(x, y);
+  }
+
+  close(reason = 'manual') {
+    this.#hide(reason);
+  }
+
+  /* ── Target binding ──────────────────────────────────────────────── */
+
+  #bindTargets() {
+    this.#targets = this.#resolveTargets();
+    for (const t of this.#targets) {
+      t.addEventListener('contextmenu', this.#onContextMenu);
+      t.addEventListener('touchstart',  this.#onTouchStart, { passive: true });
+      t.addEventListener('touchend',    this.#onTouchEnd);
+      t.addEventListener('touchcancel', this.#onTouchEnd);
+      t.addEventListener('keydown',     this.#onTargetKeydown);
+    }
+  }
+
+  #unbindTargets() {
+    for (const t of this.#targets) {
+      t.removeEventListener('contextmenu', this.#onContextMenu);
+      t.removeEventListener('touchstart',  this.#onTouchStart);
+      t.removeEventListener('touchend',    this.#onTouchEnd);
+      t.removeEventListener('touchcancel', this.#onTouchEnd);
+      t.removeEventListener('keydown',     this.#onTargetKeydown);
+    }
+    this.#targets = [];
+  }
+
+  #resolveTargets() {
+    if (this.for) {
+      try { return [...document.querySelectorAll(this.for)]; }
+      catch (e) {
+        // eslint-disable-next-line no-console
+        console.warn(`[context-menu-ui] invalid [for] selector: ${this.for}`, e);
+        return [];
+      }
+    }
+    for (const child of this.children) {
+      const tag = child.tagName.toLowerCase();
+      if (tag !== 'menu-item-ui' && tag !== 'menu-divider-ui') return [child];
+    }
+    return [];
+  }
+
+  /* ── Trigger event handlers ──────────────────────────────────────── */
+
+  #onContextMenu = (e) => {
+    if (e.defaultPrevented) return;
+    if (!this.#hasItems()) return;
+    e.preventDefault();
+    this.#lastTarget = e.currentTarget;
+    this.#show(e.clientX, e.clientY);
+  };
+
+  #onTouchStart = (e) => {
+    if (!this.#hasItems()) return;
+    const touch = e.touches[0];
+    if (!touch) return;
+    this.#touchTimer = setTimeout(() => {
+      this.#lastTarget = e.currentTarget;
+      this.#show(touch.clientX, touch.clientY);
+    }, this.longPressMs ?? LONG_PRESS_DEFAULT);
+  };
+
+  #onTouchEnd = () => {
+    if (this.#touchTimer) clearTimeout(this.#touchTimer);
+    this.#touchTimer = null;
+  };
+
+  #onTargetKeydown = (e) => {
+    if ((e.shiftKey && e.key === 'F10') || e.key === 'ContextMenu') {
+      if (!this.#hasItems()) return;
+      e.preventDefault();
+      this.#lastTarget = e.currentTarget;
+      this.openAt(null, null, e.currentTarget);
+    }
+  };
+
+  /* ── Show / hide ─────────────────────────────────────────────────── */
+
+  #hasItems() {
+    return [...this.children].some((c) => c.tagName.toLowerCase() === 'menu-item-ui');
+  }
+
+  #ensureSurface() {
+    if (this.#surface) return this.#surface;
+    const surface = document.createElement('div');
+    surface.setAttribute('data-context-menu-surface', '');
+    surface.setAttribute('popover', 'manual');
+    surface.setAttribute('role', 'menu');
+    surface.setAttribute('aria-label', this.getAttribute('aria-label') || 'Context menu');
+    surface.tabIndex = -1;
+    // Inline outline reset — the surface is appended to document.body
+    // (outside the @scope(context-menu-ui) boundary), so a scoped CSS
+    // rule wouldn't match. UA paints a 3-px default focus ring on the
+    // tabindex=-1 surface when it receives programmatic focus on open.
+    surface.style.outline = 'none';
+    surface.addEventListener('click', this.#onSurfaceClick);
+    document.body.appendChild(surface);
+    this.#surface = surface;
+    return surface;
+  }
+
+  #ensureVirtualAnchor(x, y) {
+    if (!this.#virtualAnchor) {
+      const anchor = document.createElement('div');
+      anchor.setAttribute('data-context-menu-anchor', '');
+      anchor.style.cssText = 'position:fixed;width:1px;height:1px;pointer-events:none;opacity:0;';
+      document.body.appendChild(anchor);
+      this.#virtualAnchor = anchor;
+    }
+    this.#virtualAnchor.style.left = `${x}px`;
+    this.#virtualAnchor.style.top  = `${y}px`;
+    return this.#virtualAnchor;
+  }
+
+  #show(x, y) {
+    const surface = this.#ensureSurface();
+    // Hoist items into the surface.
+    surface.replaceChildren();
+    for (const child of [...this.children]) {
+      const tag = child.tagName.toLowerCase();
+      if (tag === 'menu-item-ui' || tag === 'menu-divider-ui') {
+        surface.appendChild(child.cloneNode(true));
+      }
+    }
+    // Promote to top layer FIRST so anchorPopover can measure its size.
+    try { surface.showPopover(); } catch { /* popover API unavailable */ }
+
+    // Reuse the canonical anchor pattern — virtual 1×1 element at pointer
+    // coords, then anchorPopover() handles native CSS anchor-positioning
+    // (with position-try-fallbacks for viewport flips) + JS fallback.
+    const anchor = this.#ensureVirtualAnchor(x, y);
+    this.#anchorCleanup?.();
+    this.#anchorCleanup = anchorPopover(anchor, surface, { placement: 'bottom-start', gap: 0 });
+
+    this.open = true;
+    this.#setupOpenHandlers();
+    const first = surface.querySelector('menu-item-ui:not([disabled])');
+    queueMicrotask(() => first?.focus?.());
+
+    this.dispatchEvent(new CustomEvent('context-menu-open', {
+      bubbles: true,
+      detail: { target: this.#lastTarget, x, y },
+    }));
+  }
+
+  #hide(reason = 'manual') {
+    if (!this.open) return;
+    this.open = false;
+    this.#teardown();
+    this.dispatchEvent(new CustomEvent('context-menu-close', {
+      bubbles: true,
+      detail: { reason },
+    }));
+    try { this.#lastTarget?.focus?.(); } catch { /* noop */ }
+  }
+
+  #teardown() {
+    this.#teardownOpenHandlers();
+    this.#anchorCleanup?.();
+    this.#anchorCleanup = null;
+    try { this.#surface?.hidePopover(); } catch { /* noop */ }
+    if (this.#virtualAnchor) {
+      this.#virtualAnchor.remove();
+      this.#virtualAnchor = null;
+    }
+  }
+
+  /* ── While-open document handlers ────────────────────────────────── */
+
+  #setupOpenHandlers() {
+    this.#outsideHandler = (e) => {
+      if (!this.#surface?.contains(e.target)) this.#hide('outside');
+    };
+    this.#keyHandler = (e) => {
+      if (e.key === 'Escape') { e.stopPropagation(); this.#hide('escape'); }
+    };
+    requestAnimationFrame(() => {
+      document.addEventListener('pointerdown', this.#outsideHandler);
+      document.addEventListener('keydown', this.#keyHandler);
+    });
+  }
+
+  #teardownOpenHandlers() {
+    if (this.#outsideHandler) document.removeEventListener('pointerdown', this.#outsideHandler);
+    if (this.#keyHandler)     document.removeEventListener('keydown', this.#keyHandler);
+    this.#outsideHandler = null;
+    this.#keyHandler = null;
+  }
+
+  /* ── Item activation ─────────────────────────────────────────────── */
+
+  #onSurfaceClick = (e) => {
+    const item = e.target.closest('menu-item-ui');
+    if (!item || item.hasAttribute('disabled')) return;
+    const value = item.getAttribute('value') || '';
+    const text  = item.getAttribute('text') || item.textContent.trim();
+    this.dispatchEvent(new CustomEvent('context-menu-select', {
+      bubbles: true,
+      detail: { value, text },
+    }));
+    this.#hide('select');
+  };
+}

package/components/context-menu/context-menu.css

@@ -0,0 +1,56 @@
+/* Host styles (scoped — host IS a context-menu-ui descendant of itself). */
+@scope (context-menu-ui) {
+  :scope {
+    /* Element itself does not render — it's just a behavioral wrapper.
+       Targets (wrapped child / [for] match) render in flow normally. */
+    display: contents;
+  }
+
+  /* Authored items live in light DOM as the source of truth, but render
+     ONLY when the surface opens (the surface clones them into the popover).
+     Hide them in flow so they don't appear next to the target. */
+  :scope > menu-item-ui,
+  :scope > menu-divider-ui {
+    display: none;
+  }
+}
+
+/* Surface styles are NOT scoped to context-menu-ui — the surface is
+   appended to document.body (escapes the host's `display: contents` so
+   fixed-position + top-layer work), so any @scope rule pinned to
+   context-menu-ui as the scope root would miss.
+
+   Chrome MUST visually match menu-ui's surface — same vocabulary, same
+   tokens, same animation. menu-ui is the canonical menu surface; this
+   is just the right-click trigger surface for the same menu shape. */
+[data-context-menu-surface] {
+  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);
+  opacity: 1;
+  translate: 0 0;
+  transition: opacity var(--a-duration-fast) var(--a-easing-out),
+              translate var(--a-duration-fast) var(--a-easing-out);
+}
+
+[data-context-menu-surface]:popover-open {
+  @starting-style {
+    opacity: 0;
+    translate: 0 -4px;
+  }
+}
+
+[data-context-menu-surface]:not(:popover-open) {
+  display: none !important;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  [data-context-menu-surface] { transition: none; }
+}

package/components/context-menu/context-menu.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `<context-menu-ui>` — Right-click activated menu — the OS-native context-menu pattern as a
+web component. Distinct from `menu-ui` (which is button-triggered):
+same item shape (`menu-item-ui` children), different trigger surface
+(`contextmenu` event), and pointer-anchored positioning instead of
+element-anchored. Pattern: WAI-APG Menu.
+
+Two binding modes:
+ **A. Wrap.** Default-slot child becomes the target:
+ `<context-menu-ui><my-table>...</my-table>...items</context-menu-ui>`.
+ **B. Selector.** Point at one or more existing elements via [for]:
+ `<context-menu-ui for="#my-table">...items</context-menu-ui>`.
+
+On `contextmenu` event on a target: `preventDefault()`, position the
+menu at the pointer coords, show via Popover API. Touch long-press
+(configurable via [long-press-ms]) does the same. Shift+F10 / Menu
+key opens at the focused target's center for keyboard users.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/context-menu
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar(s). 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 interface ContextMenuCloseEventDetail {
+  /** "select" | "outside" | "escape" */
+  reason: string;
+}
+
+export type ContextMenuCloseEvent = CustomEvent<ContextMenuCloseEventDetail>;
+export interface ContextMenuOpenEventDetail {
+  /** The target element the menu was opened on. */
+  target: string;
+  /** Pointer x coord (viewport-relative); null for keyboard activation. */
+  x: number;
+  /** Pointer y coord; null for keyboard activation. */
+  y: number;
+}
+
+export type ContextMenuOpenEvent = CustomEvent<ContextMenuOpenEventDetail>;
+export interface ContextMenuSelectEventDetail {
+  /** Selected item's text. */
+  text: string;
+  /** Selected item's value. */
+  value: string;
+}
+
+export type ContextMenuSelectEvent = CustomEvent<ContextMenuSelectEventDetail>;
+
+export class UIContextMenu extends UIElement {
+  /** CSS selector(s) for target element(s). Empty = use default-slot child. */
+  for: string;
+  /** Programmatic open state. Set true to open at target center. */
+  open: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIContextMenu, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'context-menu-close', listener: (ev: ContextMenuCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'context-menu-open', listener: (ev: ContextMenuOpenEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'context-menu-select', listener: (ev: ContextMenuSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/components/context-menu/context-menu.js

@@ -0,0 +1,17 @@
+/**
+ * `<context-menu-ui>` — auto-registers the tag on import.
+ *
+ * For non-side-effect class import (test isolation, tag override), use
+ * the `class` subpath:
+ *
+ *   import { UIContextMenu } from '@adia-ai/web-components/components/context-menu/class';
+ *
+ * @see ../../USAGE.md#registration--auto-vs-explicit
+ */
+
+import { defineIfFree } from '../../core/register.js';
+import { UIContextMenu } from './context-menu.class.js';
+
+defineIfFree('context-menu-ui', UIContextMenu);
+
+export { UIContextMenu };