0
# Event Handling and Hotkeys
1

2
Comprehensive event handling system with cross-platform hotkey support, customizable shortcuts, and event pipeline management.
3

4
## Capabilities
5

6
### Hotkeys System
7

8
Cross-platform hotkey system with intelligent key combination handling.
9

10
```typescript { .api }
11
/**
12
 * Hotkeys interface for key combination handling
13
 */
14
interface Hotkeys {
15
  /** Create a hotkey checker function */
16
  createHotkey(hotkey: string): (event: KeyboardEvent) => boolean;
17
  /** Check if event matches hotkey */
18
  isHotkey(hotkey: string, event: KeyboardEvent): boolean;
19
  /** Parse hotkey string into components */
20
  parseHotkey(hotkey: string): { key: string; modifiers: string[] };
21
}
22

23
/**
24
 * Global Hotkeys utility
25
 */
26
const Hotkeys: Hotkeys;
27
```
28

29
**Usage Examples:**
30

31
```typescript
32
import { Hotkeys } from "@platejs/core";
33

34
// Create hotkey checker
35
const isBold = Hotkeys.createHotkey('mod+b');
36
const isUndo = Hotkeys.createHotkey('mod+z');
37

38
// Handle keyboard events
39
const handleKeyDown = (event: KeyboardEvent) => {
40
  if (isBold(event)) {
41
    // Apply bold formatting
42
    editor.addMark('bold', true);
43
    return;
44
  }
45
  
46
  if (isUndo(event)) {
47
    // Undo last operation
48
    editor.undo();
49
    return;
50
  }
51
};
52

53
// Direct hotkey checking
54
document.addEventListener('keydown', (event) => {
55
  if (Hotkeys.isHotkey('ctrl+s', event)) {
56
    // Save document
57
    event.preventDefault();
58
  }
59
});
60
```
61

62
### Keyboard Event Handling
63

64
Comprehensive keyboard event processing with editor integration.
65

66
```typescript { .api }
67
/**
68
 * Keyboard event handler interface
69
 */
70
interface KeyboardHandler {
71
  /** Handle keydown events */
72
  onKeyDown?: (event: KeyboardEvent, editor: SlateEditor) => boolean | void;
73
  /** Handle keyup events */
74
  onKeyUp?: (event: KeyboardEvent, editor: SlateEditor) => boolean | void;
75
  /** Handle key press events */
76
  onKeyPress?: (event: KeyboardEvent, editor: SlateEditor) => boolean | void;
77
}
78

79
/**
80
 * Register global keyboard handler
81
 * @param handler - Keyboard event handler
82
 */
83
function registerKeyboardHandler(handler: KeyboardHandler): void;
84
```
85

86
**Usage Examples:**
87

88
```typescript
89
import { registerKeyboardHandler } from "@platejs/core";
90

91
// Register custom keyboard handler
92
registerKeyboardHandler({
93
  onKeyDown: (event, editor) => {
94
    // Custom Tab handling
95
    if (event.key === 'Tab') {
96
      if (event.shiftKey) {
97
        // Shift+Tab - decrease indent
98
        editor.transforms.decreaseIndent();
99
      } else {
100
        // Tab - increase indent
101
        editor.transforms.increaseIndent();
102
      }
103
      event.preventDefault();
104
      return true; // Prevent default handling
105
    }
106
  }
107
});
108
```
109

110
### Plugin Event System
111

112
Event handling integration within the plugin system.
113

114
```typescript { .api }
115
/**
116
 * Plugin event handlers
117
 */
118
interface PluginEventHandlers {
119
  /** DOM event handlers */
120
  handlers?: {
121
    onKeyDown?: KeyboardHandler['onKeyDown'];
122
    onKeyUp?: KeyboardHandler['onKeyUp'];
123
    onClick?: (event: MouseEvent, editor: SlateEditor) => boolean | void;
124
    onFocus?: (event: FocusEvent, editor: SlateEditor) => boolean | void;
125
    onBlur?: (event: FocusEvent, editor: SlateEditor) => boolean | void;
126
  };
127
  /** Editor event handlers */
128
  onChange?: (editor: SlateEditor) => void;
129
  onSelectionChange?: (editor: SlateEditor) => void;
130
  onValueChange?: (editor: SlateEditor) => void;
131
}
132
```
133

134
**Usage Examples:**
135

