stimeo-ui 0.15.0 → 0.16.0

data/dist/controllers/listbox_controller.js

@@ -8,6 +8,16 @@ function isReservedArrowChord(event, allow = []) {
   return event.altKey && !allow.includes("alt") || event.ctrlKey && !allow.includes("ctrl") || event.metaKey && !allow.includes("meta") || event.shiftKey && !allow.includes("shift");
 }
 
+// src/utils/field_mirror.ts
+function writeField(field, value) {
+  if (field.value === value) return false;
+  field.value = value;
+  return true;
+}
+function commitField(target) {
+  target.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
 // src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
@@ -165,45 +175,79 @@ function findTypeaheadMatch(items, from, query, label = (item) => typeaheadLabel
 }
 
 // src/controllers/listbox_controller.ts
+var OBSERVED_ATTRIBUTES = ["aria-selected", "data-value"];
+function setAttributeIfChanged(element, name, value) {
+  if (element.getAttribute(name) !== value) element.setAttribute(name, value);
+}
 var ListboxController = class extends Controller {
   static targets = ["trigger", "value", "list", "option", "field"];
+  static values = {
+    placeholder: { type: String, default: "" }
+  };
   static actions = ["close", "onTriggerKeydown", "open", "select", "toggle"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   /** Stable ID of the active option; DOM targets are resolved afresh before use. */
   #activeId = null;
   /** Target ID order captured while an option is active, used only for removal fallback. */
   #activeOrder = [];
-  #connected = false;
-  /** Collapses one mutation batch of target callbacks into a single pass. */
-  #reconcile = new MicrotaskCoalescer(() => this.#reconcileActive());
+  /**
+   * Collapses the target callbacks, Value changes and observed option writes of
+   * one DOM mutation into a single pass; refused before `connect()` and after
+   * `disconnect()`.
+   */
+  #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());
+  /** Watches the option attributes a page can rewrite in place; set while connected. */
+  #observer = null;
+  /** The selection last settled: on connect, by the user, or by a reported pass. */
+  #settled = { option: null, value: "" };
   /** Accumulated typeahead query and its idle-reset timer. */
   #typeahead = new Typeahead();
-  /** Establishes the ARIA baseline, starts closed, and listens for outside clicks. */
+  /**
+   * Establishes the ARIA baseline, settles the selection without reporting it,
+   * starts closed, and listens for outside clicks.
+   */
   connect() {
     this.#normalizeSelection();
     this.close();
     document.addEventListener("click", this.#onOutsideClick, true);
-    this.#connected = true;
+    this.#settled = this.#selection();
     this.#reconcile.activate();
+    this.#observeOptions();
   }
   /**
-   * Establishes an inactive baseline for a late option, re-resolves active
-   * identity, and re-applies the selection baseline.
+   * Establishes an inactive baseline for a late option, then re-applies the
+   * selection baseline and re-resolves active identity once the batch is in.
    */
   optionTargetConnected(option) {
     option.removeAttribute("data-active");
-    if (!this.#connected) return;
-    this.#normalizeSelection();
-    this.#queueOptionReconciliation();
+    this.#reconcile.schedule();
   }
-  /** Removes controller-owned active state and reconciles the surviving targets. */
+  /**
+   * Removes controller-owned active state, then settles the selection and the
+   * active option among the surviving targets once the batch is in.
+   */
   optionTargetDisconnected(option) {
     option.removeAttribute("data-active");
-    if (this.#connected) this.#queueOptionReconciliation();
+    this.#reconcile.schedule();
+  }
+  /** Fills a form field inserted or replaced at runtime with the current selection. */
+  fieldTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /** Writes the current selection into a trigger value inserted or replaced at runtime. */
+  valueTargetConnected() {
+    this.#reconcile.schedule();
+  }
+  /**
+   * Re-renders the empty-selection label when application code (or a Turbo morph)
+   * changes `placeholder` at runtime.
+   */
+  placeholderValueChanged() {
+    this.#reconcile.schedule();
   }
   /**
    * Brings the authored DOM to the shape the APG requires, and derives the state
-   * that follows from the initial selection.
+   * that follows from the selection.
    *
    * Three things happen, and only these three — which option is chosen is the
    * author's, and is never changed:
@@ -212,27 +256,59 @@ var ListboxController = class extends Controller {
    *    selectable" in ARIA, so a forgotten attribute hides a selectable option
    *    from assistive technology.
    * 2. At most one stays `true`. The first in DOM order wins, since that is the
-   *    only deterministic reading of "which one did the author mean".
-   * 3. The trigger label and the hidden field are derived from that selection.
-   *    Without this the widget announces a choice it does not submit: the popup
-   *    says "Banana", the trigger still says "Choose…", and the form posts "".
+   *    only deterministic reading of "which one did the author mean"; an option
+   *    the page inserts ahead of the selection, already selected, takes it over.
+   * 3. The trigger label and the hidden field are derived from that selection,
+   *    an empty one included. Without this the widget announces a choice it does
+   *    not submit: the popup says "Banana", the trigger still says "Choose…", and
+   *    the form posts "".
    *
-   * No `change` fires — nothing changed, this is the initial state being told
-   * properly. The scan is the `option` target set: a `role="option"` without the
-   * target is outside the contract and is neither counted nor written.
+   * Nothing is reported here: `connect()` describes the initial state, and a
+   * page-driven pass reports a moved selection itself. The scan is the `option`
+   * target set: a `role="option"` without the target is outside the contract and
+   * is neither counted nor written.
    */
   #normalizeSelection() {
-    const options = this.optionTargets;
-    const selected = options.find((option) => option.getAttribute("aria-selected") === "true");
-    for (const option of options) {
-      option.setAttribute("aria-selected", option === selected ? "true" : "false");
-    }
-    if (selected) this.#applySelection(selected);
+    const selected = this.optionTargets.find(
+      (option) => option.getAttribute("aria-selected") === "true"
+    );
+    this.#applySelection(selected);
+  }
+  /**
+   * The pass the page's changes run: the selection is normalized and mirrored,
+   * the active option re-resolved, then a selection that moved is reported. The
+   * report comes last, so options a subscriber rewrites are the next pass's to
+   * settle.
+   */
+  #reconcileOptions() {
+    this.#normalizeSelection();
+    this.#reconcileActive();
+    this.#reportMove();
   }
-  /** Removes the document listener and clears the typeahead timer. */
+  /**
+   * Reports the selection as `reconcile` when its option or value differs from the
+   * selection last settled. The settled selection is replaced before dispatching,
+   * so a move a subscriber makes is measured against what it was told.
+   */
+  #reportMove() {
+    const { option, value } = this.#selection();
+    if (option === this.#settled.option && value === this.#settled.value) return;
+    this.#settled = { option, value };
+    this.dispatch("reconcile", { detail: { value, option } });
+  }
+  /** The selected option target, if any, and the value its field submits. */
+  #selection() {
+    const option = this.optionTargets.find((candidate) => candidate.getAttribute("aria-selected") === "true") ?? null;
+    return { option, value: option ? this.#optionValue(option) : "" };
+  }
+  /**
+   * Releases the outside-click listener and the option observer, drops a queued
+   * pass, and clears the typeahead timer.
+   */
   disconnect() {
-    this.#connected = false;
     this.#reconcile.cancel();
+    this.#observer?.disconnect();
+    this.#observer = null;
     document.removeEventListener("click", this.#onOutsideClick, true);
     this.#typeahead.reset();
   }
@@ -354,27 +430,113 @@ var ListboxController = class extends Controller {
   /** Applies selection: `aria-selected`, trigger label, hidden field, `change`. */
   #selectOption(option) {
     const { value, fieldChanged } = this.#applySelection(option);
-    if (fieldChanged) {
-      this.fieldTarget.dispatchEvent(new Event("change", { bubbles: true }));
-    }
+    this.#settled = { option, value };
+    if (fieldChanged) commitField(this.fieldTarget);
     this.dispatch("change", { detail: { value, option } });
   }
   /**
-   * Writes `option` into `aria-selected`, the trigger label and the hidden field.
-   * Emits nothing — {@link #normalizeSelection} reuses this at connect, where the
-   * state is being described rather than changed.
+   * Writes `option` — or, when it is `undefined`, no selection — into
+   * `aria-selected`, the trigger label and the hidden field. Emits nothing: the
+   * user's commit and a page-driven pass each report it their own way, and
+   * `connect()` only describes the state it finds.
    */
   #applySelection(option) {
     for (const candidate of this.optionTargets) {
-      candidate.setAttribute("aria-selected", candidate === option ? "true" : "false");
+      setAttributeIfChanged(candidate, "aria-selected", candidate === option ? "true" : "false");
     }
-    const label = (option.textContent ?? "").trim();
-    const value = option.dataset.value ?? label;
-    if (this.hasValueTarget) this.valueTarget.textContent = label;
-    const fieldChanged = this.hasFieldTarget && this.fieldTarget.value !== value;
-    if (fieldChanged) this.fieldTarget.value = value;
+    this.#dropOwnRecords();
+    const value = option ? this.#optionValue(option) : "";
+    this.#renderLabel(option);
+    const fieldChanged = this.hasFieldTarget && writeField(this.fieldTarget, value);
     return { value, fieldChanged };
   }
+  /**
+   * Keeps the trigger value on the selection: the selected option's text, or, with
+   * nothing selected, `placeholder` when it is set, else the text the value held
+   * before this controller first wrote into it.
+   *
+   * The value is this controller's only while it holds the text last written into
+   * it and nothing else — the `owns-label` marker carries that text — and the text
+   * it held before is kept in the `original-label` marker. A value the page
+   * rewrote or added an element to after that — the marker is still there but no
+   * longer matches — is the page's: with nothing selected it is left exactly as it
+   * is, `placeholder` or not, and the next selection remembers its text before
+   * replacing it. A value with no marker at all — the author's, or one a morph put
+   * back without the markers — is taken over the same way by `placeholder` or by a
+   * selection. A value that only ever showed a selection has no text of its own to
+   * return to, so it is emptied rather than left naming an option that is not
+   * selected.
+   *
+   * @stimeoRenderRoot
+   */
+  #renderLabel(option) {
+    if (!this.hasValueTarget) return;
+    const label = this.valueTarget;
+    const ownsLabel = `data-${this.identifier}-owns-label`;
+    const originalLabel = `data-${this.identifier}-original-label`;
+    const owned = label.getAttribute(ownsLabel) === label.textContent && label.childElementCount === 0;
+    if (option === void 0 && !owned && label.hasAttribute(ownsLabel)) return;
+    const text = option ? this.#optionLabel(option) : this.placeholderValue || null;
+    if (text === null) {
+      if (!owned) return;
+      label.textContent = label.getAttribute(originalLabel) ?? "";
+      label.removeAttribute(ownsLabel);
+      label.removeAttribute(originalLabel);
+      return;
+    }
+    if (!owned) {
+      const current = (label.textContent ?? "").trim();
+      if (option === void 0 || current !== text) {
+        setAttributeIfChanged(label, originalLabel, current);
+      }
+    }
+    if (label.textContent !== text) label.textContent = text;
+    setAttributeIfChanged(label, ownsLabel, text);
+  }
+  /** An option's visible label: its own text, trimmed. */
+  #optionLabel(option) {
+    return (option.textContent ?? "").trim();
+  }
+  /** The value an option submits: its `data-value`, else its label. */
+  #optionValue(option) {
+    return option.dataset.value ?? this.#optionLabel(option);
+  }
+  /**
+   * Watches the options' `aria-selected` and `data-value`. The listbox's own writes
+   * to them are dropped from the queue as they happen, so each record the callback
+   * receives is the page's, and only a record on one of the listbox's own options
+   * schedules a pass.
+   */
+  #observeOptions() {
+    const observer = new MutationObserver((records) => {
+      if (this.#concernsOptions(records)) this.#reconcile.schedule();
+    });
+    observer.observe(this.element, {
+      subtree: true,
+      attributes: true,
+      attributeFilter: OBSERVED_ATTRIBUTES
+    });
+    this.#observer = observer;
+  }
+  /**
+   * Whether any record is about one of this listbox's own options. A widget nested
+   * inside it writes the same attributes on its own elements, and those are no
+   * reason to reconcile the listbox.
+   */
+  #concernsOptions(records) {
+    const options = new Set(this.optionTargets);
+    return records.some((record) => options.has(record.target));
+  }
+  /**
+   * Drops the records the listbox's own writes just queued, so the observer never
+   * takes them for the page's. A page write queued just before goes with them and
+   * owes nothing: every such write leaves every option's `aria-selected` at the
+   * value the selection gives it, and the selection is then read back from the DOM,
+   * so it already holds what the page wrote.
+   */
+  #dropOwnRecords() {
+    this.#observer?.takeRecords();
+  }
   /**
    * Marks the option at `index` active via `data-active` and the trigger's
    * `aria-activedescendant`. Pass `-1` to clear it (the attribute is removed, not
@@ -444,10 +606,6 @@ var ListboxController = class extends Controller {
     }
     return -1;
   }
-  /** Coalesces all target callbacks from one MutationObserver batch. */
-  #queueOptionReconciliation() {
-    this.#reconcile.schedule();
-  }
   /**
    * Advances the typeahead query and activates the next matching option.
    *

data/dist/controllers/masonry_controller.js

@@ -215,8 +215,6 @@ var MasonryController = class extends Controller {
    * once per pass. The assignment is independent of the measurement because the
    * columns are uniform in width, so the order of the two passes does not change
    * the result.
-   *
-   * @stimeoRenderRoot
    */
   #relayout() {
     const items = this.itemTargets;

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();
   }