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

Contract: Forms + Validation + Suggestions

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).

Validation

• Surface validation errors inline near fields and in a form-level summary when helpful.
• Validation messages must be human-readable and action-oriented.
• 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.
• 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.