0
# Multi-format Serialization
1

2
Support for multiple serialization formats including HTML, AST fragments, and custom format parsing with extensible parser system.
3

4
## Capabilities
5

6
### AST Fragment Serialization
7

8
Handle Slate AST fragment format for clipboard and drag-and-drop operations.
9

10
```typescript { .api }
11
/**
12
 * AST plugin for Slate fragment handling
13
 */
14
const AstPlugin: SlatePlugin;
15

16
/**
17
 * Serialize nodes to AST fragment format
18
 * @param editor - Editor instance
19
 * @param nodes - Nodes to serialize
20
 * @returns AST fragment string
21
 */
22
function serializeAst(
23
  editor: SlateEditor,
24
  nodes: any[]
25
): string;
26

27
/**
28
 * Deserialize AST fragment to nodes
29
 * @param editor - Editor instance
30
 * @param fragment - AST fragment string
31
 * @returns Array of deserialized nodes
32
 */
33
function deserializeAst(
34
  editor: SlateEditor,
35
  fragment: string
36
): any[];
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import { createSlateEditor, AstPlugin, serializeAst, deserializeAst } from "@platejs/core";
43

44
const editor = createSlateEditor({
45
  plugins: [AstPlugin]
46
});
47

48
// Serialize current selection to AST
49
const selectedNodes = editor.getFragment();
50
const astFragment = serializeAst(editor, selectedNodes);
51

52
// Store fragment for later use
53
localStorage.setItem('clipboard', astFragment);
54

55
// Restore from AST fragment
56
const storedFragment = localStorage.getItem('clipboard');
57
const nodes = deserializeAst(editor, storedFragment);
58
editor.insertFragment(nodes);
59
```
60

61
### Custom Parser System
62

63
Extensible parser system for handling various data formats.
64

65
```typescript { .api }
66
/**
67
 * Parser plugin for custom format handling
68
 */
69
const ParserPlugin: SlatePlugin;
70

71
/**
72
 * Parser configuration interface
73
 */
74
interface ParserOptions {
75
  /** Format identifier */
76
  format: string;
77
  /** MIME type for format */
78
  mimeType: string;
79
  /** Deserialization function */
80
  deserialize: (data: string) => any[];
81
  /** Serialization function */
82
  serialize?: (nodes: any[]) => string;
83
  /** Format priority */
84
  priority?: number;
85
}
86

87
/**
88
 * Register a custom parser
89
 * @param options - Parser configuration
90
 */
91
function registerParser(options: ParserOptions): void;
92

93
/**
94
 * Get registered parser by format
95
 * @param format - Format identifier
96
 * @returns Parser configuration
97
 */
98
function getParser(format: string): ParserOptions | null;
99

100
/**
101
 * Parse data using registered parsers
102
 * @param editor - Editor instance
103
 * @param data - Data to parse
104
 * @param format - Format hint
105
 * @returns Parsed nodes
106
 */
107
function parseData(
108
  editor: SlateEditor,
109
  data: string,
110
  format?: string
111
): any[];
112
```
113

114
**Usage Examples:**
115

116
```typescript
117
import { registerParser, parseData } from "@platejs/core";
118

119
// Register custom Markdown parser
120
registerParser({
121
  format: 'markdown',
122
  mimeType: 'text/markdown',
123
  deserialize: (markdown: string) => {
124
    // Custom markdown parsing logic
125
    return parseMarkdownToSlate(markdown);
126
  },
127
  serialize: (nodes: any[]) => {
128
    // Custom Slate to markdown conversion
129
    return convertSlateToMarkdown(nodes);
130
  }
131
});
132

133
// Register CSV parser
134
registerParser({
135
  format: 'csv',
136
  mimeType: 'text/csv',
137
  deserialize: (csv: string) => {
138
    const rows = csv.split('\n').map(row => row.split(','));
139
    return [{
140
      type: 'table',
141
      children: rows.map(row => ({
142
        type: 'tr',
143
        children: row.map(cell => ({
144
          type: 'td',
145
          children: [{ text: cell }]
146
        }))
147
      }))
148
    }];
149
  }
150
});
151

152
// Use parsers
153
const markdownData = "# Heading\n\nParagraph with **bold** text.";
154
const nodes = parseData(editor, markdownData, 'markdown');
155
editor.insertFragment(nodes);
156
```
157

158
### Clipboard Integration
159

160
Handle clipboard operations with multiple format support.
161

