Split shared UI knowledge into atomic topic directories
This commit is contained in:
1 parent
08ff987edb
commit
b0e6402d66
37 files changed
+600
-516
No files matched your search
@@ -37,42 +37,11 @@ closed → open → submitting → success | error
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Validation
|
||||
|
||||
Validation UX follows the `forms-validation` contract (server-side on submit, inline field
|
||||
errors, form-level summary, human-readable messages).
|
||||
|
||||
## htmx Pattern (server-rendered modals)
|
||||
|
||||
```
|
||||
POST /api/entity → 200 OK + HX-Trigger: "entitySaved" (success)
|
||||
→ 422 Unprocessable + partial HTML (validation error, re-render form)
|
||||
→ 500 + error message (server error)
|
||||
```
|
||||
|
||||
- On success: server sends `HX-Trigger` header, JS listener closes modal and refreshes list.
|
||||
- On validation error: server re-renders the form partial with inline errors (422, per `go-api`).
|
||||
- On server error: show generic error toast, log full error server-side.
|
||||
|
||||
## Multi-Step Modals
|
||||
|
||||
Staged flows follow the `forms-validation` multi-step rules. Modal-specific:
|
||||
@@ -80,3 +49,10 @@ 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)
|
||||
@@ -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).
|
||||
@@ -0,0 +1,15 @@
|
||||
# Contract: Server-Rendered Modal Responses
|
||||
|
||||
Part of [modal-workflows](../contract.md).
|
||||
|
||||
## htmx Pattern (server-rendered modals)
|
||||
|
||||
```
|
||||
POST /api/entity → 200 OK + HX-Trigger: "entitySaved" (success)
|
||||
→ 422 Unprocessable + partial HTML (validation error, re-render form)
|
||||
→ 500 + error message (server error)
|
||||
```
|
||||
|
||||
- On success: server sends `HX-Trigger` header, JS listener closes modal and refreshes list.
|
||||
- On validation error: server re-renders the form partial with inline errors (422, per `go-api`).
|
||||
- On server error: show generic error toast, log full error server-side.
|
||||
Reference in new issue
Block a user