0
# Transform Functions
1

2
Editor manipulation functions for programmatic content modification, selection handling, and editor state management.
3

4
## Capabilities
5

6
### Core Transform Interface
7

8
The editor provides a comprehensive transform API accessible via `editor.transforms` or `editor.tf`.
9

10
```typescript { .api }
11
interface EditorTransforms {
12
  /** Initialize editor with value and selection */
13
  init(options: { value?: any[]; selection?: any }): void;
14
  /** Set editor value programmatically */
15
  setValue(value: any[]): void;
16
  /** Insert exit break from block elements */
17
  insertExitBreak(): void;
18
  /** Reset block to default paragraph type */
19
  resetBlock(options?: { type?: string }): void;
20
}
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { createSlateEditor, getCorePlugins } from "@platejs/core";
27

28
const editor = createSlateEditor({
29
  plugins: getCorePlugins()
30
});
31

32
// Initialize editor with content
33
editor.transforms.init({
34
  value: [
35
    { type: 'p', children: [{ text: 'Initial content' }] }
36
  ]
37
});
38

39
// Set new value
40
editor.transforms.setValue([
41
  { type: 'h1', children: [{ text: 'New heading' }] },
42
  { type: 'p', children: [{ text: 'New paragraph' }] }
43
]);
44
```
45

46
### Node Manipulation Transforms
47

48
Advanced node manipulation functions for deep editor operations.
49

50
```typescript { .api }
51
/**
52
 * Apply transformations deeply to node hierarchy
53
 * @param options - Transformation options
54
 * @returns Transformed node
55
 */
56
function applyDeepToNodes(options: {
57
  node: any;
58
  source: any;
59
  apply: (node: any) => any;
60
}): any;
61

62
/**
63
 * Merge properties deeply into node hierarchy
64
 * @param options - Merge options
65
 * @returns Merged node
66
 */
67
function mergeDeepToNodes(options: {
68
  node: any;
69
  source: any;
70
}): any;
71

72
/**
73
 * Apply default values deeply to node hierarchy
74
 * @param options - Default options
75
 * @returns Node with defaults applied
76
 */
77
function defaultsDeepToNodes(options: {
78
  node: any;
79
  source: any;
80
}): any;
81
```
82

83
**Usage Examples:**
84

85
```typescript
86
import { applyDeepToNodes, mergeDeepToNodes } from "@platejs/core";
87

88
// Apply custom styling to all nodes
89
const styledNodes = applyDeepToNodes({
90
  node: editorValue,
91
  source: { className: 'custom-style' },
92
  apply: (node) => ({ ...node, className: 'custom-style' })
93
});
94

95
// Merge properties into nodes
96
const mergedNodes = mergeDeepToNodes({
97
  node: editorValue,
98
  source: { metadata: { version: 1 } }
99
});
100
```
101

102
### Selection Transforms
103

104
Functions for programmatic selection manipulation and navigation.
105

106
```typescript { .api }
107
interface SelectionTransforms {
108
  /** Move selection to start of editor */
109
  selectAll(): void;
110
  /** Move selection to end of editor */
111
  selectEnd(): void;
112
  /** Collapse selection to a point */
113
  collapse(options?: { edge?: 'start' | 'end' }): void;
114
  /** Expand selection to include range */
115
  select(range: any): void;
116
}
117
```
118

119
### Block Transforms
120

121
Specialized transforms for block-level operations.
122

123
```typescript { .api }
124
/**
125
 * Insert exit break from current block
126
 * Handles exiting from complex blocks like code blocks or lists
127
 */
128
function insertExitBreak(): void;
129

130
/**
131
 * Reset current block to default type
132
 * @param options - Reset options
133
 */
134
function resetBlock(options?: { 
135
  type?: string;
136
  properties?: Record<string, any>;
137
}): void;
138

139
/**
140
 * Toggle block type between two types
141
 * @param type - Target block type
142
 * @param defaultType - Default type to toggle back to
143
 */
144
function toggleBlock(type: string, defaultType?: string): void;
145
```
146

147
**Usage Examples:**
148

149
```typescript
150
// Reset current block to paragraph
151
editor.transforms.resetBlock({ type: 'p' });
152

153
// Insert exit break (useful for code blocks, lists)
154
editor.transforms.insertExitBreak();
155
```
156

157
### Text Transforms
158

159
Functions for text-level operations and formatting.
160

161
```typescript { .api }
162
interface TextTransforms {
163
  /** Insert text at current selection */
164
  insertText(text: string): void;
165
  /** Delete text in current selection */
166
  deleteText(): void;
167
  /** Insert line break */
168
  insertBreak(): void;
169
  /** Insert soft break (shift+enter) */
170
  insertSoftBreak(): void;
171
}
172
```
173

174
### Advanced Transform Utilities
175

176
Utility functions for complex editor operations.
177

178
```typescript { .api }
179
/**
180
 * Normalize descendants to document fragment
181
 * @param descendants - Array of descendant nodes
182
 * @returns Document fragment
183
 */
184
function normalizeDescendantsToDocumentFragment(
185
  descendants: any[]
186
): DocumentFragment;
187

188
/**
189
 * Override editor behavior with custom functions
190
 * @param editor - Editor instance
191
 * @param overrides - Override functions
192
 * @returns Enhanced editor
193
 */
194
function overrideEditor(
195
  editor: SlateEditor,
196
  overrides: Record<string, Function>
197
): SlateEditor;
198
```
199

200
## Transform Extension System
201

202
Plugins can extend the transform system with custom operations:
203

204
```typescript { .api }
205
interface TransformExtension {
206
  [transformName: string]: (editor: SlateEditor, ...args: any[]) => void;
207
}
208

209
// Example plugin with custom transforms
210
const CustomPlugin = createSlatePlugin({
211
  key: 'custom',
212
  transforms: {
213
    insertCustomBlock: (editor, options) => {
214
      editor.insertNode({
215
        type: 'custom-block',
216
        ...options,
217
        children: [{ text: '' }]
218
      });
219
    },
220
    formatText: (editor, format) => {
221
      editor.addMark(format, true);
222
    }
223
  }
224
});
225

226
// Usage
227
editor.transforms.insertCustomBlock({ data: 'example' });
228
editor.getTransforms(CustomPlugin).insertCustomBlock({ data: 'example' });
229
```
230

231
## Transform Pipeline
232

233
Transforms support pipeline processing for complex operations:
234

235
```typescript { .api }
236
/**
237
 * Pipe multiple transform operations
238
 * @param editor - Editor instance
239
 * @param transforms - Array of transform functions
240
 */
241
function pipeTransforms(
242
  editor: SlateEditor,
243
  transforms: Array<(editor: SlateEditor) => void>
244
): void;
245
```