stimeo-ui 0.14.0 → 0.16.0

package/dist/controllers/overflow_menu_controller.js

@@ -64,10 +64,15 @@ var LayoutObserver = class {
   #resizeObserverFactory;
   #resizeObserver = null;
   #observingViewport = false;
+  #loadContainer = null;
   /** Stable bound handler so add/removeEventListener target the same reference. */
   #handleViewportResize = () => {
     this.#callback();
   };
+  /** Stable bound handler for the capture-phase `load`; see {@link observeDescendantLoads}. */
+  #handleDescendantLoad = () => {
+    this.#callback();
+  };
   constructor(callback, options = {}) {
     this.#callback = callback;
     this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
@@ -103,14 +108,35 @@ var LayoutObserver = class {
     window.removeEventListener("resize", this.#handleViewportResize);
   }
   /**
-   * Releases every observation: disconnects the {@link ResizeObserver} and
-   * removes the viewport listener. Safe to call multiple times. Call this from a
-   * controller's `disconnect()`.
+   * Starts reporting a `load` from anywhere inside `container` — an image or a
+   * frame settling changes the box it sits in, and it measures as zero high until
+   * then. `load` does not bubble, so the subscription is a capture-phase listener
+   * on the container itself and nothing the caller spells.
+   *
+   * **One container at a time.** A further call moves the observation, so a widget
+   * whose content element is swapped at runtime releases the element it let go by
+   * naming the new one — there is no second place for the release to drift from.
+   */
+  observeDescendantLoads(container) {
+    this.unobserveDescendantLoads();
+    this.#loadContainer = container;
+    container.addEventListener("load", this.#handleDescendantLoad, true);
+  }
+  /** Stops reporting descendant loads without affecting element or viewport observation. */
+  unobserveDescendantLoads() {
+    this.#loadContainer?.removeEventListener("load", this.#handleDescendantLoad, true);
+    this.#loadContainer = null;
+  }
+  /**
+   * Releases every observation: disconnects the {@link ResizeObserver} and removes
+   * the viewport and descendant-load listeners. Safe to call multiple times. Call
+   * this from a controller's `disconnect()`.
    */
   disconnect() {
     this.#resizeObserver?.disconnect();
     this.#resizeObserver = null;
     this.unobserveViewport();
+    this.unobserveDescendantLoads();
   }
 };
 
@@ -199,15 +225,20 @@ var TabindexLoan = class {
 };
 
 // src/controllers/overflow_menu_controller.ts
-var BANKED = "data-stimeo--overflow-menu-banked";
-var INDEX = "data-stimeo--overflow-menu-index";
-var BOUNDARY = "data-stimeo--overflow-menu-boundary";
-var SAVED_ROLE = "data-stimeo--overflow-menu-role";
-var SAVED_TABINDEX = "data-stimeo--overflow-menu-tabindex";
-var SAVED_MENU_TARGET = "data-stimeo--overflow-menu-saved-menu";
+var BANKED = "banked";
+var INDEX = "index";
+var BOUNDARY = "boundary";
+var SAVED_ROLE = "role";
+var SAVED_TABINDEX = "tabindex";
+var SAVED_MENU_TARGET = "saved-menu";
 var MENU_TARGET = "data-stimeo--menu-target";
 var BOOKKEEPING = [BANKED, INDEX, SAVED_ROLE, SAVED_TABINDEX, SAVED_MENU_TARGET];
+var OWNED_LABEL = "owns-label";
 var OverflowMenuController = class extends Controller {
+  /** One bookkeeping attribute, in the namespace this controller is registered under. */
+  #attr(name) {
+    return `data-${this.identifier}-${name}`;
+  }
   static targets = ["items", "more"];
   static values = {
     moreLabel: { type: String, default: "More" },
@@ -226,29 +257,42 @@ var OverflowMenuController = class extends Controller {
   #lastHidden = null;
   /** The `tabindex` this instance lends the root for the focus fallback. */
   #tabindex = new TabindexLoan();
-  /** Hands Turbo a pristine snapshot of the bar, with every item back in place. */
+  /** Hands Turbo a snapshot of the bar with every item back in place. */
   #beforeCache = new BeforeCacheReset(() => this.#restoreAll());
+  /**
+   * Whether `connect()` has run for this connection. Stimulus delivers Value
+   * callbacks ahead of it, and the first pass writes the label anyway.
+   */
+  #connected = false;
   connect() {
+    this.#connected = true;
     if (!this.hasItemsTarget || !this.hasMoreTarget) return;
-    const trigger = this.#trigger();
-    if (trigger !== null && this.#isBareTrigger(trigger)) {
-      trigger.textContent = this.moreLabelValue;
-    }
     this.#beforeCache.activate();
     this.#layout.observe(this.element);
     this.#layout.observeViewport();
     this.update();
   }
   disconnect() {
+    this.#connected = false;
     this.#layout.disconnect();
     this.#timers.clearAll();
     this.#beforeCache.deactivate();
     this.#restoreAll();
     this.#lastHidden = null;
   }
+  /**
+   * Follows a More label swapped in place by a morph, on a trigger that still holds
+   * the label this controller wrote and nothing else. Render only: nothing is
+   * measured and `change` is not dispatched here; the next pass measures the bar.
+   */
+  moreLabelValueChanged() {
+    if (!this.#connected || !this.hasItemsTarget || !this.hasMoreTarget) return;
+    this.#syncLabel();
+  }
   /** Re-measures and rebalances items between the bar and the More menu. */
   update() {
     if (!this.hasItemsTarget || !this.hasMoreTarget) return;
+    this.#syncLabel();
     this.#syncItems();
     this.moreTarget.hidden = false;
     if (this.#items.some((item) => item.parentElement !== this.itemsTarget && !this.#widths.has(item))) {
@@ -302,8 +346,8 @@ var OverflowMenuController = class extends Controller {
     else if (active !== null && this.#lostFocus(active)) active.focus();
     const count = hidden.size;
     for (const item of this.#items) {
-      if (count > 0) item.setAttribute(INDEX, String(this.#indexOf(item)));
-      else item.removeAttribute(INDEX);
+      if (count > 0) item.setAttribute(this.#attr(INDEX), String(this.#indexOf(item)));
+      else item.removeAttribute(this.#attr(INDEX));
     }
     if (count > 0 && count === this.#items.length) this.#ensureBoundary();
     else this.#removeBoundary();
@@ -318,7 +362,7 @@ var OverflowMenuController = class extends Controller {
     this.element.setAttribute("data-overflow-count", String(count));
     if (this.#lastHidden !== count) {
       this.#lastHidden = count;
-      this.dispatch("change", { detail: { visible: this.#items.length - count, hidden: count } });
+      this.dispatch("change", { detail: { overflowCount: count, total: this.#items.length } });
     }
   }
   /** The flex `column-gap` on `el` in px (0 when none / unsupported). */
@@ -348,7 +392,7 @@ var OverflowMenuController = class extends Controller {
     const bar = [];
     let boundaryAt;
     for (const el of this.itemsTarget.children) {
-      if (el instanceof HTMLTemplateElement && el.hasAttribute(BOUNDARY)) {
+      if (el instanceof HTMLTemplateElement && el.hasAttribute(this.#attr(BOUNDARY))) {
         boundaryAt ??= bar.length;
         continue;
       }
@@ -356,14 +400,14 @@ var OverflowMenuController = class extends Controller {
     }
     const banked = [];
     for (const el of this.#menuList().children) {
-      if (el instanceof HTMLElement && el.hasAttribute(BANKED)) banked.push(el);
+      if (el instanceof HTMLElement && el.hasAttribute(this.#attr(BANKED))) banked.push(el);
     }
     banked.sort((a, b) => this.#bankedIndex(a) - this.#bankedIndex(b));
     const items = this.#merge(bar, banked, boundaryAt);
     for (const el of previous) {
       if (!items.includes(el)) {
         this.#unbank(el);
-        el.removeAttribute(INDEX);
+        el.removeAttribute(this.#attr(INDEX));
       }
     }
     this.#items = items;
@@ -436,7 +480,7 @@ var OverflowMenuController = class extends Controller {
   }
   /** A finite canonical index stored on either side of the overflow split. */
   #savedIndex(item) {
-    const raw = item.getAttribute(INDEX);
+    const raw = item.getAttribute(this.#attr(INDEX));
     if (raw === null) return void 0;
     const value = Number(raw);
     return Number.isFinite(value) ? value : void 0;
@@ -444,14 +488,14 @@ var OverflowMenuController = class extends Controller {
   /** The inert split point written only when every managed item lives in More. */
   #boundary() {
     for (const el of this.itemsTarget.children) {
-      if (el instanceof HTMLTemplateElement && el.hasAttribute(BOUNDARY)) return el;
+      if (el instanceof HTMLTemplateElement && el.hasAttribute(this.#attr(BOUNDARY))) return el;
     }
     return null;
   }
   #ensureBoundary() {
     if (this.#boundary() !== null) return;
     const boundary = document.createElement("template");
-    boundary.setAttribute(BOUNDARY, "");
+    boundary.setAttribute(this.#attr(BOUNDARY), "");
     this.itemsTarget.appendChild(boundary);
   }
   #removeBoundary() {
@@ -470,17 +514,68 @@ var OverflowMenuController = class extends Controller {
     return this.moreTarget.querySelector('[data-stimeo--menu-target="trigger"]');
   }
   /**
-   * Whether the More trigger is bare enough for the label to be safe to write.
-   * Assigning `textContent` replaces *every* child node, so a trigger holding an
-   * icon would silently lose it — and the loss is permanent, since the restore
-   * pass returns items but not authored trigger content. A trigger that already
-   * carries an accessible name is left alone too: injecting visible text under a
-   * different `aria-label` would make the label and the name disagree. A trigger
-   * with neither text, nor children, nor a name has nothing to lose and gets the
-   * fallback; one that is empty *and* unnamed is the only case the label rescues.
+   * Keeps the More trigger's text on `moreLabel` wherever that text is this
+   * controller's to write: a bare trigger, or one still holding the label this
+   * controller wrote and nothing else. An empty `moreLabel` hands such a trigger
+   * back bare. A pass that finds the label already in place writes nothing, and a
+   * trigger that is neither is not written at all.
+   *
+   * @stimeoRenderRoot
+   */
+  #syncLabel() {
+    const trigger = this.#trigger();
+    if (trigger === null) return;
+    const owned = this.#ownsLabel(trigger);
+    if (!owned && !this.#isBareTrigger(trigger)) return;
+    const label = this.moreLabelValue;
+    if (label === "") {
+      this.#releaseLabel(trigger);
+      return;
+    }
+    if (owned && trigger.textContent === label) return;
+    trigger.textContent = label;
+    trigger.setAttribute(this.#attr(OWNED_LABEL), label);
+  }
+  /**
+   * Whether the trigger holds the label this controller wrote there and nothing
+   * else: the text still matches the marker, and the trigger carries nothing but
+   * text. Ownership is read afresh on every call, so a trigger the consumer adds to
+   * is theirs for as long as the addition is there.
+   */
+  #ownsLabel(trigger) {
+    return trigger.getAttribute(this.#attr(OWNED_LABEL)) === trigger.textContent && this.#carriesOnlyText(trigger);
+  }
+  /**
+   * Takes the label this controller wrote back out of the trigger, leaving it bare.
+   * A trigger that is not this controller's is left exactly as it is, marker
+   * included: taking the marker off would itself write to it.
+   */
+  #releaseLabel(trigger) {
+    if (!this.#ownsLabel(trigger)) return;
+    trigger.textContent = "";
+    trigger.removeAttribute(this.#attr(OWNED_LABEL));
+  }
+  /**
+   * Whether the More trigger is bare, so the label is safe to write: no text, no
+   * element child, no `aria-label` and no `aria-labelledby`. A trigger with neither
+   * text, nor children, nor a name has nothing to lose and gets the fallback; one
+   * that is empty *and* unnamed is the only case the label rescues.
    */
   #isBareTrigger(trigger) {
-    return (trigger.textContent ?? "").trim() === "" && trigger.firstElementChild === null && !trigger.hasAttribute("aria-label") && !trigger.hasAttribute("aria-labelledby");
+    return (trigger.textContent ?? "").trim() === "" && this.#carriesOnlyText(trigger);
+  }
+  /**
+   * Whether the trigger carries nothing but text: no element child, no
+   * `aria-label` and no `aria-labelledby`. Assigning `textContent` replaces
+   * *every* child node, so a trigger holding an icon would silently lose it — and
+   * the loss is permanent, since only the label this controller wrote is ever
+   * taken back. A trigger that carries an accessible name is left alone too:
+   * visible text written under a different `aria-label` would make the label and
+   * the name disagree. Only a trigger that carries nothing but text is ever
+   * written or emptied.
+   */
+  #carriesOnlyText(trigger) {
+    return trigger.firstElementChild === null && !trigger.hasAttribute("aria-label") && !trigger.hasAttribute("aria-labelledby");
   }
   /**
    * Whether the More menu is expanded. Menu owns that state and reflects it on the
@@ -551,9 +646,11 @@ var OverflowMenuController = class extends Controller {
     this.#reorder(this.itemsTarget, this.#items);
     for (const item of this.#items) {
       this.#unbank(item);
-      item.removeAttribute(INDEX);
+      item.removeAttribute(this.#attr(INDEX));
     }
     this.#closeMenu();
+    const trigger = this.#trigger();
+    if (trigger !== null) this.#releaseLabel(trigger);
     this.moreTarget.hidden = true;
     this.element.removeAttribute("data-overflowing");
     this.element.removeAttribute("data-overflow-count");
@@ -593,24 +690,24 @@ var OverflowMenuController = class extends Controller {
    * saving every authored value it overwrites ("" means the attribute was absent).
    */
   #bank(item) {
-    if (!item.hasAttribute(BANKED)) {
-      item.setAttribute(BANKED, "true");
-      item.setAttribute(SAVED_ROLE, item.getAttribute("role") ?? "");
-      item.setAttribute(SAVED_TABINDEX, item.getAttribute("tabindex") ?? "");
-      item.setAttribute(SAVED_MENU_TARGET, item.getAttribute(MENU_TARGET) ?? "");
+    if (!item.hasAttribute(this.#attr(BANKED))) {
+      item.setAttribute(this.#attr(BANKED), "true");
+      item.setAttribute(this.#attr(SAVED_ROLE), item.getAttribute("role") ?? "");
+      item.setAttribute(this.#attr(SAVED_TABINDEX), item.getAttribute("tabindex") ?? "");
+      item.setAttribute(this.#attr(SAVED_MENU_TARGET), item.getAttribute(MENU_TARGET) ?? "");
       item.setAttribute("role", "menuitem");
       item.setAttribute("tabindex", "-1");
       item.setAttribute(MENU_TARGET, "item");
     }
-    item.setAttribute(INDEX, String(this.#indexOf(item)));
+    item.setAttribute(this.#attr(INDEX), String(this.#indexOf(item)));
   }
   /** Undoes the banking: restores every authored value and drops the bookkeeping. */
   #unbank(item) {
-    if (!item.hasAttribute(BANKED)) return;
-    this.#restoreAttr(item, "role", item.getAttribute(SAVED_ROLE));
-    this.#restoreAttr(item, "tabindex", item.getAttribute(SAVED_TABINDEX));
-    this.#restoreAttr(item, MENU_TARGET, item.getAttribute(SAVED_MENU_TARGET));
-    for (const name of BOOKKEEPING) item.removeAttribute(name);
+    if (!item.hasAttribute(this.#attr(BANKED))) return;
+    this.#restoreAttr(item, "role", item.getAttribute(this.#attr(SAVED_ROLE)));
+    this.#restoreAttr(item, "tabindex", item.getAttribute(this.#attr(SAVED_TABINDEX)));
+    this.#restoreAttr(item, MENU_TARGET, item.getAttribute(this.#attr(SAVED_MENU_TARGET)));
+    for (const name of BOOKKEEPING) item.removeAttribute(this.#attr(name));
   }
   /** Re-applies a saved attribute value, or removes the attribute when it was absent. */
   #restoreAttr(item, name, original) {