@antadesign/anta 0.3.2 → 0.3.4

package/dist/elements/a-menu.js

@@ -1,4 +1,4 @@
-import { HTMLElementBase } from "../anta_helpers";
+import { HTMLElementBase, anchorRect, setMenuPresence } from "../anta_helpers";
 import { AMenuItemElement } from "./a-menu-item";
 import "./a-menu.css";
 const MARGIN = 4;
@@ -42,11 +42,13 @@ function trackPosition(el, onEscape) {
   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 win = doc.defaultView;
+  const root = win && win !== win.top ? doc.documentElement : null;
   const io = new IntersectionObserver(
     ([entry]) => {
       if (!entry.isIntersecting) onEscape();
     },
-    { root: null, rootMargin, threshold: ANCHOR_VISIBLE_RATIO }
+    { root, rootMargin, threshold: ANCHOR_VISIBLE_RATIO }
   );
   io.observe(el);
   return () => io.disconnect();
@@ -62,6 +64,18 @@ function pathHitsMenus(e, primaryClick = false) {
   }
   return false;
 }
+function nodeHitsMenus(node) {
+  for (const m of openStack) {
+    if (m.contains(node) || m.surface.contains(node)) return true;
+    const anchor = m.triggerAnchor;
+    if (anchor && anchor.contains(node)) return true;
+  }
+  return false;
+}
+setMenuPresence({
+  isOpen: () => openStack.length > 0,
+  contains: nodeHitsMenus
+});
 function onDocPointerDown(e) {
   if (!openStack.length) return;
   if (!pathHitsMenus(e, e.button === 0)) dismiss(e);
@@ -111,6 +125,8 @@ class AMenuElement extends HTMLElementBase {
   static observedAttributes = ["placement", "context", "coord", "offset", "nohover", "state"];
   /** Shadow-internal popover surface — the only thing we ever mutate. */
   surface;
+  /** The scrolling body inside the surface (holds the items). */
+  scrollEl;
   listening = false;
   _shown = false;
   teardown;
@@ -118,14 +134,32 @@ class AMenuElement extends HTMLElementBase {
    *  but stays visible until the consumer flips `state`. The flag lets the
    *  `closeAll` backstop skip a duplicate emit. Cleared on every show. */
   _dismissNotified = false;
+  // Custom-state carrier — exposes the menu's own open state as `:state(open)`
+  // (off-DOM, like `a-menu-item`'s `:state(active)`). Never used to mutate light
+  // DOM; see `reflectOpen`.
+  internals;
   // Submenu hover-intent timers.
   openTimer;
   closeTimer;
   // Typeahead state (root navigation).
   typeBuffer = "";
   typeTimer;
+  // Combobox (filter) state — engaged when a `[data-menu-search]` field is slotted
+  // in (e.g. `Select` with `filter`). Focus stays in that field; ArrowUp/Down move
+  // `activeItem` (a cursor, not DOM focus) and REPORT it via the `activedescendant`
+  // event, which the reactive layer reflects onto the field's `aria-activedescendant`.
+  activeItem = null;
+  comboObserver;
+  // The vertical side chosen at open (true = flipped above the anchor). A re-anchor
+  // (filtering changes height) keeps this side rather than re-deciding — a shrunk
+  // menu shouldn't hop back under the trigger.
+  _flippedTop = null;
   constructor() {
     super();
+    try {
+      this.internals = this.attachInternals?.();
+    } catch {
+    }
     const shadow = this.attachShadow({ mode: "open" });
     const style = document.createElement("style");
     style.textContent = `
@@ -136,16 +170,13 @@ class AMenuElement extends HTMLElementBase {
         left: 0;
         top: 0;
         margin: 0;
+        padding: 0;
         box-sizing: border-box;
         flex-direction: column;
-        gap: 1px;
-        min-width: var(--menu-min-width, 88px);
+        min-width: max(var(--menu-min-width, 88px), var(--_anchor-width, 0px));
         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);
+        overflow: hidden;
         background: var(--menu-bg, Canvas);
         color: var(--text-2, CanvasText);
         border: var(--menu-border, 1px solid);
@@ -184,19 +215,58 @@ class AMenuElement extends HTMLElementBase {
       @starting-style {
         .container:popover-open { opacity: 0; translate: 0 -4px; }
       }
+      /* The scrolling body \u2014 only the items scroll; the header / footer slots stay
+         fixed above and below it. min-height:0 lets it shrink so its own scrollbar
+         engages instead of the flex item overflowing. The 1px inter-item gap that
+         used to live on the container lives here now. */
+      .scroll {
+        flex: 1 1 auto;
+        min-height: 0;
+        display: flex;
+        flex-direction: column;
+        gap: 1px;
+        overflow-y: auto;
+        overscroll-behavior: contain;
+        scrollbar-width: thin;
+        /* The menu's padding lives here (not on the clipping container) so an item's
+           focus outline has room inside the scroll box instead of being clipped at
+           the edge; scroll-padding keeps a focused row off the edge when scrolled. */
+        padding: var(--menu-padding, 4px);
+        scroll-padding-block: var(--menu-padding, 4px);
+        /* Soft scroll edges: fade the content into the top / bottom only on the side
+           with more to scroll (the --fade-* vars, set from JS, are 0 otherwise). The
+           top also clears a hard --gap-top band (fully transparent, ahead of the ramp)
+           so a row scrolling up disappears cleanly under a pinned header / filter field
+           before the fade begins, instead of bleeding right against it. */
+        --fade-top: 0px;
+        --fade-bottom: 0px;
+        --gap-top: 0px;
+        -webkit-mask-image: linear-gradient(to bottom, transparent 0, transparent var(--gap-top), #000 var(--fade-top), #000 calc(100% - var(--fade-bottom)), transparent 100%);
+        mask-image: linear-gradient(to bottom, transparent 0, transparent var(--gap-top), #000 var(--fade-top), #000 calc(100% - var(--fade-bottom)), transparent 100%);
+      }
     `;
     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"));
+    const header = document.createElement("slot");
+    header.setAttribute("name", "header");
+    const scroll = document.createElement("div");
+    scroll.className = "scroll";
+    scroll.setAttribute("part", "scroll");
+    scroll.append(document.createElement("slot"));
+    scroll.addEventListener("scroll", () => this.updateScrollFade(), { passive: true });
+    this.scrollEl = scroll;
+    const footer = document.createElement("slot");
+    footer.setAttribute("name", "footer");
+    this.surface.append(header, scroll, footer);
     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();
+      if (this.isSubmenu && this.#isHover) this.scheduleClose();
     });
     this.surface.addEventListener("click", this.onSurfaceClick);
     shadow.append(style, this.surface);
@@ -248,22 +318,22 @@ class AMenuElement extends HTMLElementBase {
   get isSubmenu() {
     return !!this.closest("a-menu-item");
   }
-  get isContext() {
+  get #isContext() {
     return this.hasAttribute("context");
   }
-  get isCoord() {
+  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() {
+  get #isHover() {
     return !this.hasAttribute("nohover");
   }
-  get offset() {
+  get #offset() {
     const n = parseInt(this.getAttribute("offset") ?? "", 10);
     return Number.isFinite(n) ? n : MARGIN;
   }
-  get placement() {
+  get #placement() {
     const p = this.getAttribute("placement");
     if (p === "bottom-end" || p === "top-start" || p === "top-end" || p === "bottom" || p === "top")
       return p;
@@ -274,8 +344,32 @@ class AMenuElement extends HTMLElementBase {
   get triggerAnchor() {
     return this.closest("a-menu-item") ?? this.previousElementSibling;
   }
+  /** The focusable element to hand focus back to — the anchor itself if it's
+   *  focusable, else the first focusable within it. Positioning still uses the
+   *  anchor's box; this only picks the focus target. A custom `renderTrigger`
+   *  that returns a single focusable element (the documented contract) resolves
+   *  to that element; if it wrongly returns a non-focusable node with none
+   *  inside, this is null and `focusTrigger` warns. */
+  get #triggerFocusable() {
+    const a = this.triggerAnchor;
+    if (!a) return null;
+    const sel = 'a-input, a-button, button, [href], input:not([type="hidden"]), select, textarea, [tabindex]:not([tabindex="-1"])';
+    return a.matches(sel) ? a : a.querySelector(sel);
+  }
+  /** Return focus to the trigger. Focuses the first focusable in the anchor; if
+   *  there is none (a mis-authored trigger — e.g. `renderTrigger` returning a
+   *  fragment or a non-focusable node), warns instead of silently focusing air. */
+  focusTrigger() {
+    const f = this.#triggerFocusable;
+    if (f) f.focus();
+    else if (this.triggerAnchor) {
+      console.warn(
+        "[a-menu] trigger has no focusable element \u2014 a menu trigger (or `Select` renderTrigger) must be a single focusable element."
+      );
+    }
+  }
   /** For a submenu: the menu that contains its anchor item. */
-  get ownerMenu() {
+  get #ownerMenu() {
     if (!this.isSubmenu) return null;
     return this.triggerAnchor?.closest("a-menu") ?? null;
   }
@@ -308,13 +402,119 @@ class AMenuElement extends HTMLElementBase {
    *  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"])';
+    const sel = 'a-menu-item, a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), a-input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"]), [data-menu-search]';
     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 });
+  /** On open, seat initial focus like a native `<select>` / macOS menu: a menu
+   *  carrying a current value opens *at* that value, not at the top. Brings the
+   *  first selected row into view and, when opened via keyboard, focuses it;
+   *  with no selected row it focuses the first item (keyboard) and does nothing
+   *  otherwise. "Selected" = a `selected` row (tint) or `aria-checked` /
+   *  `aria-selected="true"` (checkable rows) — the first such visible item of
+   *  THIS menu, so a leaf buried in a closed submenu (not visible) is skipped and
+   *  a multi-select lands on its topmost checked row. */
+  seatInitialFocus(viaKeyboard) {
+    const items = this.focusableItems();
+    const selected = items.find(
+      (el) => el.hasAttribute("selected") || el.getAttribute("aria-checked") === "true" || el.getAttribute("aria-selected") === "true"
+    );
+    if (selected) this.scrollItemIntoView(selected);
+    if (viaKeyboard) (selected ?? items[0])?.focus({ preventScroll: true });
+  }
+  /** Scroll THIS menu's body so `item` sits inside the visible scroll viewport,
+   *  touching only the internal `.scroll` container — never the document, whose
+   *  scroll would trip the anchor-scrolled-out dismiss. No-op for a menu short
+   *  enough not to scroll. */
+  scrollItemIntoView(item) {
+    const c = this.scrollEl;
+    if (!c) return;
+    const pad = 4;
+    const cr = c.getBoundingClientRect();
+    const ir = item.getBoundingClientRect();
+    if (ir.top < cr.top + pad) c.scrollTop -= cr.top + pad - ir.top;
+    else if (ir.bottom > cr.bottom - pad) c.scrollTop += ir.bottom - cr.bottom + pad;
+  }
+  /** Fade the scrolling body's content into the top / bottom edges — but only on the
+   *  side that actually has more to scroll, so a short (non-scrolling) menu and the
+   *  true top / bottom stay crisp. Drives the `--fade-*` / `--gap-top` vars the
+   *  `.scroll` mask reads; runs on scroll and after every (re)position.
+   *  Shadow-internal only. */
+  updateScrollFade() {
+    const el = this.scrollEl;
+    if (!el) return;
+    const top = el.scrollTop > 1;
+    const bottom = el.scrollTop + el.clientHeight < el.scrollHeight - 1;
+    el.style.setProperty("--fade-top", top ? "16px" : "0px");
+    el.style.setProperty("--gap-top", top ? "3px" : "0px");
+    el.style.setProperty("--fade-bottom", bottom ? "14px" : "0px");
+  }
+  /* ------------------------------ combobox mode ------------------------------ */
+  /** The filter field slotted into THIS menu (never a submenu's), or null. Its
+   *  presence switches the menu to the combobox keyboard. */
+  get #searchField() {
+    const el = this.querySelector("[data-menu-search]");
+    return el && el.closest("a-menu") === this ? el : null;
+  }
+  /** Move the combobox cursor. Sets the item's `active` **property** (off-DOM
+   *  `:state(active)`, no attribute churn) for the highlight, and REPORTS the
+   *  active id via the `activedescendant` event so the reactive layer can set
+   *  `aria-activedescendant` on the light-DOM field. `null` clears the cursor. */
+  setActive(item) {
+    if (this.activeItem && this.activeItem !== item) this.activeItem.active = false;
+    this.activeItem = item;
+    if (item) {
+      item.active = true;
+      item.scrollIntoView?.({ block: "nearest" });
+    }
+    this.dispatchEvent(
+      new CustomEvent("activedescendant", { detail: { id: item?.id ?? null } })
+    );
+  }
+  /** Re-seat the cursor on the first option — but only once the filter has input.
+   *  An empty filter (e.g. right after opening) shows NO active row, so the first
+   *  ArrowDown is what steps onto the list; typing then keeps the top match active.
+   *  Rows marked `data-menu-skip-active` (e.g. a Select-all action) are skipped as
+   *  the seat target — the cursor lands on the first real option — but they stay
+   *  arrow-reachable. */
+  resetActive() {
+    const q = this.#searchField?.value;
+    if (!q || !q.trim()) return this.setActive(null);
+    const items = this.focusableItems();
+    this.setActive(items.find((it) => !it.hasAttribute("data-menu-skip-active")) ?? items[0] ?? null);
+  }
+  /** Combobox arrow / Home / End / Enter handling; returns true if it consumed the
+   *  key (so `handleKey` stops). Any other key falls through to the input (typing). */
+  handleComboKey(e) {
+    const items = this.focusableItems();
+    const idx = this.activeItem ? items.indexOf(this.activeItem) : -1;
+    switch (e.key) {
+      case "ArrowDown":
+        e.preventDefault();
+        this.setActive(items[idx < 0 ? 0 : (idx + 1) % items.length] ?? null);
+        return true;
+      case "ArrowUp":
+        e.preventDefault();
+        this.setActive(items[idx <= 0 ? items.length - 1 : idx - 1] ?? null);
+        return true;
+      case "Home":
+        e.preventDefault();
+        this.setActive(items[0] ?? null);
+        return true;
+      case "End":
+        e.preventDefault();
+        this.setActive(items[items.length - 1] ?? null);
+        return true;
+      case "Enter":
+        if (this.activeItem) {
+          e.preventDefault();
+          this.activeItem.click();
+        }
+        return true;
+      default:
+        return false;
+    }
   }
   /* ============================ open / close ============================ */
   /** Public imperative API. Routes through the same intent path as the
@@ -372,7 +572,7 @@ class AMenuElement extends HTMLElementBase {
    *  controlled `state` sync. */
   show(coord, viaKeyboard = false, _originEvent) {
     if (this.isSubmenu) {
-      const parent = this.ownerMenu;
+      const parent = this.#ownerMenu;
       if (parent) {
         const pidx = openStack.indexOf(parent);
         if (pidx !== -1) {
@@ -381,7 +581,19 @@ class AMenuElement extends HTMLElementBase {
         }
       }
     } else if (!openStack.includes(this)) {
-      closeAll();
+      const anchor = this.triggerAnchor;
+      const container = anchor ? openStack.find((m) => m !== this && m.contains(anchor)) : void 0;
+      if (container) {
+        const idx = openStack.indexOf(container);
+        for (let i = openStack.length - 1; i > idx; i--) {
+          const m = openStack[i];
+          if (m.isOpen && !m._dismissNotified) m.emitChange("closed");
+          m._doHide();
+        }
+        openStack.length = idx + 1;
+      } else {
+        closeAll();
+      }
     }
     if (openStack.includes(this)) {
       this.position(coord);
@@ -394,7 +606,29 @@ class AMenuElement extends HTMLElementBase {
       bindDocListeners(this.doc, this.view);
       this.armPositionTracker();
     }
-    if (viaKeyboard) this.focusFirstItem();
+    const search = this.#searchField;
+    if (search) {
+      ;
+      search.focus({ preventScroll: true });
+      this.resetActive();
+      this.startComboObserver();
+    } else {
+      this.seatInitialFocus(viaKeyboard);
+    }
+  }
+  /** While a filter field is open, the visible option list changes as the user
+   *  types (the consumer re-renders the matches); re-seat the cursor on the first
+   *  match. `childList` only — an item toggling its own `selected` (multi-select)
+   *  mutates deep in its subtree, not this menu's direct children, so it won't
+   *  spuriously reset the cursor. */
+  startComboObserver() {
+    this.comboObserver?.disconnect();
+    this.comboObserver = new this.view.MutationObserver(() => {
+      if (!this._shown || !this.#searchField) return;
+      this.resetActive();
+      this.position(void 0, false, true);
+    });
+    this.comboObserver.observe(this, { childList: true });
   }
   /** 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
@@ -413,6 +647,10 @@ class AMenuElement extends HTMLElementBase {
   /** Apply CLOSE to the DOM (no event). Closes this menu and everything stacked
    *  above it (its submenus). */
   hide() {
+    this.comboObserver?.disconnect();
+    this.comboObserver = void 0;
+    this.setActive(null);
+    this._flippedTop = null;
     const idx = openStack.indexOf(this);
     if (idx === -1) {
       if (this._shown) this._doHide();
@@ -431,7 +669,7 @@ class AMenuElement extends HTMLElementBase {
     if (this.surface.isConnected && !this._shown) this.surface.showPopover();
     this._shown = true;
     this._dismissNotified = false;
-    this.reflectExpanded(true);
+    this.reflectOpen(true);
     this.hideAnchorTooltip();
     this.position(coord, instant);
   }
@@ -447,27 +685,27 @@ class AMenuElement extends HTMLElementBase {
   _doHide() {
     if (this.surface.isConnected && this._shown) this.surface.hidePopover();
     this._shown = false;
-    this.reflectExpanded(false);
+    this.reflectOpen(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");
+  /** Expose the menu's OWN open state as an off-DOM custom state (`:state(open)`),
+   *  never a light-DOM attribute. A web component must not mutate light DOM — it
+   *  desyncs the worker-thread reactive model, which owns the light tree. A
+   *  submenu parent lights its open branch purely in CSS via
+   *  `a-menu-item:has(> a-menu:state(open))`; the state is element-owned (like
+   *  `a-menu-item`'s `:state(active)`) and, being off-DOM, survives a reactive
+   *  re-render without the element ever writing an attribute. Set on every menu
+   *  (harmless on roots — no `a-menu-item` parent matches the selector). */
+  reflectOpen(open) {
+    try {
+      if (open) this.internals?.states.add("open");
+      else this.internals?.states.delete("open");
+    } catch {
+    }
   }
   /* ============================ positioning ============================ */
-  position(coord, sync = false) {
+  position(coord, sync = false, reanchor = false) {
     const run = () => {
       if (!this._shown) return;
       const view = this.view;
@@ -486,30 +724,38 @@ class AMenuElement extends HTMLElementBase {
         if (top + box.height > vh - MARGIN) top = top - box.height;
         top = Math.max(MARGIN, top);
       } else if (this.isSubmenu) {
-        const it = this.triggerAnchor?.getBoundingClientRect();
+        const it = this.triggerAnchor ? anchorRect(this.triggerAnchor) : null;
         if (!it) return;
         surface.style.maxHeight = `${Math.max(MIN_HEIGHT, vh - 2 * MARGIN)}px`;
         const box = surface.getBoundingClientRect();
-        left = it.right + this.offset;
+        left = it.right + this.#offset;
         if (left + box.width > vw - MARGIN) {
-          left = it.left - box.width - this.offset;
+          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);
+        const scs = view.getComputedStyle(this.scrollEl);
+        const insetTop = parseFloat(cs.borderTopWidth) + parseFloat(cs.paddingTop) + parseFloat(scs.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();
+        const a = this.triggerAnchor ? anchorRect(this.triggerAnchor) : null;
         if (!a) return;
-        const p = this.placement;
+        surface.style.setProperty("--_anchor-width", `${Math.ceil(a.width)}px`);
+        const p = this.#placement;
         const spaceBelow = vh - a.bottom - 2 * MARGIN;
         const spaceAbove = a.top - 2 * MARGIN;
         let onTop = p.startsWith("top");
+        surface.style.maxHeight = "";
         const natural = surface.scrollHeight;
-        if (onTop && spaceAbove < natural && spaceBelow > spaceAbove) onTop = false;
-        else if (!onTop && spaceBelow < natural && spaceAbove > spaceBelow) onTop = true;
+        if (reanchor && this._flippedTop !== null) {
+          onTop = this._flippedTop;
+        } else {
+          if (onTop && spaceAbove < natural && spaceBelow > spaceAbove) onTop = false;
+          else if (!onTop && spaceBelow < natural && spaceAbove > spaceBelow) onTop = true;
+        }
+        this._flippedTop = onTop;
         const space = onTop ? spaceAbove : spaceBelow;
         surface.style.maxHeight = `${Math.max(MIN_HEIGHT, Math.floor(space))}px`;
         const box = surface.getBoundingClientRect();
@@ -517,10 +763,11 @@ class AMenuElement extends HTMLElementBase {
         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 = 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)`;
+      this.updateScrollFade();
     };
     if (sync) run();
     else requestAnimationFrame(run);
@@ -540,6 +787,23 @@ class AMenuElement extends HTMLElementBase {
    *   - 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 AMenuItemElement) {
+        if (!node.hasAttribute("disabled") && !node.querySelector("a-menu") && node.closest("a-menu") === this) {
+          node.dispatchEvent(
+            new MouseEvent("menuselect", {
+              bubbles: false,
+              altKey: e.altKey,
+              ctrlKey: e.ctrlKey,
+              metaKey: e.metaKey,
+              shiftKey: e.shiftKey
+            })
+          );
+        }
+        break;
+      }
+    }
     for (const node of e.composedPath()) {
       if (node === this.surface) break;
       if (!(node instanceof Element)) continue;
@@ -569,9 +833,8 @@ class AMenuElement extends HTMLElementBase {
     if (e.key === "Escape") {
       e.preventDefault();
       e.stopPropagation();
-      const anchor = this.triggerAnchor;
       this.requestClose(e);
-      anchor?.focus();
+      this.focusTrigger();
       return;
     }
     if (e.key === "Tab") {
@@ -587,6 +850,11 @@ class AMenuElement extends HTMLElementBase {
       f[next]?.focus();
       return;
     }
+    const search = this.#searchField;
+    if (search && (active === search || search.contains(active))) {
+      this.handleComboKey(e);
+      return;
+    }
     const within = active?.closest("a-menu") === this;
     if (within && !(active instanceof AMenuItemElement)) return;
     const items = this.focusableItems();
@@ -594,19 +862,19 @@ class AMenuElement extends HTMLElementBase {
     switch (e.key) {
       case "ArrowDown":
         e.preventDefault();
-        items[idx < 0 ? 0 : (idx + 1) % items.length]?.focus();
+        items[idx < 0 ? 0 : (idx + 1) % items.length]?.focus({ preventScroll: true });
         break;
       case "ArrowUp":
         e.preventDefault();
-        items[idx <= 0 ? items.length - 1 : idx - 1]?.focus();
+        items[idx <= 0 ? items.length - 1 : idx - 1]?.focus({ preventScroll: true });
         break;
       case "Home":
         e.preventDefault();
-        items[0]?.focus();
+        items[0]?.focus({ preventScroll: true });
         break;
       case "End":
         e.preventDefault();
-        items[items.length - 1]?.focus();
+        items[items.length - 1]?.focus({ preventScroll: true });
         break;
       case "ArrowRight": {
         const sub = this.submenuOf(active);
@@ -665,7 +933,7 @@ class AMenuElement extends HTMLElementBase {
       anchor.addEventListener("click", onClick);
       let onEnter;
       let onLeave;
-      if (this.isHover) {
+      if (this.#isHover) {
         onEnter = (e) => {
           if (e.pointerType === "mouse") this.scheduleOpen();
         };
@@ -681,7 +949,7 @@ class AMenuElement extends HTMLElementBase {
         if (onLeave) anchor.removeEventListener("pointerleave", onLeave);
         this.listening = false;
       };
-    } else if (this.isContext) {
+    } else if (this.#isContext) {
       const onContext = (e) => {
         e.preventDefault();
         this.requestOpen({ coord: [e.clientX, e.clientY], originEvent: e });
@@ -695,9 +963,9 @@ class AMenuElement extends HTMLElementBase {
       const onClick = (e) => {
         const viaKeyboard = e.detail === 0;
         let coord;
-        if (this.isCoord) {
+        if (this.#isCoord) {
           if (viaKeyboard) {
-            const r = anchor.getBoundingClientRect();
+            const r = anchorRect(anchor);
             coord = [r.left, r.bottom];
           } else {
             coord = [e.clientX, e.clientY];
@@ -731,12 +999,23 @@ class AMenuElement extends HTMLElementBase {
   scheduleClose() {
     this.cancelOpenTimer();
     if (!this._shown) return;
+    if (this.#hasKeyboardFocusInside) return;
     this.cancelCloseTimer();
     this.closeTimer = setTimeout(() => {
       this.closeTimer = void 0;
       this.requestClose();
     }, SUBMENU_CLOSE_DELAY);
   }
+  /** True when the document's focused element is inside this menu AND is
+   *  keyboard-focused (`:focus-visible`). Distinguishes "arrowed into the flyout"
+   *  (keep it open on hover-out) from a mouse-click focus (close as usual).
+   *  `activeElement` retargets to the shadow host at the document level, so a
+   *  focused menu item (or its delegated inner control) reads as a light-DOM
+   *  descendant here. */
+  get #hasKeyboardFocusInside() {
+    const active = this.doc.activeElement;
+    return !!active && this.contains(active) && active.matches(":focus-visible");
+  }
   cancelOpenTimer() {
     if (this.openTimer !== void 0) {
       clearTimeout(this.openTimer);

package/dist/elements/a-progress.css

@@ -1 +1 @@
-@layer anta{a-progress{--progress-bg: var(--bg-4);--progress-border-color: var(--border-4);--progress-indicator-bg: var(--bg-5);--progress-indicator-edge: linear-gradient( 90deg, var(--progress-indicator-bg) 0%, var(--progress-border-color) 100% );--progress-text-color: var(--text-2);--progress-hint-color: var(--text-3);display:block;container-type:inline-size;padding:4px 8px;min-height:8px;background:var(--progress-bg);border:0px solid var(--progress-border-color);border-radius:0}a-progress[tone=brand]{--progress-bg: var(--bg-4-brand);--progress-border-color: var(--border-4-brand);--progress-indicator-bg: var(--bg-5-brand);--progress-text-color: var(--text-2-brand);--progress-hint-color: var(--text-3-brand)}a-progress[tone=info]{--progress-bg: var(--bg-4-info);--progress-border-color: var(--border-4-info);--progress-indicator-bg: var(--bg-5-info);--progress-text-color: var(--text-2-info);--progress-hint-color: var(--text-3-info)}a-progress[tone=success]{--progress-bg: var(--bg-4-success);--progress-border-color: var(--border-4-success);--progress-indicator-bg: var(--bg-5-success);--progress-text-color: var(--text-2-success);--progress-hint-color: var(--text-3-success)}a-progress[tone=warning]{--progress-bg: var(--bg-4-warning);--progress-border-color: var(--border-4-warning);--progress-indicator-bg: var(--bg-5-warning);--progress-text-color: var(--text-2-warning);--progress-hint-color: var(--text-3-warning)}a-progress[tone=critical]{--progress-bg: var(--bg-4-critical);--progress-border-color: var(--border-4-critical);--progress-indicator-bg: var(--bg-5-critical);--progress-text-color: var(--text-2-critical);--progress-hint-color: var(--text-3-critical)}a-progress[tone]:not([tone=""],[tone=neutral],[tone=brand],[tone=info],[tone=success],[tone=warning],[tone=critical]){--progress-tone-source: attr(tone type(<color>), transparent);--progress-bg: oklch(from var(--progress-tone-source) .95 calc(c*.4) h);--progress-border-color: oklch(from var(--progress-tone-source) .85 calc(c*.6) h);--progress-indicator-bg: oklch(from var(--progress-tone-source) .6 c h);--progress-text-color: oklch(from var(--progress-tone-source) .45 c h);--progress-hint-color: oklch(from var(--progress-tone-source) .55 c h);.dark &{--progress-bg: oklch(from var(--progress-tone-source) .28 calc(c/2) h);--progress-border-color: oklch(from var(--progress-tone-source) .4 calc(c*.6) h);--progress-indicator-bg: oklch(from var(--progress-tone-source) .6 c h);--progress-text-color: oklch(from var(--progress-tone-source) .85 c h);--progress-hint-color: oklch(from var(--progress-tone-source) .75 c h)}}a-progress-label{display:flex;align-items:flex-start;gap:.5ch;font-variant-numeric:tabular-nums;font-feature-settings:"ss02","ss05";letter-spacing:.03em;font-size:13px;line-height:16px}a-progress-number{flex-shrink:0;color:var(--progress-text-color)}a-progress-text{flex:1 1 auto;min-width:0;color:var(--progress-text-color)}a-progress-hint{flex-shrink:0;margin-left:auto;color:var(--progress-hint-color)}}
+@layer anta{a-progress{--progress-bg: var(--bg-4);--progress-border-color: var(--border-4);--progress-indicator-bg: var(--bg-5);--progress-indicator-edge: linear-gradient( 90deg, var(--progress-indicator-bg) 0%, var(--progress-border-color) 100% );--progress-text-color: var(--text-2);--progress-hint-color: var(--text-3);display:block;container-type:inline-size;padding:4px 8px;min-height:8px;background:var(--progress-bg);border:0px solid var(--progress-border-color);border-radius:0}a-progress[round]{--progress-round: attr(round type(<length>), 999px);border-radius:var(--progress-round, 999px)}a-progress[tone=brand]{--progress-bg: var(--bg-4-brand);--progress-border-color: var(--border-4-brand);--progress-indicator-bg: var(--bg-5-brand);--progress-text-color: var(--text-2-brand);--progress-hint-color: var(--text-3-brand)}a-progress[tone=info]{--progress-bg: var(--bg-4-info);--progress-border-color: var(--border-4-info);--progress-indicator-bg: var(--bg-5-info);--progress-text-color: var(--text-2-info);--progress-hint-color: var(--text-3-info)}a-progress[tone=success]{--progress-bg: var(--bg-4-success);--progress-border-color: var(--border-4-success);--progress-indicator-bg: var(--bg-5-success);--progress-text-color: var(--text-2-success);--progress-hint-color: var(--text-3-success)}a-progress[tone=warning]{--progress-bg: var(--bg-4-warning);--progress-border-color: var(--border-4-warning);--progress-indicator-bg: var(--bg-5-warning);--progress-text-color: var(--text-2-warning);--progress-hint-color: var(--text-3-warning)}a-progress[tone=critical]{--progress-bg: var(--bg-4-critical);--progress-border-color: var(--border-4-critical);--progress-indicator-bg: var(--bg-5-critical);--progress-text-color: var(--text-2-critical);--progress-hint-color: var(--text-3-critical)}a-progress[tone]:not([tone=""],[tone=neutral],[tone=brand],[tone=info],[tone=success],[tone=warning],[tone=critical]){--progress-tone-source: attr(tone type(<color>), transparent);--progress-bg: oklch(from var(--progress-tone-source) .95 calc(c*.4) h);--progress-border-color: oklch(from var(--progress-tone-source) .85 calc(c*.6) h);--progress-indicator-bg: oklch(from var(--progress-tone-source) .6 c h);--progress-text-color: oklch(from var(--progress-tone-source) .45 c h);--progress-hint-color: oklch(from var(--progress-tone-source) .55 c h);.dark &{--progress-bg: oklch(from var(--progress-tone-source) .28 calc(c/2) h);--progress-border-color: oklch(from var(--progress-tone-source) .4 calc(c*.6) h);--progress-indicator-bg: oklch(from var(--progress-tone-source) .6 c h);--progress-text-color: oklch(from var(--progress-tone-source) .85 c h);--progress-hint-color: oklch(from var(--progress-tone-source) .75 c h)}}a-progress-label{display:flex;align-items:flex-start;gap:.5ch;font-variant-numeric:lining-nums tabular-nums;font-feature-settings:"ss02","ss05";letter-spacing:.03em;font-size:13px;line-height:16px}a-progress-number{flex-shrink:0;color:var(--progress-text-color)}a-progress-text{flex:1 1 auto;min-width:0;color:var(--progress-text-color)}a-progress-hint{flex-shrink:0;margin-left:auto;color:var(--progress-hint-color)}}