stimeo-ui 0.2.0 → 0.3.0

package/dist/controllers/overflow_menu_controller.js

@@ -2,6 +2,23 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/overflow_menu_controller.ts
 
+// src/utils/focus_candidate.ts
+function inheritsFieldsetDisabled(control) {
+  let fieldset = control.closest("fieldset[disabled]");
+  while (fieldset) {
+    const legend = Array.from(fieldset.children).find((child) => child.tagName === "LEGEND");
+    if (!legend?.contains(control)) return true;
+    fieldset = fieldset.parentElement?.closest("fieldset[disabled]") ?? null;
+  }
+  return false;
+}
+function canTakeFocus(element) {
+  if (element.closest("[hidden]")) return false;
+  if (!("disabled" in element)) return true;
+  if (element.disabled) return false;
+  return !inheritsFieldsetDisabled(element);
+}
+
 // src/utils/layout_observer.ts
 var LayoutObserver = class {
   #callback;
@@ -111,7 +128,42 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/tabindex_loan.ts
+var TabindexLoan = class {
+  #value;
+  #lent = /* @__PURE__ */ new Set();
+  /**
+   * @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") {
+    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.#lent.add(element);
+  }
+  /** 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");
+    }
+    this.#lent.clear();
+  }
+};
+
 // 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-menu-target";
+var MENU_TARGET = "data-stimeo--menu-target";
+var BOOKKEEPING = [BANKED, INDEX, SAVED_ROLE, SAVED_TABINDEX, SAVED_MENU_TARGET];
 var OverflowMenuController = class extends Controller {
   static targets = ["items", "more"];
   static values = {
@@ -122,24 +174,26 @@ var OverflowMenuController = class extends Controller {
   static events = ["change"];
   #layout = new LayoutObserver(() => this.#scheduleUpdate());
   #timers = new SafeTimeout();
-  /** The managed items in canonical (authored) order, captured at connect. */
+  /** The managed items in canonical (authored) order, rebuilt from the DOM each pass. */
   #items = [];
   #index = /* @__PURE__ */ new WeakMap();
-  /**
-   * Cached bar-context width per item. An item's natural width is location-independent,
-   * so this lets a measure pass read only the items currently in the bar (menu items
-   * reuse their last value) instead of pulling everything back to measure — one reflow,
-   * not two.
-   */
+  /** 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 pristine snapshot: the cache is written after this event. */
+  #onBeforeCache = () => {
+    this.#restoreAll();
+  };
   connect() {
     if (!this.hasItemsTarget || !this.hasMoreTarget) return;
     const trigger = this.#trigger();
-    if (trigger && (trigger.textContent ?? "").trim() === "") {
+    if (trigger !== null && this.#isBareTrigger(trigger)) {
       trigger.textContent = this.moreLabelValue;
     }
+    document.addEventListener("turbo:before-cache", this.#onBeforeCache);
     this.#layout.observe(this.element);
     this.#layout.observeViewport();
     this.update();
@@ -147,6 +201,8 @@ var OverflowMenuController = class extends Controller {
   disconnect() {
     this.#layout.disconnect();
     this.#timers.clearAll();
+    document.removeEventListener("turbo:before-cache", this.#onBeforeCache);
+    this.#restoreAll();
     this.#lastHidden = null;
   }
   /** Re-measures and rebalances items between the bar and the More menu. */
@@ -154,36 +210,67 @@ var OverflowMenuController = class extends Controller {
     if (!this.hasItemsTarget || !this.hasMoreTarget) return;
     this.#syncItems();
     this.moreTarget.hidden = false;
+    if (this.#items.some((item) => item.parentElement !== this.itemsTarget && !this.#widths.has(item))) {
+      this.#removeBoundary();
+      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 gap = this.#gap();
+    const itemGap = this.#gap(this.itemsTarget);
+    const barGap = this.#gap(this.element);
     const widthOf = (el) => this.#widths.get(el) ?? el.offsetWidth;
-    const containerWidth = this.element.clientWidth;
-    const itemsWidth = this.#items.reduce((sum, el) => sum + widthOf(el), 0);
-    let visibleWidth = itemsWidth + Math.max(0, this.#items.length - 1) * gap;
+    const containerWidth = this.element.clientWidth - this.#paddingX(this.element);
+    const rendered = this.#items.filter((item) => this.#rendered(item));
+    const itemsWidth = rendered.reduce((sum, el) => sum + widthOf(el), 0);
+    let visibleWidth = itemsWidth + Math.max(0, rendered.length - 1) * itemGap;
     const hidden = /* @__PURE__ */ new Set();
     if (visibleWidth > containerWidth) {
-      const budget = containerWidth - moreWidth - gap;
-      const dropOrder = [...this.#items].sort(
+      const budget = containerWidth - moreWidth - barGap;
+      const dropOrder = [...rendered].sort(
         (a, b) => this.#rank(b) - this.#rank(a) || this.#indexOf(b) - this.#indexOf(a)
       );
       for (const item of dropOrder) {
         if (visibleWidth <= budget) break;
         hidden.add(item);
-        visibleWidth -= widthOf(item) + gap;
+        visibleWidth -= widthOf(item) + itemGap;
       }
     }
-    const menu = this.#menuList();
-    const active = document.activeElement;
-    const refocusTrigger = active instanceof HTMLElement && hidden.has(active);
+    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();
     for (const item of this.#items) {
-      if (hidden.has(item)) this.#toMenu(item, menu);
-      else this.#toBar(item);
+      if (hidden.has(item)) this.#bank(item);
+      else this.#unbank(item);
     }
-    if (refocusTrigger) this.#trigger()?.focus();
+    this.#reorder(
+      this.#menuList(),
+      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();
+    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 && 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.moreTarget.hidden = count === 0;
     if (count > 0) this.element.setAttribute("data-overflowing", "true");
     else this.element.removeAttribute("data-overflowing");
@@ -193,30 +280,142 @@ var OverflowMenuController = class extends Controller {
       this.dispatch("change", { detail: { visible: this.#items.length - count, hidden: count } });
     }
   }
-  /** The flex `column-gap` between items in px (0 when none / unsupported). */
-  #gap() {
-    if (typeof window.getComputedStyle !== "function") return 0;
-    const style = window.getComputedStyle(this.itemsTarget);
-    const value = Number.parseFloat(style.columnGap || style.gap || "");
-    return Number.isNaN(value) ? 0 : value;
+  /** 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);
+  }
+  #styleOf(el) {
+    return typeof window.getComputedStyle === "function" ? window.getComputedStyle(el) : null;
+  }
+  #px(value) {
+    const parsed = Number.parseFloat(value ?? "");
+    return Number.isNaN(parsed) ? 0 : parsed;
   }
   /**
-   * Reconciles the managed item set with the DOM each pass: adopts items appended to the
-   * bar since last time (so the documented "add items, then call `update`" flow works)
-   * and drops any the consumer removed, then renumbers canonical indices. Banked items
-   * live in the menu (still within the controller element) and are retained.
+   * 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() {
-    const known = new Set(this.#items);
+    const previous = this.#items;
+    const bar = [];
+    let boundaryAt;
     for (const el of this.itemsTarget.children) {
-      if (el instanceof HTMLElement && !known.has(el)) this.#items.push(el);
+      if (el instanceof HTMLTemplateElement && el.hasAttribute(BOUNDARY)) {
+        boundaryAt ??= bar.length;
+        continue;
+      }
+      if (el instanceof HTMLElement) bar.push(el);
     }
-    this.#items = this.#items.filter((el) => this.element.contains(el));
+    const banked = [];
+    for (const el of this.#menuList().children) {
+      if (el instanceof HTMLElement && el.hasAttribute(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);
+      }
+    }
+    this.#items = items;
     this.#index = /* @__PURE__ */ new WeakMap();
-    this.#items.forEach((el, i) => {
+    items.forEach((el, i) => {
       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. Older or server-rendered
+   * markup has no boundary; for that compatibility path the saved index is used 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;
+    canonical.forEach((index, i) => {
+      if (index !== void 0) lastKnown = i;
+    });
+    if (lastKnown === -1) {
+      if (boundaryAt !== void 0) {
+        return [...bar.slice(0, boundaryAt), ...banked, ...bar.slice(boundaryAt)];
+      }
+      const restored = [...bar];
+      for (const item of banked) {
+        restored.splice(Math.min(this.#bankedIndex(item), restored.length), 0, item);
+      }
+      return restored;
+    }
+    const items = [];
+    let next = 0;
+    const drainWhile = (accept) => {
+      while (next < banked.length) {
+        const item = banked[next];
+        if (item === void 0 || !accept(this.#bankedIndex(item))) break;
+        items.push(item);
+        next++;
+      }
+    };
+    bar.forEach((el, i) => {
+      const index = canonical[i];
+      if (index !== void 0) drainWhile((saved) => saved < index);
+      else if (i > lastKnown) drainWhile(() => true);
+      items.push(el);
+    });
+    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(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) {
+      if (el instanceof HTMLTemplateElement && el.hasAttribute(BOUNDARY)) return el;
+    }
+    return null;
+  }
+  #ensureBoundary() {
+    if (this.#boundary() !== null) return;
+    const boundary = document.createElement("template");
+    boundary.setAttribute(BOUNDARY, "");
+    this.itemsTarget.appendChild(boundary);
+  }
+  #removeBoundary() {
+    this.#boundary()?.remove();
+  }
   /** Debounced re-measure for resize-driven churn. */
   #scheduleUpdate() {
     this.#timers.clearAll();
@@ -229,41 +428,166 @@ var OverflowMenuController = class extends Controller {
   #trigger() {
     return this.moreTarget.querySelector('[data-stimeo--menu-target="trigger"]');
   }
-  /** Restores an item to the bar, stripping the menu semantics we may have added. */
-  #toBar(item) {
-    this.itemsTarget.appendChild(item);
-    if (item.dataset.overflowMenuized === void 0) return;
-    item.removeAttribute("data-stimeo--menu-target");
-    this.#restoreAttr(item, "role", item.dataset.overflowOrigRole);
-    this.#restoreAttr(item, "tabindex", item.dataset.overflowOrigTabindex);
-    delete item.dataset.overflowMenuized;
-    delete item.dataset.overflowOrigRole;
-    delete item.dataset.overflowOrigTabindex;
-  }
-  /** Banks an item into the menu with menuitem semantics for Menu to manage. */
-  #toMenu(item, menu) {
-    if (item.dataset.overflowMenuized === void 0) {
-      item.dataset.overflowMenuized = "true";
-      item.dataset.overflowOrigRole = item.getAttribute("role") ?? "";
-      item.dataset.overflowOrigTabindex = item.getAttribute("tabindex") ?? "";
+  /**
+   * 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.
+   */
+  #isBareTrigger(trigger) {
+    return (trigger.textContent ?? "").trim() === "" && 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;
+    const menu = this.application.getControllerForElementAndIdentifier(
+      this.moreTarget,
+      "stimeo--menu"
+    );
+    if (menu) {
+      menu.close();
+      return;
+    }
+    this.#trigger()?.setAttribute("aria-expanded", "false");
+    const list = this.#menuList();
+    if (list !== this.moreTarget) list.hidden = true;
+  }
+  /** The managed item that is, or contains, `el` — focus rescue works on either. */
+  #ownerOf(el) {
+    return this.#items.find((item) => item === el || item.contains(el)) ?? null;
+  }
+  /** 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];
+      if (item !== void 0 && canTakeFocus(item)) {
+        item.focus();
+        return;
+      }
+    }
+    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);
+    for (const item of this.#items) {
+      this.#unbank(item);
+      item.removeAttribute(INDEX);
+    }
+    this.#closeMenu();
+    this.moreTarget.hidden = true;
+    this.element.removeAttribute("data-overflowing");
+    this.element.removeAttribute("data-overflow-count");
+    this.#tabindex.returnAll();
+  }
+  /**
+   * 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--) {
+      const item = sequence[i];
+      if (item === void 0) continue;
+      if (item.parentElement !== parent || item.nextElementSibling !== next) {
+        this.#insert(parent, item, next);
+      }
+      next = item;
+    }
+  }
+  /** Relocates `item`, preferring `moveBefore` (keeps focus and element state). */
+  #insert(parent, item, before) {
+    const move = parent.moveBefore;
+    if (typeof move === "function") {
+      try {
+        move.call(parent, item, before);
+        return;
+      } catch {
+      }
+    }
+    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(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) ?? "");
       item.setAttribute("role", "menuitem");
       item.setAttribute("tabindex", "-1");
-      item.setAttribute("data-stimeo--menu-target", "item");
+      item.setAttribute(MENU_TARGET, "item");
     }
-    menu.appendChild(item);
+    item.setAttribute(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);
   }
   /** Re-applies a saved attribute value, or removes the attribute when it was absent. */
   #restoreAttr(item, name, original) {
-    if (original === void 0 || original === "") item.removeAttribute(name);
+    if (original === null || original === "") item.removeAttribute(name);
     else item.setAttribute(name, original);
   }
   #indexOf(item) {
     return this.#index.get(item) ?? 0;
   }
-  /** Retention rank: lower keeps longer; no `data-priority` ranks lowest (drops first). */
+  /**
+   * 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) return Number.POSITIVE_INFINITY;
+    if (raw === null || raw.trim() === "") return Number.POSITIVE_INFINITY;
     const value = Number(raw);
     return Number.isNaN(value) ? Number.POSITIVE_INFINITY : value;
   }