0
# Editor Core
1

2
The `CodeMirrorEditor` class is the main editor implementation providing all text editing functionality including cursor management, selection handling, text operations, and integration with CodeMirror 6.
3

4
## Capabilities
5

6
### CodeMirrorEditor Class
7

8
Main editor implementation that integrates CodeMirror 6 with JupyterLab's editor interface.
9

10
```typescript { .api }
11
/**
12
 * CodeMirror editor implementation
13
 * Provides complete text editing functionality with CodeMirror 6 integration
14
 */
15
class CodeMirrorEditor implements CodeEditor.IEditor {
16
  constructor(options: CodeMirrorEditor.IOptions);
17
  
18
  // Signals
19
  readonly edgeRequested: Signal<this, CodeEditor.EdgeLocation>;
20
  
21
  // Core properties
22
  readonly host: HTMLElement;
23
  readonly editor: EditorView;
24
  readonly doc: Text;
25
  readonly model: CodeEditor.IModel;
26
  readonly lineCount: number;
27
  readonly lineHeight: number;
28
  readonly charWidth: number;
29
  readonly isDisposed: boolean;
30
  readonly state: EditorState;
31
  
32
  // UUID management
33
  uuid: string;
34
  
35
  // Lifecycle
36
  dispose(): void;
37
  
38
  // Configuration
39
  getOption(option: string): unknown;
40
  hasOption(option: string): boolean;
41
  setOption(option: string, value: unknown): void;
42
  setOptions(options: Record<string, any>): void;
43
  setBaseOptions(options: Record<string, any>): void;
44
  
45
  // Extension injection (alpha)
46
  injectExtension(ext: Extension): void;
47
  
48
  // Text operations
49
  getLine(line: number): string | undefined;
50
  getOffsetAt(position: CodeEditor.IPosition): number;
51
  getPositionAt(offset: number): CodeEditor.IPosition;
52
  getRange(from: { line: number; ch: number }, to: { line: number; ch: number }, separator?: string): string;
53
  
54
  // History
55
  undo(): void;
56
  redo(): void;
57
  clearHistory(): void;
58
  
59
  // Focus management
60
  focus(): void;
61
  hasFocus(): boolean;
62
  blur(): void;
63
  
64
  // Line operations
65
  firstLine(): number;
66
  lastLine(): number;
67
  newIndentedLine(): void;
68
  
69
  // Coordinates and positioning
70
  cursorCoords(where: boolean, mode?: 'window' | 'page' | 'local'): { left: number; top: number; bottom: number };
71
  revealPosition(position: CodeEditor.IPosition): void;
72
  revealSelection(selection: CodeEditor.IRange): void;
73
  getCoordinateForPosition(position: CodeEditor.IPosition): CodeEditor.ICoordinate | null;
74
  getPositionForCoordinate(coordinate: CodeEditor.ICoordinate): CodeEditor.IPosition | null;
75
  
76
  // Cursor management
77
  getCursorPosition(): CodeEditor.IPosition;
78
  setCursorPosition(position: CodeEditor.IPosition, options?: { bias?: number; origin?: string; scroll?: boolean }): void;
79
  
80
  // Selection management
81
  getSelection(): CodeEditor.ITextSelection;
82
  setSelection(selection: CodeEditor.IRange): void;
83
  getSelections(): CodeEditor.ITextSelection[];
84
  setSelections(selections: CodeEditor.IRange[]): void;
85
  replaceSelection(text: string): void;
86
  
87
  // Token operations
88
  getTokens(): CodeEditor.IToken[];
89
  getTokenAt(offset: number): CodeEditor.IToken;
90
  getTokenAtCursor(): CodeEditor.IToken;
91
  
92
  // Command execution
93
  execCommand(command: Command | StateCommand): void;
94
}
95

96
interface CodeMirrorEditor.IOptions extends CodeEditor.IOptions {
97
  extensionsRegistry?: IEditorExtensionRegistry;
98
  languages?: IEditorLanguageRegistry;
99
}
100
```
101

102
**Usage Examples:**
103

104
```typescript
105
import { CodeMirrorEditor } from "@jupyterlab/codemirror";
106
import { CodeEditor } from "@jupyterlab/codeeditor";
107

108
// Create editor with model
109
const model = new CodeEditor.Model();
110
const editor = new CodeMirrorEditor({
111
  model,
112
  host: document.createElement('div'),
113
  uuid: 'my-editor-id'
114
});
115

116
// Set content and language
117
model.sharedModel.setSource("def hello():\n    print('Hello, World!')");
118
model.mimeType = "text/x-python";
119

120
// Position cursor and focus
121
editor.setCursorPosition({ line: 1, column: 4 });
122
editor.focus();
123

124
// Get tokens for syntax highlighting information
125
const tokens = editor.getTokens();
126
console.log(tokens); // Array of syntax tokens
127

128
// Select text programmatically
129
editor.setSelection({
130
  start: { line: 0, column: 0 },
131
  end: { line: 0, column: 3 }
132
});
133

134
// Replace selected text
135
editor.replaceSelection("async def");
136
```
137

138
### Focus and Event Handling
139

140
The editor handles focus events and provides signals for edge detection.
141

142
```typescript { .api }
143
/**
144
 * Signal emitted when the editor reaches top or bottom edge
145
 * Useful for notebook cell navigation
146
 */
147
readonly edgeRequested: Signal<this, CodeEditor.EdgeLocation>;
148

149
// Focus management
150
focus(): void;
151
hasFocus(): boolean;
152
blur(): void;
153
```
154

155
### Configuration Management
156

