# Changes to records

> What was done to a list of records, as a value: told to its owner, applied, and turned about to undo it.

An interface that edits many records at once — a grid, a list of items — does
not own them: an application does, and so may a server, and so may other people
editing at the same time. What the interface did is best said as a change: what
was changed, where, from what and to what.

## Best practices

**Say what changed, not only what there now is.** A change names the fields it
altered with the value each took and the value each held, the records it added
and where, the records it took away and from where. An owner with a hundred
thousand records, or a store that is not a list at all, can apply that; it
cannot afford to compare two copies of everything.

**Leave untouched what was not changed.** A record that a change does not touch
is the same record after it, so that whatever else shows the data redraws only
what changed.

**Keep what is needed to take it back.** A change that carries the values it
replaced and the records it removed can be turned about: undo is the same
change, reversed, and redo is the change again. Nothing has to be remembered
besides.

**Put back the very records.** Undoing a removal returns the records that were
removed, to the places they were in — not copies, and not at the end.

**Make one action one change to undo.** A paste that fills cells and adds
records to hold the rest is one action; it is taken back whole.

**Add a record only for something.** Typing into the row that waits after the
last record makes a record. Clearing it, or pasting nothing into it, does not.

**Ignore what no longer applies.** A change that names a record that is no
longer there changes nothing there, rather than failing.

See also [Undo and redo](https://ui.publictheta.com/foundations/history.md) and
[Data grid](https://ui.publictheta.com/components/data-grid.md).

## Behaviour

Each statement is verified by a test in Chromium, Chromium (touch), Firefox, WebKit, WebKit (touch), unless it names the environments it applies to or is marked open.

### Applying

- A change to fields changes those fields, and leaves every other record the very one it was.
- An insertion puts records in at its place, and the rest follow.
- A removal takes out each run, each at its place in the list as it was.
- A change that names a record that is not there changes nothing there.

### Undoing

- A change, then what undoes it, gives back the list as it was — the same records, in the same places.
- Undoing what undid a change does the change again.

### Runs

- Places side by side are one run; the places may be given in any order, and twice.
- Places that are not in the list are left out.

## Reference implementation

React: `npx shadcn@latest add https://ui.publictheta.com/r/record-changes.json`