76 lines
3.9 KiB
Markdown
76 lines
3.9 KiB
Markdown
# Contract: Modal Workflows
|
|
|
|
Version: 1.4
|
|
|
|
## 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
|
|
|
|
- Use one shared modal shell and behavior for every modal. Individual dialogs
|
|
supply their title, content and actions; they do not reimplement shell layout,
|
|
dismissal, busy handling or wizard navigation controls.
|
|
- Place the close control at the left of the header, as in macOS, and center
|
|
the title in the modal. Place wizard back and next controls beside the close
|
|
control, using a matching left/right icon pair visually separated from close.
|
|
Keep both arrows visible on every step and disable unavailable directions.
|
|
Put the highlighted, icon-only save action at the far right of the header on
|
|
every step; validate the workflow when it is submitted. Keep other header
|
|
actions accessible without overlapping the title, including on narrow screens.
|
|
- Modal footers contain no icon buttons. Where an action belongs in the footer,
|
|
use a text-labelled button that states the action. Do not hide required actions.
|
|
- 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 `submitting` state).
|
|
- 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
|
|
`click` handler with `event.target === backdrop` is not enough: the browser fires `click` on
|
|
the common ancestor of the press and release targets, which is the backdrop. Record the
|
|
`pointerdown`/`mousedown` target 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-Trigger` header, 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.
|