0
# Utility Functions
1

2
Essential utility functions for node manipulation, plugin management, and editor state operations.
3

4
## Capabilities
5

6
### Node Manipulation Utilities
7

8
Functions for deep node operations and hierarchy manipulation.
9

10
```typescript { .api }
11
/**
12
 * Apply transformations deeply to node hierarchy
13
 * @param options - Transformation configuration
14
 * @returns Transformed node structure
15
 */
16
function applyDeepToNodes(options: {
17
  /** Source node to transform */
18
  node: any;
19
  /** Source data to apply */
20
  source: any;
21
  /** Transform function to apply */
22
  apply: (node: any) => any;
23
}): any;
24

25
/**
26
 * Merge properties deeply into node hierarchy
27
 * @param options - Merge configuration
28
 * @returns Merged node structure
29
 */
30
function mergeDeepToNodes(options: {
31
  /** Target node to merge into */
32
  node: any;
33
  /** Source properties to merge */
34
  source: any;
35
}): any;
36

37
/**
38
 * Apply default values deeply to node hierarchy
39
 * @param options - Default configuration
40
 * @returns Node with defaults applied
41
 */
42
function defaultsDeepToNodes(options: {
43
  /** Target node */
44
  node: any;
45
  /** Default values to apply */
46
  source: any;
47
}): any;
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { applyDeepToNodes, mergeDeepToNodes } from "@platejs/core";
54

55
// Add metadata to all nodes
56
const nodesWithMetadata = applyDeepToNodes({
57
  node: editorValue,
58
  source: { timestamp: Date.now() },
59
  apply: (node) => ({ ...node, metadata: { timestamp: Date.now() } })
60
});
61

62
// Merge styling into specific node types
63
const styledNodes = mergeDeepToNodes({
64
  node: editorValue,
65
  source: { 
66
    p: { className: 'paragraph' },
67
    h1: { className: 'heading-1' }
68
  }
69
});
70
```
71

72
### Plugin Management Utilities
73

74
Functions for plugin system operations and configuration.
75

76
```typescript { .api }
77
/**
78
 * Override plugins by key with new configurations
79
 * @param plugins - Array of plugins to modify
80
 * @param overrides - Override configurations by plugin key
81
 * @returns Array of plugins with overrides applied
82
 */
83
function overridePluginsByKey(
84
  plugins: any[],
85
  overrides: Record<string, any>
86
): any[];
87

88
/**
89
 * Get injected plugins based on match conditions
90
 * @param editor - Editor instance
91
 * @param match - Match function for plugin injection
92
 * @returns Array of injected plugins
93
 */
94
function getInjectedPlugins(
95
  editor: SlateEditor,
96
  match: (plugin: any) => boolean
97
): any[];
98

99
/**
100
 * Omit plugin context properties
101
 * @param plugin - Plugin to modify
102
 * @param keys - Keys to omit
103
 * @returns Plugin without specified context
104
 */
105
function omitPluginContext<T>(
106
  plugin: T,
107
  keys: string[]
108
): Omit<T, keyof any>;
109
```
110

111
**Usage Examples:**
112

113
```typescript
114
import { overridePluginsByKey, getCorePlugins } from "@platejs/core";
115

116
// Override specific plugin configurations
117
const customizedPlugins = overridePluginsByKey(
118
  getCorePlugins(),
119
  {
120
    'history': { options: { maxSize: 200 } },
121
    'debug': { options: { logLevel: 'warn' } }
122
  }
123
);
124

125
const editor = createSlateEditor({
126
  plugins: customizedPlugins
127
});
128
```
129

130
### Node Property Utilities
131

132
Functions for extracting and manipulating node properties.
133

134
```typescript { .api }
135
/**
136
 * Get plugin-specific node properties
137
 * @param editor - Editor instance
138
 * @param plugin - Plugin configuration
139
 * @returns Node properties for the plugin
140
 */
141
function getPluginNodeProps<T>(
142
  editor: SlateEditor,
143
  plugin: WithRequiredKey<T>
144
): Record<string, any>;
145

146
/**
147
 * Get node data attributes for HTML rendering
148
 * @param node - Node to extract attributes from
149
 * @returns Object with data attributes
150
 */
151
function getNodeDataAttributes(node: any): Record<string, string>;
152

153
/**
154
 * Get Slate CSS classes for node styling
155
 * @param options - Styling options
156
 * @returns CSS class string
157
 */
158
function getSlateClass(options: {
159
  type?: string;
160
  selected?: boolean;
161
  focused?: boolean;
162
}): string;
163
```
164

165
### Document Fragment Utilities
166

167
Functions for working with document fragments and normalization.
168

169
```typescript { .api }
170
/**
171
 * Normalize descendants to document fragment
172
 * @param descendants - Array of descendant nodes
173
 * @returns Normalized document fragment
174
 */
175
function normalizeDescendantsToDocumentFragment(
176
  descendants: any[]
177
): DocumentFragment;
178

179
/**
180
 * Convert nodes to HTML elements
181
 * @param nodes - Slate nodes to convert
182
 * @returns Array of HTML elements
183
 */
184
function nodesToElements(nodes: any[]): HTMLElement[];
185
```
186

