Submission & Pending State

## What a submission's pending state is A submit is not an instant. It is a **unit of work** with a beginning, an in-flight period, and a settlement that is either a success or a failure. The **pending state** is the part of that unit the interface renders while the work is in flight. It is one value per submission — not one per button, and not a loose collection of booleans scattered across the form. Three jobs sit on it: 1. **Acknowledge.** The user pressed something; the screen must change almost immediately, or they will reasonably conclude nothing happened and press again. 2. **Guard cheaply.** While one write is in flight, the control that started it should not start a second identical one. 3. **Stay honest.** Nothing may read as saved, and no value may be cleared, before the response says so. ## Derive the flag, do not sprinkle it Set the value once as the handler begins, and clear it in a path that also runs when the request rejects **or when the handler throws before the request is even sent**. A pending value cleared only on the success path is the most common bug in hand-rolled submission code: one failure and the form is disabled until a reload. Where the framework tracks an in-flight submission itself — exposing that submission's pending status, its returned result and its error as one tracked thing — prefer it over three hand-kept values. It settles even when the handler throws, and every control that needs the status reads one source instead of being handed the flag down a chain of inputs. How soon a just-written flag can be read back differs by reactivity model. In a runtime that re-runs the component function on each state write, the handler keeps reading the value captured in the run that created it and sees the new one only on the next run. In a fine-grained runtime, the write is visible to the next read straight away. In a compile-time runtime the assignment is rewritten into a notification, but the re-render is still scheduled rather than immediate. That gap does not matter for rendering a spinner; it matters a great deal when you want the flag to also block a second submission inside the same frame. ## What to disable, and what to leave alone - Disable the **submit control**, not every field. A user re-reading what they typed loses focus and context when the whole form goes inert, and in a browser host disabled controls also drop out of the submitted field set — which breaks you badly if you ever fall back to native submission. - Do **not** unmount the control and render something else in its place. Focus is lost, and assistive technology gets a removal rather than a state change. - Keep the control's **accessible name stable**. Add a busy state and, if you like, a visible label change; do not replace text with a bare spinner glyph. - In a browser host, if the disabled control is the form's **default button**, pressing Enter in a text field no longer submits either — a useful side effect, but only for that one path. ## Feedback the disabled attribute does not give you - A **polite live region** that announces `Saving…` and then the outcome. A control flipping to disabled announces nothing by itself. - A **short delay** — a couple of hundred milliseconds — before showing a spinner, so a fast response does not flash. - For genuinely slow work, a line that says so, and a way out (cancel, or leave-and-notify), rather than an indefinite spinner. - **Never clear the values on send.** If the request fails, everything the user typed must still be there. ## Settlement | Outcome | Pending | Values | Errors | Focus | |---|---|---|---|---| | Success, stay on the screen | clear | reset for a create-another flow, keep for an edit and re-baseline what is dirty | clear | leave where it is, announce the result | | Success, navigate away | keep until the next screen commits, so the old form does not flash back to enabled | irrelevant once replaced | clear | move to the new screen's heading | | Failure | clear | keep every value exactly as typed | show the message, per field where you can map it | move to the first offending field or the summary | | Superseded or abandoned | clear for the current submission only | keep | ignore the late response | unchanged | ## The limit of this guard Disabling the control is feedback first and a convenience guard second. It closes the path through that control, and nothing more. Duplicate writes can still arrive from another submission path, from a remount that resets the flag, or from a retry after a lost response — so the correctness story ends at an idempotent write on the server side, not at an attribute in the markup.