@adia-ai/web-components 0.6.36 → 0.6.38

package/components/button/button.css

@@ -161,15 +161,23 @@ button-ui[color="danger"]:not([disabled]):hover {
     --button-fg-default: var(--button-fg-danger, var(--button-fg-danger-default));
   }
   :scope[color="success"] {
-    --button-bg-default: var(--a-success-strong);
+    /* Consume the L3 `-bg` alias, not the L2 `-strong` step. Currently
+       resolves identically (both = `-50`), but consuming `-bg` future-
+       proofs if the surface-step ever redirects (as -warning-bg did
+       in v0.6.36 to fix muddy contrast). */
+    --button-bg-default: var(--a-success-bg);
     --button-fg-default: var(--a-success-fg);
   }
   :scope[color="info"] {
-    --button-bg-default: var(--a-info-strong);
+    --button-bg-default: var(--a-info-bg);
     --button-fg-default: var(--a-info-fg);
   }
   :scope[color="warning"] {
-    --button-bg-default: var(--a-warning-strong);
+    /* `--a-warning-bg` (bright amber, scheme-independent) not
+       `-strong` (mid-tone). The pair `-strong` + `-fg` gives muddy
+       brown-on-brown — the L3 `-bg` is the canonical solid-warning
+       surface paired with `-fg` (dark text). */
+    --button-bg-default: var(--a-warning-bg);
     --button-fg-default: var(--a-warning-fg);
   }
 

package/components/calendar-picker/calendar-picker.a2ui.json

@@ -66,6 +66,21 @@
       "type": "string",
       "default": "Select date..."
     },
+    "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",
+      "enum": [
+        "top",
+        "bottom",
+        "left",
+        "right",
+        "top-start",
+        "top-end",
+        "bottom-start",
+        "bottom-end"
+      ],
+      "default": "bottom"
+    },
     "value": {
       "description": "Selected date (ISO string)",
       "type": "string",

package/components/calendar-picker/calendar-picker.class.js

@@ -68,6 +68,10 @@ export class UICalendarPicker extends UIFormElement {
     min:         { type: String,  default: '', reflect: true },
     max:         { type: String,  default: '', reflect: true },
     open:        { type: Boolean, default: false, reflect: true },
+    // Popover placement — yaml documented this as reflect:true since v1;
+    // the JS reads it via getAttribute('placement') in the anchorPopover
+    // call site. Declaring here so el.placement = 'top' also updates.
+    placement:   { type: String,  default: 'bottom', reflect: true },
   };
 
   static template = () => null;
@@ -139,8 +143,10 @@ export class UICalendarPicker extends UIFormElement {
     if (this.open) {
       this.#renderCalendar();
       this.#popover?.showPopover?.();
+      // ADR-0034 Rule 2: calendar panel (~330px) >> trigger button (~200px) → center.
+      // Consumer can override via placement="bottom-start|top|…" attribute.
       this.#anchorCleanup = anchorPopover(this.#trigger, this.#popover, {
-        placement: 'bottom-start', gap: 4,
+        placement: this.getAttribute('placement') || 'bottom', gap: 4,
       });
       this.#openRaf = requestAnimationFrame(() => {
         this.#openRaf = null;

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/card/card.a2ui.json

@@ -113,7 +113,23 @@
       "alert",
       "skeleton"
     ],
-    "slots": {},
+    "slots": {
+      "description": {
+        "description": "Optional descriptive text beneath the heading. Renders in the header slot at body-subtle typography. Use for short metadata lines (timestamp, author, status sentence)."
+      },
+      "action": {
+        "description": "Trailing action cluster in the header (e.g. icon-buttons, menu trigger, more-options). Aligns to the header's flex-end edge."
+      },
+      "action-leading": {
+        "description": "Leading action cluster in the header (e.g. back button, switcher, breadcrumb-context). Aligns to the header's flex-start edge, before the icon/heading column."
+      },
+      "heading": {
+        "description": "Card title. Renders in the header slot with title typography. Typically a short noun phrase or document/object name."
+      },
+      "icon": {
+        "description": "Optional leading icon for the card header (status / brand / type marker). Renders next to the heading. Use `<icon-ui name=\"…\">` or any inline icon element."
+      }
+    },
     "states": [
       {
         "description": "Default, ready for interaction.",

package/components/card/card.yaml

@@ -58,7 +58,30 @@ props:
     - soft
     - primary
 events: {}
-slots: {}
+slots:
+  icon:
+    description: >-
+      Optional leading icon for the card header (status / brand / type
+      marker). Renders next to the heading. Use `<icon-ui name="…">` or
+      any inline icon element.
+  heading:
+    description: >-
+      Card title. Renders in the header slot with title typography.
+      Typically a short noun phrase or document/object name.
+  description:
+    description: >-
+      Optional descriptive text beneath the heading. Renders in the
+      header slot at body-subtle typography. Use for short metadata
+      lines (timestamp, author, status sentence).
+  action:
+    description: >-
+      Trailing action cluster in the header (e.g. icon-buttons, menu
+      trigger, more-options). Aligns to the header's flex-end edge.
+  action-leading:
+    description: >-
+      Leading action cluster in the header (e.g. back button, switcher,
+      breadcrumb-context). Aligns to the header's flex-start edge,
+      before the icon/heading column.
 states:
 - name: idle
   description: Default, ready for interaction.

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');
+  };
+}