stimeo-ui 0.15.0 → 0.16.0

data/dist/controllers/dialog_controller.js

@@ -365,18 +365,32 @@ var FocusTrap = class {
   }
 };
 
+// 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/dialog_controller.ts
 var DialogController = class extends Controller {
   static targets = ["trigger", "dialog"];
   static actions = ["close", "closeOnBackdrop", "open"];
+  static events = ["close", "open"];
   /** Owns the modal side effects; Escape closes, focus falls back to the trigger. */
   #trap = new FocusTrap(() => this.dialogTarget, {
-    onEscape: () => this.close(),
+    onEscape: () => this.#close("escape"),
     fallbackFocus: () => this.hasTriggerTarget ? this.triggerTarget : null
   });
+  /** Whether state moves are reported: set once `connect()` settled the baseline. */
+  #reporting = false;
   /** Starts closed (idempotently reflects the closed state on the markup). */
   connect() {
     if (this.hasDialogTarget) this.dialogTarget.hidden = true;
+    this.#reporting = true;
   }
   /**
    * Reverts the modal side effects (scroll lock, background `inert`, keydown
@@ -385,24 +399,37 @@ var DialogController = class extends Controller {
    * teardown.
    */
   disconnect() {
+    this.#reporting = false;
     this.#trap.deactivate({ restoreFocus: false });
   }
   /** Opens the dialog, traps focus, and locks background scroll. */
