stimeo-ui 0.5.0 → 0.7.0

package/dist/controllers/submit_once_controller.d.ts

@@ -1,48 +1,79 @@
 import { Controller } from '@hotwired/stimulus';
 
-/** Submit-capable controls this controller can disable. */
-type SubmitButton = HTMLButtonElement | HTMLInputElement;
+/** Native controls that can submit a form. */
+type SubmitControl = HTMLButtonElement | HTMLInputElement;
 /**
- * Headless "submit once" behavior: disables the form's submit button(s) on submit
- * to prevent a double submission, optionally swaps in a busy label, and restores
- * on completion. The Headless superset of Rails' `disable_with` (no dedicated APG
- * pattern; follows the WCAG "status messages" practice via `aria-busy`).
+ * Headless form-scoped double-submit guard (identifier:
+ * `stimeo--submit-once`). It disables every native submit control associated
+ * with the submitting form, publishes busy state, and restores only the state
+ * it still owns when the operation finishes.
  *
- * Markup contract (identifier: `stimeo--submit-once`):
- *   <form data-controller="stimeo--submit-once"
- *         data-stimeo--submit-once-busy-label-value="Submitting…">
- *     <button type="submit" data-stimeo--submit-once-target="submit">Send</button>
- *   </form>
+ * Turbo forms need no `data-action`: the controller observes
+ * `turbo:submit-start` and `turbo:submit-end` itself.
  *
- * Zero wiring for Turbo forms: `connect()` subscribes to `turbo:submit-start`
- * itself (symmetric with the `turbo:submit-end` it already listens for), so no
- * `data-action` is required. The public {@link start} action stays available for
- * **non-Turbo** forms, where you bind it to the native event yourself:
- * `data-action="submit->stimeo--submit-once#start"`. Re-entrancy is guarded — once
- * busy, a second `start` (auto + manual, or a duplicate event) no-ops.
+ * A non-Turbo async form owns its own lifecycle and declares each transition:
+ * `submit->stimeo--submit-once#start` applies the busy state synchronously,
+ * before the request is issued, and `#finish` / `#cancel` end it. Cancelling the
+ * event's default is how such a form suppresses the native navigation, so it
+ * never means the submission died — only `#cancel` does. A submit already
+ * cancelled by an earlier listener never starts a session at all.
  *
- * On submit it disables every `submit` target (or, with none, the form's native
- * `button[type=submit]` / `input[type=submit]`), sets `aria-busy` on them and
- * `data-submitting` on the form, and swaps the **triggering** button's visible
- * label for the busy label (per-button `data-submit-once-busy-label` overrides the
- * form's `busyLabel` Value). It restores on Turbo's `turbo:submit-end`, or after
- * `timeout` ms, re-enabling the buttons and putting the labels back.
+ * ```html
+ * <form data-controller="stimeo--submit-once"
+ *       data-action="submit->stimeo--submit-once#start
+ *                    save:complete->stimeo--submit-once#finish
+ *                    save:error->stimeo--submit-once#cancel">
+ *   <button type="submit">Save</button>
+ * </form>
+ * ```
+ *
+ * A form whose submit a later listener vetoes needs `#cancel` wired to that
+ * veto, or a non-zero `timeout`, to leave the busy state.
+ *
+ * Plain text buttons can use `busyLabel` (overridden by
+ * `data-submit-once-busy-label`). A button with authored structure instead uses
+ * an `idle` / `busy` target pair inside that button, so icons and descendants
+ * are never replaced with `textContent`:
+ *
+ * ```html
+ * <form data-controller="stimeo--submit-once"
+ *       data-stimeo--submit-once-announce-text-value="Saving…"
+ *       data-stimeo--submit-once-announce-ready-text-value="Saved.">
+ *   <button type="submit" data-stimeo--submit-once-target="submit">
+ *     <span data-stimeo--submit-once-target="idle">Save</span>
+ *     <span data-stimeo--submit-once-target="busy" hidden>Saving…</span>
+ *   </button>
+ * </form>
+ * ```
+ *
+ * Events:
+ * - `stimeo--submit-once:start` — `{ form, submitter }`.
+ * - `stimeo--submit-once:end` — `{ form, submitter, reason, success? }`, where
+ *   `reason` is `"turbo"`, `"timeout"`, `"manual"`, or `"canceled"`. Only
+ *   `"canceled"` skips the completion announcement, because no operation ran.
  *
  * @remarks
- * Behavior only — no spinner is drawn (pair with {@link "spinner"}). The submit-end
- * listener and the timeout are torn down on `disconnect()` (Turbo navigation
- * included), and `connect()` clears any stale busy state parked in a restored cache
- * snapshot so a button is never left disabled. Non-Turbo caveat: the buttons are
- * disabled synchronously inside the `submit` handler, and a plain HTML submission
- * builds its entry list *after* that event — so a disabled submitter's `name`/`value`
- * is excluded from the payload. Turbo is unaffected (it appends the submitter's
- * name/value from attributes when building `FormData`); mirror the value into a
- * hidden field when a non-Turbo form depends on it.
+ * Behavior only: the consumer owns every visual, label, and announcement
+ * string. `announceText` / `announceReadyText` are empty by default and speak
+ * through the page's shared `stimeo--announcer` only on real state transitions.
+ * Attribute writes use {@link AttributeLease}, so a consumer mutation made
+ * while busy wins over restoration. {@link DetachGate} preserves an in-flight
+ * session across an in-page move, while {@link BeforeCacheReset} rewinds the
+ * snapshot before Turbo caches it. Cache/detach rewinds are silent and never
+ * move focus.
  */
 declare class SubmitOnceController extends Controller<HTMLElement> {
     #private;
     static targets: string[];
     static values: {
+        announceText: {
+            type: StringConstructor;
+            default: string;
+        };
+        announceReadyText: {
+            type: StringConstructor;
+            default: string;
+        };
         busyLabel: {
             type: StringConstructor;
             default: string;
@@ -56,21 +87,46 @@ declare class SubmitOnceController extends Controller<HTMLElement> {
             default: boolean;
         };
     };
-    static actions: readonly ["start"];
+    static actions: readonly ["cancel", "finish", "start"];
     static events: readonly ["start", "end"];
-    readonly submitTargets: SubmitButton[];
-    readonly hasSubmitTarget: boolean;
+    readonly submitTargets: SubmitControl[];
+    readonly idleTargets: HTMLElement[];
+    readonly busyTargets: HTMLElement[];
+    announceTextValue: string;
+    announceReadyTextValue: string;
     busyLabelValue: string;
     timeoutValue: number;
     restoreFocusValue: boolean;
     connect(): void;
     disconnect(): void;
     /**
-     * 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: Event): void;
+    /**
+     * 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?: Event): void;
+    /**
+     * 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?: Event): void;
+    /** Disables a newly connected explicit submit target during its form's session. */
+    submitTargetConnected(target: SubmitControl): void;
 }
 
 export { SubmitOnceController };