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
```