0
# List Normalizers
1

2
Normalizer functions that automatically maintain consistent list structure and numbering. These functions are called automatically by the editor to ensure list integrity.
3

4
## Capabilities
5

6
### normalizeListStart
7

8
Normalizes list start numbering based on previous list items and restart markers.
9

10
```typescript { .api }
11
/**
12
 * Normalizes list start numbering based on previous items and restart markers
13
 * @param editor - The Slate editor instance
14
 * @param entry - The list entry to normalize
15
 * @param options - Options for sibling list queries
16
 * @returns True if normalization was applied, false otherwise
17
 */
18
function normalizeListStart<N extends ElementOf<E>, E extends Editor = Editor>(
19
  editor: E,
20
  entry: ElementEntryOf<E>,
21
  options?: Partial<GetSiblingListOptions<N, E>>
22
): boolean;
23
```
24

25
**Usage Example:**
26

27
```typescript
28
import { normalizeListStart } from "@udecode/plate-list";
29

30
// Typically called automatically by the editor
31
const normalized = normalizeListStart(editor, listEntry);
32
if (normalized) {
33
  console.log('List numbering was updated');
34
}
35
```
36

37
### normalizeListNotIndented
38

39
Removes list formatting from nodes that no longer have indentation.
40

41
```typescript { .api }
42
/**
43
 * Removes list formatting from nodes without indentation
44
 * @param editor - The Slate editor instance
45
 * @param entry - The node entry to check and normalize
46
 * @returns True if normalization was applied, false otherwise
47
 */
48
function normalizeListNotIndented(
49
  editor: Editor,
50
  entry: NodeEntry
51
): boolean;
52
```
53

54
**Usage Example:**
55

56
```typescript
57
import { normalizeListNotIndented } from "@udecode/plate-list";
58

59
// Remove list formatting from unindented nodes
60
const wasNormalized = normalizeListNotIndented(editor, nodeEntry);
61
```
62

63
### withInsertBreakList
64

65
Editor override that handles line breaks within todo lists, ensuring new todo items are created with unchecked state.
66

67
```typescript { .api }
68
/**
69
 * Editor override for handling line breaks in todo lists
70
 * @param context - The editor context with transforms
71
 * @returns Override object with insertBreak transform
72
 */
73
function withInsertBreakList(context: {
74
  editor: Editor;
75
  tf: { insertBreak: () => void };
76
}): {
77
  transforms: {
78
    insertBreak(): void;
79
  };
80
};
81
```
82

83
### getListExpectedListStart
84

85
Utility function that calculates the expected start number for a list item based on restart markers and previous items.
86

87
```typescript { .api }
88
/**
89
 * Calculates expected list start number
90
 * @param entry - The current list entry
91
 * @param prevEntry - The previous list entry (optional)
92
 * @returns The expected start number
93
 */
94
function getListExpectedListStart(
95
  entry: NodeEntry,
96
  prevEntry?: NodeEntry
97
): number;
98
```
99

100
**Usage Example:**
101

102
```typescript
103
import { getListExpectedListStart, getPreviousList } from "@udecode/plate-list";
104

105
const currentEntry = getListAbove(editor);
106
if (currentEntry) {
107
  const previousEntry = getPreviousList(editor, currentEntry);
108
  const expectedStart = getListExpectedListStart(currentEntry, previousEntry);
109
  console.log(`This list item should start at: ${expectedStart}`);
110
}
111
```
112

113
## Normalization Flow
114

115
### Automatic Normalization
116

117
The Plate List plugin automatically runs normalizers when:
118

119
1. **Insert Operations**: Adding new list items
120
2. **Remove Operations**: Deleting list items
121
3. **Set Operations**: Changing list properties
122
4. **Merge/Split Operations**: Combining or splitting list items
123

124
### Normalization Sequence
125

126
1. **Structure Normalization**: `normalizeListNotIndented` removes list formatting from unindented nodes
127
2. **Numbering Normalization**: `normalizeListStart` updates list numbering based on sequence and restart markers
128
3. **Break Handling**: `withInsertBreakList` manages line breaks in todo lists
129

130
### Manual Normalization
131

132
While normalization typically happens automatically, you can trigger it manually:
133

134
```typescript
135
import { normalizeListStart, normalizeListNotIndented } from "@udecode/plate-list";
136

137
// Normalize a specific list entry
138
const listEntry = getListAbove(editor);
139
if (listEntry) {
140
  // Check and fix indentation first
141
  normalizeListNotIndented(editor, listEntry);
142
  
143
  // Then fix numbering
144
  normalizeListStart(editor, listEntry);
145
}
146
```
147

148
## List Restart Behavior
149

150
### listRestart Property
151

152
Forces immediate restart of list numbering:
153

154
```typescript
155
// This will start numbering from 5 regardless of previous items
156
editor.tf.setNodes({
157
  listRestart: 5
158
}, { at: listItemPath });
159
```
160

161
### listRestartPolite Property
162

163
Only restarts numbering if at the beginning of a list:
164

165
```typescript
166
// This will only restart at 1 if this is the first item in a list sequence
167
editor.tf.setNodes({
168
  listRestartPolite: 1
169
}, { at: listItemPath });
170
```
171

172
### Expected Start Calculation
173

174
The `getListExpectedListStart` function follows this priority:
175

176
1. **listRestart**: Always takes precedence
177
2. **listRestartPolite**: Only applies if no previous list item
178
3. **Sequential**: Previous item's start + 1
179
4. **Default**: Start at 1
180

181
## Integration with Editor
182

183
### Plugin Integration
184

185
Normalizers are automatically integrated through the `BaseListPlugin`:
186

187
```typescript
188
import { BaseListPlugin } from "@udecode/plate-list";
189
import { createPlateEditor } from "@udecode/plate";
190

191
const editor = createPlateEditor({
192
  plugins: [BaseListPlugin], // Normalizers are included automatically
193
});
194
```
195

196
### Custom Normalization Options
197

198
Configure normalization behavior through plugin options:
199

200
```typescript
201
const editor = createPlateEditor({
202
  plugins: [
203
    BaseListPlugin.configure({
204
      options: {
205
        getSiblingListOptions: {
206
          breakOnEqIndentNeqListStyleType: true,
207
          breakOnLowerIndent: true,
208
          // Custom normalization behavior
209
        }
210
      }
211
    })
212
  ],
213
});
214
```
215

216
### Performance Considerations
217

218
- Normalizers run within `withoutNormalizing` blocks to batch changes
219
- Only affected list items are normalized, not the entire document
220
- Normalization is skipped when no changes are needed
221

222
## Common Normalization Scenarios
223

224
### Fixing Broken List Sequences
225

226
```typescript
227
// After deleting list items, numbering may be inconsistent
228
// Normalizers automatically fix this:
229
// Before: 1, 2, 4, 5 (item 3 was deleted)
230
// After:  1, 2, 3, 4 (automatically renumbered)
231
```
232

233
### Handling Indentation Changes
234

235
```typescript
236
// When outdenting removes all indentation:
237
// Before: Indented list item with listStyleType
238
// After:  Regular paragraph (list formatting removed)
239
```
240

241
### Todo List Line Breaks
242

243
```typescript
244
// When pressing Enter in a todo list:
245
// Creates new todo item with checked: false
246
// Maintains proper list structure
247
```