tessl/npm-jupyterlab--codemirror

CodeMirror 6 editor provider for JupyterLab with comprehensive language support, themes, extensions, and collaborative editing capabilities

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Editor Core

Name: tessl/npm-jupyterlab--codemirror
Author: tessl

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.

Capabilities

CodeMirrorEditor Class

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

/**
 * CodeMirror editor implementation
 * Provides complete text editing functionality with CodeMirror 6 integration
 */
class CodeMirrorEditor implements CodeEditor.IEditor {
  constructor(options: CodeMirrorEditor.IOptions);
  
  // Signals
  readonly edgeRequested: Signal<this, CodeEditor.EdgeLocation>;
  
  // Core properties
  readonly host: HTMLElement;
  readonly editor: EditorView;
  readonly doc: Text;
  readonly model: CodeEditor.IModel;
  readonly lineCount: number;
  readonly lineHeight: number;
  readonly charWidth: number;
  readonly isDisposed: boolean;
  readonly state: EditorState;
  
  // UUID management
  uuid: string;
  
  // Lifecycle
  dispose(): void;
  
  // Configuration
  getOption(option: string): unknown;
  hasOption(option: string): boolean;
  setOption(option: string, value: unknown): void;
  setOptions(options: Record<string, any>): void;
  setBaseOptions(options: Record<string, any>): void;
  
  // Extension injection (alpha)
  injectExtension(ext: Extension): void;
  
  // Text operations
  getLine(line: number): string | undefined;
  getOffsetAt(position: CodeEditor.IPosition): number;
  getPositionAt(offset: number): CodeEditor.IPosition;
  getRange(from: { line: number; ch: number }, to: { line: number; ch: number }, separator?: string): string;
  
  // History
  undo(): void;
  redo(): void;
  clearHistory(): void;
  
  // Focus management
  focus(): void;
  hasFocus(): boolean;
  blur(): void;
  
  // Line operations
  firstLine(): number;
  lastLine(): number;
  newIndentedLine(): void;
  
  // Coordinates and positioning
  cursorCoords(where: boolean, mode?: 'window' | 'page' | 'local'): { left: number; top: number; bottom: number };
  revealPosition(position: CodeEditor.IPosition): void;
  revealSelection(selection: CodeEditor.IRange): void;
  getCoordinateForPosition(position: CodeEditor.IPosition): CodeEditor.ICoordinate | null;
  getPositionForCoordinate(coordinate: CodeEditor.ICoordinate): CodeEditor.IPosition | null;
  
  // Cursor management
  getCursorPosition(): CodeEditor.IPosition;
  setCursorPosition(position: CodeEditor.IPosition, options?: { bias?: number; origin?: string; scroll?: boolean }): void;
  
  // Selection management
  getSelection(): CodeEditor.ITextSelection;
  setSelection(selection: CodeEditor.IRange): void;
  getSelections(): CodeEditor.ITextSelection[];
  setSelections(selections: CodeEditor.IRange[]): void;
  replaceSelection(text: string): void;
  
  // Token operations
  getTokens(): CodeEditor.IToken[];
  getTokenAt(offset: number): CodeEditor.IToken;
  getTokenAtCursor(): CodeEditor.IToken;
  
  // Command execution
  execCommand(command: Command | StateCommand): void;
}

interface CodeMirrorEditor.IOptions extends CodeEditor.IOptions {
  extensionsRegistry?: IEditorExtensionRegistry;
  languages?: IEditorLanguageRegistry;
}

Usage Examples:

import { CodeMirrorEditor } from "@jupyterlab/codemirror";
import { CodeEditor } from "@jupyterlab/codeeditor";

// Create editor with model
const model = new CodeEditor.Model();
const editor = new CodeMirrorEditor({
  model,
  host: document.createElement('div'),
  uuid: 'my-editor-id'
});

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

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

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

// Select text programmatically
editor.setSelection({
  start: { line: 0, column: 0 },
  end: { line: 0, column: 3 }
});

// Replace selected text
editor.replaceSelection("async def");

