Split shared UI knowledge into atomic topic directories

This commit is contained in:
mchus committed 2026-10-03 09:28:15 +03:00
1 parent 08ff987edb
commit b0e6402d66
37 files changed
+600 -516

No files matched your search

@@ -0,0 +1,29 @@
# Draft state belongs to the editor
The following snapshot function illustrates the inputs and extra state the close guard must
consider. It is not a complete modal controller. The application owns loading, submit state,
focus management, topmost-modal selection and the in-page discard confirmation.
```js
function draftSnapshot(form, pendingDeletes, pendingToggles) {
const fields = [...form.querySelectorAll('input, select, textarea')].map(field => {
if (field.type === 'checkbox' || field.type === 'radio') {
return [field.name || field.id, field.value, field.checked];
}
if (field instanceof HTMLSelectElement && field.multiple) {
return [field.name || field.id, [...field.selectedOptions].map(option => option.value)];
}
return [field.name || field.id, field.value];
});
return JSON.stringify([fields, [...pendingDeletes].sort(),
[...pendingToggles].sort(([a], [b]) => a.localeCompare(b))]);
}
```
Take the clean snapshot after async initialization. Include new/deleted child rows and every
draft field, even if it has no form input. File editors additionally track selected files.
Do not silently write on input change or reset the clean snapshot after each render.
Before a user close request, reject it while submitting; otherwise compare the current snapshot
and ask to discard only if dirty. Programmatic close after a successful save is a separate path.
Use [modal-workflows](../contract.md) for the full behavior contract. The example covers snapshot comparison only; it is not a complete close guard.
@@ -0,0 +1,24 @@
# Contract: Modal Drafts and Explicit Save
Part of [modal-workflows](../contract.md).
## Explicit Save and Unsaved Changes
- Edit modals persist only on the labeled Save action. Field changes, autofill, child additions,
removals and state toggles remain draft state; no hidden writes on `change` or `blur`.
- Visually mark staged toggles (for example a dashed outline) and explain that Save applies
them. Do not present a draft state as already persisted.
- Track dirty state against a snapshot taken after initial asynchronous loading. Include state
outside inputs, such as pending deletions and toggle maps. Reset the snapshot only after
loading or successful save, never after an unrelated rerender of the edited content.
- Route Escape, backdrop and close buttons through one shared close guard. For dirty forms,
show an in-page choice: Continue editing / Close without saving. Escape on that confirmation
keeps the edits; Escape elsewhere acts on only the topmost modal.
- While submitting, block closing as well as double submission. On failure retain entered
values and show the error inline. If saving requires multiple requests, remember applied
operations so retry does not duplicate them; do not imply that partial success was rolled back.
- Removing a draft child may be staged without an immediate confirmation. Before committing
destructive deletion of persisted data, the separate confirmation required above must still
name the affected records and any cascade. A Save label alone is not that confirmation.
See the [snapshot example](README.md).