Settings: how a screen saves
From mnema-talk v3.3.13, rendered on this site.
One screen, one rule. A settings screen either saves every field at once or saves every field with one explicit Save. It never mixes the two: a Save button promises that nothing on its form has been stored yet, and an instant control next to it breaks that promise ("did the icon save? why is Save still off?").
This follows the common guidance: NN/g, Toggle-Switch Guidelines: "separate controls that produce instant results from those that require clicking a command button", toggles take effect immediately and never wait for Save; Apple and Material treat switches as instant and keep Save/Done for forms that commit several values at once.
Which pattern
| Kind of setting | Pattern | Examples |
|---|---|---|
| Personal preference: affects only the person who sets it, is cheap to undo | Immediate. The change applies when it is made; a quiet "Saved" confirms it. | audio and voice, notification levels, DM policy, push preview, this device |
| Shared or admin configuration: affects other people, or several fields only make sense together | Draft + Save. Edit a draft, nothing is stored until Save; the unsaved-changes bar; a discard prompt when leaving. | Talk and channel settings, roles, community, invites, automod rules, webhooks, bots |
Actions are not fields. Create, delete, reorder, revoke, test, rotate, "send reset mail" and wizards (two-factor, import, export, delete account) do something once. They run when pressed, ask first when destructive, and report through a toast. They may sit on a draft screen; only the screen's fields follow its pattern. An action on a draft screen sits in its own titled section after the form, never among the fields, and is never shaped like a field: no switch, checkbox or select that writes on change. Every action confirms success (a toast, or the result shown in place, such as a revealed secret) and reports failure with a toast.
Images are fields. An icon, avatar or banner on a draft screen is part of the
draft: picking a file only shows a preview, Remove only marks it, and both are
uploaded or deleted on Save (useStagedImage). Only a screen without a Save button
may upload an image the moment it is picked, with a toast. The profile card is such a
screen: avatar and banner are changed on the card itself, while name and bio open
their own inline editor with its own bar.
Draft + Save
Built from three shared parts, never a one-off variant:
web/src/shared/composables/useSettingsDraft.ts: the draft, dirty detection, reset, the save lifecycle, the discard guard and Ctrl/Cmd+S.web/src/shared/components/UnsavedChangesBar.vue: the footer with "You have unsaved changes", Reset, Save and the inline error.web/src/shared/composables/useStagedImage.ts: an image field of the draft (File,'remove'ornullfor unchanged), its preview and its normaliser.
Rules:
- Every field is in the draft, including toggles. Nothing is persisted on change.
- Changed means different after normalising, field by field (
normalise.text,.count,.set,.flag, or your own): surrounding whitespace,0and empty for "unlimited", empty vs null, the order of a role list. The Save button is on iff the draft differs from the saved state and is valid (validatereturns field errors). - Save is one lifecycle:
savereceives only the changed fields and writes them in a defined order. If the API has separate calls, callcommit(keys)after each one that went through. A later failure then leaves only the rest unsaved and says "Some changes were saved, the rest was not". Errors show inline in the bar, next to the fields they belong to, not only as a toast. - After Save the draft is the saved state. If the saved state changes elsewhere, fields you did not touch follow it; fields you are editing keep your value.
- Leaving with unsaved changes asks "Discard changes?": closing a dialog
(
BaseDialog :guard="form.guard"), replacing the edited item by another (another role, another bot, another webhook) and reloading the page (beforeunload, automatic). - Ctrl/Cmd+S inside the form saves it, and so does Enter in a one-line field
(
@keydown="form.onKeydown"). A form with several fields has no implicit submit. - A container keeps its drafts alive. The admin console keeps every tab mounted, so
switching tabs loses nothing; closing the console asks once for all of them
(
provideDraftScope()+BaseDialog :guard). A draft that is not a field form (the channel order, a list of overwrites) still usesUnsavedChangesBaranduseLeaveGuard(dirty), withdirtycomputed by comparing with the saved state, never a hand-set flag. - Save confirms itself: a success toast from
saved(or the dialog closing with one). One screen has one bar: a second draft on the same screen uses aninlinebar inside its own card, never a second sticky one.
Immediate
Use usePreferenceSave().run(change) and show <SavedIndicator :visible="saved" />
where the setting sits. A failed change is reported with a toast and the control goes
back to the real value. Do not add a Save button to such a screen. Every write of
the screen shows the indicator, including sliders and device pickers that persist
through a store watcher. A write that reports failure by a return value (not a throw)
is checked and reported the same way.
A one-off form that does something (change password, change e-mail, create a channel) names its button after the action ("Change password", "Create"), not "Save", and closing it with typed input asks first.
web/src/shared/composables/settingsPatterns.test.ts checks the parts that can be checked
mechanically: a draft component never uses the immediate helpers, an image picker on
a draft screen goes through useStagedImage, and a component with an unsaved bar
tracks it with a draft or a leave guard.
Choosing
If a wrong value would surprise somebody else, or two fields have to be valid together, use a draft. If it only changes how this person's app behaves, apply it at once. When in doubt, ask: "does a half-finished edit make sense here?" If it does not, it is a draft.