Undo and redo
How Edytor groups edits into undo steps, the undo and redo APIs, and how undo behaves when several people edit the same document.
Every document has one local history. Undo reverts your own edits only, never a collaborator’s, and restores the selection you had. This page covers the shortcuts and APIs, what one undo step contains, and the rules that apply when others edit at the same time.
Undo and redo
| Action | Keys |
|---|---|
| Undo | Mod+Z |
| Redo | Mod+Shift+Z, or Ctrl+Y on Windows and Linux |
Mod is Cmd on macOS and Ctrl elsewhere. Undo and redo from the browser’s Edit menu or a context menu go through the same history.
From code, call the view’s methods:
<script lang="ts">
import type { EdytorInstance } from 'edytor';
let { edytor }: { edytor?: EdytorInstance } = $props();
</script>
<button onclick={() => edytor?.historyUndo()}>Undo</button>
<button onclick={() => edytor?.historyRedo()}>Redo</button>
historyUndo() restores the selection this view had before the step; historyRedo() restores the one it had after. If a collaborator deleted the place a recorded caret pointed to, the view keeps its current selection instead.
Both return nothing. Each call sets edytor.dispatcher.last to { operation: 'undo' } or 'redo' with a status: applied when a step was replayed, noop when the stack was empty, and refused on a readonly view or a read-only document. Read it to tell a refused undo from an empty stack. These two calls are the view’s only history API: the keys (Mod+Z, Mod+Shift+Z, Ctrl+Y) and the browser’s undo intents reach them, so a readonly view never rewinds the shared document. document.history (below) is the document’s own history, the raw path, which no view’s readonly guards.
Without a view, use the document’s history directly. It restores no selection:
import { createDocument } from 'edytor';
const document = createDocument({ value: { children: [] } });
document.history.undo();
document.history.redo();
document.history.canUndo(); // edytor's undo manager
document.clearHistory(); // drop both stacks
All views of one document share its history. An edit made in one view can be undone from another; only the view that issues the undo restores its selection.
What one step contains
Edytor groups edits the way a text editor does:
- Typing at the caret joins the previous step if that step was typing or a text deletion, it continues where that step left the caret, and it follows it within the capture window (500 ms by default). Moving the caret and typing again starts a new step, however short the pause, and so does typing right after any other step (a column resize, a data change, a paste, a conversion), as in Notion.
- Deletions (Backspace, Delete, cut, deleting a selection or blocks) start a new step.
- Enter is a step of its own.
- Paste and drop each start a new step.
- Structural edits (inserting, duplicating, converting, removing, nesting, unnesting and moving blocks, formatting) start a new step, whether they come from a key, a menu, a toolbar or a plugin calling a block command.
- Markdown and slash conversions are a step of their own. Undo gives back what you typed as text:
##becomes a paragraph##,**b**becomes**b*, and/h2+ Enter becomes the/h2text. - An IME composition (Japanese, Chinese, Korean input, and so on) is one step with its commit. One left before it shows anything (a key, a click or leaving the editor right after it starts over text selected in one block) changes nothing and adds no step. Over selected blocks, or text selected across blocks, the selection is replaced as the composition starts, so one left then leaves that replacement, one step.
- Copy records nothing.
A command that plugins refuse records nothing. One edytor.transact call is never split across steps.
These rules do not depend on how fast you work: a menu action a few milliseconds after typing is still its own step, and so is the kind picked from the block handle’s + (the new block and its kind are one step; opening the menu adds nothing).
Commands you call
- One step each. Each operation of the view (
edytor.insertBlocks,edytor.setBlock,edytor.patchData,edytor.formatRange, deletions and the rest) is a step. - Continuing at the caret. Only
edytor.insertTextandedytor.insertInlinecan join the previous step, and only when they continue at the caret that step left, as typing does. - Typing into a property. A property write (
patchData) that sets text joins the step of the one before it when it sets the same properties of the same block to text, such as typing into an input bound toblock.data.title. The property writes of one task (block.data.a = 1; block.data.b = 2) are one step. A flag, a number or a delete in a task of its own is always its own step (see Properties).
Several commands as one step
To make several commands one step, run them in one edytor.transact call: that is the only guarantee.
edytor.dispatcher.run(kind, body) makes what body runs synchronously one step, as long as its commands commit within the capture window. kind names the edit (an input type such as insertText, or format, insertBlocks, insertFromPaste), and the rules above apply by it: a kind they do not cover (run('myConvert', …)) starts a new step, as a structural edit does, so it never joins the typing before it.
Writes outside the history
A write that completes a step already taken belongs to no step of its own: edytor.dispatcher.outside(body) runs body’s commands outside the history. They are admitted (refused in readonly), shown to hooks and recorded in dispatcher.last like any command, but they start no step and join none, so the typing around them groups as if they never came.
- Example. The image plugin uses it for an upload’s URL: pasting an image file places the image block at once (one step), and the URL that arrives later fills it outside the history. Undoing the paste removes the image, URL included, and redo brings it back whole.
- Only where the step covers it. Call it only where the step it completes covers its write (here, by creating the block).
- Not inside a transaction. It throws, writing nothing, when called inside another transaction (inside
edytor.transact, a command or a change callback), since its writes would take that transaction’s step: call it from a later task, as an upload’s answer is.
Capture window and limit
Set the capture window when you create the document. 0 makes every commit its own step:
import { createDocument } from 'edytor';
const document = createDocument({ history: { captureTimeout: 300 } });
The undo stack keeps the newest 200 steps (history: { limit }; Infinity keeps every step). An older step is dropped, and what it kept to undo is released: the text it deleted, kept hidden until then so the undo could show it again, is removed for good, so a long session does not keep every deleted character in memory and in the stored document. A new edit after an undo drops the redo steps the same way. Call document.clearHistory() to drop both stacks at points where undo no longer makes sense, such as after a save.
import { createDocument } from 'edytor';
const document = createDocument({ history: { limit: 500 } });
When the page closes
When the page leaves for good, its session’s history ends: the view calls document.endHistory() at a pagehide the browser’s back/forward cache keeps nothing of. Every step is released as above, and the blocks this session deleted become the purge’s at once: the room removes them at its next daily run instead of after purgeAfterDays (see the purge). Nothing else changes for anyone: only this session’s undo could have brought them back, and a version restore still can, from the version. A page the back/forward cache keeps, a tab that only lost its connection and your other tabs keep their history. The release is one small write at unload: when it is lost (Firefox closes a page’s sockets before pagehide, so from Firefox it reaches the room only through another open tab of the document), the deletes wait for the purge horizon, as before. Without a view, call document.endHistory() yourself when the session ends; undo starts empty afterwards.
Undo with collaborators
Remote edits never enter your history, and your undo only takes back what you did. When edits overlap, these rules apply:
- Your undo removes only your own contributions. If you create a block (or press Enter) and a collaborator types into it, undoing your creation leaves the block with their text, even if their text arrives after your undo. A block stays while it holds another person’s text or a child.
- Undoing a split puts the text of the second half back into the first line, including anything a collaborator typed there.
- Concurrent deletes. Each person’s delete of a piece of text is their own. If two people delete the same text at the same time and one of them undoes, the text stays deleted until the other undoes too; then it comes back once, not twice.
- Explicit deletes win. When you delete a block while someone types into it, the block stays deleted.
- Deleting a selected parent moves its unselected children into its place; undo puts them back under it, with any edits collaborators made to them meanwhile.
- An emptied document shows a local empty paragraph when concurrent edits delete every block. Nothing is written for it until someone types, so undo never has to remove it, and two people typing into an emptied document each keep their line.
Concurrent editing explains these rules in detail.