157
Dynamic configuration system allowing runtime changes to editor behavior.
158

159
```typescript { .api }
160
// Get current option value
161
getOption(option: string): unknown;
162

163
// Check if option exists
164
hasOption(option: string): boolean;
165

166
// Set single option
167
setOption(option: string, value: unknown): void;
168

169
// Set multiple options (preferred for batch updates)
170
setOptions(options: Record<string, any>): void;
171

172
// Set base configuration
173
setBaseOptions(options: Record<string, any>): void;
174
```
175

176
**Common Configuration Options:**
177

178
```typescript
179
// Line numbers
180
editor.setOption('lineNumbers', true);
181

182
// Line wrapping
183
editor.setOption('lineWrap', true);
184

185
// Tab size
186
editor.setOption('tabSize', 4);
187

188
// Read-only mode
189
editor.setOption('readOnly', true);
190

191
// Custom theme
192
editor.setOption('theme', 'dark');
193

194
// Multiple options at once
195
editor.setOptions({
196
  lineNumbers: true,
197
  lineWrap: true,
198
  tabSize: 2,
199
  fontSize: 14
200
});
201
```
202

203
### Text and Position Operations
204

205
Comprehensive text manipulation and position handling.
206

207
```typescript { .api }
208
// Line operations
209
getLine(line: number): string | undefined;
210
firstLine(): number;
211
lastLine(): number;
212
readonly lineCount: number;
213

214
// Position conversion
215
getOffsetAt(position: CodeEditor.IPosition): number;
216
getPositionAt(offset: number): CodeEditor.IPosition;
217

218
// Text extraction
219
getRange(
220
  from: { line: number; ch: number }, 
221
  to: { line: number; ch: number }, 
222
  separator?: string
223
): string;
224

225
// Coordinate conversion
226
getCoordinateForPosition(position: CodeEditor.IPosition): CodeEditor.ICoordinate | null;
227
getPositionForCoordinate(coordinate: CodeEditor.ICoordinate): CodeEditor.IPosition | null;
228
```
229

230
### Selection and Cursor Management
231

232
Advanced cursor and selection handling with multi-cursor support.
233

234
```typescript { .api }
235
// Single cursor
236
getCursorPosition(): CodeEditor.IPosition;
237
setCursorPosition(
238
  position: CodeEditor.IPosition, 
239
  options?: { bias?: number; origin?: string; scroll?: boolean }
240
): void;
241

242
// Single selection
243
getSelection(): CodeEditor.ITextSelection;
244
setSelection(selection: CodeEditor.IRange): void;
245

246
// Multiple selections
247
getSelections(): CodeEditor.ITextSelection[];
248
setSelections(selections: CodeEditor.IRange[]): void;
249

250
// Text replacement
251
replaceSelection(text: string): void;
252
```
253

254
### Token Operations
255

256
Access to syntax highlighting tokens for advanced text analysis.
257

258
```typescript { .api }
259
/**
260
 * Get all tokens in the editor
261
 * Useful for syntax analysis and custom highlighting
262
 */
263
getTokens(): CodeEditor.IToken[];
264

265
/**
266
 * Get token at specific offset
267
 * @param offset - Character offset in document
268
 */
269
getTokenAt(offset: number): CodeEditor.IToken;
270

271
/**
272
 * Get token at current cursor position
273
 */
274
getTokenAtCursor(): CodeEditor.IToken;
275
```
276

277
**Token Structure:**
278

279
```typescript { .api }
280
interface CodeEditor.IToken {
281
  value: string;    // Token text content
282
  offset: number;   // Character offset in document
283
  type?: string;    // Token type for syntax highlighting
284
}
285
```
286

287
### Command Execution
288

289
Execute CodeMirror commands programmatically.
290

291
```typescript { .api }
292
/**
293
 * Execute a CodeMirror command on the editor
294
 * @param command - CodeMirror Command or StateCommand to execute
295
 */
296
execCommand(command: Command | StateCommand): void;
297
```
298

299
**Usage Examples:**
300

301
```typescript
302
import { indentMore, indentLess } from "@codemirror/commands";
303

304
// Indent selected text
305
editor.execCommand(indentMore);
306

307
// Dedent selected text
308
editor.execCommand(indentLess);
309

310
// Custom state command
311
const customCommand: StateCommand = (target) => {
312
  // Custom command logic
313
  return true;
314
};
315
editor.execCommand(customCommand);
316
```
317

318
### Extension Injection
319

320
Experimental API for injecting extensions at runtime.
321

322
```typescript { .api }
323
/**
324
 * Inject an extension into the editor (alpha/experimental)
325
 * @param ext - CodeMirror 6 extension to inject
326
 */
327
injectExtension(ext: Extension): void;
328
```
329

330
**Usage Example:**
331

332
```typescript
333
import { lineNumbers } from "@codemirror/view";
334

335
// Inject line numbers extension
336
editor.injectExtension(lineNumbers());
337
```
338

339
## Types
340

341
```typescript { .api }
342
interface CodeEditor.IPosition {
343
  line: number;
344
  column: number;
345
}
346

347
interface CodeEditor.IRange {
348
  start: CodeEditor.IPosition;
349
  end: CodeEditor.IPosition;
350
}
351

352
interface CodeEditor.ITextSelection extends CodeEditor.IRange {
353
  uuid: string;
354
}
355

356
interface CodeEditor.ICoordinate {
357
  left: number;
358
  top: number;
359
  right?: number;
360
  bottom?: number;
361
}
362

363
type CodeEditor.EdgeLocation = 'top' | 'topLine' | 'bottom';
364
```