0
# Slate History
1
2
Slate History provides a comprehensive undo/redo history implementation for Slate rich text editors through operation-based state tracking. It seamlessly integrates with Slate editors to track all document operations in undo and redo stacks, enabling users to undo and redo changes while preserving selection state.
3
4
## Package Information
5
6
- **Package Name**: slate-history
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install slate-history`
10
- **Peer Dependencies**: `slate >= 0.114.3`
11
12
## Core Imports
13
14
```typescript
15
import { withHistory, HistoryEditor, History, HISTORY, SAVING, MERGING, SPLITTING_ONCE } from "slate-history";
16
```
17
18
For CommonJS:
19
20
```javascript
21
const { withHistory, HistoryEditor, History, HISTORY, SAVING, MERGING, SPLITTING_ONCE } = require("slate-history");
22
```
23
24
**Most Common Usage:**
25
26
```typescript
27
import { withHistory, HistoryEditor, History } from "slate-history";
28
```
29
30
**Required Slate Types:**
31
32
```typescript
33
// These types from slate are used in the API signatures
34
import { Editor, BaseEditor, Operation, Range } from "slate";
35
```
36
37
## Basic Usage
38
39
```typescript
40
import { createEditor } from "slate";
41
import { withHistory } from "slate-history";
42
43
// Create an editor with history functionality
44
const editor = withHistory(createEditor());
45
46
// Use undo and redo methods
47
editor.undo();
48
editor.redo();
49
50
// Check if editor has history functionality
51
if (HistoryEditor.isHistoryEditor(editor)) {
52
console.log("Editor has history support");
53
}
54
```
55
56
With React:
57
58
```typescript
59
import { withReact } from "slate-react";
60
import { withHistory } from "slate-history";
61
import { createEditor } from "slate";
62
63
const editor = withReact(withHistory(createEditor()));
64
```
65
66
## Architecture
67
68
Slate History is built around several key components:
69
70
- **withHistory Plugin**: Core plugin function that transforms a Slate editor into a history-enabled editor
71
- **HistoryEditor Interface**: Extended editor interface with history methods and state management utilities
72
- **History Object**: Data structure containing undo and redo operation stacks
73
- **Operation Batching**: Intelligent grouping of related operations for optimal undo/redo behavior
74
- **State Management**: WeakMap-based state tracking for merging, saving, and splitting behaviors
75
76
## Capabilities
77
78
### History Plugin
79
80
The core plugin that adds undo/redo functionality to Slate editors through operation tracking and batch management.
81
82
```typescript { .api }
83
function withHistory<T extends Editor>(editor: T): T & HistoryEditor;
84
```
85
86
[History Plugin](./with-history.md)
87
88
### Editor Methods and State Management
89
90
Helper methods for controlling history behavior, checking editor state, and managing operation batching.
91
92
```typescript { .api }
93
interface HistoryEditor extends BaseEditor {
94
history: History;
95
undo: () => void;
96
redo: () => void;
97
writeHistory: (stack: 'undos' | 'redos', batch: any) => void;
98
}
99
```
100
101
[History Editor](./history-editor.md)
102
103
### History Data Structure
104
105
The core data structure and utilities for managing undo/redo operation stacks.
106
107
```typescript { .api }
108
interface History {
109
redos: Batch[];
110
undos: Batch[];
111
}
112
113
// Internal batch structure (not exported)
114
interface Batch {
115
operations: Operation[];
116
selectionBefore: Range | null;
117
}
118
119
// Static methods
120
namespace History {
121
function isHistory(value: any): value is History;
122
}
123
```
124
125
[History Structure](./history.md)
126
127
## Types
128
129
```typescript { .api }
130
interface HistoryEditor extends BaseEditor {
131
history: History;
132
undo: () => void;
133
redo: () => void;
134
writeHistory: (stack: 'undos' | 'redos', batch: any) => void;
135
}
136
137
interface History {
138
redos: Batch[];
139
undos: Batch[];
140
}
141
142
// Internal batch structure (not exported)
143
interface Batch {
144
operations: Operation[];
145
selectionBefore: Range | null;
146
}
147
148
// WeakMap exports for advanced usage
149
const HISTORY: WeakMap<Editor, History>;
150
const SAVING: WeakMap<Editor, boolean | undefined>;
151
const MERGING: WeakMap<Editor, boolean | undefined>;
152
const SPLITTING_ONCE: WeakMap<Editor, boolean | undefined>;
153
```