136
```typescript
137
import { createSlatePlugin } from "@platejs/core";
138

139
const MyPlugin = createSlatePlugin({
140
  key: 'myPlugin',
141
  handlers: {
142
    onKeyDown: (event, editor) => {
143
      if (event.key === 'Enter' && event.ctrlKey) {
144
        // Ctrl+Enter - insert specific block
145
        editor.insertNode({
146
          type: 'action-item',
147
          children: [{ text: '' }]
148
        });
149
        return true;
150
      }
151
    },
152
    onClick: (event, editor) => {
153
      // Handle custom click behavior
154
      console.log('Click handled by plugin');
155
    }
156
  },
157
  onChange: (editor) => {
158
    // React to editor changes
159
    console.log('Editor content changed');
160
  }
161
});
162
```
163

164
### Event Pipeline System
165

166
Event processing pipeline for coordinated event handling across plugins.
167

168
```typescript { .api }
169
/**
170
 * Event pipeline configuration
171
 */
172
interface EventPipeline {
173
  /** Pipeline priority */
174
  priority?: number;
175
  /** Pipeline condition */
176
  condition?: (event: Event, editor: SlateEditor) => boolean;
177
  /** Pipeline handler */
178
  handler: (event: Event, editor: SlateEditor) => boolean | void;
179
}
180

181
/**
182
 * Register event pipeline
183
 * @param pipeline - Pipeline configuration
184
 */
185
function registerEventPipeline(pipeline: EventPipeline): void;
186
```
187

188
### Composition Event Handling
189

190
Support for input method editors (IME) and composition events.
191

192
```typescript { .api }
193
/**
194
 * Composition event handlers
195
 */
196
interface CompositionHandlers {
197
  /** Composition start */
198
  onCompositionStart?: (event: CompositionEvent, editor: SlateEditor) => void;
199
  /** Composition update */
200
  onCompositionUpdate?: (event: CompositionEvent, editor: SlateEditor) => void;
201
  /** Composition end */
202
  onCompositionEnd?: (event: CompositionEvent, editor: SlateEditor) => void;
203
}
204
```
205

206
### Custom Event Types
207

208
Support for custom editor events and event dispatching.
209

210
```typescript { .api }
211
/**
212
 * Custom editor event
213
 */
214
interface EditorEvent<T = any> {
215
  /** Event type */
216
  type: string;
217
  /** Event data */
218
  data: T;
219
  /** Event timestamp */
220
  timestamp: number;
221
  /** Event source */
222
  source: 'user' | 'api' | 'plugin';
223
}
224

225
/**
226
 * Dispatch custom editor event
227
 * @param editor - Editor instance
228
 * @param event - Event to dispatch
229
 */
230
function dispatchEditorEvent<T>(
231
  editor: SlateEditor, 
232
  event: EditorEvent<T>
233
): void;
234

235
/**
236
 * Listen for custom editor events
237
 * @param editor - Editor instance
238
 * @param eventType - Event type to listen for
239
 * @param handler - Event handler function
240
 */
241
function addEventListener<T>(
242
  editor: SlateEditor,
243
  eventType: string,
244
  handler: (event: EditorEvent<T>) => void
245
): void;
246
```
247

248
## Hotkey Patterns
249

250
Common hotkey patterns and platform-specific handling:
251

252
```typescript { .api }
253
// Platform-specific modifiers
254
const HOTKEYS = {
255
  // Cross-platform (mod = Cmd on Mac, Ctrl elsewhere)
256
  BOLD: 'mod+b',
257
  ITALIC: 'mod+i',
258
  UNDERLINE: 'mod+u',
259
  UNDO: 'mod+z',
260
  REDO: 'mod+shift+z',
261
  SAVE: 'mod+s',
262
  
263
  // Specific platforms
264
  MAC_REDO: 'cmd+y',
265
  WIN_REDO: 'ctrl+y',
266
  
267
  // Function keys
268
  HELP: 'f1',
269
  RENAME: 'f2',
270
  
271
  // Special combinations
272
  SELECT_ALL: 'mod+a',
273
  FIND: 'mod+f',
274
  REPLACE: 'mod+h'
275
} as const;
276
```
277

278
**Usage Examples:**
279

280
```typescript
281
import { Hotkeys } from "@platejs/core";
282

283
// Plugin with comprehensive hotkey support
284
const FormattingPlugin = createSlatePlugin({
285
  key: 'formatting',
286
  handlers: {
287
    onKeyDown: (event, editor) => {
288
      if (Hotkeys.isHotkey('mod+b', event)) {
289
        editor.toggleMark('bold');
290
        return true;
291
      }
292
      
293
      if (Hotkeys.isHotkey('mod+i', event)) {
294
        editor.toggleMark('italic');
295
        return true;
296
      }
297
      
298
      if (Hotkeys.isHotkey('mod+shift+x', event)) {
299
        editor.transforms.clearFormatting();
300
        return true;
301
      }
302
    }
303
  }
304
});
305
```