Defines a settings screen with explicit section-level saves, clear dirty and pending states, safe navigation, permission-aware controls, and recoverable concurrent-edit behavior.
Package status: reference context ready for human review. The contract and test scenarios are complete, but no claim is made that an adopting implementation has passed them.
Decision
Use explicit Save per coherent settings section. Keep draft values local until validation succeeds, serialize a version with each save, and never make a failed request look persisted.
Scope
- Section navigation, dirty state, validation, save lifecycle, permissions, and concurrent changes.
- Deep links to sections and restoration after authentication.
- Accessible feedback for successful and failed saves.
Outside this block
- The domain semantics of every possible setting.
- An autosave implementation or a generic form-building framework.
Contract
- Each section owns its draft, validation, save, and reset state; saving one section does not submit unrelated drafts.
- Save is enabled only for authorized users with valid changes and is disabled while that section is pending.
- Navigating away with unsaved changes triggers a single clear choice to discard, stay, or save when saving is possible.
- Server validation maps errors to fields and a summary without erasing valid draft values.
- A successful response replaces the base version and announces the changed section; a transport success without a committed version is not success.
- Read-only controls explain why they cannot be changed without exposing permissions the viewer should not know.
Implementation guidance
- Use a version or ETag per settings resource to detect concurrent edits.
- Keep URL section identifiers stable and independent of translated labels.
- Return normalized persisted values so the client does not guess server transformations.
- Focus the error summary on submit failure and link each entry to its field.
Failure handling and safeguards
- On a version conflict, preserve the draft and show server-versus-draft differences; do not last-write-wins silently.
- On network uncertainty, query the resource version before offering another save.
- If authorization changes while the page is open, reject the mutation and refresh capabilities without discarding the draft.
Verification and operations
- Measure save success, validation failure, conflict rate, abandoned dirty drafts, and time in pending state.
- Test direct section URLs, back navigation, refresh, keyboard traversal, and screen-reader announcements.
- Review settings with high support volume for wording or grouping changes.
The executable-looking examples in this package are fixtures and acceptance contracts. Run
python tools/validate.py from the collection root to check package structure and metadata; then
implement and execute the scenarios in the target repository.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - The adopting team must map actors, data classes, error vocabulary, and ownership to its system.
References
- No external normative source is required; this package defines a project decision.