@antadesign/anta 0.2.2 → 0.3.1

package/dist/elements/a-menu.js

@@ -0,0 +1,763 @@
+import { HTMLElementBase } from "../anta_helpers";
+import { AMenuItemElement } from "./a-menu-item";
+import "./a-menu.css";
+const MARGIN = 4;
+const MIN_HEIGHT = 96;
+const SUBMENU_OPEN_DELAY = 130;
+const SUBMENU_CLOSE_DELAY = 130;
+const TYPEAHEAD_RESET = 500;
+const ANCHOR_VISIBLE_RATIO = 0.5;
+const openStack = [];
+let docBound = false;
+let boundDoc = null;
+let boundView = null;
+let removePosTracker = null;
+function bindDocListeners(doc, view) {
+  if (docBound) return;
+  doc.addEventListener("pointerdown", onDocPointerDown, true);
+  doc.addEventListener("keydown", onDocKeyDown, true);
+  doc.addEventListener("contextmenu", onDocContextMenu, true);
+  view.addEventListener("resize", onResize);
+  boundDoc = doc;
+  boundView = view;
+  docBound = true;
+}
+function unbindDocListeners() {
+  if (!docBound) return;
+  boundDoc?.removeEventListener("pointerdown", onDocPointerDown, true);
+  boundDoc?.removeEventListener("keydown", onDocKeyDown, true);
+  boundDoc?.removeEventListener("contextmenu", onDocContextMenu, true);
+  boundView?.removeEventListener("resize", onResize);
+  removePosTracker?.();
+  removePosTracker = null;
+  boundDoc = null;
+  boundView = null;
+  docBound = false;
+}
+function trackPosition(el, onEscape) {
+  if (typeof IntersectionObserver === "undefined") return () => {
+  };
+  const doc = el.ownerDocument;
+  const rect = el.getBoundingClientRect();
+  const vw = doc.documentElement.clientWidth;
+  const vh = doc.documentElement.clientHeight;
+  const rootMargin = `${-rect.top}px ${-(vw - rect.right)}px ${-(vh - rect.bottom)}px ${-rect.left}px`;
+  const io = new IntersectionObserver(
+    ([entry]) => {
+      if (!entry.isIntersecting) onEscape();
+    },
+    { root: null, rootMargin, threshold: ANCHOR_VISIBLE_RATIO }
+  );
+  io.observe(el);
+  return () => io.disconnect();
+}
+function pathHitsMenus(e, primaryClick = false) {
+  const path = e.composedPath();
+  for (const m of openStack) {
+    if (path.includes(m.surface)) return true;
+    const anchor = m.triggerAnchor;
+    if (!anchor) continue;
+    if (primaryClick && m.hasAttribute("context")) continue;
+    if (path.includes(anchor)) return true;
+  }
+  return false;
+}
+function onDocPointerDown(e) {
+  if (!openStack.length) return;
+  if (!pathHitsMenus(e, e.button === 0)) dismiss(e);
+}
+function onDocContextMenu(e) {
+  if (!openStack.length) return;
+  if (!pathHitsMenus(e)) dismiss(e);
+}
+function onResize() {
+  if (!openStack.length) return;
+  dismiss();
+}
+function onDocKeyDown(e) {
+  const menu = openStack[openStack.length - 1];
+  if (!menu) return;
+  menu.handleKey(e);
+}
+function dismiss(originEvent) {
+  openStack[0]?.requestClose(originEvent);
+}
+function closeAll() {
+  for (let i = openStack.length - 1; i >= 0; i--) {
+    const m = openStack[i];
+    if (m.isOpen && !m._dismissNotified) m.emitChange("closed");
+    m._doHide();
+  }
+  openStack.length = 0;
+  unbindDocListeners();
+}
+const anchorToMenu = /* @__PURE__ */ new WeakMap();
+function handleIntersection(entries) {
+  for (const entry of entries) {
+    const menu = anchorToMenu.get(entry.target);
+    if (!menu) continue;
+    if (!menu.listening && entry.isIntersecting) {
+      requestAnimationFrame(() => menu.setupListeners());
+    } else if (menu.listening && !entry.isIntersecting) {
+      requestAnimationFrame(() => {
+        menu.teardownListeners();
+        if (menu.isOpen) menu.close();
+      });
+    }
+  }
+}
+const lazyObserver = typeof IntersectionObserver !== "undefined" ? new IntersectionObserver(handleIntersection, { root: null, rootMargin: "0px", threshold: 0 }) : null;
+class AMenuElement extends HTMLElementBase {
+  static observedAttributes = ["placement", "context", "coord", "offset", "nohover", "state"];
+  /** Shadow-internal popover surface — the only thing we ever mutate. */
+  surface;
+  listening = false;
+  _shown = false;
+  teardown;
+  /** A controlled menu was told to dismiss (it emitted `statechange→'closed'`)
+   *  but stays visible until the consumer flips `state`. The flag lets the
+   *  `closeAll` backstop skip a duplicate emit. Cleared on every show. */
+  _dismissNotified = false;
+  // Submenu hover-intent timers.
+  openTimer;
+  closeTimer;
+  // Typeahead state (root navigation).
+  typeBuffer = "";
+  typeTimer;
+  constructor() {
+    super();
+    const shadow = this.attachShadow({ mode: "open" });
+    const style = document.createElement("style");
+    style.textContent = `
+      :host { display: contents; }
+
+      .container {
+        position: fixed;
+        left: 0;
+        top: 0;
+        margin: 0;
+        box-sizing: border-box;
+        flex-direction: column;
+        gap: 1px;
+        min-width: var(--menu-min-width, 88px);
+        max-width: calc(100vw - ${2 * MARGIN}px);
+        max-height: calc(100dvh - ${2 * MARGIN}px);
+        overflow-y: auto;
+        overscroll-behavior: contain;
+        scrollbar-width: thin;
+        padding: var(--menu-padding, 4px);
+        background: var(--menu-bg, Canvas);
+        color: var(--text-2, CanvasText);
+        border: var(--menu-border, 1px solid);
+        border-radius: var(--menu-radius, 8px);
+        box-shadow: var(--menu-shadow, 0 8px 24px rgba(0,0,0,0.2));
+        -webkit-backdrop-filter: var(--menu-backdrop-filter, blur(20px));
+        backdrop-filter: var(--menu-backdrop-filter, blur(20px));
+        outline: none;
+
+        /* Closed / exit state \u2014 fade + a tiny vertical settle (no horizontal
+           shift). This 140ms governs the EXIT (open \u2192 closed); the enter is a
+           touch quicker (see :popover-open below) so the menu feels snappy to
+           open but unhurried to dismiss. 'display' and 'overlay' transition with
+           'allow-discrete' so the menu stays in the top layer and visible while
+           it animates OUT, then hides. */
+        opacity: 0;
+        translate: 0 -4px;
+        transition:
+          opacity 140ms ease-out,
+          translate 140ms ease-out,
+          display 140ms allow-discrete,
+          overlay 140ms allow-discrete;
+      }
+      .container:popover-open {
+        display: flex;
+        opacity: 1;
+        translate: 0 0;
+        /* Enter (closed \u2192 open) \u2014 quicker than the exit above. */
+        transition:
+          opacity 100ms ease-out,
+          translate 100ms ease-out,
+          display 100ms allow-discrete,
+          overlay 100ms allow-discrete;
+      }
+      /* Enter: start from the closed state and transition in. */
+      @starting-style {
+        .container:popover-open { opacity: 0; translate: 0 -4px; }
+      }
+    `;
+    this.surface = document.createElement("div");
+    this.surface.className = "container";
+    this.surface.setAttribute("part", "menu");
+    this.surface.setAttribute("popover", "manual");
+    this.surface.append(document.createElement("slot"));
+    this.surface.addEventListener("pointerenter", (e) => {
+      if (e.pointerType !== "mouse") return;
+      if (this.isSubmenu) this.cancelCloseTimer();
+    });
+    this.surface.addEventListener("pointerleave", (e) => {
+      if (e.pointerType !== "mouse") return;
+      if (this.isSubmenu && this.isHover) this.scheduleClose();
+    });
+    this.surface.addEventListener("click", this.onSurfaceClick);
+    shadow.append(style, this.surface);
+  }
+  connectedCallback() {
+    const anchor = this.triggerAnchor;
+    if (anchor) {
+      anchorToMenu.set(anchor, this);
+      lazyObserver?.observe(anchor);
+    }
+    if (this.hasAttribute("state")) requestAnimationFrame(() => this.syncState());
+  }
+  disconnectedCallback() {
+    this.hide();
+    this.teardownListeners();
+    this.cancelOpenTimer();
+    this.cancelCloseTimer();
+    const anchor = this.triggerAnchor;
+    if (anchor && anchorToMenu.get(anchor) === this) {
+      anchorToMenu.delete(anchor);
+      lazyObserver?.unobserve(anchor);
+    }
+  }
+  attributeChangedCallback(name) {
+    if (name === "state") {
+      this.syncState();
+      return;
+    }
+    if (this.listening) {
+      this.teardownListeners();
+      this.setupListeners();
+    }
+  }
+  /** Apply the controlled `state` attribute to actual visibility, silently.
+   *  Absent → uncontrolled (no-op here; triggers manage it). */
+  syncState() {
+    if (!this.isConnected) return;
+    const v = this.getAttribute("state");
+    if (v === "open" && !this._shown) this.show();
+    else if (v === "closed" && this._shown) this.hide();
+  }
+  /** Controlled iff the consumer is managing the `state` attribute. */
+  get isControlled() {
+    return this.hasAttribute("state");
+  }
+  /* --- config getters --- */
+  /** A submenu is an `<a-menu>` nested inside an `<a-menu-item>` — derived from
+   *  structure, no `submenu` attribute needed (the parent item is the anchor). */
+  get isSubmenu() {
+    return !!this.closest("a-menu-item");
+  }
+  get isContext() {
+    return this.hasAttribute("context");
+  }
+  get isCoord() {
+    return this.hasAttribute("coord");
+  }
+  // Submenus open on hover by default; `nohover` opts out (click-only). Root
+  // menus never consult this — it's read only on the submenu paths.
+  get isHover() {
+    return !this.hasAttribute("nohover");
+  }
+  get offset() {
+    const n = parseInt(this.getAttribute("offset") ?? "", 10);
+    return Number.isFinite(n) ? n : MARGIN;
+  }
+  get placement() {
+    const p = this.getAttribute("placement");
+    if (p === "bottom-end" || p === "top-start" || p === "top-end" || p === "bottom" || p === "top")
+      return p;
+    return "bottom-start";
+  }
+  /** Root menu: the previous element sibling is the trigger. Submenu: the
+   *  enclosing menu item. One deterministic rule per case — no ambiguity. */
+  get triggerAnchor() {
+    return this.closest("a-menu-item") ?? this.previousElementSibling;
+  }
+  /** For a submenu: the menu that contains its anchor item. */
+  get ownerMenu() {
+    if (!this.isSubmenu) return null;
+    return this.triggerAnchor?.closest("a-menu") ?? null;
+  }
+  get isOpen() {
+    return this._shown;
+  }
+  /* --- focusable items belonging to THIS menu (not nested submenus) --- */
+  /** Skip elements that can't actually take focus — `display:none` (incl. a
+   *  closed submenu's contents), `visibility:hidden`, `content-visibility`
+   *  skipped — so navigation never lands on a hidden node (programmatic
+   *  `.focus()` on one silently fails). `getClientRects` is the fallback where
+   *  `checkVisibility` isn't available. */
+  isVisible(el) {
+    const check = el.checkVisibility;
+    if (typeof check === "function") {
+      return check.call(el, { visibilityProperty: true, contentVisibilityAuto: true });
+    }
+    return el.getClientRects().length > 0;
+  }
+  /** The subset of `focusables()` that are menu items (drives arrow / Home /
+   *  End / type-ahead navigation). Same visibility / disabled / ownership
+   *  filter — just narrowed to `a-menu-item`. */
+  focusableItems() {
+    return this.focusables().filter(
+      (el) => el instanceof AMenuItemElement
+    );
+  }
+  /** Every tabbable element belonging to THIS menu (items + nested controls
+   *  like inputs / sliders / buttons), in DOM order, visible and enabled —
+   *  used to trap Tab within the open menu. Submenu contents are excluded
+   *  (their nearest `a-menu` is the submenu). */
+  focusables() {
+    const sel = 'a-menu-item, a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+    return Array.from(this.querySelectorAll(sel)).filter(
+      (el) => el.closest("a-menu") === this && !el.hasAttribute("disabled") && this.isVisible(el)
+    );
+  }
+  focusFirstItem() {
+    this.focusableItems()[0]?.focus({ preventScroll: true });
+  }
+  /* ============================ open / close ============================ */
+  /** Public imperative API. Routes through the same intent path as the
+   *  triggers, so it emits `statechange` and respects controlled mode. */
+  open(opts) {
+    this.requestOpen(opts);
+  }
+  close(originEvent) {
+    this.requestClose(originEvent);
+  }
+  toggle(opts) {
+    if (this._shown) this.requestClose(opts?.originEvent);
+    else this.requestOpen(opts);
+  }
+  /** Dispatch the single `statechange` event (requested + previous state),
+   *  `cancelable` and *before* applying. Returns `false` if a handler vetoed it
+   *  via `preventDefault()` — the uncontrolled veto (see requestOpen/Close). */
+  emitChange(next, opts) {
+    return this.dispatchEvent(
+      new CustomEvent("statechange", {
+        cancelable: true,
+        detail: {
+          next,
+          prev: this._shown ? "open" : "closed",
+          coord: opts?.coord,
+          originEvent: opts?.originEvent
+        }
+      })
+    );
+  }
+  /** Intent to open (trigger / method / keyboard). Emits the cancelable
+   *  `statechange`; applies the visibility itself ONLY when uncontrolled and
+   *  not vetoed — a controlled menu waits for the consumer to flip `state`. */
+  requestOpen(opts) {
+    if (this._shown) {
+      this.show(opts?.coord, opts?.viaKeyboard, opts?.originEvent);
+      return;
+    }
+    const ok = this.emitChange("open", opts);
+    if (this.isControlled) return;
+    if (ok) this.show(opts?.coord, opts?.viaKeyboard, opts?.originEvent);
+  }
+  /** Intent to close. Emits the cancelable `statechange`; hides itself only when
+   *  uncontrolled and not vetoed. */
+  requestClose(originEvent) {
+    if (!this._shown) return;
+    const ok = this.emitChange("closed", { originEvent });
+    if (this.isControlled) {
+      this._dismissNotified = true;
+      return;
+    }
+    if (ok) this.hide();
+  }
+  /** Apply OPEN to the DOM (no event) — used by uncontrolled intent and by the
+   *  controlled `state` sync. */
+  show(coord, viaKeyboard = false, _originEvent) {
+    if (this.isSubmenu) {
+      const parent = this.ownerMenu;
+      if (parent) {
+        const pidx = openStack.indexOf(parent);
+        if (pidx !== -1) {
+          for (let i = openStack.length - 1; i > pidx; i--) openStack[i]._doHide();
+          openStack.length = pidx + 1;
+        }
+      }
+    } else if (!openStack.includes(this)) {
+      closeAll();
+    }
+    if (openStack.includes(this)) {
+      this.position(coord);
+      return;
+    }
+    const wasEmpty = openStack.length === 0;
+    this._doShow(coord, !wasEmpty);
+    openStack.push(this);
+    if (wasEmpty) {
+      bindDocListeners(this.doc, this.view);
+      this.armPositionTracker();
+    }
+    if (viaKeyboard) this.focusFirstItem();
+  }
+  /** Watch the root trigger and dismiss the system once it scrolls out of the
+   *  spot it held at open (see trackPosition). Deferred a frame so the trigger's
+   *  post-open layout has settled before the rect is snapshotted; guarded in case
+   *  the menu closed in between. Tracks the root anchor only — submenus ride
+   *  inside it, so if the root anchor goes, the whole system should go. */
+  armPositionTracker() {
+    const anchor = this.triggerAnchor;
+    if (!anchor) return;
+    this.view.requestAnimationFrame(() => {
+      if (!this._shown || openStack[0] !== this) return;
+      removePosTracker?.();
+      removePosTracker = trackPosition(anchor, () => dismiss());
+    });
+  }
+  /** Apply CLOSE to the DOM (no event). Closes this menu and everything stacked
+   *  above it (its submenus). */
+  hide() {
+    const idx = openStack.indexOf(this);
+    if (idx === -1) {
+      if (this._shown) this._doHide();
+      return;
+    }
+    for (let i = openStack.length - 1; i >= idx; i--) openStack[i]._doHide();
+    openStack.length = idx;
+    if (openStack.length === 0) unbindDocListeners();
+  }
+  /** Shadow-only show: open the popover and position it. `instant` positions
+   *  synchronously (no rAF), so a menu opening over an already-visible one is
+   *  placed before its first paint — it still fades in via the CSS transition.
+   *  Relies on the Popover API without feature detection — see "Browser
+   *  support" in README.md. */
+  _doShow(coord, instant = false) {
+    if (this.surface.isConnected && !this._shown) this.surface.showPopover();
+    this._shown = true;
+    this._dismissNotified = false;
+    this.reflectExpanded(true);
+    this.hideAnchorTooltip();
+    this.position(coord, instant);
+  }
+  /** Dismiss any tooltip on the trigger as the menu opens, so the trigger's
+   *  hover tooltip doesn't linger over the just-opened menu. `a-tooltip.hide()`
+   *  mutates only its own shadow internals (like `el.focus()`), so this is
+   *  allowed under the no-light-DOM-mutation rule. No-op when the trigger has no
+   *  tooltip (or it hasn't upgraded). */
+  hideAnchorTooltip() {
+    this.triggerAnchor?.querySelectorAll("a-tooltip").forEach((t) => t.hide?.());
+  }
+  /** Shadow-only hide. */
+  _doHide() {
+    if (this.surface.isConnected && this._shown) this.surface.hidePopover();
+    this._shown = false;
+    this.reflectExpanded(false);
+    this.cancelOpenTimer();
+    this.cancelCloseTimer();
+  }
+  /** Mirror the open state onto a SUBMENU parent's `aria-expanded`. This is the
+   *  one sanctioned light-DOM ARIA mutation (like `el.focus()`): the anchor is
+   *  an `<a-menu-item>` the `MenuItem` wrapper renders WITH a resting
+   *  `aria-expanded="false"` baseline, so a reactive re-render resets it to a
+   *  valid value and the next open/close re-syncs.
+   *
+   *  A ROOT menu's trigger is a consumer-owned sibling we don't render and have
+   *  no baseline for — writing to it would mutate foreign DOM (and couldn't
+   *  self-heal), so we leave its `aria-expanded` to the consumer. The menu is
+   *  still announced and Esc-dismissable; consumers add `aria-haspopup="menu"`
+   *  to their trigger themselves. (`context` menus aren't triggers either.) */
+  reflectExpanded(open) {
+    if (!this.isSubmenu) return;
+    this.triggerAnchor?.setAttribute("aria-expanded", open ? "true" : "false");
+  }
+  /* ============================ positioning ============================ */
+  position(coord, sync = false) {
+    const run = () => {
+      if (!this._shown) return;
+      const view = this.view;
+      const vw = view.innerWidth;
+      const vh = view.innerHeight;
+      const surface = this.surface;
+      let left = MARGIN;
+      let top = MARGIN;
+      if (coord) {
+        surface.style.maxHeight = `${Math.max(MIN_HEIGHT, vh - 2 * MARGIN)}px`;
+        const box = surface.getBoundingClientRect();
+        left = coord[0];
+        if (left + box.width > vw - MARGIN) left = vw - box.width - MARGIN;
+        left = Math.max(MARGIN, left);
+        top = coord[1];
+        if (top + box.height > vh - MARGIN) top = top - box.height;
+        top = Math.max(MARGIN, top);
+      } else if (this.isSubmenu) {
+        const it = this.triggerAnchor?.getBoundingClientRect();
+        if (!it) return;
+        surface.style.maxHeight = `${Math.max(MIN_HEIGHT, vh - 2 * MARGIN)}px`;
+        const box = surface.getBoundingClientRect();
+        left = it.right + this.offset;
+        if (left + box.width > vw - MARGIN) {
+          left = it.left - box.width - this.offset;
+        }
+        left = Math.max(MARGIN, left);
+        const cs = view.getComputedStyle(surface);
+        const insetTop = parseFloat(cs.borderTopWidth) + parseFloat(cs.paddingTop);
+        top = it.top - insetTop;
+        if (top + box.height > vh - MARGIN) top = vh - box.height - MARGIN;
+        top = Math.max(MARGIN, top);
+      } else {
+        const a = this.triggerAnchor?.getBoundingClientRect();
+        if (!a) return;
+        const p = this.placement;
+        const spaceBelow = vh - a.bottom - 2 * MARGIN;
+        const spaceAbove = a.top - 2 * MARGIN;
+        let onTop = p.startsWith("top");
+        const natural = surface.scrollHeight;
+        if (onTop && spaceAbove < natural && spaceBelow > spaceAbove) onTop = false;
+        else if (!onTop && spaceBelow < natural && spaceAbove > spaceBelow) onTop = true;
+        const space = onTop ? spaceAbove : spaceBelow;
+        surface.style.maxHeight = `${Math.max(MIN_HEIGHT, Math.floor(space))}px`;
+        const box = surface.getBoundingClientRect();
+        const align = p.endsWith("end") ? "end" : p.endsWith("start") ? "start" : "center";
+        left = align === "center" ? a.left + a.width / 2 - box.width / 2 : align === "end" ? a.right - box.width : a.left;
+        if (left + box.width > vw - MARGIN) left = vw - box.width - MARGIN;
+        left = Math.max(MARGIN, left);
+        top = onTop ? a.top - box.height - this.offset : a.bottom + this.offset;
+        top = Math.max(MARGIN, top);
+      }
+      surface.style.transform = `translate(${Math.round(left)}px, ${Math.round(top)}px)`;
+    };
+    if (sync) run();
+    else requestAnimationFrame(run);
+  }
+  /* ====================== click / close contract ====================== */
+  /**
+   * Fully declarative close contract — decided synchronously from the DOM, so
+   * it never depends on the consumer's click handler (which in a worker-thread
+   * runtime can't `preventDefault` on the UI thread). The menu never
+   * stops/prevents the click, so the consumer's selection handler always runs.
+   *
+   * Walk the click's composedPath outward to the surface; the NEAREST marker
+   * wins:
+   *   - `data-menu-open`  → keep the menu open (a Done button can still close
+   *                          from inside such a region — it's hit first).
+   *   - `a-menu-item` (a choice) or `data-menu-close` → close the menu.
+   *   - nothing → keep open (plain custom content doesn't dismiss).
+   */
+  onSurfaceClick = (e) => {
+    for (const node of e.composedPath()) {
+      if (node === this.surface) break;
+      if (!(node instanceof Element)) continue;
+      if (node.hasAttribute("data-menu-open")) return;
+      if (node instanceof AMenuItemElement) {
+        if (node.hasAttribute("disabled")) {
+          e.preventDefault();
+          return;
+        }
+        if (node.querySelector("a-menu")) return;
+        return this.closeSystem(e);
+      }
+      if (node.hasAttribute("data-menu-close")) return this.closeSystem(e);
+    }
+  };
+  /** Close the whole open menu system from the root down. */
+  closeSystem(e) {
+    const root = openStack[0] ?? this;
+    root.requestClose(e);
+  }
+  /* ============================ keyboard ============================ */
+  /** Called by the coordinator on the topmost open menu. Handles navigation;
+   *  Enter / Space activation is handled by a-menu-item's own global keydown
+   *  (which synthesizes a click → routed through onSurfaceClick). */
+  handleKey(e) {
+    const active = this.doc.activeElement;
+    if (e.key === "Escape") {
+      e.preventDefault();
+      e.stopPropagation();
+      const anchor = this.triggerAnchor;
+      this.requestClose(e);
+      anchor?.focus();
+      return;
+    }
+    if (e.key === "Tab") {
+      const f = this.focusables();
+      if (!f.length) return;
+      e.preventDefault();
+      const i = active ? f.indexOf(active) : -1;
+      if (i === -1) {
+        f[0]?.focus();
+        return;
+      }
+      const next = e.shiftKey ? i === 0 ? f.length - 1 : i - 1 : i === f.length - 1 ? 0 : i + 1;
+      f[next]?.focus();
+      return;
+    }
+    const within = active?.closest("a-menu") === this;
+    if (within && !(active instanceof AMenuItemElement)) return;
+    const items = this.focusableItems();
+    const idx = active ? items.indexOf(active) : -1;
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        items[idx < 0 ? 0 : (idx + 1) % items.length]?.focus();
+        break;
+      case "ArrowUp":
+        e.preventDefault();
+        items[idx <= 0 ? items.length - 1 : idx - 1]?.focus();
+        break;
+      case "Home":
+        e.preventDefault();
+        items[0]?.focus();
+        break;
+      case "End":
+        e.preventDefault();
+        items[items.length - 1]?.focus();
+        break;
+      case "ArrowRight": {
+        const sub = this.submenuOf(active);
+        if (sub) {
+          e.preventDefault();
+          sub.requestOpen({ viaKeyboard: true });
+        }
+        break;
+      }
+      case "ArrowLeft":
+        if (this.isSubmenu) {
+          e.preventDefault();
+          const anchorItem = this.triggerAnchor;
+          this.requestClose(e);
+          anchorItem?.focus();
+        }
+        break;
+      default:
+        if (e.key.length === 1 && !e.metaKey && !e.ctrlKey && !e.altKey) {
+          this.typeahead(e.key, items);
+        }
+    }
+  }
+  submenuOf(item) {
+    if (!item || !(item instanceof AMenuItemElement)) return null;
+    return item.querySelector("a-menu");
+  }
+  typeahead(ch, items) {
+    this.typeBuffer += ch.toLowerCase();
+    clearTimeout(this.typeTimer);
+    this.typeTimer = setTimeout(() => this.typeBuffer = "", TYPEAHEAD_RESET);
+    const match = items.find((it) => this.itemLabel(it).startsWith(this.typeBuffer));
+    match?.focus();
+  }
+  /** The item's own visible label for type-ahead. Prefers the
+   *  `<a-menu-item-label>` text so it excludes a trailing `kbd` hint AND — for
+   *  a submenu parent — the entire nested `<a-menu>` flyout's text (which is a
+   *  light-DOM descendant, so it'd otherwise be folded into `textContent`). */
+  itemLabel(it) {
+    const label = it.querySelector("a-menu-item-label");
+    return ((label ?? it).textContent ?? "").trim().toLowerCase();
+  }
+  /* ====================== trigger listener wiring ====================== */
+  setupListeners() {
+    if (this.listening) return;
+    const anchor = this.triggerAnchor;
+    if (!anchor) {
+      this.listening = true;
+      return;
+    }
+    if (this.isSubmenu) {
+      const onClick = (e) => {
+        if (e.composedPath().includes(this.surface)) return;
+        this.requestOpen({ originEvent: e });
+      };
+      anchor.addEventListener("click", onClick);
+      let onEnter;
+      let onLeave;
+      if (this.isHover) {
+        onEnter = (e) => {
+          if (e.pointerType === "mouse") this.scheduleOpen();
+        };
+        onLeave = (e) => {
+          if (e.pointerType === "mouse") this.scheduleClose();
+        };
+        anchor.addEventListener("pointerenter", onEnter);
+        anchor.addEventListener("pointerleave", onLeave);
+      }
+      this.teardown = () => {
+        anchor.removeEventListener("click", onClick);
+        if (onEnter) anchor.removeEventListener("pointerenter", onEnter);
+        if (onLeave) anchor.removeEventListener("pointerleave", onLeave);
+        this.listening = false;
+      };
+    } else if (this.isContext) {
+      const onContext = (e) => {
+        e.preventDefault();
+        this.requestOpen({ coord: [e.clientX, e.clientY], originEvent: e });
+      };
+      anchor.addEventListener("contextmenu", onContext);
+      this.teardown = () => {
+        anchor.removeEventListener("contextmenu", onContext);
+        this.listening = false;
+      };
+    } else {
+      const onClick = (e) => {
+        const viaKeyboard = e.detail === 0;
+        let coord;
+        if (this.isCoord) {
+          if (viaKeyboard) {
+            const r = anchor.getBoundingClientRect();
+            coord = [r.left, r.bottom];
+          } else {
+            coord = [e.clientX, e.clientY];
+          }
+        }
+        if (this._shown) this.requestClose(e);
+        else this.requestOpen({ coord, viaKeyboard, originEvent: e });
+      };
+      anchor.addEventListener("click", onClick);
+      this.teardown = () => {
+        anchor.removeEventListener("click", onClick);
+        this.listening = false;
+      };
+    }
+    this.listening = true;
+  }
+  teardownListeners() {
+    this.teardown?.();
+    this.teardown = void 0;
+  }
+  /* --- submenu hover-intent timers --- */
+  scheduleOpen() {
+    this.cancelCloseTimer();
+    if (this._shown) return;
+    this.cancelOpenTimer();
+    this.openTimer = setTimeout(() => {
+      this.openTimer = void 0;
+      this.requestOpen();
+    }, SUBMENU_OPEN_DELAY);
+  }
+  scheduleClose() {
+    this.cancelOpenTimer();
+    if (!this._shown) return;
+    this.cancelCloseTimer();
+    this.closeTimer = setTimeout(() => {
+      this.closeTimer = void 0;
+      this.requestClose();
+    }, SUBMENU_CLOSE_DELAY);
+  }
+  cancelOpenTimer() {
+    if (this.openTimer !== void 0) {
+      clearTimeout(this.openTimer);
+      this.openTimer = void 0;
+    }
+  }
+  cancelCloseTimer() {
+    if (this.closeTimer !== void 0) {
+      clearTimeout(this.closeTimer);
+      this.closeTimer = void 0;
+    }
+  }
+}
+function register_a_menu() {
+  if (typeof customElements === "undefined") return;
+  if (!customElements.get("a-menu")) {
+    customElements.define("a-menu", AMenuElement);
+  }
+}
+register_a_menu();
+export {
+  AMenuElement,
+  register_a_menu
+};