feat: the editor records, shows and applies tracked changes

Two marks carry a revision with its author and date: an insertion is
marked text, a deletion is text kept and struck through. Consecutive
typing joins one change; accept/reject work at the cursor or on all.

ODF splits the pair — text:change-start/-end around an insertion, a
text:change where a deletion was, its text in the tracked-changes
registry. DOCX uses w:ins/w:del with w:delText. Both round-trip, and
accepting every change gives the document an unrecorded edit would.
This commit is contained in:
Steffen Becker committed 2026-08-14 07:48:10 +02:00
1 parent da438a7655
commit 5ee4eec5d7
18 files changed
+646 -16

No files matched your search

+8
View File
@@ -64,6 +64,9 @@ import { AutoCorrect } from './extensions/autoCorrect';
import { HEADING_LEVELS } from '../export/odt';
import { styleSheet } from '../styles/sheet.svelte';
import { noteSettings } from '../storage/notes.svelte';
import { recordChanges } from '../storage/trackChanges.svelte';
import { loadDocProperties } from '../storage/docProperties';
import { Insertion, Deletion, TrackChanges } from './extensions/trackChanges';
export const extensions = [
// textBox and columns have their own groups so only the document (not
@@ -195,6 +198,11 @@ export const extensions = [
FormattingMarks,
SpellCheck,
// Last of the typing extensions: its handleTextInput runs after every input rule.
// Recorded revisions: an insertion is marked text, a deletion is text kept and
// marked. Round-trips to ODF <text:tracked-changes> and DOCX w:ins/w:del.
Insertion,
Deletion,
TrackChanges.configure({ recording: recordChanges, author: () => loadDocProperties().author.trim() }),
AutoCorrect,
SearchReplace,
// Word/LibreOffice key bindings that aren't TipTap defaults; body:true adds the
+1
View File
@@ -30,6 +30,7 @@ Five topics are large enough to have their own deep-dive — read the file befor
- **`bulletList.ts`** / **`orderedList.ts`** — the TipTap lists plus a marker-type attr: `setBulletChar` (innermost list, `null` = default cycle) and the ordered numbering cycle (`utils/orderedListTypes.ts`, multilevel targets the outermost list).
- **`link.ts`** — hyperlink mark; owns `Mod-k`, which fires the event `Toolbar.svelte` listens for to open the link dialog. A `#name` href targets a bookmark: `Editor.svelte`'s `handleClick` scrolls to it instead of opening a tab. The `plain` attr (`data-plain`, `editor.css`) suppresses the editor's own blue: Word paints a link through its **Hyperlink character style**, which arrives as an ordinary mark, so every DOCX link is plain and one carrying no style is drawn like the text around it — while LibreOffice paints every ODF `text:a` styled or not (probed), so those never are. The DOCX exporter paints `#0563C1` only on a non-plain link, which is how a round trip tells its own links from a file's.
- **`comment.ts`** — an annotation on a range of text, a mark like `bookmark`: the whole comment (author, date, body, resolved) rides its attrs, so two runs of one comment merge back together and no second store is needed. `commentRanges(doc)` walks every range (an id split by a paragraph boundary yields several, which is why the commands walk all of them), `comments(doc)` keeps one per id for `CommentsPane.svelte`. A point comment — LibreOffice's, made with nothing selected, written with no `office:name` and no end element — attaches on import to the run before it, else the one after: the editor's comment is a mark and needs a range.
- **`trackChanges.ts`** — the `insertion`/`deletion` marks plus the recording plugin. `appendTransaction` marks whatever a transaction added, and `adjacentInsertion` reuses the id of the run just before it when the author matches, so a typed sentence is one change and not one per keystroke. A delete never reaches the document: `filterTransaction` rejects it and dispatches a mark pass instead (the author's own pending insertion is removed for real, as both word processors do). Every transaction of our own carries the `RECORDING` meta — accept/reject included, or its `tr.delete` would be read as a fresh user deletion and marked up again. `revisions(doc)` merges adjacent runs of one id, so an export writes one change per id.
- **`caption.ts`** — a caption is an ordinary paragraph in the `Caption` style (LibreOffice's, probed: 10pt italic, 0.212cm above and below) holding one `sequenceField` atom, its running number. `sequenceFields(doc)` counts one counter per category in document order; the cached `number` attr is what an export writes, and an `appendTransaction` (off the undo stack) plus an `onCreate` pass keep it true — a file's own cached numbers are unreadable wherever the format is not arabic. The counter's name differs per format: ODF `Illustration`/`Table`, Word `Figure`/`Table`, and `ODF_SEQ_CATEGORY` reads both back. `CaptionDialog.svelte` (References tab) owns the insert.
- **`bookmark.ts`** / **`crossReference.ts`** — a named range of text (a mark) and the live references to it (`REF`/`PAGEREF`). `ToolbarExpanded.svelte` owns both dialogs, as it does the link one.
- **`searchReplace.ts`** — Find & Replace: decorations highlight all matches, commands navigate/replace. Touches the document only for actual replacements. `useRegex` takes the term as a pattern instead of escaping it (a whole-word search then wraps it in a non-capturing group first, so the `\b` guards bound the alternation); each match keeps its captures so `expandGroups` can fill `$1`…`$9`/`$&` in the replacement.
+262
View File
@@ -0,0 +1,262 @@
import { Extension, Mark, mergeAttributes } from '@tiptap/core';
import type { Node as PMNode } from '@tiptap/pm/model';
import { Plugin, PluginKey, type EditorState, type Transaction } from '@tiptap/pm/state';
// Recorded revisions, as both word processors keep them: an insertion is text marked as
// added, a deletion is text still in the document but marked as removed — nothing is
// dropped until a change is accepted. Two marks carry it (author, date and a shared id
// per change), so a revision survives every editing operation the way a comment does.
//
// ODF stores the pair in a <text:tracked-changes> registry and points at it from the
// body; a deletion's text lives in the registry, an insertion's stays inline. Word wraps
// runs in <w:ins>/<w:del> instead, keeping a deletion's text in <w:delText>. Both are
// probed — see src/lib/export/CLAUDE.md.
export type RevisionKind = 'insertion' | 'deletion';
export type Revision = {
kind: RevisionKind;
id: string;
author: string;
date: string;
from: number;
to: number;
/** The text the change covers — a deletion's is what would come back on reject. */
text: string;
};
export function newRevisionId(): string {
return `r${Date.now().toString(36)}${Math.floor(Math.random() * 1e4).toString(36)}`;
}
// Whether the editor is recording. A document-level switch, like LibreOffice's Edit ▸
// Track Changes ▸ Record; the extension reads it through this option so the toolbar can
// flip it without rebuilding the editor.
export const RECORDING = new PluginKey<boolean>('trackChangesRecording');
function revisionMark(name: RevisionKind, attr: string) {
return Mark.create({
name,
// The range is fixed: typing at either end is its own change, as in Word.
inclusive: false,
excludes: '',
addAttributes() {
return {
id: { default: '', parseHTML: (el) => el.getAttribute(attr) || '', renderHTML: (a) => ({ [attr]: String(a.id ?? '') }) },
author: { default: '', parseHTML: (el) => el.getAttribute('data-rev-author') || '', renderHTML: (a) => ({ 'data-rev-author': String(a.author ?? '') }) },
date: { default: '', parseHTML: (el) => el.getAttribute('data-rev-date') || '', renderHTML: (a) => ({ 'data-rev-date': String(a.date ?? '') }) },
};
},
parseHTML() {
return [{ tag: `span[${attr}]` }];
},
renderHTML({ HTMLAttributes }) {
return ['span', mergeAttributes(HTMLAttributes, { class: `pm-${name}` }), 0];
},
});
}
export const Insertion = revisionMark('insertion', 'data-insertion');
export const Deletion = revisionMark('deletion', 'data-deletion');
// Every recorded change in document order, adjacent runs of one id merged.
export function revisions(doc: PMNode): Revision[] {
const out: Revision[] = [];
let last: Revision | null = null;
doc.descendants((node, pos) => {
if (!node.isText) { last = null; return true; }
const mark = node.marks.find((m) => m.type.name === 'insertion' || m.type.name === 'deletion');
if (!mark) { last = null; return false; }
const kind = mark.type.name as RevisionKind;
const id = String(mark.attrs.id ?? '');
if (last && last.id === id && last.kind === kind && last.to === pos) {
last.to = pos + node.nodeSize;
last.text += node.text ?? '';
return false;
}
last = {
kind, id,
author: String(mark.attrs.author ?? ''),
date: String(mark.attrs.date ?? ''),
from: pos, to: pos + node.nodeSize, text: node.text ?? '',
};
out.push(last);
return false;
});
return out;
}
declare module '@tiptap/core' {
interface Commands<ReturnType> {
trackChanges: {
/** Accept the change under the cursor, or every one when `all`. */
acceptRevisions: (all?: boolean) => ReturnType;
/** Reject the change under the cursor, or every one when `all`. */
rejectRevisions: (all?: boolean) => ReturnType;
};
}
}
// The revisions a command applies to: all of them, or the ones the selection touches
// (an empty selection takes the change the caret sits in).
function targets(state: EditorState, all: boolean): Revision[] {
const list = revisions(state.doc);
if (all) return list;
const { from, to } = state.selection;
return list.filter((r) => (from === to ? r.from <= from && from <= r.to : r.from < to && from < r.to));
}
// Applying a change is one pass from the end, so earlier positions stay valid. The
// RECORDING meta keeps the plugin's hands off it: without it the delete below is read
// as a fresh user deletion and marked up again instead of running.
function apply(state: EditorState, tr: Transaction, list: Revision[], accept: boolean): void {
const drop = accept ? 'deletion' : 'insertion';
for (const r of [...list].sort((a, b) => b.from - a.from)) {
if (r.kind === drop) tr.delete(r.from, r.to);
else tr.removeMark(r.from, r.to, state.schema.marks[r.kind]);
}
tr.setMeta(RECORDING, true);
}
export const TrackChanges = Extension.create<{ recording: () => boolean; author: () => string }>({
name: 'trackChanges',
addOptions() {
return { recording: () => false, author: () => '' };
},
addCommands() {
return {
acceptRevisions: (all = false) => ({ state, tr, dispatch }) => {
const list = targets(state, all);
if (!list.length) return false;
if (dispatch) apply(state, tr, list, true);
return true;
},
rejectRevisions: (all = false) => ({ state, tr, dispatch }) => {
const list = targets(state, all);
if (!list.length) return false;
if (dispatch) apply(state, tr, list, false);
return true;
},
};
},
addProseMirrorPlugins() {
const options = this.options;
return [
new Plugin({
key: RECORDING,
// Typing is intercepted here rather than by a keymap: every path that inserts
// text — a paste, an input rule, a drop — goes through appendTransaction, and
// each would otherwise need its own hook.
appendTransaction: (transactions, oldState, newState) => {
if (!options.recording()) return null;
if (!transactions.some((t) => t.docChanged)) return null;
// Our own accept/reject and the mark pass below must not recurse.
if (transactions.some((t) => t.getMeta(RECORDING))) return null;
const tr = newState.tr;
let touched = false;
const author = options.author();
for (const t of transactions) {
if (!t.docChanged) continue;
for (const step of t.steps) {
const map = step.getMap();
map.forEach((_oldStart, _oldEnd, newStart, newEnd) => {
if (newEnd <= newStart) return;
const from = tr.mapping.map(newStart);
const to = tr.mapping.map(newEnd);
// Anything freshly in the document is an insertion; a delete never gets
// this far, because it was turned into a mark before it ran (below).
// Typing joins the run it continues, so a sentence is one change and not
// one per keystroke.
tr.addMark(from, to, newState.schema.marks.insertion.create(
adjacentInsertion(newState, from, author) ?? { id: newRevisionId(), author, date: new Date().toISOString() },
));
touched = true;
});
}
}
return touched ? tr.setMeta(RECORDING, true).setMeta('addToHistory', false) : null;
},
// A deletion must not reach the document: mark the range instead. Text already
// marked as an insertion is the author's own and is simply removed, which is
// what both word processors do.
filterTransaction: (tr, state) => {
if (!options.recording() || tr.getMeta(RECORDING)) return true;
if (!tr.docChanged || !isPureDelete(tr, state)) return true;
const ranges: [number, number][] = [];
for (const step of tr.steps) {
const map = step.getMap();
map.forEach((oldStart, oldEnd) => { if (oldEnd > oldStart) ranges.push([oldStart, oldEnd]); });
}
if (!ranges.length) return true;
const marked = state.tr;
const attrs = { id: newRevisionId(), author: options.author(), date: new Date().toISOString() };
let any = false;
for (const [from, to] of ranges) {
for (const keep of keptRanges(state, from, to)) {
marked.addMark(keep[0], keep[1], state.schema.marks.deletion.create(attrs));
any = true;
}
// The author's own unaccepted insertion goes for real.
for (const own of [...ownInsertions(state, from, to)].reverse()) marked.delete(own[0], own[1]);
}
if (!any && !marked.docChanged) return true;
queueMicrotask(() => this.editor.view.dispatch(marked.setMeta(RECORDING, true)));
return false;
},
}),
];
},
});
// The attrs of the insertion the text just before `pos` belongs to, when the same author
// made it — what makes consecutive typing one change rather than one per keystroke.
function adjacentInsertion(state: EditorState, pos: number, author: string): Record<string, string> | null {
const before = pos > 0 ? state.doc.resolve(pos).nodeBefore : null;
const mark = before?.marks.find((m) => m.type.name === 'insertion');
if (!mark || String(mark.attrs.author ?? '') !== author) return null;
return { id: String(mark.attrs.id), author, date: String(mark.attrs.date) };
}
// A transaction that only removes content (backspace, delete, cut) — a replacement
// inserts as well, and its insertion half must still run.
function isPureDelete(tr: Transaction, state: EditorState): boolean {
if (!tr.steps.length) return false;
return tr.doc.content.size < state.doc.content.size
&& tr.steps.every((step) => {
let inserted = 0;
step.getMap().forEach((_os, _oe, ns, ne) => { inserted += ne - ns; });
return inserted === 0;
});
}
// The parts of [from,to) that are not the author's own pending insertion — the ones a
// delete turns into a deletion mark.
function keptRanges(state: EditorState, from: number, to: number): [number, number][] {
const own = ownInsertions(state, from, to);
const out: [number, number][] = [];
let cursor = from;
for (const [s, e] of own) {
if (s > cursor) out.push([cursor, s]);
cursor = Math.max(cursor, e);
}
if (cursor < to) out.push([cursor, to]);
return out;
}
function ownInsertions(state: EditorState, from: number, to: number): [number, number][] {
const out: [number, number][] = [];
state.doc.nodesBetween(from, to, (node, pos) => {
if (!node.isText) return true;
if (!node.marks.some((m) => m.type.name === 'insertion')) return false;
out.push([Math.max(from, pos), Math.min(to, pos + node.nodeSize)]);
return false;
});
return out;
}