0
# Slate Prop Types
1

2
Slate Prop Types provides React PropTypes validators for Slate editor data structures. It offers validation for all major Slate objects including blocks, documents, marks, selections, and their corresponding collection types, enabling type checking during development for Slate-based rich text editors.
3

4
## Package Information
5

6
- **Package Name**: slate-prop-types
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install slate-prop-types`
10
- **Peer Dependencies**: immutable (>=3.8.1), slate (>=0.32.0 <0.50.0)
11

12
## Core Imports
13

14
```javascript
15
import Types from "slate-prop-types";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const Types = require("slate-prop-types");
22
```
23

24
Note: This package only exports a default export, not named exports.
25

26
For UMD (browser):
27

28
```html
29
<script src="https://unpkg.com/slate-prop-types/dist/slate-prop-types.min.js"></script>
30
<!-- Available as global SlatePropTypes -->
31
```
32

33
## Basic Usage
34

35
```javascript
36
import React from "react";
37
import PropTypes from "prop-types";
38
import Types from "slate-prop-types";
39

40
// Component using slate prop type validators
41
const SlateEditor = ({ value, document, selection }) => {
42
  return (
43
    <div>
44
      {/* Your Slate editor implementation */}
45
    </div>
46
  );
47
};
48

49
SlateEditor.propTypes = {
50
  value: Types.value.isRequired,
51
  document: Types.document,
52
  selection: Types.selection,
53
};
54

55
// Usage with collection types
56
const BlockList = ({ blocks, nodes }) => {
57
  return (
58
    <div>
59
      {/* Render blocks */}
60
    </div>
61
  );
62
};
63

64
BlockList.propTypes = {
65
  blocks: Types.blocks.isRequired,
66
  nodes: Types.nodes,
67
};
68
```
69

70
## Capabilities
71

72
### Individual Slate Object Validators
73

74
Validators for individual Slate data types.
75

76
```javascript { .api }
77
// Block element validator
78
Types.block: PropType;
79
Types.block.isRequired: PropType;
80

81
// Change operation validator  
82
Types.change: PropType;
83
Types.change.isRequired: PropType;
84

85
// Data object validator
86
Types.data: PropType;
87
Types.data.isRequired: PropType;
88

89
// Document validator
90
Types.document: PropType;
91
Types.document.isRequired: PropType;
92

93
// Inline element validator
94
Types.inline: PropType;
95
Types.inline.isRequired: PropType;
96

97
// Leaf node validator
98
Types.leaf: PropType;
99
Types.leaf.isRequired: PropType;
100

101
// Mark/formatting validator
102
Types.mark: PropType;
103
Types.mark.isRequired: PropType;
104

105
// Node validator
106
Types.node: PropType;
107
Types.node.isRequired: PropType;
108

109
// Range selection validator
110
Types.range: PropType;
111
Types.range.isRequired: PropType;
112

113
// Selection validator
114
Types.selection: PropType;
115
Types.selection.isRequired: PropType;
116

117
// Value/state validator
118
Types.value: PropType;
119
Types.value.isRequired: PropType;
120

121
// Text node validator
122
Types.text: PropType;
123
Types.text.isRequired: PropType;
124
```
125

126
### Collection Type Validators
127

128
Validators for Slate collection types (Lists and Sets).
129

130
```javascript { .api }
131
// List of Block elements
132
Types.blocks: PropType;
133
Types.blocks.isRequired: PropType;
134

135
// List of Inline elements
136
Types.inlines: PropType;
137
Types.inlines.isRequired: PropType;
138

139
// List of Leaf nodes
140
Types.leaves: PropType;
141
Types.leaves.isRequired: PropType;
142

143
// Set of Mark objects
144
Types.marks: PropType;
145
Types.marks.isRequired: PropType;
146

147
// List of Node objects
148
Types.nodes: PropType;
149
Types.nodes.isRequired: PropType;
150

151
// List of Range objects
152
Types.ranges: PropType;
153
Types.ranges.isRequired: PropType;
154

155
// List of Text nodes
156
Types.texts: PropType;
157
Types.texts.isRequired: PropType;
158
```
159

160
## PropType Validator Interface
161

162
Each exported prop type validator follows the standard React PropTypes interface:
163

164
### Optional Validation
165

166
```javascript
167
componentName.propTypes = {
168
  // Allows null, undefined, or valid Slate block
169
  myBlock: Types.block,
170
};
171
```
172

173
### Required Validation
174

175
```javascript
176
componentName.propTypes = {
177
  // Throws error if null, undefined, or invalid
178
  myBlock: Types.block.isRequired,
179
};
180
```
181

182
### Validation Behavior
183

184
- **Valid Value**: Returns `null` (no error)
185
- **Invalid Value**: Returns `Error` object with descriptive message
186
- **Null/Undefined**: 
187
  - Optional: Returns `null` (no error)
188
  - Required: Returns `Error` object
189

190
### Error Messages
191

192
When validation fails, descriptive error messages are provided:
193

194
```javascript
195
// Example error message for invalid block
196
"Invalid prop `myBlock` supplied to `MyComponent`, expected a Slate `Block` but received: [object Object]"
197

