stimeo-ui 0.14.0 → 0.16.0

data/dist/controllers/toggle_group_controller.js

@@ -29,6 +29,29 @@ function ownerOf(candidates, node) {
   return candidates[ownerIndex(candidates, node)] ?? null;
 }
 
+// src/utils/field_mirror.ts
+function writeFields(container, values, { name, form = "" }) {
+  const current = [...container.children];
+  const submits = current.length === values.length && current.every(
+    (child, index) => child instanceof HTMLInputElement && child.type === "hidden" && child.value === values[index] && child.name === name && (child.getAttribute("form") ?? "") === form
+  );
+  if (submits) return false;
+  container.replaceChildren(
+    ...values.map((value) => {
+      const input = document.createElement("input");
+      input.type = "hidden";
+      input.name = name;
+      input.value = value;
+      if (form !== "") input.setAttribute("form", form);
+      return input;
+    })
+  );
+  return true;
+}
+function commitField(target) {
+  target.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
 // src/utils/focus_candidate.ts
 function inheritsFieldsetDisabled(control) {
   let fieldset = control.closest("fieldset[disabled]");
@@ -57,6 +80,39 @@ function isInteractiveHost(element) {
   return false;
 }
 
+// src/utils/microtask_coalescer.ts
+var MicrotaskCoalescer = class {
+  #run;
+  #queued = false;
+  #active = false;
+  #generation = 0;
+  /** @param run - the single reconciliation pass, invoked at most once per batch. */
+  constructor(run) {
+    this.#run = run;
+  }
+  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
+  activate() {
+    this.#active = true;
+  }
+  /** Closes the window and drops any pending pass; call from `disconnect()`. */
+  cancel() {
+    this.#active = false;
+    this.#queued = false;
+    this.#generation += 1;
+  }
+  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
+  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();
+    });
+  }
+};
+
 // src/utils/roving_tabindex.ts
 var RovingTabindex = class {
   /** Returns the current ordered item elements; called on every operation. */
@@ -100,6 +156,7 @@ function rovingMove(current, length, delta, wrap) {
 // src/controllers/toggle_group_controller.ts
 var ITEM_ATTRIBUTES = [
   "aria-pressed",
+  "data-value",
   "disabled",
   "hidden",
   "type",
@@ -109,24 +166,37 @@ var ITEM_ATTRIBUTES = [
 ];
 var hasModifier = (event) => event.altKey || event.ctrlKey || event.metaKey || event.shiftKey;
 var ToggleGroupController = class extends Controller {
-  static targets = ["item"];
+  static targets = ["item", "fields"];
   static values = {
-    mode: { type: String, default: "multiple" }
+    mode: { type: String, default: "multiple" },
+    name: { type: String, default: "values[]" },
+    form: { type: String, default: "" }
   };
   static actions = ["onKeydown", "toggle"];
-  static events = ["change"];
+  static events = ["change", "reconcile"];
   #roving = new RovingTabindex(() => this.#managedTargets);
   #handledEvents = /* @__PURE__ */ new WeakSet();
   #managedItems = /* @__PURE__ */ new Set();
   #originalTabindex = /* @__PURE__ */ new Map();
   #ownedPressed = /* @__PURE__ */ new Set();
   #internalPressedValues = /* @__PURE__ */ new Map();
+  /** One pass per batch of item, Value, and retained-element changes. */
+  #pass = new MicrotaskCoalescer(() => this.#reconcileDom());
   #observer = null;
   #connected = false;
+  /** The pressed set last published: read on connect, then committed or reported. */
+  #committedValues = [];
+  /**
+   * How many presses the user has committed, so a press whose reports are still
+   * going out can tell that a listener has committed a newer one meanwhile.
+   */
+  #presses = 0;
   /**
    * Normalizes state and establishes one roving entry point. A single authored
    * `tabindex="0"` survives reconnect; otherwise the first pressed, navigable
-   * item wins, falling back to the first navigable item.
+   * item wins, falling back to the first navigable item. The pressed set it
+   * settles on is the one a later move is measured from; connecting reports
+   * nothing.
    */
   connect() {
     const currentItems = new Set(this.itemTargets);
@@ -140,6 +210,8 @@ var ToggleGroupController = class extends Controller {
     for (const item of this.itemTargets) this.#reconcileHost(item, false);
     this.#normalizeSelection();
     this.#ensureTabStop(preferred);
+    this.#mirrorFields(false);
+    this.#committedValues = this.#pressedValues();
     this.element.addEventListener("click", this.#onClickCapture, true);
     this.element.addEventListener("keydown", this.#onKeydownCapture, true);
     this.element.addEventListener("click", this.#onClick);
@@ -147,11 +219,16 @@ var ToggleGroupController = class extends Controller {
     this.element.addEventListener("focusin", this.#onFocusin);
     this.#connected = true;
     this.#internalPressedValues.clear();
+    this.#pass.activate();
     this.#observeMutations();
   }
-  /** Releases every listener and observer while retaining DOM state for Turbo cache/reconnect. */
+  /**
+   * Releases every listener, the observer, and a pass still queued, while
+   * retaining DOM state for Turbo cache/reconnect.
+   */
   disconnect() {
     this.#connected = false;
+    this.#pass.cancel();
     this.element.removeEventListener("click", this.#onClickCapture, true);
     this.element.removeEventListener("keydown", this.#onKeydownCapture, true);
     this.element.removeEventListener("click", this.#onClick);
@@ -161,25 +238,29 @@ var ToggleGroupController = class extends Controller {
     this.#observer = null;
     this.#internalPressedValues.clear();
   }
-  /** Drops a newly connected item from the Tab sequence before reconciling the group. */
+  /** Drops a newly connected item from the Tab sequence before the batch is reconciled. */
   itemTargetConnected(item) {
     if (!this.#connected) return;
     this.#reconcileHost(item, true);
-    this.#normalizeSelection();
-    this.#ensureTabStop();
+    this.#pass.schedule();
   }
-  /** Restores attributes owned only while an element is an item and repairs the Tab stop. */
+  /** Restores attributes owned only while an element is an item, then reconciles the batch. */
   itemTargetDisconnected(item) {
     if (!this.#connected) return;
     this.#releaseItem(item);
-    this.#normalizeSelection();
-    this.#ensureTabStop();
+    this.#pass.schedule();
   }
   /** Reconciles the single-selection invariant when the Stimulus Value changes. */
   modeValueChanged() {
-    if (!this.#connected) return;
-    this.#normalizeSelection();
-    this.#ensureTabStop();
+    this.#pass.schedule();
+  }
+  /** Rebuilds the submitted fields when the public name changes at runtime. */
+  nameValueChanged() {
+    this.#pass.schedule();
+  }
+  /** Repoints the submitted fields when the owning form changes at runtime. */
+  formValueChanged() {
+    this.#pass.schedule();
   }
   /**
    * Toggles the action's item. Per-item action wiring is optional because click
@@ -272,7 +353,17 @@ var ToggleGroupController = class extends Controller {
     event.preventDefault();
     if (destination) this.#setActive(destination, true);
   }
-  /** Applies one user toggle and dispatches the documented change detail. */
+  /**
+   * Applies one user toggle and dispatches the documented change detail. The set
+   * it leaves is taken as published before either report goes out, so a
+   * listener that presses again or writes `aria-pressed` is measured from it. A
+   * listener of the native `change` that presses again has had that newer press
+   * reported, so this press's `change` would describe a set that is gone and is
+   * not dispatched.
+   *
+   * @stimeoRuntimeOnly `mode` is the rule this one press follows; the lasting single-press
+   *   normalisation is a render root of its own.
+   */
   #toggleItem(item) {
     if (!this.#isSupportedHost(item) || this.#isActivationDisabled(item)) return;
     if (!this.#managedItems.has(item)) this.#reconcileHost(item, true);
@@ -284,15 +375,58 @@ var ToggleGroupController = class extends Controller {
       this.#setPressed(item, willPress);
     }
     this.#setActive(item);
+    const values = this.#pressedValues();
+    this.#committedValues = values;
+    this.#presses += 1;
+    const press = this.#presses;
+    this.#mirrorFields(true);
+    if (press !== this.#presses) return;
     this.dispatch("change", {
-      detail: { value: this.#itemValue(item), pressed: willPress, values: this.#pressedValues() }
+      detail: { value: this.#itemValue(item), pressed: willPress, values: [...values] }
     });
   }
-  /** Reconciles supported hosts, pressed state, and the roving invariant after a DOM mutation. */
-  #reconcile() {
+  /**
+   * Mirrors the pressed values into the optional fields container.
+   *
+   * @stimeoRenderRoot
+   */
+  #mirrorFields(notify) {
+    if (!this.hasFieldsTarget) return;
+    const options = { name: this.nameValue, form: this.formValue };
+    if (writeFields(this.fieldsTarget, this.#pressedValues(), options) && notify) {
+      commitField(this.fieldsTarget);
+    }
+  }
+  /**
+   * Reconciles supported hosts, pressed state, the roving invariant, and the
+   * fields after the page changed the group, then reports a pressed set that
+   * moved. Records still queued are read first, so an author's write is not lost
+   * when observation is suspended for this pass's own writes; observation resumes
+   * before the report, so an edit a listener makes is seen by the next pass.
+   */
+  #reconcileDom() {
+    const observer = this.#observer;
+    if (observer) {
+      this.#releaseAuthoredPressed(observer.takeRecords());
+      observer.disconnect();
+    }
     for (const item of this.itemTargets) this.#reconcileHost(item, true);
     this.#normalizeSelection();
     this.#ensureTabStop();
+    this.#mirrorFields(false);
+    this.#internalPressedValues.clear();
+    if (observer) this.#observeWith(observer);
+    this.#reportMove();
+  }
+  /** Reports a pressed set that moved since the one this group last published. */
+  #reportMove() {
+    const values = this.#pressedValues();
+    const previous = this.#committedValues;
+    if (values.length === previous.length && values.every((value, i) => value === previous[i])) {
+      return;
+    }
+    this.#committedValues = values;
+    this.dispatch("reconcile", { detail: { values: [...values] } });
   }
   /** Begins or ends ownership according to the item's current host semantics. */
   #reconcileHost(item, dropFromTabSequence) {
@@ -328,7 +462,11 @@ var ToggleGroupController = class extends Controller {
       item.setAttribute("aria-pressed", "false");
     }
   }
-  /** Makes the first DOM-ordered pressed item the sole pressed item in single mode. */
+  /**
+   * Makes the first DOM-ordered pressed item the sole pressed item in single mode.
+   *
+   * @stimeoRenderRoot
+   */
   #normalizeSelection() {
     for (const item of this.#managedTargets) this.#normalizePressed(item);
     if (this.modeValue !== "single") return;
@@ -377,7 +515,7 @@ var ToggleGroupController = class extends Controller {
   }
   /** Whether the closest Toggle Group scope around a target is this instance. */
   #ownsEventTarget(target) {
-    return target instanceof Element && target.closest('[data-controller~="stimeo--toggle-group"]') === this.element;
+    return target instanceof Element && target.closest(`[data-controller~="${this.identifier}"]`) === this.element;
   }
   /** Hosts whose activation model can be owned without conflicting native behavior. */
   #isSupportedHost(item) {
@@ -425,9 +563,7 @@ var ToggleGroupController = class extends Controller {
   #observeMutations() {
     const observer = new MutationObserver((records) => {
       this.#releaseAuthoredPressed(records);
-      observer.disconnect();
-      this.#reconcile();
-      this.#observeWith(observer);
+      this.#pass.schedule();
     });
     this.#observer = observer;
     this.#observeWith(observer);

data/dist/controllers/toolbar_controller.js

@@ -14,11 +14,19 @@ function isReservedArrowChord(event, allow = []) {
 }
 
 // src/utils/composition_tracker.ts
+var COMPOSITION_INPUT_TYPES = /* @__PURE__ */ new Set([
+  "insertCompositionText",
+  "insertFromComposition",
+  "deleteCompositionText",
+  "deleteByComposition"
+]);
 var CompositionTracker = class {
   #observedTargets = /* @__PURE__ */ new Set();
   #activeTargets = /* @__PURE__ */ new Set();
   #onStart;
   #onEnd;
+  /** The field whose confirming `input` is still owed, while the window is open. */
+  #confirmedTarget = null;
   constructor(options = {}) {
     this.#onStart = options.onStart;
     this.#onEnd = options.onEnd;
@@ -28,6 +36,7 @@ var CompositionTracker = class {
     if (this.#observedTargets.has(target)) return;
     target.addEventListener("compositionstart", this.#handleStart);
     target.addEventListener("compositionend", this.#handleEnd);
+    target.addEventListener("keydown", this.#handleKeydown);
     this.#observedTargets.add(target);
   }
   /** Stops tracking one target and clears any active composition it owned. */
@@ -35,29 +44,52 @@ var CompositionTracker = class {
     if (!this.#observedTargets.delete(target)) return;
     target.removeEventListener("compositionstart", this.#handleStart);
     target.removeEventListener("compositionend", this.#handleEnd);
+    target.removeEventListener("keydown", this.#handleKeydown);
     this.#activeTargets.delete(target);
+    if (this.#confirmedTarget === target) this.#confirmedTarget = null;
   }
   /** Releases every listener and clears state so reconnect starts cleanly. */
   disconnect() {
     for (const target of this.#observedTargets) {
       target.removeEventListener("compositionstart", this.#handleStart);
       target.removeEventListener("compositionend", this.#handleEnd);
+      target.removeEventListener("keydown", this.#handleKeydown);
     }
     this.#observedTargets.clear();
     this.#activeTargets.clear();
+    this.#confirmedTarget = null;
   }
   /** True when lifecycle tracking or the current event reports composition. */
   isComposing(event) {
     return this.#activeTargets.size > 0 || event?.isComposing === true;
   }
+  /**
+   * Whether `event` is the `input` echoing the composition just confirmed.
+   *
+   * Asking closes the window either way, so one confirmation is folded at most
+   * once and a consumer asks once per `input`.
+   */
+  consumesConfirmedInput(event) {
+    const confirmed = this.#confirmedTarget;
+    this.#confirmedTarget = null;
+    if (confirmed === null || confirmed !== event.target) return false;
+    const inputType = event.inputType;
+    return !inputType || COMPOSITION_INPUT_TYPES.has(inputType);
+  }
   #handleStart = (event) => {
+    this.#confirmedTarget = null;
     if (event.currentTarget) this.#activeTargets.add(event.currentTarget);
     this.#onStart?.(event);
   };
   #handleEnd = (event) => {
     if (event.currentTarget) this.#activeTargets.delete(event.currentTarget);
+    this.#confirmedTarget = event.target;
     this.#onEnd?.(event);
   };
+  /** A key on an observed field opens an edit of its own, so no echo is owed. */
+  #handleKeydown = () => {
+    this.#confirmedTarget = null;
+  };
 };
 
 // src/utils/event_owner.ts

data/dist/controllers/tooltip_controller.js

@@ -164,6 +164,16 @@ function isScrollable(element) {
   return /auto|scroll|overlay/.test(style.overflow + style.overflowX + style.overflowY);
 }
 
+// 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/tooltip_controller.ts
 var TooltipController = class extends Controller {
   static targets = ["trigger", "content"];
@@ -173,6 +183,7 @@ var TooltipController = class extends Controller {
     closeOnScroll: { type: Boolean, default: false }
   };
   static actions = ["hide", "show"];
+  static events = ["close", "open"];
   /** Registry whose pending timers are cancelled individually with their guard ids. */
   #timers = new SafeTimeout();
   /** Escape-stack membership while shown; the shared resolver dismisses via it. */
@@ -186,15 +197,19 @@ var TooltipController = class extends Controller {
   #pointerActive = false;
   /** Cleanup for the dismiss-on-scroll listeners while shown, or `null`. */
   #stopScrollDismiss = null;
+  /** Whether state moves are reported: set once `connect()` settled the baseline. */
+  #reporting = false;
   /** Starts hidden with no stale timer or interaction state from a prior connection. */
   connect() {
     this.#cancelShow();
     this.#cancelHide();
     this.#resetInteractionState();
-    this.#conceal();
+    this.#conceal("api");
+    this.#reporting = true;
   }
   /** Clears timers, the Escape-stack membership, and scroll listeners so nothing outlives the element. */
   disconnect() {
+    this.#reporting = false;
     this.#cancelShow();
     this.#cancelHide();
     this.#resetInteractionState();
@@ -204,20 +219,22 @@ var TooltipController = class extends Controller {
   }
   /** Shows after `showDelay`, recording the focus/pointer reason supplied by an action event. */
   show(event) {
+    const reason = stateReasonFor(event);
     this.#activateInteraction(event);
     this.#cancelHide();
     if (this.#isVisible || this.#pendingShow !== null) return;
     if (this.showDelayValue <= 0) {
-      this.#reveal();
+      this.#reveal(reason);
       return;
     }
     this.#pendingShow = this.#timers.set(() => {
       this.#pendingShow = null;
-      this.#reveal();
+      this.#reveal(reason);
     }, this.showDelayValue);
   }
   /** Hides after `hideDelay` once no focus/pointer reason remains; eventless calls are explicit. */
   hide(event) {
+    const reason = stateReasonFor(event);
     const interactionEnded = this.#deactivateInteraction(event);
     if (interactionEnded && this.#hasActiveInteraction) {
       this.#cancelHide();
@@ -226,38 +243,47 @@ var TooltipController = class extends Controller {
     this.#cancelShow();
     if (!this.#isVisible || this.#pendingHide !== null) return;
     if (this.hideDelayValue <= 0) {
-      this.#conceal();
+      this.#conceal(reason);
       return;
     }
     this.#pendingHide = this.#timers.set(() => {
       this.#pendingHide = null;
-      this.#conceal();
+      this.#conceal(reason);
     }, this.hideDelayValue);
   }
-  /** Reveals the content and joins the Escape stack / starts the scroll watcher. */
-  #reveal() {
+  /**
+   * Reveals the content, reports a move, and joins the Escape stack / scroll watcher.
+   *
+   * @stimeoRuntimeOnly `closeOnScroll` decides whether this reveal wires the scroll dismissal; what
+   *   is shown does not depend on it.
+   */
+  #reveal(reason) {
     if (!this.hasContentTarget) return;
+    const was = this.#isVisible;
     this.contentTarget.hidden = false;
     this.contentTarget.setAttribute("data-state", "open");
-    this.#escapeLayer.activate(document, { onDismiss: () => this.#dismiss() });
+    if (!was && this.#reporting) this.dispatch("open", { detail: { reason }, cancelable: false });
+    this.#escapeLayer.activate(document, { onDismiss: () => this.#dismiss("escape") });
     if (this.closeOnScrollValue && !this.#stopScrollDismiss) {
-      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => this.#dismiss());
+      this.#stopScrollDismiss = observeScrollDismiss(this.element, () => this.#dismiss("scroll"));
     }
   }
-  /** Hides the content and leaves the Escape stack / stops the scroll watcher. */
-  #conceal() {
+  /** Hides the content, reports a move, and leaves the Escape stack / scroll watcher. */
+  #conceal(reason) {
+    const was = this.#isVisible;
     this.#escapeLayer.deactivate();
     this.#stopScrollDismiss?.();
     this.#stopScrollDismiss = null;
     if (!this.hasContentTarget) return;
     this.contentTarget.hidden = true;
     this.contentTarget.setAttribute("data-state", "closed");
+    if (was && this.#reporting) this.dispatch("close", { detail: { reason }, cancelable: false });
   }
   /** Cancels pending timers and conceals immediately (shared Escape / scroll path). */
-  #dismiss() {
+  #dismiss(reason) {
     this.#cancelShow();
     this.#cancelHide();
-    this.#conceal();
+    this.#conceal(reason);
   }
   /** Records the modality whose enter/focus event requires the tooltip to stay visible. */
   #activateInteraction(event) {

data/dist/controllers/transition_controller.js

@@ -277,6 +277,10 @@ var TransitionController = class extends Controller {
     if (state === "entered" || state === "entering") this.leave();
     else this.enter();
   }
+  /**
+   * @stimeoRuntimeOnly The class lists and `timeout` shape this one transition; `#finish` strips
+   *   the classes, so none of them stays at rest.
+   */
   #run(kind) {
     this.#cancel();
     const isEnter = kind === "enter";