162
```typescript { .api }
163
/**
164
 * Clipboard data interface
165
 */
166
interface ClipboardData {
167
  /** Plain text representation */
168
  text: string;
169
  /** HTML representation */
170
  html?: string;
171
  /** AST fragment */
172
  fragment?: string;
173
  /** Custom format data */
174
  [format: string]: string;
175
}
176

177
/**
178
 * Write data to clipboard with multiple formats
179
 * @param editor - Editor instance
180
 * @param data - Data to write
181
 */
182
function writeClipboard(
183
  editor: SlateEditor,
184
  data: ClipboardData
185
): Promise<void>;
186

187
/**
188
 * Read data from clipboard with format detection
189
 * @param editor - Editor instance
190
 * @returns Clipboard data with detected formats
191
 */
192
function readClipboard(
193
  editor: SlateEditor
194
): Promise<ClipboardData>;
195
```
196

197
### Drag and Drop Support
198

199
Multi-format support for drag and drop operations.
200

201
```typescript { .api }
202
/**
203
 * Drag data interface
204
 */
205
interface DragData {
206
  /** Data transfer object */
207
  dataTransfer: DataTransfer;
208
  /** Supported formats */
209
  formats: string[];
210
  /** Drag source information */
211
  source?: {
212
    editor: SlateEditor;
213
    nodes: any[];
214
  };
215
}
216

217
/**
218
 * Handle drop event with format detection
219
 * @param editor - Editor instance
220
 * @param event - Drop event
221
 * @returns Processing result
222
 */
223
function handleDrop(
224
  editor: SlateEditor,
225
  event: DragEvent
226
): Promise<boolean>;
227

228
/**
229
 * Prepare drag data with multiple formats
230
 * @param editor - Editor instance
231
 * @param nodes - Nodes to drag
232
 * @returns Prepared drag data
233
 */
234
function prepareDragData(
235
  editor: SlateEditor,
236
  nodes: any[]
237
): DragData;
238
```
239

240
### Format Detection
241

242
Automatic format detection for unknown data.
243

244
```typescript { .api }
245
/**
246
 * Detect data format from content
247
 * @param data - Data to analyze
248
 * @param mimeType - Optional MIME type hint
249
 * @returns Detected format or null
250
 */
251
function detectFormat(
252
  data: string,
253
  mimeType?: string
254
): string | null;
255

256
/**
257
 * Format detection rules
258
 */
259
interface FormatDetectionRule {
260
  /** Format identifier */
261
  format: string;
262
  /** Detection function */
263
  detect: (data: string, mimeType?: string) => boolean;
264
  /** Detection priority */
265
  priority: number;
266
}
267

268
/**
269
 * Register format detection rule
270
 * @param rule - Detection rule
271
 */
272
function registerFormatDetection(rule: FormatDetectionRule): void;
273
```
274

275
### Export/Import System
276

277
Comprehensive export and import system with format conversion.
278

279
```typescript { .api }
280
/**
281
 * Export editor content to specified format
282
 * @param editor - Editor instance
283
 * @param format - Target format
284
 * @param options - Export options
285
 * @returns Exported data
286
 */
287
function exportContent(
288
  editor: SlateEditor,
289
  format: string,
290
  options?: {
291
    nodes?: any[];
292
    pretty?: boolean;
293
    metadata?: Record<string, any>;
294
  }
295
): string;
296

297
/**
298
 * Import content from specified format
299
 * @param editor - Editor instance
300
 * @param data - Data to import
301
 * @param format - Source format
302
 * @param options - Import options
303
 * @returns Imported nodes
304
 */
305
function importContent(
306
  editor: SlateEditor,
307
  data: string,
308
  format: string,
309
  options?: {
310
    replace?: boolean;
311
    position?: number[];
312
    normalize?: boolean;
313
  }
314
): any[];
315
```
316

317
**Usage Examples:**
318

319
```typescript
320
import { exportContent, importContent, detectFormat } from "@platejs/core";
321

322
// Export to different formats
323
const htmlExport = exportContent(editor, 'html', { pretty: true });
324
const markdownExport = exportContent(editor, 'markdown');
325
const astExport = exportContent(editor, 'ast');
326

327
// Import with format detection
328
const unknownData = `# Title\n\nSome content...`;
329
const detectedFormat = detectFormat(unknownData);
330
if (detectedFormat) {
331
  const importedNodes = importContent(editor, unknownData, detectedFormat);
332
  editor.insertFragment(importedNodes);
333
}
334

335
// Batch export for multiple formats
336
const exports = {
337
  html: exportContent(editor, 'html'),
338
  markdown: exportContent(editor, 'markdown'),
339
  plain: exportContent(editor, 'text')
340
};
341
```
342

343
## Supported Formats
344

345
Built-in format support includes:
346

347
```typescript { .api }
348
/** Built-in formats */
349
const SUPPORTED_FORMATS = {
350
  HTML: 'html',
351
  AST: 'ast',
352
  TEXT: 'text',
353
  JSON: 'json'
354
} as const;
355

356
/** Format MIME types */
357
const FORMAT_MIME_TYPES = {
358
  'html': 'text/html',
359
  'ast': 'application/x-slate-fragment',
360
  'text': 'text/plain',
361
  'json': 'application/json'
362
} as const;
363
```