198
// Example error message for missing required prop
199
"The prop `myBlock` is marked as required in `MyComponent`, but it was not supplied."
200
```
201

202
## Slate Type Dependencies
203

204
All validators use Slate's built-in type checking methods for validation:
205

206
```javascript { .api }
207
// Internal validation functions (not directly exposed)
208
Block.isBlock(value): boolean;
209
Block.isBlockList(value): boolean;
210
Change.isChange(value): boolean;
211
Data.isData(value): boolean;
212
Document.isDocument(value): boolean;
213
Inline.isInline(value): boolean;
214
Inline.isInlineList(value): boolean;
215
Leaf.isLeaf(value): boolean;
216
Leaf.isLeafList(value): boolean;
217
Mark.isMark(value): boolean;
218
Mark.isMarkSet(value): boolean;
219
Node.isNode(value): boolean;
220
Node.isNodeList(value): boolean;
221
Range.isRange(value): boolean;
222
Range.isRangeList(value): boolean;
223
Selection.isSelection(value): boolean;
224
Value.isValue(value): boolean;
225
Text.isText(value): boolean;
226
Text.isTextList(value): boolean;
227
```
228

229
## Types
230

231
```javascript { .api }
232
/**
233
 * PropType validator function interface
234
 * @param props - Component props object
235
 * @param propName - Name of the prop being validated
236
 * @param componentName - Name of the component
237
 * @param location - Location description (e.g., "prop", "context")
238
 * @param propFullName - Full prop name for nested validation (optional)
239
 * @returns null if valid, Error if invalid
240
 */
241
interface PropTypeValidator {
242
  (props: object, propName: string, componentName: string, location: string, propFullName?: string): Error | null;
243
  isRequired: PropTypeValidator;
244
}
245

246
/**
247
 * Main Types export - object containing all prop type validators
248
 */
249
interface Types {
250
  // Individual validators
251
  block: PropTypeValidator;
252
  change: PropTypeValidator;
253
  data: PropTypeValidator;
254
  document: PropTypeValidator;
255
  inline: PropTypeValidator;
256
  leaf: PropTypeValidator;
257
  mark: PropTypeValidator;
258
  node: PropTypeValidator;
259
  range: PropTypeValidator;
260
  selection: PropTypeValidator;
261
  value: PropTypeValidator;
262
  text: PropTypeValidator;
263
  
264
  // Collection validators
265
  blocks: PropTypeValidator;
266
  inlines: PropTypeValidator;
267
  leaves: PropTypeValidator;
268
  marks: PropTypeValidator;
269
  nodes: PropTypeValidator;
270
  ranges: PropTypeValidator;
271
  texts: PropTypeValidator;
272
}
273
```
274

275
## Advanced Usage Examples
276

277
### Complex Component Validation
278

279
```javascript
280
import React from "react";
281
import PropTypes from "prop-types";
282
import Types from "slate-prop-types";
283

284
const RichTextEditor = ({ 
285
  value, 
286
  document, 
287
  selection, 
288
  blocks, 
289
  marks, 
290
  onChange, 
291
  onSelectionChange 
292
}) => {
293
  return (
294
    <div className="slate-editor">
295
      {/* Editor implementation */}
296
    </div>
297
  );
298
};
299

300
RichTextEditor.propTypes = {
301
  // Required Slate objects
302
  value: Types.value.isRequired,
303
  onChange: PropTypes.func.isRequired,
304
  
305
  // Optional Slate objects
306
  document: Types.document,
307
  selection: Types.selection,
308
  
309
  // Collection types
310
  blocks: Types.blocks,
311
  marks: Types.marks,
312
  
313
  // Event handlers
314
  onSelectionChange: PropTypes.func,
315
};
316

317
RichTextEditor.defaultProps = {
318
  document: null,
319
  selection: null,
320
  blocks: null,
321
  marks: null,
322
  onSelectionChange: () => {},
323
};
324
```
325

326
### Plugin Prop Validation
327

328
```javascript
329
const SlatePlugin = ({ nodes, ranges, marks }) => {
330
  // Plugin implementation
331
  return null;
332
};
333

334
SlatePlugin.propTypes = {
335
  nodes: Types.nodes.isRequired,
336
  ranges: Types.ranges,
337
  marks: Types.marks,
338
};
339

340
export default SlatePlugin;
341
```