stimeo-ui 0.6.0 → 0.7.0

package/dist/controllers/submit_once_controller.js

@@ -2,6 +2,142 @@ import { Controller } from '@hotwired/stimulus';
 
 // src/controllers/submit_once_controller.ts
 
+// src/utils/announce.ts
+function announce(message, options = {}) {
+  const text = message.trim();
+  if (text.length === 0) return;
+  window.dispatchEvent(
+    new CustomEvent("stimeo--announcer:announce", {
+      detail: { message: text, assertive: options.assertive === true }
+    })
+  );
+}
+
+// src/utils/attribute_lease.ts
+var AttributeLease = class {
+  #attribute;
+  #records = /* @__PURE__ */ new Map();
+  /** @param attribute - The attribute whose temporary values this lease owns. */
+  constructor(attribute) {
+    this.#attribute = attribute;
+  }
+  /** Writes or removes the leased attribute while preserving its authored value. */
+  write(element, value) {
+    const existing = this.#records.get(element);
+    if (existing) {
+      existing.written = value;
+    } else {
+      this.#records.set(element, {
+        original: element.getAttribute(this.#attribute),
+        written: value
+      });
+    }
+    this.#reflect(element, value);
+  }
+  /** Returns one lease without overwriting a value subsequently authored by a consumer. */
+  return(element) {
+    const record = this.#records.get(element);
+    if (!record) return;
+    this.#records.delete(element);
+    const stillOwned = element.getAttribute(this.#attribute) === record.written;
+    if (stillOwned) this.#reflect(element, record.original);
+  }
+  /** Reflects only a real value transition, avoiding self-triggered mutation work. */
+  #reflect(element, value) {
+    if (element.getAttribute(this.#attribute) === value) return;
+    if (value === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, value);
+  }
+  /** Returns every outstanding lease using the same ownership check as {@link return}. */
+  returnAll() {
+    for (const element of Array.from(this.#records.keys())) this.return(element);
+  }
+};
+
+// src/utils/before_cache_reset.ts
+var BeforeCacheReset = class _BeforeCacheReset {
+  /** Every subscribed instance, iterated by the one shared document listener. */
+  static #subscribers = /* @__PURE__ */ new Set();
+  /** The shared listener; installed while at least one instance is subscribed. */
+  static #onBeforeCache = () => {
+    for (const subscriber of _BeforeCacheReset.#subscribers) subscriber.#rewind();
+  };
+  #rewind;
+  /** @param rewind - the pass that returns this controller's state to its initial form. */
+  constructor(rewind) {
+    this.#rewind = rewind;
+  }
+  /** Subscribes to `turbo:before-cache`; call from `connect()`. Idempotent. */
+  activate() {
+    const first = _BeforeCacheReset.#subscribers.size === 0;
+    _BeforeCacheReset.#subscribers.add(this);
+    if (first) {
+      document.addEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+    }
+  }
+  /** Unsubscribes; call from `disconnect()`. Safe when never subscribed. */
+  deactivate() {
+    _BeforeCacheReset.#subscribers.delete(this);
+    if (_BeforeCacheReset.#subscribers.size > 0) return;
+    document.removeEventListener("turbo:before-cache", _BeforeCacheReset.#onBeforeCache);
+  }
+};
+
+// src/utils/detach_gate.ts
+var DetachGate = class _DetachGate {
+  /** Set while a probe is queued, waiting for a reconnect to cancel it. */
+  #pending = false;
+  /**
+   * True while a probe is queued — the last disconnect was ambiguous and no
+   * reconnect has cancelled it yet. Read it from `connect()` to tell the
+   * reconnect half of an in-page move from a first connect: a controller whose
+   * initialisation restarts a measurement (a min-duration floor, an elapsed
+   * counter) must skip it for the move, where nothing actually restarted.
+   */
+  get pending() {
+    return this.#pending;
+  }
+  /**
+   * True when the disconnect is definitely a real detach — the element left
+   * the document, or `data-controller` no longer lists the identifier. False
+   * means ambiguous (in-page move or observed-root exit), NOT "alive".
+   */
+  static isDetached(host) {
+    if (!host.element.isConnected) return true;
+    const tokens = (host.element.getAttribute("data-controller") ?? "").split(/\s+/);
+    return !tokens.includes(host.identifier);
+  }
+  /**
+   * Call from `disconnect()`: runs `teardown` synchronously on a definite
+   * detach (fast path), otherwise defers it one microtask — a reconnect
+   * ({@link cancel} from `connect()`) keeps the state, no reconnect runs it.
+   * One microtask is the whole probe window: Stimulus reconnects a moved
+   * element within the same mutation batch, before the checkpoint drains.
+   */
+  disconnected(host, teardown) {
+    if (_DetachGate.isDetached(host)) {
+      this.#pending = false;
+      teardown();
+      return;
+    }
+    this.#pending = true;
+    queueMicrotask(() => {
+      if (!this.#pending) return;
+      this.#pending = false;
+      teardown();
+    });
+  }
+  /**
+   * Disarms a pending probe. Call from `connect()` (the reconnect that proves
+   * an in-page move) and from the head of any teardown path not routed through
+   * {@link disconnected} (disabled-toggle, Escape), so an orphaned probe can
+   * never run the teardown a second time.
+   */
+  cancel() {
+    this.#pending = false;
+  }
+};
+
 // src/utils/safe_timeout.ts
 var TimerRegistry = class {
   /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
@@ -56,169 +192,311 @@ var SafeTimeout = class extends TimerRegistry {
 };
 
 // src/controllers/submit_once_controller.ts
-var ORIGINAL_LABEL = "data-submit-once-original-label";
-var DISABLED_MARKER = "data-submit-once-disabled";
 var BUTTON_BUSY_LABEL = "data-submit-once-busy-label";
 var SubmitOnceController = class extends Controller {
-  static targets = ["submit"];
+  static targets = ["submit", "idle", "busy"];
   static values = {
+    announceText: { type: String, default: "" },
+    announceReadyText: { type: String, default: "" },
     busyLabel: { type: String, default: "" },
     timeout: { type: Number, default: 0 },
     restoreFocus: { type: Boolean, default: false }
   };
-  static actions = ["start"];
+  static actions = ["cancel", "finish", "start"];
   static events = ["start", "end"];
-  #timeouts = new SafeTimeout();
-  #timeoutId = null;
-  #busy = false;
-  #submitter = null;
+  #timers = new SafeTimeout();
+  #gate = new DetachGate();
+  #beforeCache = new BeforeCacheReset(() => this.#rewindForCache());
+  #sessions = /* @__PURE__ */ new Map();
+  #disabled = new AttributeLease("disabled");
+  #controlBusy = new AttributeLease("aria-busy");
+  #formBusy = new AttributeLease("aria-busy");
+  #submitting = new AttributeLease("data-submitting");
+  #ariaLabel = new AttributeLease("aria-label");
+  #hidden = new AttributeLease("hidden");
   #onSubmitStart = (event) => {
     this.start(event);
   };
   #onSubmitEnd = (event) => {
-    const success = event.detail?.success;
-    this.#restore(success);
+    this.#complete(this.#eventForm(event), "turbo", this.#eventSuccess(event));
+  };
+  /** Blocks a later native submit while one for the same form is still active. */
+  #onNativeSubmit = (event) => {
+    const session = this.#sessionFor(event.target);
+    if (!session) return;
+    this.#syncControls(session);
+    event.preventDefault();
   };
   connect() {
+    this.#gate.cancel();
+    this.#beforeCache.activate();
+    this.element.addEventListener("submit", this.#onNativeSubmit, true);
     this.element.addEventListener("turbo:submit-start", this.#onSubmitStart);
     this.element.addEventListener("turbo:submit-end", this.#onSubmitEnd);
-    this.#clearStaleBusy();
   }
   disconnect() {
+    this.element.removeEventListener("submit", this.#onNativeSubmit, true);
     this.element.removeEventListener("turbo:submit-start", this.#onSubmitStart);
     this.element.removeEventListener("turbo:submit-end", this.#onSubmitEnd);
-    this.#clearTimeout();
+    this.#beforeCache.deactivate();
+    this.#gate.disconnected(this, () => this.#teardown());
   }
   /**
-   * Enters the busy state for the submission started by `event`. Accepts both a
-   * native `SubmitEvent` (manual `submit->#start` on non-Turbo forms) and Turbo's
-   * `turbo:submit-start` CustomEvent (auto-subscribed in `connect`).
+   * Begins the submission represented by `event`.
+   *
+   * Native `submit` events are intended for non-Turbo async forms. Turbo calls
+   * this path through its auto-subscribed `turbo:submit-start` event. An event
+   * whose default an earlier listener already cancelled carries no submission,
+   * so it starts nothing.
    */
   start(event) {
-    if (this.#busy) return;
-    this.#busy = true;
-    const buttons = this.#buttons;
-    const submitter = this.#resolveSubmitter(event, buttons);
-    this.#submitter = submitter;
-    for (const button of buttons) {
-      this.#enterBusy(button, button === submitter);
-    }
-    this.element.setAttribute("data-submitting", "true");
-    this.element.setAttribute("aria-busy", "true");
-    this.dispatch("start", { detail: {} });
+    if (event.defaultPrevented) return;
+    const form = this.#eventForm(event);
+    if (!form || this.#sessions.has(form)) return;
+    const controls = this.#submitControls(form);
+    const submitter = this.#resolveSubmitter(event, controls);
+    const session = {
+      form,
+      submitter,
+      submitterHadFocus: submitter !== null && document.activeElement === submitter,
+      controls: /* @__PURE__ */ new Set(),
+      timeoutId: null,
+      labelWrite: null,
+      idlePart: null,
+      busyPart: null
+    };
+    this.#sessions.set(form, session);
+    this.#formBusy.write(form, "true");
+    this.#submitting.write(form, "true");
+    this.#syncControls(session, controls);
+    this.#enterLabel(session);
+    this.dispatch("start", { detail: { form, submitter } });
     if (this.timeoutValue > 0) {
-      this.#timeoutId = this.#timeouts.set(() => this.#restore(false), this.timeoutValue);
-    }
-  }
-  /** Restores the non-busy state, re-enabling buttons and putting labels back. */
-  #restore(success) {
-    if (!this.#busy) return;
-    this.#busy = false;
-    this.#clearTimeout();
-    for (const button of this.#buttons) {
-      this.#exitBusy(button);
-    }
-    this.element.removeAttribute("data-submitting");
-    this.element.removeAttribute("aria-busy");
-    this.dispatch("end", { detail: { success } });
-    if (this.restoreFocusValue && this.#submitter) {
-      this.#submitter.focus();
-    }
-    this.#submitter = null;
-  }
-  /** Disables a button, marks it busy, and swaps the trigger's label. */
-  #enterBusy(button, isTrigger) {
-    if (!button.disabled) {
-      button.disabled = true;
-      button.setAttribute(DISABLED_MARKER, "true");
-      button.setAttribute("aria-busy", "true");
-    }
-    if (!isTrigger) return;
-    const label = button.getAttribute(BUTTON_BUSY_LABEL) ?? this.busyLabelValue;
+      session.timeoutId = this.#timers.set(
+        () => this.#complete(form, "timeout", false),
+        this.timeoutValue
+      );
+    }
+    announce(this.announceTextValue);
+  }
+  /**
+   * Completes a non-Turbo async submission for the form associated with
+   * `event`. When called directly with no event, it completes the controller's
+   * sole active form (or the controller element itself when it is a form).
+   */
+  finish(event) {
+    const form = event ? this.#eventForm(event) : this.#defaultForm();
+    this.#complete(form, "manual", event ? this.#eventSuccess(event) : void 0);
+  }
+  /**
+   * Abandons the submission for the form associated with `event` because it
+   * never reached the network — a veto from validation, or a request the
+   * consumer gave up before sending. With no event it targets the controller's
+   * sole active form, exactly like {@link finish}.
+   *
+   * The distinction from `finish` is observable: a request that ran and failed
+   * is `finish` with `success: false` and still announces completion, while a
+   * submission that never happened announces nothing.
+   */
+  cancel(event) {
+    const form = event ? this.#eventForm(event) : this.#defaultForm();
+    this.#complete(form, "canceled", false);
+  }
+  /** Disables a newly connected explicit submit target during its form's session. */
+  submitTargetConnected(target) {
+    const session = this.#sessionFor(target.form);
+    if (!session || !this.#isNativeSubmitControl(target)) return;
+    this.#enterControl(session, target);
+  }
+  /** Ends one session, restores owned state, and reports the observable completion. */
+  #complete(form, reason, success) {
+    const session = this.#sessionFor(form);
+    if (!session) return;
+    this.#sessions.delete(session.form);
+    this.#returnSessionState(session);
+    const detail = success === void 0 ? { form: session.form, submitter: session.submitter, reason } : { form: session.form, submitter: session.submitter, reason, success };
+    this.dispatch("end", { detail });
+    this.#restoreFocus(session);
+    if (reason !== "canceled") announce(this.announceReadyTextValue);
+  }
+  /** Applies the busy state to every current native/explicit control exactly once. */
+  #syncControls(session, controls = this.#submitControls(session.form)) {
+    for (const control of controls) this.#enterControl(session, control);
+  }
+  /** Temporarily disables one enabled submit control while retaining authored state. */
+  #enterControl(session, control) {
+    if (session.controls.has(control) || control.matches(":disabled")) return;
+    session.controls.add(control);
+    this.#disabled.write(control, "");
+    this.#controlBusy.write(control, "true");
+  }
+  /** Swaps only the triggering control's safe label channel. */
+  #enterLabel(session) {
+    const control = session.submitter;
+    if (!control) return;
+    const idlePart = this.#partInside(control, this.idleTargets);
+    const busyPart = this.#partInside(control, this.busyTargets);
+    if (idlePart && busyPart) {
+      session.idlePart = idlePart;
+      session.busyPart = busyPart;
+      this.#hidden.write(idlePart, "");
+      this.#hidden.write(busyPart, null);
+    }
+    const label = control.getAttribute(BUTTON_BUSY_LABEL) ?? this.busyLabelValue;
     if (label.length === 0) return;
-    if (!button.hasAttribute(ORIGINAL_LABEL)) {
-      button.setAttribute(ORIGINAL_LABEL, this.#getLabel(button));
+    if (control instanceof HTMLInputElement) {
+      if (control.type !== "submit") return;
+      session.labelWrite = {
+        channel: "value",
+        control,
+        original: control.value,
+        written: label
+      };
+      control.value = label;
+      return;
     }
-    this.#setLabel(button, label);
+    if (control.hasAttribute("aria-label")) {
+      this.#ariaLabel.write(control, label);
+      return;
+    }
+    if (control.childElementCount > 0) return;
+    session.labelWrite = {
+      channel: "text",
+      control,
+      original: control.textContent ?? "",
+      written: label
+    };
+    control.textContent = label;
   }
-  /** Re-enables a button we disabled and restores its parked label, if any. */
-  #exitBusy(button) {
-    if (button.hasAttribute(DISABLED_MARKER)) {
-      button.disabled = false;
-      button.removeAttribute(DISABLED_MARKER);
-      button.removeAttribute("aria-busy");
+  /** Returns labels, controls, and form hooks, respecting intervening consumer writes. */
+  #returnSessionState(session) {
+    if (session.timeoutId !== null) {
+      this.#timers.clear(session.timeoutId);
+      session.timeoutId = null;
+    }
+    if (session.labelWrite?.channel === "value") {
+      const { control, original, written } = session.labelWrite;
+      if (control.value === written) control.value = original;
+    } else if (session.labelWrite?.channel === "text") {
+      const { control, original, written } = session.labelWrite;
+      if (control.childElementCount === 0 && control.textContent === written) {
+        control.textContent = original;
+      }
     }
-    const original = button.getAttribute(ORIGINAL_LABEL);
-    if (original !== null) {
-      this.#setLabel(button, original);
-      button.removeAttribute(ORIGINAL_LABEL);
+    session.labelWrite = null;
+    if (session.submitter instanceof HTMLButtonElement) {
+      this.#ariaLabel.return(session.submitter);
     }
+    if (session.idlePart) this.#hidden.return(session.idlePart);
+    if (session.busyPart) this.#hidden.return(session.busyPart);
+    session.idlePart = null;
+    session.busyPart = null;
+    for (const control of session.controls) {
+      this.#controlBusy.return(control);
+      this.#disabled.return(control);
+    }
+    session.controls.clear();
+    this.#submitting.return(session.form);
+    this.#formBusy.return(session.form);
   }
-  /** Resets busy state left in a restored cache snapshot without firing events. */
-  #clearStaleBusy() {
-    this.#busy = false;
-    if (this.element.hasAttribute("data-submitting")) {
-      this.element.removeAttribute("data-submitting");
-      this.element.removeAttribute("aria-busy");
+  /** Restores focus only when disabling the focused submitter actually stranded it. */
+  #restoreFocus(session) {
+    const submitter = session.submitter;
+    if (!this.restoreFocusValue || !session.submitterHadFocus || !submitter?.isConnected) return;
+    const active = document.activeElement;
+    if (active === null || active === document.body || active === document.documentElement) {
+      submitter.focus();
     }
-    for (const button of this.#buttons) {
-      this.#exitBusy(button);
+  }
+  /** Silently abandons every session before caching or on a real detach. */
+  #abandonSessions() {
+    this.#timers.clearAll();
+    for (const session of this.#sessions.values()) {
+      session.timeoutId = null;
+      this.#returnSessionState(session);
     }
+    this.#sessions.clear();
   }
-  /** The triggering button: the event's submitter when ours, else the first button. */
-  #resolveSubmitter(event, buttons) {
-    const submitter = this.#eventSubmitter(event);
-    if (submitter && this.#isSubmitButton(submitter) && buttons.includes(submitter)) {
-      return submitter;
+  /** Keeps Turbo's cached snapshot idle, without events, announcements, or focus moves. */
+  #rewindForCache() {
+    this.#abandonSessions();
+  }
+  /** Tears down a true detach; an in-page move is canceled by the next `connect()`. */
+  #teardown() {
+    this.#gate.cancel();
+    this.#abandonSessions();
+  }
+  /** All native controls associated with `form`, plus valid explicit targets. */
+  #submitControls(form) {
+    const controls = /* @__PURE__ */ new Set();
+    for (const element of Array.from(form.elements)) {
+      if (this.#isNativeSubmitControl(element)) controls.add(element);
+    }
+    const root = form.getRootNode();
+    for (const image of root.querySelectorAll('input[type="image"]')) {
+      if (image.form === form) controls.add(image);
     }
-    return buttons[0] ?? null;
+    return Array.from(controls);
   }
-  /**
-   * Reads the submitter from a native `SubmitEvent` (`event.submitter`) or from
-   * Turbo's `turbo:submit-start` detail (`detail.formSubmission.submitter`), so
-   * the busy label swaps onto the right button under either path.
-   */
+  /** Resolves the real submitter, falling back to the first enabled submit control. */
+  #resolveSubmitter(event, controls) {
+    const submitter = this.#eventSubmitter(event);
+    if (submitter && controls.includes(submitter)) return submitter;
+    return controls.find((control) => !control.matches(":disabled")) ?? controls[0] ?? null;
+  }
+  /** Reads a native or Turbo submitter without assuming `SubmitEvent` exists. */
   #eventSubmitter(event) {
     if (typeof SubmitEvent !== "undefined" && event instanceof SubmitEvent) {
-      return event.submitter;
+      return this.#isNativeSubmitControl(event.submitter) ? event.submitter : null;
     }
     const detail = event.detail;
-    return detail?.formSubmission?.submitter ?? null;
-  }
-  /** The controlled buttons: `submit` targets, or the form's native submit controls. */
-  get #buttons() {
-    if (this.hasSubmitTarget) return this.submitTargets;
-    return Array.from(
-      this.element.querySelectorAll('button[type="submit"], input[type="submit"]')
-    );
-  }
-  #isSubmitButton(el) {
-    return el instanceof HTMLButtonElement || el instanceof HTMLInputElement;
-  }
-  /** Reads a button's visible label (input value, aria-label, or text). */
-  #getLabel(button) {
-    if (button instanceof HTMLInputElement) return button.value;
-    const aria = button.getAttribute("aria-label");
-    if (aria !== null) return aria;
-    return button.textContent ?? "";
-  }
-  /** Writes a button's visible label through the same channel it was read from. */
-  #setLabel(button, text) {
-    if (button instanceof HTMLInputElement) {
-      button.value = text;
-      return;
-    }
-    if (button.hasAttribute("aria-label")) {
-      button.setAttribute("aria-label", text);
-      return;
-    }
-    button.textContent = text;
+    const submitter = detail?.formSubmission?.submitter;
+    return this.#isNativeSubmitControl(submitter) ? submitter : null;
+  }
+  /** Finds the form represented by an action/Turbo event and verifies this scope owns it. */
+  #eventForm(event) {
+    const detail = event.detail;
+    const target = event.target;
+    const candidate = (target instanceof HTMLFormElement ? target : null) ?? (target instanceof Element ? target.closest("form") : null) ?? detail?.formSubmission?.formElement ?? detail?.form ?? this.#eventSubmitter(event)?.form ?? (this.element instanceof HTMLFormElement ? this.element : null);
+    return candidate && this.#ownsForm(candidate) ? candidate : null;
   }
-  #clearTimeout() {
-    if (this.#timeoutId !== null) {
-      this.#timeouts.clear(this.#timeoutId);
-      this.#timeoutId = null;
+  /** The only unambiguous form for a direct `finish()` call. */
+  #defaultForm() {
+    if (this.element instanceof HTMLFormElement && this.#ownsForm(this.element))
+      return this.element;
+    if (this.#sessions.size === 1) return this.#sessions.keys().next().value ?? null;
+    return null;
+  }
+  /** Prevents an ancestor controller from also taking over a nested instance's form. */
+  #ownsForm(form) {
+    let candidate = form;
+    while (candidate) {
+      const identifiers = (candidate.getAttribute("data-controller") ?? "").split(/\s+/);
+      if (identifiers.includes(this.identifier)) return candidate === this.element;
+      candidate = candidate.parentElement;
     }
+    return false;
+  }
+  /** Returns the active session for a form-shaped external event value. */
+  #sessionFor(candidate) {
+    if (!(candidate instanceof HTMLFormElement)) return void 0;
+    return this.#sessions.get(candidate);
+  }
+  /** Effective native submit controls, including implicit buttons and image inputs. */
+  #isNativeSubmitControl(element) {
+    if (element instanceof HTMLButtonElement) return element.type === "submit";
+    return element instanceof HTMLInputElement && (element.type === "submit" || element.type === "image");
+  }
+  /** Finds a structured label part belonging to this button, not a nested control. */
+  #partInside(control, parts) {
+    return parts.find(
+      (part) => control.contains(part) && part.closest("button, input[type=submit], input[type=image]") === control
+    ) ?? null;
+  }
+  /** Reads an optional boolean `success` from Turbo or a manual completion event. */
+  #eventSuccess(event) {
+    const success = event.detail?.success;
+    return typeof success === "boolean" ? success : void 0;
   }
 };