Files
bible/rules/patterns/modal-workflows/contract.md

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.