stimeo-ui 0.14.0 → 0.16.0

data/dist/controllers/menu_controller.js

@@ -160,6 +160,16 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/state_reason.ts
+var FOCUS_EVENTS = /* @__PURE__ */ new Set(["blur", "focus", "focusin", "focusout"]);
+var POINTER_EVENTS = /* @__PURE__ */ new Set(["mouseenter", "mouseleave", "pointerenter", "pointerleave"]);
+function stateReasonFor(event) {
+  if (!event) return "api";
+  if (FOCUS_EVENTS.has(event.type)) return "focus";
+  if (POINTER_EVENTS.has(event.type)) return "pointer";
+  return "user";
+}
+
 // src/controllers/menu_controller.ts
 var MenuController = class extends Controller {
   static targets = ["trigger", "menu", "item"];
@@ -171,6 +181,7 @@ var MenuController = class extends Controller {
     "open",
     "toggle"
   ];
+  static events = ["close", "open"];
   #timers = new SafeTimeout();
   /** Escape-stack membership while open; the shared resolver dismisses via it. */
   #escapeLayer = new EscapeLayer();
@@ -182,16 +193,20 @@ var MenuController = class extends Controller {
   #clickOwner = null;
   /** Clicks already turned into an activation, so the two paths run it once. */
   #activated = /* @__PURE__ */ new WeakSet();
+  /** Whether state moves are reported: set once `connect()` settled the baseline. */
+  #reporting = false;
   /** Starts closed and registers activation / outside-click listeners. */
   connect() {
-    this.close();
+    this.#close("api");
     this.element.addEventListener("click", this.#onItemClickCapture, true);
     this.element.addEventListener("click", this.#onDelegatedItemClick);
     this.element.addEventListener("keydown", this.#onDelegatedItemKeydown);
     document.addEventListener("click", this.#onOutsideClick, true);
+    this.#reporting = true;
   }
   /** Releases the listeners, stack membership, and any pending Tab-close task. */
   disconnect() {
+    this.#reporting = false;
     this.#timers.clearAll();
     this.#escapeLayer.deactivate();
     this.element.removeEventListener("click", this.#onItemClickCapture, true);
@@ -200,32 +215,44 @@ var MenuController = class extends Controller {
     document.removeEventListener("click", this.#onOutsideClick, true);
   }
   /** Toggles the menu open/closed. Bound via `data-action` (click). */
-  toggle() {
+  toggle(event) {
     if (this.#isOpen) {
-      this.close();
+      this.close(event);
     } else {
-      this.open();
+      this.open(event);
       this.#focusFirst();
     }
   }
   /** Opens the menu and reflects the expanded state on the trigger. */
-  open() {
+  open(event) {
+    this.#open(stateReasonFor(event));
+  }
+  /** Closes the menu and reflects the collapsed state on the trigger. */
+  close(event) {
+    this.#close(stateReasonFor(event));
+  }
+  /** Opens the menu, reflects the expanded state, and reports a move. */
+  #open(reason) {
     this.#timers.clearAll();
     if (!this.hasMenuTarget) return;
+    const was = this.#isOpen;
     this.#escapeLayer.activate(document, {
-      onDismiss: () => this.#closeAndRestore(),
+      onDismiss: () => this.#closeAndRestore("escape"),
       claims: claimsWhileFocusWithin(this.element)
     });
     this.menuTarget.hidden = false;
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "true");
+    if (!was && this.#reporting) this.dispatch("open", { detail: { reason }, cancelable: false });
   }
-  /** Closes the menu and reflects the collapsed state on the trigger. */
-  close() {
+  /** Closes the menu, reflects the collapsed state, and reports a move. */
+  #close(reason) {
     this.#timers.clearAll();
     this.#escapeLayer.deactivate();
     if (!this.hasMenuTarget) return;
+    const was = this.#isOpen;
     this.menuTarget.hidden = true;
     if (this.hasTriggerTarget) this.triggerTarget.setAttribute("aria-expanded", "false");
+    if (was && this.#reporting) this.dispatch("close", { detail: { reason }, cancelable: false });
   }
   /**
    * Opens the menu with the keyboard per the APG (Down → first, Up → last).
@@ -240,11 +267,11 @@ var MenuController = class extends Controller {
     if (isReservedArrowChord(event)) return;
     if (event.key === "ArrowDown") {
       event.preventDefault();
-      this.open();
+      this.open(event);
       this.#focusFirst();
     } else if (event.key === "ArrowUp") {
       event.preventDefault();
-      this.open();
+      this.open(event);
       this.#focusLast();
     }
   }
@@ -281,7 +308,7 @@ var MenuController = class extends Controller {
         break;
       case "Tab":
         this.#timers.clearAll();
-        this.#timers.set(() => this.close(), 0);
+        this.#timers.set(() => this.#close("focus"), 0);
         break;
     }
   }
@@ -302,21 +329,21 @@ var MenuController = class extends Controller {
       if (this.#activated.has(event)) return;
       this.#activated.add(event);
     }
-    this.#closeAndRestore();
+    this.#closeAndRestore("select");
   }
   /** Closes and returns focus to the trigger (Escape / item-activation path). */
-  #closeAndRestore() {
-    this.close();
+  #closeAndRestore(reason) {
+    this.#close(reason);
     if (this.hasTriggerTarget) this.triggerTarget.focus();
   }
   /** Closes the menu when a click lands outside the controller's element. */
   #onOutsideClick = (event) => {
-    if (this.#isOpen && !this.element.contains(event.target)) this.close();
+    if (this.#isOpen && !this.element.contains(event.target)) this.#close("outside");
   };
   /**
    * Delegated twin of {@link onItemKeydown}, bound on the controller element.
    *
-   * An item that arrives *after* connect — Overflow Menu moves toolbar controls
+   * An item that arrives *after* connect — `stimeo--overflow-menu` moves toolbar controls
    * into this menu at runtime — carries whatever `data-action` its author wrote,
    * and that is exactly the binding a consumer forgets, because the markup that
    * declares the item lives nowhere near the menu. Listening on the container
@@ -371,10 +398,12 @@ var MenuController = class extends Controller {
   };
   /** Moves focus to the first navigable item (no-op if none). */
   #focusFirst() {
+    if (!this.#isOpen) return;
     this.#navigableItems[0]?.focus();
   }
   /** Moves focus to the last navigable item (no-op if none). */
   #focusLast() {
+    if (!this.#isOpen) return;
     const items = this.#navigableItems;
     items[items.length - 1]?.focus();
   }

data/dist/controllers/menubar_controller.js

@@ -200,6 +200,16 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/state_reason.ts
+var FOCUS_EVENTS = /* @__PURE__ */ new Set(["blur", "focus", "focusin", "focusout"]);
+var POINTER_EVENTS = /* @__PURE__ */ new Set(["mouseenter", "mouseleave", "pointerenter", "pointerleave"]);
+function stateReasonFor(event) {
+  if (!event) return "api";
+  if (FOCUS_EVENTS.has(event.type)) return "focus";
+  if (POINTER_EVENTS.has(event.type)) return "pointer";
+  return "user";
+}
+
 // src/utils/typeahead.ts
 var TYPEAHEAD_RESET_MS = 500;
 var Typeahead = class {
@@ -263,6 +273,7 @@ var STATE_ATTRIBUTES = ["disabled", "hidden"];
 var MenubarController = class extends Controller {
   static targets = ["top", "menu", "item"];
   static actions = ["activate", "onItemKeydown", "onTopKeydown", "toggle"];
+  static events = ["close", "open"];
   /** Roving tabindex across the top-level menuitems (one Tab stop). */
   #roving = new RovingTabindex(() => this.topTargets);
   /** Typeahead query and its idle-reset timer (scoped to the open menu). */
@@ -281,6 +292,8 @@ var MenubarController = class extends Controller {
    * stop on mount and from resurrecting one after teardown.
    */
   #connected = false;
+  /** Whether state moves are reported: set once `connect()` settled the baseline. */
+  #reporting = false;
   /** The element inside the menubar that last took DOM focus, if any. */
   #focused = null;
   /**
@@ -314,7 +327,7 @@ var MenubarController = class extends Controller {
    * close the menu.
    */
   connect() {
-    this.#closeAllMenus();
+    this.#closeAllMenus("api");
     this.#reconcile();
     this.element.addEventListener("click", this.#onDisabledClickCapture, true);
     this.element.addEventListener("focusin", this.#onFocusIn);
@@ -330,10 +343,12 @@ var MenubarController = class extends Controller {
       });
     }
     this.#connected = true;
+    this.#reporting = true;
   }
   /** Removes the listeners, stack membership, and any pending timer (typeahead / Tab close). */
   disconnect() {
     this.#connected = false;
+    this.#reporting = false;
     this.#escapeLayer.deactivate();
     this.#layerActive = false;
     this.element.removeEventListener("click", this.#onDisabledClickCapture, true);
@@ -395,10 +410,11 @@ var MenubarController = class extends Controller {
   /** Toggles a top item's menu. Bound via `data-action` (click on the top item). */
   toggle(event) {
     const top = event.currentTarget;
+    const reason = stateReasonFor(event);
     if (this.#isExpanded(top)) {
-      this.#closeMenu(top);
+      this.#closeMenu(top, reason);
     } else {
-      this.#openMenu(top, "first");
+      this.#openMenu(top, "first", reason);
     }
   }
   /** Keyboard handling while focus is on a top item. */
@@ -414,27 +430,27 @@ var MenubarController = class extends Controller {
     switch (event.key) {
       case "ArrowRight":
         event.preventDefault();
-        this.#gotoTop(tops[(index + step + length) % length], anyOpen);
+        this.#gotoTop(tops[(index + step + length) % length], anyOpen, "user");
         break;
       case "ArrowLeft":
         event.preventDefault();
-        this.#gotoTop(tops[(index - step + length) % length], anyOpen);
+        this.#gotoTop(tops[(index - step + length) % length], anyOpen, "user");
         break;
       case "ArrowDown":
         event.preventDefault();
-        this.#openMenu(tops[index], "first");
+        this.#openMenu(tops[index], "first", "user");
         break;
       case "ArrowUp":
         event.preventDefault();
-        this.#openMenu(tops[index], "last");
+        this.#openMenu(tops[index], "last", "user");
         break;
       case "Home":
         event.preventDefault();
-        this.#gotoTop(tops[0], anyOpen);
+        this.#gotoTop(tops[0], anyOpen, "user");
         break;
       case "End":
         event.preventDefault();
-        this.#gotoTop(tops[length - 1], anyOpen);
+        this.#gotoTop(tops[length - 1], anyOpen, "user");
         break;
       case "Tab":
         this.#closeMenusSoon();
@@ -492,14 +508,14 @@ var MenubarController = class extends Controller {
     const item = event.currentTarget;
     const menu = item.closest("[role='menu']");
     const top = this.#topFor(menu);
-    this.#closeAllMenus();
+    this.#closeAllMenus("select");
     this.#focusTop(top);
   }
   /** Moves the roving focus to `top`, opening its menu when one was open. */
-  #gotoTop(top, reopen) {
+  #gotoTop(top, reopen, reason) {
     if (!top) return;
     if (reopen) {
-      this.#openMenu(top, "first");
+      this.#openMenu(top, "first", reason);
     } else {
       this.#roving.setActive(this.topTargets.indexOf(top), { focus: true });
     }
@@ -526,20 +542,23 @@ var MenubarController = class extends Controller {
    * this "open a menu" path. A dangling top is still an ordinary roving
    * destination while nothing is open.
    */
-  #openMenu(top, focus) {
+  #openMenu(top, focus, reason) {
     if (!top) return;
     const menu = this.#menuFor(top);
     if (!menu || this.#isActivationBlocked(top)) {
       if (menu || !top.hasAttribute("aria-controls")) {
-        this.#closeAllMenus();
+        this.#closeAllMenus(reason);
         this.#focusTop(top);
       }
       return;
     }
     this.#timers.clearAll();
-    this.#closeAllMenus();
+    const was = this.#isExpanded(top);
+    this.#closeAllMenus(reason, top);
     menu.hidden = false;
     top.setAttribute("aria-expanded", "true");
+    if (!was) this.#report("open", top, menu, reason);
+    if (!this.#isExpanded(top)) return;
     this.#escapeLayer.activate(document, {
       onDismiss: () => this.#dismissOpenMenu(),
       claims: claimsWhileFocusWithin(this.element)
@@ -554,19 +573,32 @@ var MenubarController = class extends Controller {
    * no menu (a plain command in an otherwise popup-bearing menubar) is left alone
    * — stamping `aria-expanded="false"` on it would announce a popup it lacks.
    */
-  #closeMenu(top) {
+  #closeMenu(top, reason, silent = false) {
     if (!top) return;
     const menu = this.#menuFor(top);
     if (!menu) return;
+    const was = this.#isExpanded(top);
     menu.hidden = true;
     top.setAttribute("aria-expanded", "false");
+    if (was && !silent) this.#report("close", top, menu, reason);
     this.#syncEscapeLayer();
   }
-  /** Closes every menu and resets the typeahead query. */
-  #closeAllMenus() {
-    for (const top of this.topTargets) this.#closeMenu(top);
+  /**
+   * Closes every menu and resets the typeahead query. `except` still has its
+   * attributes rewritten — the caller is about to reopen it — but its move is
+   * left for that caller to report.
+   */
+  #closeAllMenus(reason, except = null) {
+    for (const top of this.topTargets) this.#closeMenu(top, reason, top === except);
     this.#typeahead.reset();
   }
+  /** Names the menu that moved, so a subscriber does not have to re-derive it. */
+  #report(name, top, menu, reason) {
+    if (!this.#reporting) return;
+    const detail = { reason, index: this.topTargets.indexOf(top), menu };
+    if (name === "open") this.dispatch("open", { detail, cancelable: false });
+    else this.dispatch("close", { detail, cancelable: false });
+  }
   /**
    * Closes every menu on the next task instead of synchronously.
    *
@@ -577,7 +609,7 @@ var MenubarController = class extends Controller {
   #closeMenusSoon() {
     if (!this.#isAnyOpen) return;
     this.#timers.clearAll();
-    this.#timers.set(() => this.#closeAllMenus(), 0);
+    this.#timers.set(() => this.#closeAllMenus("focus"), 0);
   }
   /**
    * Escape path, invoked by the shared resolver: pressed inside an open menu it
@@ -589,11 +621,11 @@ var MenubarController = class extends Controller {
     const menu = ownerOf(this.menuTargets, document.activeElement);
     if (menu) {
       const top = this.#topFor(menu);
-      this.#closeMenu(top);
+      this.#closeMenu(top, "escape");
       this.#focusTop(top);
       return;
     }
-    this.#closeAllMenus();
+    this.#closeAllMenus("escape");
   }
   /** Opens the menu of the navigable top item `delta` steps from `menu`'s owner. */
   #moveToAdjacentMenu(menu, delta) {
@@ -603,7 +635,7 @@ var MenubarController = class extends Controller {
     const current = tops.indexOf(top);
     if (current === -1) return;
     const next = (current + delta + tops.length) % tops.length;
-    this.#openMenu(tops[next], "first");
+    this.#openMenu(tops[next], "first", "user");
   }
   /**
    * Closes when a click lands outside the controller's element. Focus is left on
@@ -611,7 +643,9 @@ var MenubarController = class extends Controller {
    * docs.
    */
   #onOutsideClick = (event) => {
-    if (this.#isAnyOpen && !this.element.contains(event.target)) this.#closeAllMenus();
+    if (this.#isAnyOpen && !this.element.contains(event.target)) {
+      this.#closeAllMenus("outside");
+    }
   };
   /**
    * Captures clicks so `aria-disabled` top items and commands cannot reach

data/dist/controllers/meter_controller.js

@@ -76,8 +76,12 @@ function rangeFraction(value, min, max) {
 }
 
 // src/controllers/meter_controller.ts
-var OWNED_VALUE_TEXT = "data-stimeo--meter-owns-valuetext";
+var OWNED_VALUE_TEXT = "owns-valuetext";
 var MeterController = class extends Controller {
+  /** The marker above, in the namespace this controller is registered under. */
+  get #ownedValueText() {
+    return `data-${this.identifier}-${OWNED_VALUE_TEXT}`;
+  }
   static targets = ["bar"];
   static values = {
     announceText: { type: String, default: "" },
@@ -157,7 +161,7 @@ var MeterController = class extends Controller {
   }
   /** Whether a threshold attribute is present (absent = no threshold). */
   #hasThreshold(name) {
-    return this.element.hasAttribute(`data-stimeo--meter-${name}-value`);
+    return this.element.hasAttribute(`data-${this.identifier}-${name}-value`);
   }
   /**
    * Classifies `value` into a `low`/`medium`/`high` segment. Values at or below
@@ -199,16 +203,16 @@ var MeterController = class extends Controller {
    */
   #applyValueText({ value, ratio, state }) {
     if (this.valueTextValue.length === 0) {
-      if (this.element.hasAttribute(OWNED_VALUE_TEXT)) {
+      if (this.element.hasAttribute(this.#ownedValueText)) {
         this.element.removeAttribute("aria-valuetext");
-        this.element.removeAttribute(OWNED_VALUE_TEXT);
+        this.element.removeAttribute(this.#ownedValueText);
       }
       return;
     }
     const percent = Math.round(ratio * 100);
     const text = this.valueTextValue.replaceAll("{value}", String(value)).replaceAll("{percent}", String(percent)).replaceAll("{state}", state);
     this.element.setAttribute("aria-valuetext", text);
-    this.element.setAttribute(OWNED_VALUE_TEXT, "");
+    this.element.setAttribute(this.#ownedValueText, "");
   }
 };