Focus and Event Handling

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

/**
 * Signal emitted when the editor reaches top or bottom edge
 * Useful for notebook cell navigation
 */
readonly edgeRequested: Signal<this, CodeEditor.EdgeLocation>;

// Focus management
focus(): void;
hasFocus(): boolean;
blur(): void;

Configuration Management

Dynamic configuration system allowing runtime changes to editor behavior.

// Get current option value
getOption(option: string): unknown;

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

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

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

// Set base configuration
setBaseOptions(options: Record<string, any>): void;

Common Configuration Options:

// Line numbers
editor.setOption('lineNumbers', true);

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

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

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

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

// Multiple options at once
editor.setOptions({
  lineNumbers: true,
  lineWrap: true,
  tabSize: 2,
  fontSize: 14
});

Text and Position Operations

Comprehensive text manipulation and position handling.

// Line operations
getLine(line: number): string | undefined;
firstLine(): number;
lastLine(): number;
readonly lineCount: number;

// Position conversion
getOffsetAt(position: CodeEditor.IPosition): number;
getPositionAt(offset: number): CodeEditor.IPosition;

// Text extraction
getRange(
  from: { line: number; ch: number }, 
  to: { line: number; ch: number }, 
  separator?: string
): string;

// Coordinate conversion
getCoordinateForPosition(position: CodeEditor.IPosition): CodeEditor.ICoordinate | null;
getPositionForCoordinate(coordinate: CodeEditor.ICoordinate): CodeEditor.IPosition | null;

Selection and Cursor Management

Advanced cursor and selection handling with multi-cursor support.

// Single cursor
getCursorPosition(): CodeEditor.IPosition;
setCursorPosition(
  position: CodeEditor.IPosition, 
  options?: { bias?: number; origin?: string; scroll?: boolean }
): void;

// Single selection
getSelection(): CodeEditor.ITextSelection;
setSelection(selection: CodeEditor.IRange): void;

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

// Text replacement
replaceSelection(text: string): void;

Token Operations

Access to syntax highlighting tokens for advanced text analysis.

/**
 * Get all tokens in the editor
 * Useful for syntax analysis and custom highlighting
 */
getTokens(): CodeEditor.IToken[];

/**
 * Get token at specific offset
 * @param offset - Character offset in document
 */
getTokenAt(offset: number): CodeEditor.IToken;

/**
 * Get token at current cursor position
 */
getTokenAtCursor(): CodeEditor.IToken;

Token Structure:

interface CodeEditor.IToken {
  value: string;    // Token text content
  offset: number;   // Character offset in document
  type?: string;    // Token type for syntax highlighting
}

Command Execution

Execute CodeMirror commands programmatically.

/**
 * Execute a CodeMirror command on the editor
 * @param command - CodeMirror Command or StateCommand to execute
 */
execCommand(command: Command | StateCommand): void;

Usage Examples:

import { indentMore, indentLess } from "@codemirror/commands";

// Indent selected text
editor.execCommand(indentMore);

// Dedent selected text
editor.execCommand(indentLess);

// Custom state command
const customCommand: StateCommand = (target) => {
  // Custom command logic
  return true;
};
editor.execCommand(customCommand);

Extension Injection

Experimental API for injecting extensions at runtime.

/**
 * Inject an extension into the editor (alpha/experimental)
 * @param ext - CodeMirror 6 extension to inject
 */
injectExtension(ext: Extension): void;

Usage Example:

import { lineNumbers } from "@codemirror/view";

// Inject line numbers extension
editor.injectExtension(lineNumbers());

Types

interface CodeEditor.IPosition {
  line: number;
  column: number;
}

interface CodeEditor.IRange {
  start: CodeEditor.IPosition;
  end: CodeEditor.IPosition;
}

interface CodeEditor.ITextSelection extends CodeEditor.IRange {
  uuid: string;
}

interface CodeEditor.ICoordinate {
  left: number;
  top: number;
  right?: number;
  bottom?: number;
}

type CodeEditor.EdgeLocation = 'top' | 'topLine' | 'bottom';