stimeo-ui 0.15.0 → 0.16.0

data/dist/controllers/combobox_controller.js

@@ -21,11 +21,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;
@@ -35,6 +43,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. */
@@ -42,31 +51,59 @@ 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/field_mirror.ts
+function commitField(target) {
+  target.dispatchEvent(new Event("change", { bubbles: true }));
+}
+
 // src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
@@ -112,20 +149,64 @@ function scrollOptionIntoView(list, option) {
   }
 }
 
+// src/utils/state_regions.ts
+var StateRegions = class {
+  #whenTrue;
+  #whenFalse;
+  #taken = /* @__PURE__ */ new WeakSet();
+  constructor(options) {
+    this.#whenTrue = options.whenTrue;
+    this.#whenFalse = options.whenFalse ?? null;
+  }
+  /** Shows the regions inside `host` that belong to `isTrue` and hides the others. */
+  reflect(host, isTrue) {
+    const shown = this.#inside(host, this.#whenTrue());
+    if (!this.#whenFalse) {
+      for (const region of shown) this.#write(region, !isTrue);
+      return;
+    }
+    const hiddenSide = this.#inside(host, this.#whenFalse());
+    if (shown.length === 0 || hiddenSide.length === 0) {
+      for (const region of shown) this.#give(region);
+      for (const region of hiddenSide) this.#give(region);
+      return;
+    }
+    for (const region of shown) this.#write(region, !isTrue);
+    for (const region of hiddenSide) this.#write(region, isTrue);
+  }
+  /** Writes `hidden` where it moves, noting which regions it takes out of view. */
+  #write(region, hidden) {
+    if (hidden) this.#taken.add(region);
+    else this.#taken.delete(region);
+    if (region.hidden !== hidden) region.hidden = hidden;
+  }
+  /** Returns a region this instance hid; one it never hid keeps what it carries. */
+  #give(region) {
+    if (this.#taken.delete(region)) region.hidden = false;
+  }
+  /** The declared regions that sit within `host`, which may be the host itself. */
+  #inside(host, regions) {
+    return regions.filter((region) => host.contains(region));
+  }
+};
+
 // src/controllers/combobox_controller.ts
 var ComboboxController = class extends Controller {
-  static targets = ["input", "list", "option"];
+  static targets = ["input", "list", "option", "empty"];
   static actions = ["close", "filter", "onKeydown", "open", "selectByClick"];
   static events = ["selected"];
+  /** Owns `hidden` on the regions declared for the empty state. */
+  #emptyRegion = new StateRegions({ whenTrue: () => this.emptyTargets });
   /** Stable ID of the active option; the live element is resolved before every use. */
   #activeId = null;
   #connected = false;
   /** Collapses one mutation batch of target callbacks into a single pass. */
   #reconcile = new MicrotaskCoalescer(() => this.#reconcileOptions());
   /**
-   * Suppresses {@link open} for the duration of the programmatic re-focus in
-   * `#select`, so committing a value (which returns focus to the input)
-   * does not immediately re-open the listbox via a `focus`-bound action.
+   * Suppresses {@link ComboboxController.open | open} for the duration of the
+   * programmatic re-focus in `#select`, so committing a value (which returns focus
+   * to the input) does not immediately re-open the listbox via a `focus`-bound
+   * action.
    */
   #suppressOpen = false;
   /** Owns IME lifecycle state; confirmed text re-filters the list once. */
@@ -154,6 +235,10 @@ var ComboboxController = class extends Controller {
   inputTargetDisconnected(input) {
     this.#composition.unobserve(input);
   }
+  /** Settles a connecting region on the side the empty state is on. */
+  emptyTargetConnected() {
+    this.#reflectEmptyState();
+  }
   /** Establishes the active-state baseline, then reconciles a runtime addition. */
   optionTargetConnected(option) {
     option.setAttribute("aria-selected", "false");
@@ -206,7 +291,7 @@ var ComboboxController = class extends Controller {
   close() {
     if (!this.hasListTarget) return;
     this.listTarget.hidden = true;
-    this.element.removeAttribute("data-stimeo--combobox-empty");
+    this.#reflectEmptyState();
     if (this.hasInputTarget) this.inputTarget.setAttribute("aria-expanded", "false");
     this.#setActive(-1);
   }
@@ -300,10 +385,10 @@ var ComboboxController = class extends Controller {
    * Commits an option: fills the input, closes the listbox, notifies listeners.
    *
    * An input removed while the popup is open leaves the options clickable, and
-   * {@link close} already survives that state. Selection does too: the popup
-   * comes down and listeners still hear the choice, with only the field-bound
-   * half — the value write, the focus return, and the native `change` — skipped,
-   * because there is no field to carry them.
+   * {@link ComboboxController.close | close} already survives that state. Selection
+   * does too: the popup comes down and listeners still hear the choice, with only
+   * the field-bound half — the value write, the focus return, and the native
+   * `change` — skipped, because there is no field to carry them.
    */
   #select(option) {
     const value = option.dataset.value ?? (option.textContent ?? "").trim();
@@ -319,23 +404,28 @@ var ComboboxController = class extends Controller {
     this.inputTarget.focus();
     this.#suppressOpen = false;
     if (changed) {
-      this.inputTarget.dispatchEvent(new Event("change", { bubbles: true }));
+      commitField(this.inputTarget);
     }
     this.dispatch("selected", { detail: { value } });
   }
   /**
-   * Reflects whether the open listbox currently has zero matching options by
-   * toggling `data-stimeo--combobox-empty` on the root element. Behavior only:
-   * consumers decide how to present the empty state (hide the list, show a
-   * "no results" node, etc.) via CSS keyed off this attribute.
+   * Writes whether the open listbox has zero matching options to the state hook
+   * `data-stimeo--combobox-empty` on the root element and to the regions declared
+   * for that state. Behavior only: consumers decide how to present the empty state
+   * via CSS keyed off the attribute, while the `empty` targets carry the copy.
+   *
+   * Every path that can change the answer — opening, filtering, reconciling a
+   * runtime option change, and closing — ends here, so the hook and the regions
+   * are a pure function of the state rather than of the order things happened in.
    */
   #reflectEmptyState() {
     const empty = !this.#isClosed && this.#visibleOptions().length === 0;
     if (empty) {
-      this.element.setAttribute("data-stimeo--combobox-empty", "");
+      this.element.setAttribute(`data-${this.identifier}-empty`, "");
     } else {
-      this.element.removeAttribute("data-stimeo--combobox-empty");
+      this.element.removeAttribute(`data-${this.identifier}-empty`);
     }
+    this.#emptyRegion.reflect(this.element, empty);
   }
   /**
    * Marks the visible option at `index` active via `aria-selected` and the

data/dist/controllers/command_palette_controller.js

@@ -21,11 +21,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;
@@ -35,6 +43,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. */
@@ -42,29 +51,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/before_cache_reset.ts
@@ -511,9 +543,9 @@ var CommandPaletteController = class _CommandPaletteController extends Controlle
    * the restored snapshot already shows the dialog open, honor that rather than
    * re-deriving from the declarative `open` Value (which would slam a user-opened
    * palette shut). The `open` Value only seeds the initial state of a genuinely
-   * fresh render. We normalize to a clean closed baseline first so {@link open}
-   * runs its full setup — the `FocusTrap` is a fresh instance after a
-   * reconnect and must be re-activated.
+   * fresh render. We normalize to a clean closed baseline first so
+   * {@link CommandPaletteController.open | open} runs its full setup — the
+   * `FocusTrap` is a fresh instance after a reconnect and must be re-activated.
    */
   connect() {
     document.addEventListener("keydown", this.#onGlobalKeydown);

data/dist/controllers/conditional_fields_controller.js

@@ -26,6 +26,54 @@ function canTakeFocus(element) {
   return !inheritsFieldsetDisabled(element);
 }
 
+// src/utils/form_reset_watcher.ts
+var FormResetWatcher = class {
+  #owns;
+  #onReset;
+  #frames = /* @__PURE__ */ new Set();
+  #generation = 0;
+  /**
+   * @param owns - whether `form` owns a control this controller derives from.
+   * @param onReset - the reconciliation pass, run once per honoured reset.
+   */
+  constructor(owns, onReset) {
+    this.#owns = owns;
+    this.#onReset = onReset;
+  }
+  /** Subscribes to `reset` at the document; call from `connect()`. Idempotent. */
+  observe() {
+    document.addEventListener("reset", this.#handleReset, true);
+  }
+  /** Unsubscribes and drops every pending pass; call from `disconnect()`. */
+  disconnect() {
+    document.removeEventListener("reset", this.#handleReset, true);
+    this.#generation += 1;
+    for (const frame of this.#frames) cancelAnimationFrame(frame);
+    this.#frames.clear();
+  }
+  #handleReset = (event) => {
+    const form = event.target;
+    if (!(form instanceof HTMLFormElement) || !this.#owns(form)) return;
+    const generation = this.#generation;
+    queueMicrotask(() => {
+      if (generation !== this.#generation) return;
+      if (event.eventPhase === Event.NONE) {
+        this.#settle(event);
+        return;
+      }
+      const frame = requestAnimationFrame(() => {
+        this.#frames.delete(frame);
+        this.#settle(event);
+      });
+      this.#frames.add(frame);
+    });
+  };
+  /** Runs the pass unless a listener cancelled the reset before it landed. */
+  #settle(event) {
+    if (!event.defaultPrevented) this.#onReset();
+  }
+};
+
 // src/utils/listener_set.ts
 var ListenerSet = class {
   /** The generation every `add` joins until the next `dispose()`. */
@@ -175,6 +223,10 @@ var ConditionalFieldsController = class extends Controller {
   /** Coalesces one target/morph/mutation batch into one full DOM reconciliation. */
   #reconcile = new MicrotaskCoalescer(() => this.#reconcileDom());
   #listeners = new ListenerSet();
+  #formReset = new FormResetWatcher(
+    (form) => this.#hasTriggerOwnedBy(form),
+    () => this.#reconcile.schedule()
+  );
   /** Provides the last-resort focus landmark without claiming an authored tabindex. */
   #rootTabindex = new TabindexLoan();
   /** Watches retained targets and controls whose declarative or reflected state changed. */
@@ -191,15 +243,6 @@ var ConditionalFieldsController = class extends Controller {
   #onMorph = () => {
     this.#reconcile.schedule();
   };
-  /** Reconciles the settled defaults after a non-cancelled owning form reset. */
-  #onReset = (event) => {
-    const form = event.target;
-    if (form instanceof HTMLFormElement && this.#hasTriggerOwnedBy(form)) {
-      queueMicrotask(() => {
-        if (!event.defaultPrevented) this.#reconcile.schedule();
-      });
-    }
-  };
   /** Reflects initial live state and opens every retained-DOM reconciliation path. */
   connect() {
     this.#lastVisible = /* @__PURE__ */ new WeakMap();
@@ -216,7 +259,7 @@ var ConditionalFieldsController = class extends Controller {
     this.#listeners.add(this.element, "change", this.#onTriggerInput);
     this.#listeners.add(this.element, "input", this.#onTriggerInput);
     this.#listeners.add(this.element, "turbo:morph-element", this.#onMorph);
-    document.addEventListener("reset", this.#onReset, true);
+    this.#formReset.observe();
   }
   /** Releases all external resources and returns the temporary focus landmark loan. */
   disconnect() {
@@ -224,7 +267,7 @@ var ConditionalFieldsController = class extends Controller {
     this.#observing = false;
     this.#observer.disconnect();
     this.#listeners.dispose();
-    document.removeEventListener("reset", this.#onReset, true);
+    this.#formReset.disconnect();
     this.#rootTabindex.returnAll();
   }
   /** Reconciles after a trigger target is inserted or restored. */
@@ -258,6 +301,8 @@ var ConditionalFieldsController = class extends Controller {
   /**
    * Computes one settled plan, shows destinations before hiding sources, and then
    * returns logical transitions in DOM order after every region is internally coherent.
+   *
+   * @stimeoRenderRoot
    */
   #settle(triggers = this.triggerTargets) {
     const regions = this.regionTargets;

data/dist/controllers/confirm_controller.js

@@ -423,6 +423,9 @@ var ConfirmController = class extends Controller {
   /**
    * Opens the dialog for `message` and resolves once the user confirms or cancels.
    * Degrades to native `window.confirm` when no dialog target is present.
+   *
+   * @stimeoRuntimeOnly The labels word the one dialog this call opens; every opening writes both
+   *   labels again, and the dialog stays hidden between prompts.
    */
   #prompt(message) {
     if (!this.hasDialogTarget) return Promise.resolve(window.confirm(message));

data/dist/controllers/context_menu_controller.js

@@ -151,22 +151,37 @@ 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/context_menu_controller.ts
 var ContextMenuController = class extends Controller {
   static targets = ["region", "menu", "item"];
   static actions = ["activate", "onItemKeydown", "onRegionKeydown", "open"];
+  static events = ["close", "open"];
   #timers = new SafeTimeout();
   /** Escape-stack membership while open; the shared resolver dismisses via it. */
   #escapeLayer = new EscapeLayer();
+  /** Whether state moves are reported: set once `connect()` settled the baseline. */
+  #reporting = false;
   /** Starts closed and registers delegated activation and outside-pointer listeners. */
   connect() {
-    this.#closeMenu();
+    this.#closeMenu("api");
     this.element.addEventListener("click", this.#onItemClickCapture, true);
     document.addEventListener("click", this.#onOutsidePointer, true);
     document.addEventListener("contextmenu", this.#onOutsidePointer, true);
+    this.#reporting = true;
   }
   /** Releases the listeners, stack membership, and pending Tab-close task. */
   disconnect() {
+    this.#reporting = false;
     this.#timers.clearAll();
     this.#escapeLayer.deactivate();
     this.element.removeEventListener("click", this.#onItemClickCapture, true);
@@ -179,7 +194,7 @@ var ContextMenuController = class extends Controller {
    */
   open(event) {
     event.preventDefault();
-    this.#openAt(event.clientX, event.clientY);
+    this.#openAt(event.clientX, event.clientY, stateReasonFor(event));
   }
   /** Keyboard entry on the region: `Shift+F10` / `ContextMenu` open at center. */
   onRegionKeydown(event) {
@@ -188,7 +203,7 @@ var ContextMenuController = class extends Controller {
     if (!isContextKey) return;
     event.preventDefault();
     const rect = this.hasRegionTarget ? this.regionTarget.getBoundingClientRect() : { left: 0, top: 0, width: 0, height: 0 };
-    this.#openAt(rect.left + rect.width / 2, rect.top + rect.height / 2);
+    this.#openAt(rect.left + rect.width / 2, rect.top + rect.height / 2, stateReasonFor(event));
   }
   /** Roving focus and closing keys inside the menu. */
   onItemKeydown(event) {
@@ -221,39 +236,44 @@ var ContextMenuController = class extends Controller {
         break;
       case "Tab":
         this.#timers.clearAll();
-        this.#timers.set(() => this.#closeMenu(), 0);
+        this.#timers.set(() => this.#closeMenu("focus"), 0);
         break;
     }
   }
   /** Closes after an item is activated and restores focus to the region. */
   activate() {
-    this.#closeAndRestore();
+    this.#closeAndRestore("select");
   }
   /** Opens the menu at viewport coordinates `(x, y)` and focuses the first item. */
-  #openAt(x, y) {
+  #openAt(x, y, reason) {
     if (!this.hasMenuTarget) return;
     this.#timers.clearAll();
+    const was = this.#isOpen;
     this.#escapeLayer.activate(document, {
-      onDismiss: () => this.#closeAndRestore(),
+      onDismiss: () => this.#closeAndRestore("escape"),
       claims: claimsWhileFocusWithin(this.element)
     });
     this.menuTarget.style.setProperty("--stimeo--context-menu-x", `${x}px`);
     this.menuTarget.style.setProperty("--stimeo--context-menu-y", `${y}px`);
     this.menuTarget.hidden = false;
     if (this.hasRegionTarget) this.regionTarget.setAttribute("data-state", "open");
+    if (!was && this.#reporting) this.dispatch("open", { detail: { reason }, cancelable: false });
+    if (!this.#isOpen) return;
     this.#navigableItems[0]?.focus();
   }
-  /** Hides the menu and reflects the collapsed state on the region. */
-  #closeMenu() {
+  /** Hides the menu, reflects the collapsed state on the region, and reports a move. */
+  #closeMenu(reason) {
     this.#timers.clearAll();
     this.#escapeLayer.deactivate();
     if (!this.hasMenuTarget) return;
+    const was = this.#isOpen;
     this.menuTarget.hidden = true;
     if (this.hasRegionTarget) this.regionTarget.setAttribute("data-state", "closed");
+    if (was && this.#reporting) this.dispatch("close", { detail: { reason }, cancelable: false });
   }
   /** Closes the menu and returns focus to the region (Escape / activation). */
-  #closeAndRestore() {
-    this.#closeMenu();
+  #closeAndRestore(reason) {
+    this.#closeMenu(reason);
     if (this.hasRegionTarget) this.regionTarget.focus();
   }
   /**
@@ -264,7 +284,7 @@ var ContextMenuController = class extends Controller {
    * open.
    */
   #onOutsidePointer = (event) => {
-    if (this.#isOpen && !this.element.contains(event.target)) this.#closeMenu();
+    if (this.#isOpen && !this.element.contains(event.target)) this.#closeMenu("outside");
   };
   /**
    * Captures clicks so `aria-disabled` commands cannot reach consumer handlers.