modal-workflows 1.3: a backdrop close needs the press and the release on the backdrop; the page behind an open modal does not scroll. controls-selection 1.4: dropdowns open upward when there is no room below and never leave the viewport. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
3.0 KiB
3.0 KiB
Contract: Modal Workflows
Version: 1.3
State Machine
Every modal has exactly these states:
closed → open → submitting → success | error
↓
cancel → closed
open: form visible, submit enabled.submitting: form disabled, spinner on submit button, no double-submit possible.success: close modal, show toast, refresh affected data.error: stay open, show error message inline, re-enable form.cancel: close without changes, no confirmation needed unless form is dirty.
Rules
- Destructive actions (delete, archive, bulk remove) require a separate confirmation modal — not just a disabled button. Confirmation modal must name the target: "Delete component ABC-123?"
- Never close a modal automatically on error — keep it open so the user can retry or copy the error.
- Submit button text must describe the action: "Save", "Delete", "Archive" — not "OK" or "Confirm".
- Modal title must match the action: "Edit Component", "Delete Asset" — not generic "Modal".
- Escape key and clicking the backdrop close the modal (unless in
submittingstate). - A backdrop close requires the whole click on the backdrop: the pointer must go down AND come
up on it. A press that starts inside the dialog (selecting text in an input, dragging a slider
or scrollbar) and is released outside it must NOT close the modal. A bare
clickhandler withevent.target === backdropis not enough: the browser firesclickon the common ancestor of the press and release targets, which is the backdrop. Record thepointerdown/mousedowntarget and close only when it is the backdrop too. - Implement this once, in shared modal code that covers every modal in the app, not per modal.
- While a modal is open the page behind it must not scroll. Wheel, touch and keyboard scrolling move the dialog only, and reaching the dialog's end must not chain to the page. Reserve the scrollbar gutter so locking the page does not shift the layout under the backdrop.
Validation
Validation UX follows the forms-validation contract (server-side on submit, inline field
errors, form-level summary, human-readable messages).
htmx Pattern (server-rendered modals)
POST /api/entity → 200 OK + HX-Trigger: "entitySaved" (success)
→ 422 Unprocessable + partial HTML (validation error, re-render form)
→ 500 + error message (server error)
- On success: server sends
HX-Triggerheader, JS listener closes modal and refreshes list. - On validation error: server re-renders the form partial with inline errors (422, per
go-api). - On server error: show generic error toast, log full error server-side.
Multi-Step Modals
Staged flows follow the forms-validation multi-step rules. Modal-specific:
- Use only when the workflow genuinely requires staged input (e.g. import preview → confirm).
- Show a step indicator (Step 1 of 3).
- Single-step edits must NOT be split into multi-step without good reason.