-  open() {
+  open(event) {
+    this.#open(stateReasonFor(event));
+  }
+  /** Closes the dialog, restores scroll, and returns focus to the opener. */
+  close(event) {
+    this.#close(stateReasonFor(event));
+  }
+  /** Closes when the backdrop (the dialog target itself) is clicked. */
+  closeOnBackdrop(event) {
+    if (event.target === this.dialogTarget) this.#close("outside");
+  }
+  /** Reveals the dialog, reports a move, then traps focus and locks scroll. */
+  #open(reason) {
     if (!this.hasDialogTarget || this.#isOpen) return;
     this.dialogTarget.hidden = false;
+    if (this.#reporting) this.dispatch("open", { detail: { reason }, cancelable: false });
+    if (!this.#isOpen) return;
     this.#trap.activate();
   }
-  /** Closes the dialog, restores scroll, and returns focus to the opener. */
-  close() {
+  /** Hides the dialog, reports a move, then restores scroll and focus. */
+  #close(reason) {
     if (!this.hasDialogTarget || !this.#isOpen) return;
     this.dialogTarget.hidden = true;
+    if (this.#reporting) this.dispatch("close", { detail: { reason }, cancelable: false });
+    if (this.#isOpen) return;
     this.#trap.deactivate();
   }
-  /** Closes when the backdrop (the dialog target itself) is clicked. */
-  closeOnBackdrop(event) {
-    if (event.target === this.dialogTarget) this.close();
-  }
   /** Whether the dialog is currently visible. */
   get #isOpen() {
     return this.hasDialogTarget && !this.dialogTarget.hidden;

data/dist/controllers/direct_upload_controller.js

@@ -121,6 +121,12 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/template_row.ts
+function cloneTemplateRoot(template) {
+  const root = template.content.firstElementChild;
+  return root instanceof HTMLElement ? root.cloneNode(true) : null;
+}
+
 // src/controllers/direct_upload_controller.ts
 var REMOVE_DELAY = 4e3;
 var DirectUploadController = class extends Controller {
@@ -186,7 +192,12 @@ var DirectUploadController = class extends Controller {
     this.#syncAggregate();
     this.dispatch("progress", { detail: { id, percent: clamped } });
   }
-  /** Marks a not-yet-settled row done at 100%, announces it, and emits `done`. */
+  /**
+   * Marks a not-yet-settled row done at 100%, announces it, and emits `done`.
+   *
+   * @stimeoRuntimeOnly `announceDoneText` words the one announcement of this completion and
+   *   `removeOnDone` decides whether it arms the row's removal.
+   */
   #complete(id, name) {
     const row = this.#rowFor(id, name);
     if (row === null || this.#isSettled(row)) return;
@@ -204,6 +215,8 @@ var DirectUploadController = class extends Controller {
    * Returns whether the failure is rendered by this widget (used to decide the
    * `direct-upload:error` default), which also holds when the row already
    * displays an earlier failure.
+   *
+   * @stimeoRuntimeOnly `announceErrorText` words the one announcement of this failure.
    */
   #fail(id, error, name) {
     const row = this.#rowFor(id, name);
@@ -219,7 +232,12 @@ var DirectUploadController = class extends Controller {
     const state = row.getAttribute("data-upload-state");
     return state === "done" || state === "error";
   }
-  /** Re-arms `removeOnDone` for completed rows after a reconnect. */
+  /**
+   * Re-arms `removeOnDone` for completed rows after a reconnect.
+   *
+   * @stimeoRuntimeOnly `removeOnDone` decides whether reconnecting arms the removal of finished
+   *   rows again.
+   */
   #rescheduleRemovals() {
     if (!this.removeOnDoneValue) return;
     this.#prune();
@@ -242,8 +260,8 @@ var DirectUploadController = class extends Controller {
       this.#rows.delete(key);
     }
     if (!this.hasRowTarget || !this.hasListTarget) return null;
-    const clone = this.rowTarget.content.firstElementChild?.cloneNode(true);
-    if (!(clone instanceof HTMLElement)) return null;
+    const clone = cloneTemplateRoot(this.rowTarget);
+    if (!clone) return null;
     this.#applyName(clone, name);
     clone.setAttribute("data-upload-state", "uploading");
     this.#applyProgress(clone, 0);

data/dist/controllers/dirty_form_controller.js

@@ -79,7 +79,20 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
+// src/utils/transient_hooks.ts
+var TransientHooks = class {
+  #attributes;
+  constructor(options) {
+    this.#attributes = options.attributes;
+  }
+  /** Drops the declared hooks from `element`; what it carries besides stays. */
+  reset(element) {
+    for (const attribute of this.#attributes) element.removeAttribute(attribute);
+  }
+};
+
 // src/controllers/dirty_form_controller.ts
+var TRANSIENT = new TransientHooks({ attributes: ["data-dirty"] });
 var visitCoordinators = /* @__PURE__ */ new WeakMap();
 var TurboVisitCoordinator = class {
   #document;
@@ -206,7 +219,7 @@ var DirtyFormController = class extends Controller {
     this.#resetSubmission();
     this.#baseline = this.#serialize();
     this.#setDirty(false);
-    this.element.removeAttribute("data-dirty");
+    TRANSIENT.reset(this.element);
     this.#listeners.add(this.element, "input", this.#onFieldChange);
     this.#listeners.add(this.element, "change", this.#onFieldChange);
     this.#listeners.add(this.element, "submit", this.#onSubmit);

data/dist/controllers/dismissible_controller.js

@@ -123,6 +123,7 @@ var DismissibleController = class extends Controller {
   get #root() {
     return this.hasRootTarget ? this.rootTarget : this.element;
   }
+  /** @stimeoRuntimeOnly `mode` decides how this one dismissal takes the element away. */
   #performDismiss() {
     const root = this.#root;
     const mode = this.modeValue === "hide" ? "hide" : "remove";

data/dist/controllers/drawer_controller.js

@@ -365,6 +365,16 @@ var FocusTrap = class {
   }
 };
 
+// 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/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -567,17 +577,20 @@ var DrawerController = class extends Controller {
     open: { type: Boolean, default: false }
   };
   static actions = ["close", "closeOnBackdrop", "open"];
+  static events = ["close", "open"];
   /** Exact panel currently owned by the modal lifecycle (survives target churn safely). */
   #activePanel = null;
   /** Owns the modal side effects; Escape closes, focus falls back to the trigger. */
   #trap = new FocusTrap(() => this.#activePanel ?? this.panelTarget, {
-    onEscape: () => this.close(),
+    onEscape: () => this.#close("escape"),
     fallbackFocus: () => this.hasTriggerTarget ? this.triggerTarget : null
   });
   /** Owns the cancellable close-transition wait and its bounded fallback. */
   #transition = new TransitionCompletion();
   /** Distinguishes dynamic target churn from callbacks around controller teardown. */
   #connected = false;
+  /** Whether state moves are reported: set once `connect()` settled the baseline. */
+  #reporting = false;
   /**
    * Reflects placement and establishes the initial open/closed state.
    *
@@ -585,9 +598,9 @@ var DrawerController = class extends Controller {
    * restored snapshot whose panel is already `data-state="open"` stays open
    * rather than being re-derived from the declarative `open` Value (which would
    * close a user-opened drawer). The `open` Value only seeds a genuinely fresh
-   * render. We normalize to a clean closed baseline first so {@link open} runs its
-   * full reveal + trap activation — the `FocusTrap` is inactive after a
-   * disconnect and must be re-activated.
+   * render. We normalize to a clean closed baseline first so
+   * {@link DrawerController.open | open} runs its full reveal + trap activation —
+   * the `FocusTrap` is inactive after a disconnect and must be re-activated.
    */
   connect() {
     this.#connected = true;
@@ -595,11 +608,13 @@ var DrawerController = class extends Controller {
     this.#reflectPlacement();
     const shouldOpen = this.#isOpen || this.openValue;
     this.#applyClosedState();
-    if (shouldOpen) this.open();
+    if (shouldOpen) this.#open("api");
+    this.#reporting = true;
   }
   /** Reverts the modal side effects and pending hide if torn down while open. */
   disconnect() {
     this.#connected = false;
+    this.#reporting = false;
     this.#transition.cancel();
     this.#trap.deactivate({ restoreFocus: false });
     this.#activePanel = null;
@@ -630,7 +645,11 @@ var DrawerController = class extends Controller {
     this.#reflectPlacement();
   }
   /** Opens the drawer: reveals it, syncs `data-state`, traps focus. */
-  open() {
+  open(event) {
+    this.#open(stateReasonFor(event));
+  }
+  /** Reveals the drawer, syncs `data-state`, reports a move, then traps focus. */
+  #open(reason) {
     if (!this.hasPanelTarget || this.#isOpen) return;
     this.#transition.cancel();
     this.#activePanel = this.panelTarget;
@@ -639,31 +658,46 @@ var DrawerController = class extends Controller {
     void this.panelTarget.offsetWidth;
     this.#setState("open");
     this.openValue = true;
+    if (this.#reporting) this.dispatch("open", { detail: { reason }, cancelable: false });
+    if (!this.#isOpen) return;
     this.#trap.activate();
   }
   /**
    * Closes the drawer: syncs `data-state` to start the exit transition, then
    * defers both `hidden` *and* the modal teardown (scroll lock / background
-   * `inert` / focus restore) until the transition finishes — see
-   * `#applyHidden`. This keeps the background inert and focus trapped while
-   * the drawer is still visually on screen, preserving the modal contract during
-   * the exit animation.
+   * `inert` / focus restore) until the transition finishes. This keeps the
+   * background inert and focus trapped while the drawer is still visually on
+   * screen, preserving the modal contract during the exit animation.
    */
-  close() {
+  close(event) {
+    this.#close(stateReasonFor(event));
+  }
+  /** Closes only when the overlay itself (not its contents) is clicked. */
+  closeOnBackdrop(event) {
+    if (this.hasOverlayTarget && event.target === this.overlayTarget) this.#close("outside");
+  }
+  /** Starts the exit transition, reports a move, then defers `hidden` and teardown. */
+  #close(reason) {
     if (!this.hasPanelTarget || !this.#isOpen) return;
     this.openValue = false;
     this.#setState("closed");
+    if (this.#reporting) this.dispatch("close", { detail: { reason }, cancelable: false });
+    if (this.#isOpen) return;
     this.#hideAfterTransition();
   }
-  /** Closes only when the overlay itself (not its contents) is clicked. */
-  closeOnBackdrop(event) {
-    if (this.hasOverlayTarget && event.target === this.overlayTarget) this.close();
-  }
-  /** Writes `data-placement` from the current `placement` value. */
+  /**
+   * Writes `data-placement` from the current `placement` value.
+   *
+   * @stimeoRenderRoot
+   */
   #reflectPlacement() {
     if (this.hasPanelTarget) this.panelTarget.setAttribute("data-placement", this.#placement);
   }
-  /** Reconciles a replacement panel and companion overlay from its explicit DOM state. */
+  /**
+   * Reconciles a replacement panel and companion overlay from its explicit DOM state.
+   *
+   * @stimeoRenderRoot
+   */
   #adoptPanel(panel) {
     this.#transition.cancel();
     const trapWasActive = this.#trap.active;
@@ -719,8 +753,9 @@ var DrawerController = class extends Controller {
    * Runs once the close transition has finished: applies `hidden` to the panel
    * and overlay, then reverts the modal side effects (scroll lock, background
    * `inert`, keydown listener) and restores focus to the opener. Deferring the
-   * `FocusTrap` teardown to here — rather than at {@link close} time — keeps
-   * the background unreachable and focus trapped for the whole exit animation.
+   * `FocusTrap` teardown to here — rather than at
+   * {@link DrawerController.close | close} time — keeps the background unreachable
+   * and focus trapped for the whole exit animation.
    */
   #applyHidden(panel) {
     panel.hidden = true;

data/dist/controllers/dropdown_controller.js

@@ -109,40 +109,64 @@ var EscapeLayer = class _EscapeLayer {
   }
 };
 
+// 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/dropdown_controller.ts
 var DropdownController = class extends Controller {
   static targets = ["trigger", "menu"];
   static actions = ["close", "open", "toggle"];
+  static events = ["close", "open"];
   /** 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;
   /** Closes the menu when a click lands outside the controller's element. */
   #onOutsideClick = (event) => {
     if (!this.element.contains(event.target)) {
-      this.close();
+      this.#close("outside");
     }
   };
   /** Starts in the closed state and registers outside-click handling. */
   connect() {
     this.#associateTriggerWithMenu();
-    this.close();
+    this.#close("api");
     document.addEventListener("click", this.#onOutsideClick, true);
+    this.#reporting = true;
   }
   /** Removes the listeners registered in {@link connect}. */
   disconnect() {
+    this.#reporting = false;
     this.#escapeLayer.deactivate();
     document.removeEventListener("click", this.#onOutsideClick, true);
   }
   /** Toggles the menu between open and closed. Bound via `data-action`. */
-  toggle() {
+  toggle(event) {
     if (this.#isOpen) {
-      this.close();
+      this.close(event);
     } else {
-      this.open();
+      this.open(event);
     }
   }
   /** Reveals the menu and reflects the open state on the trigger. */
-  open() {
+  open(event) {
+    this.#open(stateReasonFor(event));
+  }
+  /** Hides the menu and reflects the closed state on the trigger. */
+  close(event) {
+    this.#close(stateReasonFor(event));
+  }
+  /** Reveals the menu, reflects the open state, and reports a move. */
+  #open(reason) {
     if (!this.hasMenuTarget) return;
+    const was = this.#isOpen;
     this.#escapeLayer.activate(document, {
       onDismiss: () => this.#closeAndRestore(),
       claims: claimsWhileFocusWithin(this.element)
@@ -151,19 +175,22 @@ var DropdownController = class extends Controller {
     if (this.hasTriggerTarget) {
       this.triggerTarget.setAttribute("aria-expanded", "true");
     }
+    if (!was && this.#reporting) this.dispatch("open", { detail: { reason }, cancelable: false });
   }
-  /** Hides the menu and reflects the closed state on the trigger. */
-  close() {
+  /** Hides the menu, reflects the closed state, and reports a move. */
+  #close(reason) {
+    const was = this.#isOpen;
     this.#escapeLayer.deactivate();
     if (!this.hasMenuTarget) return;
     this.menuTarget.hidden = true;
     if (this.hasTriggerTarget) {
       this.triggerTarget.setAttribute("aria-expanded", "false");
     }
+    if (was && this.#reporting) this.dispatch("close", { detail: { reason }, cancelable: false });
   }
   /** Closes and restores focus to the trigger (the keyboard-dismissal path). */
   #closeAndRestore() {
-    this.close();
+    this.#close("escape");
     if (this.hasTriggerTarget) this.triggerTarget.focus();
   }
   /** Whether the menu is currently visible. */

data/dist/controllers/editable_controller.js

@@ -3,11 +3,19 @@ import { Controller } from '@hotwired/stimulus';
 // src/controllers/editable_controller.ts
 
 // 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;
@@ -17,6 +25,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. */
@@ -24,29 +33,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/controllers/editable_controller.ts
@@ -79,6 +111,8 @@ var EditableController = class extends Controller {
    * "saves wherever focus moved" true only for focus that leaves the input
    * itself, and tabbing straight past an inner button would strand the editor
    * open.
+   *
+   * @stimeoRuntimeOnly `submitOnBlur` decides whether this one blur commits the edit.
    */
   #onFocusOut = (event) => {
     const from = event.target;