stimeo-ui 0.16.0 → 0.18.0

package/dist/controllers/overflow_menu_controller.js

@@ -1,37 +1,5 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/overflow_menu_controller.ts
-
-// src/utils/before_cache_reset.ts
-var BeforeCacheReset = class _BeforeCacheReset {
-  /** Every subscribed instance, iterated by the one shared document listener. */
-  static #subscribers = /* @__PURE__ */ new Set();
-  /** The shared listener; installed while at least one instance is subscribed. */
-  static #onBeforeCache = () => {
-    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
-  };
-  #rewind;
-  /** @param rewind - the pass that returns this controller's state to its initial form. */
-  constructor(rewind) {
-    this.#rewind = rewind;
-  }
-  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
-  activate() {
-    const first = _BeforeCacheReset.#subscribers.size === 0;
-    _BeforeCacheReset.#subscribers.add(this);
-    if (first) {
-      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
-    }
-  }
-  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
-  deactivate() {
-    _BeforeCacheReset.#subscribers.delete(this);
-    if (_BeforeCacheReset.#subscribers.size > 0) return;
-    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
-  }
-};
-
-// src/utils/event_owner.ts
 function ownerIndex(candidates, node) {
   if (!(node instanceof Node)) return -1;
   return candidates.findIndex((candidate) => candidate.contains(node));
@@ -40,7 +8,6 @@ function ownerOf(candidates, node) {
   return candidates[ownerIndex(candidates, node)] ?? null;
 }
 
-// src/utils/focus_candidate.ts
 function inheritsFieldsetDisabled(control) {
   let fieldset = control.closest("fieldset[disabled]");
   while (fieldset) {
@@ -50,26 +17,39 @@ function inheritsFieldsetDisabled(control) {
   }
   return false;
 }
+function unslotted(element) {
+  return element.assignedSlot === null && element.parentElement?.shadowRoot != null;
+}
+function flatTreeParent(element) {
+  if (unslotted(element)) return null;
+  const parent = element.assignedSlot ?? element.parentNode;
+  if (parent instanceof ShadowRoot) return parent.host;
+  return parent instanceof Element ? parent : null;
+}
 function canTakeFocus(element) {
-  if (element.closest("[hidden], [inert]")) return false;
+  for (let node = element; node; node = flatTreeParent(node)) {
+    if (unslotted(node) || node.matches("[hidden], [inert]")) return false;
+  }
   if (element instanceof HTMLInputElement && element.type === "hidden") return false;
   if (!("disabled" in element)) return true;
   if (element.disabled) return false;
   return !inheritsFieldsetDisabled(element);
 }
+function deepActiveElement(ownerDocument) {
+  let active = ownerDocument.activeElement;
+  while (active?.shadowRoot?.activeElement) active = active.shadowRoot.activeElement;
+  return active;
+}
 
-// src/utils/layout_observer.ts
 var LayoutObserver = class {
   #callback;
   #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();
   };
@@ -77,11 +57,6 @@ var LayoutObserver = class {
     this.#callback = callback;
     this.#resizeObserverFactory = options.resizeObserverFactory ?? (typeof ResizeObserver === "undefined" ? null : (cb) => new ResizeObserver(cb));
   }
-  /**
-   * Starts observing an element's size. Repeated calls observe additional
-   * elements through the same shared observer. No-ops when no
-   * `ResizeObserver` implementation is available.
-   */
   observe(element) {
     if (!this.#resizeObserverFactory) return;
     if (!this.#resizeObserver) {
@@ -91,47 +66,28 @@ var LayoutObserver = class {
     }
     this.#resizeObserver.observe(element);
   }
-  /** Stops observing a single element while leaving any others in place. */
   unobserve(element) {
     this.#resizeObserver?.unobserve(element);
   }
-  /** Starts observing viewport resizes. Idempotent: the listener is added once. */
   observeViewport() {
     if (this.#observingViewport) return;
     this.#observingViewport = true;
     window.addEventListener("resize", this.#handleViewportResize);
   }
-  /** Stops observing viewport resizes without affecting element observation. */
   unobserveViewport() {
     if (!this.#observingViewport) return;
     this.#observingViewport = false;
     window.removeEventListener("resize", this.#handleViewportResize);
   }
-  /**
-   * 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;
@@ -140,43 +96,228 @@ var LayoutObserver = class {
   }
 };
 
-// src/utils/safe_timeout.ts
+var ListenerSet = class {
+  #abort = new AbortController();
+  add(target, type, handler, options) {
+    target.addEventListener(type, handler, { ...options, signal: this.#abort.signal });
+  }
+  dispose() {
+    this.#abort.abort();
+    this.#abort = new AbortController();
+  }
+};
+
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  constructor(run) {
+    this.#run = run;
+  }
+  activate() {
+    this.#active = true;
+  }
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  get pending() {
+    return this.#queued;
+  }
+  schedule() {
+    if (!this.#active || this.#queued) return;
+    this.#queued = true;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation || !this.#queued || !this.#active) return;
+      this.#queued = false;
+      this.#run();
+    });
+  }
+};
+
+var MorphRenderWatcher = class {
+  #listeners = new ListenerSet();
+  #pass;
+  #element = null;
+  #onMorph = () => this.#pass.schedule();
+  constructor(run) {
+    this.#pass = new MicrotaskCoalescer(run);
+  }
+  observe(element) {
+    if (this.#element === element) return;
+    this.disconnect();
+    this.#element = element;
+    this.#pass.activate();
+    this.#listeners.add(element, "turbo:morph-element", this.#onMorph);
+  }
+  schedule() {
+    this.#pass.schedule();
+  }
+  get pending() {
+    return this.#pass.pending;
+  }
+  disconnect() {
+    this.#listeners.dispose();
+    this.#pass.cancel();
+    this.#element = null;
+  }
+};
+
+var MAX_TIMER_DELAY_MS = 2147483647;
+
+var NUMBER_BOUNDS = {
+  timer: { finite: true, min: 0, max: MAX_TIMER_DELAY_MS }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
+function setAttributeIfChanged(element, name, value, beforeWrite) {
+  if (element.getAttribute(name) === value) return false;
+  if (value === null) element.removeAttribute(name);
+  else element.setAttribute(name, value);
+  return true;
+}
+
+var OwnedText = class {
+  #attribute;
+  #channel;
+  #guard;
+  #writes = /* @__PURE__ */ new WeakMap();
+  constructor(attribute, channel = "text", guard = () => true) {
+    this.#attribute = attribute;
+    this.#channel = channel;
+    this.#guard = guard;
+  }
+  hasRecord(element) {
+    return element.hasAttribute(this.#attribute);
+  }
+  read(element, evidence = {}) {
+    if (evidence.source === "live") return this.#writes.get(element) ?? null;
+    const raw = element.getAttribute(this.#attribute);
+    if (raw === null) return null;
+    try {
+      const record = JSON.parse(raw);
+      if (!Array.isArray(record) || record.length !== 3 || record[0] !== this.#channel || typeof record[1] !== "string" || typeof record[2] !== "string")
+        return null;
+      return { original: record[1], written: record[2] };
+    } catch {
+      return null;
+    }
+  }
+  owns(element, evidence = {}) {
+    return this.#ownedRecord(element, evidence) !== null;
+  }
+  #ownedRecord(element, evidence) {
+    const record = this.read(element, evidence);
+    if (record === null || !this.#guard(element)) return null;
+    if (this.#channel === "text" && element.firstElementChild !== null) return null;
+    const current = this.#current(element);
+    return current === record.written || evidence.source === "live" && evidence.allowOriginal === true && current === record.original ? record : null;
+  }
+  write(element, written, original, force = false) {
+    const current = this.#current(element);
+    if (current === null) return;
+    const before = original ?? this.#writes.get(element)?.original ?? this.read(element)?.original ?? current;
+    if (force || current !== written) this.#put(element, written);
+    this.remember(element, written, before);
+  }
+  remember(element, written, original) {
+    const current = this.#current(element);
+    if (current === null) return;
+    const before = original ?? this.#writes.get(element)?.original ?? this.read(element)?.original ?? current;
+    this.#writes.set(element, { original: before, written });
+    setAttributeIfChanged(
+      element,
+      this.#attribute,
+      JSON.stringify([this.#channel, before, written])
+    );
+  }
+  clear(element, evidence = {}) {
+    if (!this.owns(element, evidence)) return false;
+    if (this.#current(element) !== "") this.#put(element, "");
+    this.forget(element);
+    return true;
+  }
+  restore(element, evidence = {}) {
+    const record = this.#ownedRecord(element, evidence);
+    if (record === null) return false;
+    if (this.#current(element) !== record.original) this.#put(element, record.original);
+    this.forget(element);
+    return true;
+  }
+  forget(element) {
+    setAttributeIfChanged(element, this.#attribute, null);
+    this.#writes.delete(element);
+  }
+  #current(element) {
+    if (this.#channel === "text") return element.textContent ?? "";
+    return element instanceof HTMLInputElement ? element.value : null;
+  }
+  #put(element, text) {
+    if (this.#channel === "text") element.textContent = text;
+    else if (element instanceof HTMLInputElement) element.value = text;
+  }
+};
+
 var TimerRegistry = class {
-  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
   ids = /* @__PURE__ */ new Set();
-  /**
-   * Cancels a single tracked timer.
-   *
-   * No-ops if the id is unknown (already cleared, fired, or never owned by this
-   * registry), so callers can clear defensively without guarding.
-   */
   clear(id) {
     if (this.ids.delete(id)) {
       this.cancel(id);
     }
   }
-  /**
-   * Cancels every tracked timer. Call this from a controller's `disconnect()`
-   * to guarantee no timer outlives the element.
-   */
   clearAll() {
     for (const id of this.ids) {
       this.cancel(id);
     }
     this.ids.clear();
   }
-  /** Number of timers currently tracked (pending). */
   get size() {
     return this.ids.size;
   }
 };
 var SafeTimeout = class extends TimerRegistry {
-  /**
-   * Schedules `callback` after `delay` ms and returns the timer id.
-   *
-   * The id is removed from the registry automatically when the timeout fires,
-   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
-   */
   set(callback, delay) {
     const id = this.schedule(() => {
       this.ids.delete(id);
@@ -193,38 +334,136 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
-// src/utils/tabindex_loan.ts
-var TabindexLoan = class {
+function queryOpenDescendants(root, selector) {
+  const matches = [];
+  const roots = [root];
+  for (const scope of roots) {
+    matches.push(...scope.querySelectorAll(selector));
+    if (scope.nodeType === Node.ELEMENT_NODE) {
+      const shadow = scope.shadowRoot;
+      if (shadow) roots.push(shadow);
+    }
+    for (const element of scope.querySelectorAll("*")) {
+      if (element.shadowRoot) roots.push(element.shadowRoot);
+    }
+  }
+  return matches;
+}
+
+function sharedRegistry(key, create) {
+  const symbol = Symbol.for(key);
+  const scope = globalThis;
+  const existing = scope[symbol];
+  if (existing !== void 0) return existing;
+  const registry = create();
+  Object.defineProperty(globalThis, symbol, { value: registry });
+  return registry;
+}
+
+function holdsFocus(element) {
+  return element.matches(":focus") || deepActiveElement(element.ownerDocument) === element;
+}
+var TabindexLoan = class _TabindexLoan {
+  static #registry = sharedRegistry(
+    "stimeo-ui.tabindex-loan.registry.v1",
+    () => ({ stacks: /* @__PURE__ */ new WeakMap(), names: /* @__PURE__ */ new Set() })
+  );
   #value;
+  #record;
+  #preserveFocus;
   #lent = /* @__PURE__ */ new Set();
-  /** Returns live loans before Turbo can copy them into its page snapshot. */
-  #beforeCache = new BeforeCacheReset(() => this.returnAll());
-  /**
-   * @param value - the `tabindex` to lend. `"-1"` (the default) is
-   *   programmatically focusable but not a Tab stop; `"0"` is a real Tab stop,
-   *   which a scroll region with no focusable content of its own needs.
-   */
-  constructor(value = "-1") {
+  constructor(value, owner, options = {}) {
     this.#value = value;
-  }
-  /** Lends `element` the value; no-ops when it already carries a `tabindex`. */
-  lend(element) {
-    if (element.hasAttribute("tabindex")) return;
-    element.setAttribute("tabindex", this.#value);
+    this.#record = `data-${owner}-tabindex-loan`;
+    this.#preserveFocus = options.preserveFocus === true;
+    _TabindexLoan.#registry.names.add(this.#record);
+  }
+  lend(element, options = {}) {
+    const stack = this.#stack(element);
+    const current = element.getAttribute("tabindex");
+    const held = stack.find((hold) => hold.loan === this) ?? stack.find(
+      (hold) => hold.loan === null && hold.record === this.#record && hold.value === this.#value
+    );
+    const linked = stack.at(-1)?.value === current;
+    if (!held && options.onlyIfUnfocusable && (current !== null || element.tabIndex >= 0)) return;
+    if (!held && current !== null && !linked) return;
     this.#lent.add(element);
-    this.#beforeCache.activate();
+    if (held) held.loan = this;
+    else stack.push({ loan: this, record: this.#record, value: this.#value, linked });
+    this.#mark(element, stack);
+    if (current === null || !held && current !== this.#value) {
+      element.setAttribute("tabindex", this.#value);
+    }
+  }
+  return(element) {
+    const stack = this.#stack(element);
+    const hold = stack.find((held) => held.loan === this) ?? stack.find(
+      (held) => held.loan === null && held.record === this.#record && held.value === this.#value
+    );
+    if (!hold) return false;
+    if (!this.#release(element, stack, hold, this.#preserveFocus)) {
+      hold.loan = this;
+      this.#lent.add(element);
+      return false;
+    }
+    this.#lent.delete(element);
+    return true;
   }
-  /** Takes back every loan whose value is still the one that was lent. */
   returnAll() {
-    for (const element of this.#lent) {
-      if (element.getAttribute("tabindex") === this.#value) element.removeAttribute("tabindex");
+    for (const element of Array.from(this.#lent)) this.return(element);
+  }
+  reclaim(element) {
+    if (element.getAttribute(this.#record) !== this.#value) return;
+    const stack = this.#stack(element);
+    const hold = stack.find((held) => held.loan === null && held.record === this.#record);
+    if (hold && !holdsFocus(element)) this.#release(element, stack, hold);
+  }
+  reclaimWithin(root) {
+    for (const element of queryOpenDescendants(root, `[${this.#record}]`)) {
+      this.reclaim(element);
+    }
+  }
+  #stack(element) {
+    const stacks = _TabindexLoan.#registry.stacks;
+    const stack = stacks.get(element) ?? this.#seed(element);
+    stacks.set(element, stack);
+    return stack;
+  }
+  #seed(element) {
+    const current = element.getAttribute("tabindex");
+    const holds = [];
+    for (const record of _TabindexLoan.#registry.names) {
+      const value = element.getAttribute(record);
+      if (value !== null) holds.push({ loan: null, record, value, linked: true });
+    }
+    holds.sort((one, other) => Number(one.value === current) - Number(other.value === current));
+    for (const [index, hold] of holds.entries()) hold.linked = index > 0;
+    return holds;
+  }
+  #release(element, stack, hold, preserveFocus = false) {
+    const current = element.getAttribute("tabindex");
+    const index = stack.indexOf(hold);
+    const owns = current === hold.value && !stack.slice(index + 1).some((above2) => above2.value === current);
+    if (owns && preserveFocus && holdsFocus(element)) return false;
+    stack.splice(index, 1);
+    const above = stack[index];
+    if (above) above.linked &&= hold.linked;
+    this.#mark(element, stack);
+    if (!owns) return true;
+    const below = hold.linked ? stack[index - 1] : void 0;
+    if (!below) element.removeAttribute("tabindex");
+    else if (below.value !== current) element.setAttribute("tabindex", below.value);
+    return true;
+  }
+  #mark(element, stack) {
+    const records = /* @__PURE__ */ new Map([[this.#record, null]]);
+    for (const hold of stack) records.set(hold.record, hold.value);
+    for (const [name, recorded] of records) {
+      setAttributeIfChanged(element, name, recorded);
     }
-    this.#lent.clear();
-    this.#beforeCache.deactivate();
   }
 };
 
-// src/controllers/overflow_menu_controller.ts
 var BANKED = "banked";
 var INDEX = "index";
 var BOUNDARY = "boundary";
@@ -234,8 +473,13 @@ 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. */
+var OverflowMenuController = class _OverflowMenuController extends Controller {
+  #labelText = new OwnedText(
+    this.#attr(OWNED_LABEL),
+    "text",
+    (trigger) => this.#carriesOnlyText(trigger)
+  );
+  #numbers = new NumberValueReader();
   #attr(name) {
     return `data-${this.identifier}-${name}`;
   }
@@ -244,66 +488,84 @@ var OverflowMenuController = class extends Controller {
     moreLabel: { type: String, default: "More" },
     debounce: { type: Number, default: 100 }
   };
+  static valueConstraints = {
+    debounce: NUMBER_BOUNDS.timer
+  };
   static actions = ["update"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   #layout = new LayoutObserver(() => this.#scheduleUpdate());
   #timers = new SafeTimeout();
-  /** The managed items in canonical (authored) order, rebuilt from the DOM each pass. */
   #items = [];
   #index = /* @__PURE__ */ new WeakMap();
-  /** Cached bar-context width per item; see the class remarks for the staleness caveat. */
   #widths = /* @__PURE__ */ new WeakMap();
-  /** Last reported overflow count, so `change` fires only on transitions. */
   #lastHidden = null;
-  /** The `tabindex` this instance lends the root for the focus fallback. */
-  #tabindex = new TabindexLoan();
-  /** 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.
-   */
+  #pass = 0;
+  #restoring = false;
+  #tabindex = new TabindexLoan("-1", this.identifier);
+  #bar = null;
+  #wrapper = null;
   #connected = false;
+  #morphRender = new MorphRenderWatcher(() => this.#reconcile());
   connect() {
+    this.#tabindex.reclaim(this.element);
+    this.#morphRender.observe(this.element);
     this.#connected = true;
     if (!this.hasItemsTarget || !this.hasMoreTarget) return;
-    this.#beforeCache.activate();
     this.#layout.observe(this.element);
     this.#layout.observeViewport();
     this.update();
   }
   disconnect() {
+    this.#morphRender.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.
-   */
+  itemsTargetConnected() {
+    this.#followTargets();
+  }
+  itemsTargetDisconnected(bar) {
+    if (bar === this.#bar && !this.itemsTargets.includes(bar)) this.#release();
+    this.#followTargets();
+  }
+  moreTargetConnected() {
+    this.#followTargets();
+  }
+  moreTargetDisconnected(more) {
+    if (more === this.#wrapper && !this.moreTargets.includes(more)) this.#release();
+    this.#followTargets();
+  }
   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;
+    const detail = this.#render();
+    if (detail) this.dispatch("change", { detail });
+  }
+  #reconcile() {
+    const detail = this.#render();
+    if (detail) this.dispatch("reconcile", { detail });
+  }
+  #render() {
+    if (this.#restoring || !this.hasItemsTarget || !this.hasMoreTarget) return null;
+    const pass = ++this.#pass;
+    this.#bar = this.itemsTarget;
+    this.#wrapper = this.moreTarget;
     this.#syncLabel();
-    this.#syncItems();
+    this.#syncItems(this.itemsTarget, this.moreTarget);
     this.moreTarget.hidden = false;
     if (this.#items.some((item) => item.parentElement !== this.itemsTarget && !this.#widths.has(item))) {
-      this.#removeBoundary();
+      this.#removeBoundary(this.itemsTarget);
       for (const item of this.#items) this.#unbank(item);
       this.#reorder(this.itemsTarget, this.#items);
     }
     for (const item of this.#items) {
       if (item.parentElement === this.itemsTarget) this.#widths.set(item, item.offsetWidth);
     }
-    const moreWidth = (this.#trigger() ?? this.moreTarget).offsetWidth;
+    const moreWidth = (this.#trigger(this.moreTarget) ?? this.moreTarget).offsetWidth;
     const itemGap = this.#gap(this.itemsTarget);
     const barGap = this.#gap(this.element);
     const widthOf = (el) => this.#widths.get(el) ?? el.offsetWidth;
@@ -325,36 +587,39 @@ var OverflowMenuController = class extends Controller {
     }
     const active = document.activeElement instanceof HTMLElement ? document.activeElement : null;
     const focused = active === null ? null : this.#ownerOf(active);
-    const retreating = focused !== null && hidden.has(focused) && focused.parentElement === this.itemsTarget && // i.e. *starting* to retreat
-    !this.#menuExpanded();
-    const returning = focused !== null && !hidden.has(focused) && focused.parentElement !== this.itemsTarget && // i.e. *leaving* the menu
-    this.#menuExpanded();
-    if (hidden.size === 0 || hidden.size !== this.#items.length) this.#removeBoundary();
+    const retreating = focused !== null && hidden.has(focused) && focused.parentElement === this.itemsTarget &&
+    !this.#menuExpanded(this.moreTarget);
+    const returning = focused !== null && !hidden.has(focused) && focused.parentElement !== this.itemsTarget &&
+    this.#menuExpanded(this.moreTarget);
+    if (hidden.size === 0 || hidden.size !== this.#items.length) {
+      this.#removeBoundary(this.itemsTarget);
+    }
     for (const item of this.#items) {
       if (hidden.has(item)) this.#bank(item);
       else this.#unbank(item);
     }
     this.#reorder(
-      this.#menuList(),
+      this.#menuList(this.moreTarget),
       this.#items.filter((item) => hidden.has(item))
     );
     this.#reorder(
       this.itemsTarget,
       this.#items.filter((item) => !hidden.has(item))
     );
-    if (retreating) (this.#trigger() ?? this.moreTarget).focus();
+    if (retreating) (this.#trigger(this.moreTarget) ?? this.moreTarget).focus();
     else if (active !== null && this.#lostFocus(active)) active.focus();
+    if (pass !== this.#pass) return null;
     const count = hidden.size;
     for (const item of this.#items) {
       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();
     const inMore = document.activeElement instanceof HTMLElement && this.moreTarget.contains(document.activeElement);
     if (count === 0 || returning) {
-      this.#closeMenu();
-      if (inMore) this.#rescueFocus();
+      this.#closeMenu(this.moreTarget);
+      if (inMore && pass === this.#pass) this.#rescueFocus();
+      if (pass !== this.#pass) return null;
     }
     this.moreTarget.hidden = count === 0;
     if (count > 0) this.element.setAttribute("data-overflowing", "true");
@@ -362,15 +627,14 @@ var OverflowMenuController = class extends Controller {
     this.element.setAttribute("data-overflow-count", String(count));
     if (this.#lastHidden !== count) {
       this.#lastHidden = count;
-      this.dispatch("change", { detail: { overflowCount: count, total: this.#items.length } });
+      return { overflowCount: count, total: this.#items.length };
     }
+    return null;
   }
-  /** The flex `column-gap` on `el` in px (0 when none / unsupported). */
   #gap(el) {
     const style = this.#styleOf(el);
     return style === null ? 0 : this.#px(style.columnGap || style.gap);
   }
-  /** Horizontal padding on `el` in px — `clientWidth` counts it, the content box cannot. */
   #paddingX(el) {
     const style = this.#styleOf(el);
     return style === null ? 0 : this.#px(style.paddingLeft) + this.#px(style.paddingRight);
@@ -382,16 +646,11 @@ var OverflowMenuController = class extends Controller {
     const parsed = Number.parseFloat(value ?? "");
     return Number.isNaN(parsed) ? 0 : parsed;
   }
-  /**
-   * Rebuilds the managed set and the canonical order from the DOM. The bar's children
-   * give the order of everything inline (so a leading insert is not silently appended)
-   * and {@link #merge} weaves the banked items back among them.
-   */
-  #syncItems() {
+  #syncItems(row, more) {
     const previous = this.#items;
     const bar = [];
     let boundaryAt;
-    for (const el of this.itemsTarget.children) {
+    for (const el of row.children) {
       if (el instanceof HTMLTemplateElement && el.hasAttribute(this.#attr(BOUNDARY))) {
         boundaryAt ??= bar.length;
         continue;
@@ -399,7 +658,7 @@ var OverflowMenuController = class extends Controller {
       if (el instanceof HTMLElement) bar.push(el);
     }
     const banked = [];
-    for (const el of this.#menuList().children) {
+    for (const el of this.#menuList(more).children) {
       if (el instanceof HTMLElement && el.hasAttribute(this.#attr(BANKED))) banked.push(el);
     }
     banked.sort((a, b) => this.#bankedIndex(a) - this.#bankedIndex(b));
@@ -416,29 +675,6 @@ var OverflowMenuController = class extends Controller {
       this.#index.set(el, i);
     });
   }
-  /**
-   * Interleaves the banked items back among the bar's children.
-   *
-   * A saved index is a position in the *canonical* order, so it can only be compared
-   * against another canonical position — never used as an offset into the current bar,
-   * which is a shorter and differently-indexed list. (Doing so survives an untouched
-   * round trip and silently scrambles the order as soon as the consumer inserts into a
-   * bar that is already short, and `#bank()` then burns the scrambled index back into
-   * the attribute, so widening never heals it.) Each bar child the controller already
-   * knows carries its canonical index from the previous pass; a banked item goes in
-   * front of the first known child whose index is higher.
-   *
-   * Children never seen before — inserted by the consumer since the last pass — have no
-   * canonical position yet, so they keep their DOM neighbours. The exception is a
-   * *trailing* run of them: appending to the bar means appending to the toolbar, so
-   * everything banked is emitted before it.
-   *
-   * With no known child at all (a fresh instance connecting to markup that already
-   * holds banked items), a fully-banked snapshot's inert boundary preserves whether an
-   * unindexed run was prepended or appended before connect. Markup that holds banked items but no boundary —
-   * server-rendered or hand-authored — uses the saved index as the
-   * offset, the inverse of the move that banked it.
-   */
   #merge(bar, banked, boundaryAt) {
     const canonical = bar.map((el) => this.#index.get(el) ?? this.#savedIndex(el));
     let lastKnown = -1;
@@ -474,56 +710,50 @@ var OverflowMenuController = class extends Controller {
     drainWhile(() => true);
     return items;
   }
-  /** The canonical index a banked item saved, or ∞ (append) when it carries none. */
   #bankedIndex(item) {
     return this.#savedIndex(item) ?? Number.POSITIVE_INFINITY;
   }
-  /** A finite canonical index stored on either side of the overflow split. */
   #savedIndex(item) {
     const raw = item.getAttribute(this.#attr(INDEX));
     if (raw === null) return void 0;
     const value = Number(raw);
     return Number.isFinite(value) ? value : void 0;
   }
-  /** The inert split point written only when every managed item lives in More. */
-  #boundary() {
-    for (const el of this.itemsTarget.children) {
+  #boundary(bar) {
+    for (const el of bar.children) {
       if (el instanceof HTMLTemplateElement && el.hasAttribute(this.#attr(BOUNDARY))) return el;
     }
     return null;
   }
   #ensureBoundary() {
-    if (this.#boundary() !== null) return;
+    if (this.#boundary(this.itemsTarget) !== null) return;
     const boundary = document.createElement("template");
     boundary.setAttribute(this.#attr(BOUNDARY), "");
     this.itemsTarget.appendChild(boundary);
   }
-  #removeBoundary() {
-    this.#boundary()?.remove();
+  #removeBoundary(bar) {
+    this.#boundary(bar)?.remove();
   }
-  /** Debounced re-measure for resize-driven churn. */
   #scheduleUpdate() {
     this.#timers.clearAll();
-    this.#timers.set(() => this.update(), this.debounceValue);
-  }
-  /** Returns the menu list the items are banked into (falls back to the More wrapper). */
-  #menuList() {
-    return this.moreTarget.querySelector('[data-stimeo--menu-target="menu"]') ?? this.moreTarget;
-  }
-  #trigger() {
-    return this.moreTarget.querySelector('[data-stimeo--menu-target="trigger"]');
-  }
-  /**
-   * 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
-   */
+    this.#timers.set(() => this.update(), this.#safeDebounce);
+  }
+  #followTargets() {
+    if (this.#restoring || this.#lastHidden === null) return;
+    const bar = this.hasItemsTarget ? this.itemsTarget : null;
+    const more = this.hasMoreTarget ? this.moreTarget : null;
+    if (bar === this.#bar && more === this.#wrapper) return;
+    this.#release();
+    this.#morphRender.schedule();
+  }
+  #menuList(more) {
+    return more.querySelector('[data-stimeo--menu-target="menu"]') ?? more;
+  }
+  #trigger(more) {
+    return more.querySelector('[data-stimeo--menu-target="trigger"]');
+  }
   #syncLabel() {
-    const trigger = this.#trigger();
+    const trigger = this.#trigger(this.moreTarget);
     if (trigger === null) return;
     const owned = this.#ownsLabel(trigger);
     if (!owned && !this.#isBareTrigger(trigger)) return;
@@ -532,93 +762,43 @@ var OverflowMenuController = class extends Controller {
       this.#releaseLabel(trigger);
       return;
     }
-    if (owned && trigger.textContent === label) return;
-    trigger.textContent = label;
-    trigger.setAttribute(this.#attr(OWNED_LABEL), label);
+    this.#labelText.write(trigger, 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);
+    return this.#labelText.owns(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.
-   */
+    this.#labelText.clear(trigger);
+  }
   #isBareTrigger(trigger) {
     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
-   * trigger's `aria-expanded`, so read the contract rather than guess from `hidden`
-   * (which is absent until Menu connects).
-   */
-  #menuExpanded() {
-    return this.#trigger()?.getAttribute("aria-expanded") === "true";
-  }
-  /**
-   * Collapses the More menu before its wrapper is hidden. Menu owns the state (and the
-   * Escape-stack membership that goes with it), so ask it; the DOM fallback covers markup
-   * that reached an expanded state with no Menu mounted.
-   */
-  #closeMenu() {
-    if (!this.#menuExpanded()) return;
+  #menuExpanded(more) {
+    return this.#trigger(more)?.getAttribute("aria-expanded") === "true";
+  }
+  #closeMenu(more) {
+    if (!this.#menuExpanded(more)) return;
     const menu = this.application.getControllerForElementAndIdentifier(
-      this.moreTarget,
+      more,
       "stimeo--menu"
     );
     if (menu) {
       menu.close();
       return;
     }
-    this.#trigger()?.setAttribute("aria-expanded", "false");
-    const list = this.#menuList();
-    if (list !== this.moreTarget) list.hidden = true;
+    this.#trigger(more)?.setAttribute("aria-expanded", "false");
+    const list = this.#menuList(more);
+    if (list !== more) list.hidden = true;
   }
-  /** The managed item that is, or contains, `el` — focus rescue works on either. */
   #ownerOf(el) {
     return ownerOf(this.#items, el);
   }
-  /** Whether the item takes up room in the bar; an authored `hidden` one does not. */
   #rendered(item) {
     return !item.hasAttribute("hidden");
   }
-  /**
-   * Moves focus out of the More wrapper just before it is hidden, to the last
-   * item in canonical order that can hold it. When every item refuses, the root
-   * takes focus instead of letting the browser drop it to `<body>`, borrowing a
-   * `tabindex="-1"` just-in-time — not a Tab stop, and handed back on restore
-   * when this controller was the one that added it.
-   */
   #rescueFocus() {
     for (let i = this.#items.length - 1; i >= 0; i--) {
       const item = this.#items[i];
@@ -630,38 +810,38 @@ var OverflowMenuController = class extends Controller {
     this.#tabindex.lend(this.element);
     this.element.focus();
   }
-  /**
-   * Whether `el` held focus, is still in a visible part of this controller, and lost it —
-   * what a re-insert does in a real browser. An item that retreated into a collapsed menu
-   * is excluded: it sits in a `hidden` subtree and must not be focused back.
-   */
   #lostFocus(el) {
     return el.isConnected && document.activeElement !== el && this.element.contains(el) && el.closest("[hidden]") === null;
   }
-  /** Returns every item to the bar and removes all traces of this controller. */
   #restoreAll() {
     if (!this.hasItemsTarget || !this.hasMoreTarget) return;
-    this.#syncItems();
-    this.#removeBoundary();
-    this.#reorder(this.itemsTarget, this.#items);
+    this.#giveBack(this.itemsTarget, this.moreTarget);
+  }
+  #release() {
+    if (this.#bar && this.#wrapper) this.#giveBack(this.#bar, this.#wrapper);
+  }
+  #giveBack(bar, more) {
+    this.#bar = null;
+    this.#wrapper = null;
+    const restoring = this.#restoring;
+    this.#restoring = true;
+    this.#pass++;
+    this.#syncItems(bar, more);
+    this.#removeBoundary(bar);
+    this.#reorder(bar, this.#items);
     for (const item of this.#items) {
       this.#unbank(item);
       item.removeAttribute(this.#attr(INDEX));
     }
-    this.#closeMenu();
-    const trigger = this.#trigger();
+    this.#closeMenu(more);
+    const trigger = this.#trigger(more);
     if (trigger !== null) this.#releaseLabel(trigger);
-    this.moreTarget.hidden = true;
+    more.hidden = true;
     this.element.removeAttribute("data-overflowing");
     this.element.removeAttribute("data-overflow-count");
     this.#tabindex.returnAll();
+    this.#restoring = restoring;
   }
-  /**
-   * Makes `parent`'s managed children match `sequence`, moving only what is out of place.
-   * Walking backwards lets each item be compared against the element that should follow
-   * it, so an unchanged run costs zero DOM mutations — the point of the exercise, since
-   * every re-insert blurs the focused node.
-   */
   #reorder(parent, sequence) {
     let next = null;
     for (let i = sequence.length - 1; i >= 0; i--) {
@@ -673,7 +853,6 @@ var OverflowMenuController = class extends Controller {
       next = item;
     }
   }
-  /** Relocates `item`, preferring `moveBefore` (keeps focus and element state). */
   #insert(parent, item, before) {
     const move = parent.moveBefore;
     if (typeof move === "function") {
@@ -685,10 +864,6 @@ var OverflowMenuController = class extends Controller {
     }
     parent.insertBefore(item, before);
   }
-  /**
-   * Gives an item menuitem semantics for Menu to drive and records its canonical index,
-   * saving every authored value it overwrites ("" means the attribute was absent).
-   */
   #bank(item) {
     if (!item.hasAttribute(this.#attr(BANKED))) {
       item.setAttribute(this.#attr(BANKED), "true");
@@ -701,7 +876,6 @@ var OverflowMenuController = class extends Controller {
     }
     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(this.#attr(BANKED))) return;
     this.#restoreAttr(item, "role", item.getAttribute(this.#attr(SAVED_ROLE)));
@@ -709,7 +883,6 @@ var OverflowMenuController = class extends Controller {
     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) {
     if (original === null || original === "") item.removeAttribute(name);
     else item.setAttribute(name, original);
@@ -717,20 +890,22 @@ var OverflowMenuController = class extends Controller {
   #indexOf(item) {
     return this.#index.get(item) ?? 0;
   }
-  /**
-   * Retention rank: lower keeps longer. An absent, empty, or non-numeric `data-priority`
-   * ranks lowest (drops first) — empty is the common ERB accident
-   * (`data-priority="<%= maybe_nil %>"`), and `Number("")` is 0, which would otherwise
-   * read as the *highest* retention.
-   */
   #rank(item) {
     const raw = item.getAttribute("data-priority");
     if (raw === null || raw.trim() === "") return Number.POSITIVE_INFINITY;
     const value = Number(raw);
     return Number.isNaN(value) ? Number.POSITIVE_INFINITY : value;
   }
+  get #safeDebounce() {
+    return this.#numbers.read(
+      this,
+      "debounce",
+      this.debounceValue,
+      _OverflowMenuController.values.debounce.default,
+      _OverflowMenuController.valueConstraints.debounce
+    );
+  }
 };
 
 export { OverflowMenuController };
-//# sourceMappingURL=overflow_menu_controller.js.map
 //# sourceMappingURL=overflow_menu_controller.js.map