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

59 lines
2.7 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
- 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).
## 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.
## Topic Contracts
Draft editors also follow the draft contract. The htmx response example applies only to that integration.
- [Modal Drafts and Explicit Save](drafts/contract.md)
- [Server-Rendered Modal Responses](server-rendering/contract.md)