187
### Type Checking Utilities
188

189
Functions for runtime type checking and validation.
190

191
```typescript { .api }
192
/**
193
 * Check if value matches a specific node type
194
 * @param value - Value to check
195
 * @param type - Expected node type
196
 * @returns True if value matches type
197
 */
198
function isType(value: any, type: string): boolean;
199

200
/**
201
 * Check if node is a specific element type
202
 * @param node - Node to check
203
 * @param type - Element type to match
204
 * @returns True if node matches element type
205
 */
206
function isElement(node: any, type?: string): boolean;
207

208
/**
209
 * Check if node is a text node
210
 * @param node - Node to check
211
 * @returns True if node is text
212
 */
213
function isText(node: any): boolean;
214

215
/**
216
 * Check if editor selection is outside specific bounds
217
 * @param editor - Editor instance
218
 * @param bounds - Boundary configuration
219
 * @returns True if selection is outside bounds
220
 */
221
function isSelectOutside(
222
  editor: SlateEditor,
223
  bounds?: { path?: number[]; offset?: number }
224
): boolean;
225
```
226

227
### Event Pipeline Utilities
228

229
Functions for managing event processing pipelines.
230

231
```typescript { .api }
232
/**
233
 * Pipe insert data query through processing chain
234
 * @param editor - Editor instance
235
 * @param dataTransfer - Data transfer object
236
 * @returns Processed data
237
 */
238
function pipeInsertDataQuery(
239
  editor: SlateEditor,
240
  dataTransfer: DataTransfer
241
): any;
242

243
/**
244
 * Pipe node change events through processing chain
245
 * @param editor - Editor instance
246
 * @param node - Changed node
247
 * @returns Processing result
248
 */
249
function pipeOnNodeChange(
250
  editor: SlateEditor,
251
  node: any
252
): void;
253

254
/**
255
 * Pipe text change events through processing chain
256
 * @param editor - Editor instance
257
 * @param text - Changed text
258
 * @returns Processing result
259
 */
260
function pipeOnTextChange(
261
  editor: SlateEditor,
262
  text: string
263
): void;
264
```
265

266
### CSS Class Utilities
267

268
Functions for managing CSS classes and styling.
269

270
```typescript { .api }
271
/**
272
 * Strip HTML class names from elements
273
 * @param html - HTML string to process
274
 * @returns HTML with class names removed
275
 */
276
function stripHtmlClassNames(html: string): string;
277

278
/**
279
 * Strip Slate data attributes from HTML
280
 * @param html - HTML string to process
281
 * @returns HTML with Slate attributes removed
282
 */
283
function stripSlateDataAttributes(html: string): string;
284

285
/**
286
 * Generate CSS class string for Slate elements
287
 * @param options - Class generation options
288
 * @returns CSS class string
289
 */
290
function generateSlateClass(options: {
291
  prefix?: string;
292
  type?: string;
293
  modifiers?: string[];
294
}): string;
295
```
296

297
### Editor Enhancement Utilities
298

299
Functions for extending and modifying editor behavior.
300

301
```typescript { .api }
302
/**
303
 * Override editor methods with custom implementations
304
 * @param editor - Editor instance to modify
305
 * @param overrides - Override method implementations
306
 * @returns Enhanced editor
307
 */
308
function overrideEditor(
309
  editor: SlateEditor,
310
  overrides: Record<string, Function>
311
): SlateEditor;
312

313
/**
314
 * Extend editor API with additional methods
315
 * @param editor - Editor instance
316
 * @param extensions - API extensions
317
 * @returns Editor with extended API
318
 */
319
function extendApi(
320
  editor: SlateEditor,
321
  extensions: Record<string, Function>
322
): SlateEditor;
323

324
/**
325
 * Get inject match configuration for plugin
326
 * @param plugin - Plugin configuration
327
 * @returns Inject match function
328
 */
329
function getInjectMatch<T>(
330
  plugin: WithRequiredKey<T>
331
): (node: any) => boolean;
332
```
333

334
**Usage Examples:**
335

336
```typescript
337
import { 
338
  overrideEditor, 
339
  extendApi, 
340
  isType,
341
  getSlateClass 
342
} from "@platejs/core";
343

344
// Extend editor with custom methods
345
const enhancedEditor = extendApi(editor, {
346
  insertSpecialBlock: () => {
347
    editor.insertNode({
348
      type: 'special-block',
349
      children: [{ text: '' }]
350
    });
351
  },
352
  
353
  hasBlockType: (type: string) => {
354
    const [match] = editor.nodes({
355
      match: n => isType(n, type)
356
    });
357
    return !!match;
358
  }
359
});
360

361
// Use enhanced API
362
enhancedEditor.api.insertSpecialBlock();
363
const hasHeading = enhancedEditor.api.hasBlockType('h1');
364

365
// Generate CSS classes
366
const elementClass = getSlateClass({
367
  type: 'paragraph',
368
  selected: true,
369
  focused: false
370
});
371
```