Files
bible/rules/patterns/forms-validation/contract.md
T

48 lines
2.1 KiB
Markdown

# Contract: Forms + Validation + Suggestions
Version: 1.2
This contract owns validation UX and multi-step flow rules for all form surfaces,
including modals (`modal-workflows` adds only modal-specific mechanics).
## Form Structure
- Group fields semantically and keep labels explicit.
- Inputs requiring suggestions may use `datalist` or equivalent autocomplete UI.
- Suggestion sources must represent the full relevant scope (not only visible rows from paginated tables).
- Size fields by expected content: a short identifier/date beside a flexible name field is
preferable to equal-width columns. Align read-only metadata with adjacent editable values.
- Group editable child rows under the requirement/parent they satisfy, with indentation or
light connector lines. Label row controls even when repeated visible labels are omitted.
- Collapse field groups on narrow screens; retain horizontal scrolling for genuinely tabular
child editors. A fixed desktop width must not make the Save action unreachable.
## Validation
- Validate on submit server-side. Client-side validation is optional progressive enhancement only.
- Surface validation errors inline near fields and in a form-level summary when helpful.
- Validation messages must be human-readable and action-oriented: "Serial number is required" —
not "serial_number: cannot be null".
- Do not hide required-field errors behind generic submit failures.
## Multi-Step Flow
Recommended stages:
1. `edit`
2. `review`
3. `confirm/submit`
4. `result`
Rules:
- Users must be able to return from review to edit without losing entered values.
- The confirm step must summarise what will happen before a destructive or irreversible action.
- Destructive or irreversible actions require explicit confirmation.
- Query- or state-driven step transitions should be deterministic and testable.
## File Inputs in Forms
- If a workflow includes upload, the file control should be clearly labeled and the supported formats explicit.
- Import parsing/preview may be delegated to a dedicated import/export pattern, but the form contract must remain clear.