history.ts · Source

history.tspackages/editor/src/history.tsraw ← src3,758 B← Back to the app
1/**
2 * @factory/editor — undo/redo history (TASK-0058).
3 *
4 * Block-operation history, in-memory, **100 steps** (the durable history is
5 * page/block versions — this is the session buffer). The model is
6 * settle-point snapshots of the block forest: one `step` per user-visible
7 * change group (a keypress burst coalesces into one step via `commit`;
8 * Tiptap's own transaction history feeds `commit` calls from the canvas).
9 *
10 * `History` is pure (no tiptap, no timers) and fully unit-testable:
11 * `record(before, after)` → `undo()` / `redo()` return the snapshot to
12 * restore, with the 100-step cap and branch truncation (a new edit after
13 * an undo discards the redo branch — standard editor semantics).
14 */
15 
16import type { BlockDto, HistoryStep } from "./types.js";
17 
18/** Max undo steps (PRODUCT-SPEC / functional-requirements §4.3: 100). */
19export const HISTORY_LIMIT = 100;
20 
21export interface HistorySnapshot {
22  readonly label: string;
23  readonly blocks: readonly BlockDto[];
24}
25 
26/**
27 * The undo/redo buffer. `undo()` pops the top step and returns the
28 * pre-state to restore; `redo()` re-applies the next stashed step.
29 */
30export class History {
31  private undoStack: HistoryStep[] = [];
32  private redoStack: HistoryStep[] = [];
33 
34  /**
35   * Coalesced snapshot of the current state (the state BEFORE the most
36   * recent committed step, or the initial state before any step). Used by
37   * the canvas to know what `record` should diff against.
38   */
39  private baseline: readonly BlockDto[];
40 
41  constructor(initial?: readonly BlockDto[]) {
42    this.baseline = [...(initial ?? [])];
43  }
44 
45  get canUndo(): boolean {
46    return this.undoStack.length > 0;
47  }
48 
49  get canRedo(): boolean {
50    return this.redoStack.length > 0;
51  }
52 
53  /** Number of undo steps currently available. */
54  get depth(): number {
55    return this.undoStack.length;
56  }
57 
58  /**
59   * Commit one settle point. `after` must differ from `before` (or the
60   * label may coalesce with the previous step — a continuation of the same
61   * burst, e.g. typing; the previous step's `after` is replaced so undo
62   * jumps to before the whole burst).
63   */
64  record(before: readonly BlockDto[], after: readonly BlockDto[], label: string): void {
65    const last = this.undoStack[this.undoStack.length - 1];
66    if (last !== undefined && last.label === label && this.redoStack.length === 0) {
67      // coalesce: extend the previous step (typing burst)
68      this.undoStack[this.undoStack.length - 1] = { label, before: last.before, after: [...after] };
69      this.baseline = [...after];
70      return;
71    }
72    this.undoStack.push({ label, before: [...before], after: [...after] });
73    if (this.undoStack.length > HISTORY_LIMIT) {
74      this.undoStack.shift();
75    }
76    this.redoStack = [];
77    this.baseline = [...after];
78  }
79 
80  /** Undo one step; returns the pre-state to restore, or null if none. */
81  undo(): HistorySnapshot | null {
82    const step = this.undoStack.pop();
83    if (step === undefined) return null;
84    this.redoStack.push(step);
85    this.baseline = [...step.before];
86    return { label: step.label, blocks: step.before };
87  }
88 
89  /** Redo one step; returns the post-state to restore, or null if none. */
90  redo(): HistorySnapshot | null {
91    const step = this.redoStack.pop();
92    if (step === undefined) return null;
93    this.undoStack.push(step);
94    this.baseline = [...step.after];
95    return { label: step.label, blocks: step.after };
96  }
97 
98  /** The state the next `record` should treat as `before`. */
99  current(): readonly BlockDto[] {
100    return this.baseline;
101  }
102 
103  /** Drop all history (page switch / reload). */
104  reset(initial?: readonly BlockDto[]): void {
105    this.undoStack = [];
106    this.redoStack = [];
107    this.baseline = [...(initial ?? [])];
108  }
109}
110