tessl/npm-lexical

Lexical is an extensible text editor framework that provides excellent reliability, accessible and performance.

—

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

Command System

Name: tessl/npm-lexical
Author: tessl

Comprehensive command system for handling user interactions, keyboard events, and programmatic editor operations. Lexical's command system provides a powerful event-driven architecture that allows for extensible and predictable editor behavior.

Capabilities

Command Creation and Types

Core utilities for creating and working with typed commands.

/**
 * Create a typed command
 * @param type - Optional command type identifier
 * @returns Typed command instance
 */
function createCommand<T = void>(type?: string): LexicalCommand<T>;

/**
 * Type representing a Lexical command
 */
interface LexicalCommand<T = void> {
  type?: string;
}

/**
 * Extract payload type from command
 */
type CommandPayloadType<TCommand extends LexicalCommand<unknown>> = 
  TCommand extends LexicalCommand<infer TPayload> ? TPayload : never;

/**
 * Command listener function type
 */
type CommandListener<P> = (payload: P, editor: LexicalEditor) => boolean;

/**
 * Command listener priority levels
 */
type CommandListenerPriority = 0 | 1 | 2 | 3 | 4;

Text Input Commands

Commands for handling text input and modification.

/** Command for controlled text insertion */
const CONTROLLED_TEXT_INSERTION_COMMAND: LexicalCommand<string | InputEvent>;

/** Command for inserting line breaks */
const INSERT_LINE_BREAK_COMMAND: LexicalCommand<boolean>;

/** Command for inserting paragraphs */
const INSERT_PARAGRAPH_COMMAND: LexicalCommand<void>;

/** Command for inserting tabs */
const INSERT_TAB_COMMAND: LexicalCommand<void>;

/** Command for removing text */
const REMOVE_TEXT_COMMAND: LexicalCommand<InputEvent | null>;

/** Command for deleting characters */
const DELETE_CHARACTER_COMMAND: LexicalCommand<boolean>;

/** Command for deleting words */
const DELETE_WORD_COMMAND: LexicalCommand<boolean>;

/** Command for deleting lines */
const DELETE_LINE_COMMAND: LexicalCommand<boolean>;

Text Formatting Commands

Commands for applying text formatting and styles.

/** Command for formatting text */
const FORMAT_TEXT_COMMAND: LexicalCommand<TextFormatType>;

/** Command for formatting elements */
const FORMAT_ELEMENT_COMMAND: LexicalCommand<ElementFormatType>;

/** Command for indenting content */
const INDENT_CONTENT_COMMAND: LexicalCommand<void>;

/** Command for outdenting content */
const OUTDENT_CONTENT_COMMAND: LexicalCommand<void>;

type TextFormatType = 'bold' | 'italic' | 'strikethrough' | 'underline' | 'code' | 'subscript' | 'superscript' | 'highlight';
type ElementFormatType = 'left' | 'center' | 'right' | 'justify' | 'start' | 'end';

Keyboard Event Commands

Commands corresponding to keyboard interactions.

/** Arrow key commands */
const KEY_ARROW_DOWN_COMMAND: LexicalCommand<KeyboardEvent>;
const KEY_ARROW_LEFT_COMMAND: LexicalCommand<KeyboardEvent>;
const KEY_ARROW_RIGHT_COMMAND: LexicalCommand<KeyboardEvent>;
const KEY_ARROW_UP_COMMAND: LexicalCommand<KeyboardEvent>;

/** Special key commands */
const KEY_BACKSPACE_COMMAND: LexicalCommand<KeyboardEvent>;
const KEY_DELETE_COMMAND: LexicalCommand<KeyboardEvent>;
const KEY_ENTER_COMMAND: LexicalCommand<KeyboardEvent>;
const KEY_ESCAPE_COMMAND: LexicalCommand<KeyboardEvent>;
const KEY_SPACE_COMMAND: LexicalCommand<KeyboardEvent>;
const KEY_TAB_COMMAND: LexicalCommand<KeyboardEvent>;

/** Generic key event commands */
const KEY_DOWN_COMMAND: LexicalCommand<KeyboardEvent>;
const KEY_MODIFIER_COMMAND: LexicalCommand<KeyboardEvent>;

Mouse and Touch Commands

Commands for handling mouse and touch interactions.

/** Command for click events */
const CLICK_COMMAND: LexicalCommand<MouseEvent>;

/** Command for focus events */
const FOCUS_COMMAND: LexicalCommand<FocusEvent>;

/** Command for blur events */
const BLUR_COMMAND: LexicalCommand<FocusEvent>;

/** Drag and drop commands */
const DRAGSTART_COMMAND: LexicalCommand<DragEvent>;
const DRAGOVER_COMMAND: LexicalCommand<DragEvent>;
const DRAGEND_COMMAND: LexicalCommand<DragEvent>;
const DROP_COMMAND: LexicalCommand<DragEvent>;

Clipboard Commands

Commands for clipboard operations.

/** Command for copy operations */
const COPY_COMMAND: LexicalCommand<ClipboardEvent | KeyboardEvent>;

/** Command for cut operations */
const CUT_COMMAND: LexicalCommand<ClipboardEvent | KeyboardEvent>;

/** Command for paste operations */
const PASTE_COMMAND: LexicalCommand<ClipboardEvent>;

/** Type for paste command payloads */
type PasteCommandType = ClipboardEvent | InputEvent | KeyboardEvent;

/** Command for inserting clipboard nodes into selection */
const SELECTION_INSERT_CLIPBOARD_NODES_COMMAND: LexicalCommand<{
  nodes: Array<LexicalNode>;
  selection: BaseSelection;
}>;

History Commands

Commands for undo/redo functionality.

/** Command for undo operations */
const UNDO_COMMAND: LexicalCommand<void>;

/** Command for redo operations */
const REDO_COMMAND: LexicalCommand<void>;

/** Command to check if undo is available */
const CAN_UNDO_COMMAND: LexicalCommand<boolean>;

/** Command to check if redo is available */
const CAN_REDO_COMMAND: LexicalCommand<boolean>;

/** Command to clear editor history */
const CLEAR_HISTORY_COMMAND: LexicalCommand<void>;

Selection Commands

Commands for selection management and changes.

/** Command fired when selection changes */
const SELECTION_CHANGE_COMMAND: LexicalCommand<void>;

/** Command for selecting all content */
const SELECT_ALL_COMMAND: LexicalCommand<KeyboardEvent>;

/** Movement modifiers for selection commands */
const MOVE_TO_END: string;
const MOVE_TO_START: string;

Editor State Commands

Commands for managing overall editor state.

/** Command to clear all editor content */
const CLEAR_EDITOR_COMMAND: LexicalCommand<void>;

Usage Examples:

import { 
  createCommand, 
  FORMAT_TEXT_COMMAND, 
  INSERT_PARAGRAPH_COMMAND,
  UNDO_COMMAND,
  SELECTION_CHANGE_COMMAND,
  COMMAND_PRIORITY_HIGH 
} from "lexical";

// Create custom command
const CUSTOM_COMMAND = createCommand<{ data: string }>('CUSTOM_COMMAND');

// Register command listener
const removeListener = editor.registerCommand(
  FORMAT_TEXT_COMMAND,
  (formatType) => {
    console.log('Formatting text:', formatType);
    return false; // Allow other listeners to handle
  },
  COMMAND_PRIORITY_HIGH
);

// Register selection change listener
editor.registerCommand(
  SELECTION_CHANGE_COMMAND,
  () => {
    const selection = $getSelection();
    console.log('Selection changed:', selection);
    return false;
  },
  COMMAND_PRIORITY_LOW
);

// Dispatch commands
editor.dispatchCommand(FORMAT_TEXT_COMMAND, 'bold');
editor.dispatchCommand(INSERT_PARAGRAPH_COMMAND, undefined);
editor.dispatchCommand(UNDO_COMMAND, undefined);

// Dispatch custom command
editor.dispatchCommand(CUSTOM_COMMAND, { data: 'example' });

// Remove listener when done
removeListener();

Command Listener Management

Methods for registering and managing command listeners on the editor.

interface LexicalEditor {
  /**
   * Register a command listener
   * @param command - Command to listen for
   * @param listener - Function to handle command
   * @param priority - Execution priority (higher numbers execute first)
   * @returns Function to remove the listener
   */
  registerCommand<P>(
    command: LexicalCommand<P>,
    listener: CommandListener<P>,
    priority: CommandListenerPriority
  ): () => void;

  /**
   * Dispatch a command to all listeners
   * @param command - Command to dispatch
   * @param payload - Command payload
   * @returns True if any listener handled the command
   */
  dispatchCommand<P>(command: LexicalCommand<P>, payload: P): boolean;
}

Advanced Command Patterns

Common patterns for working with commands in Lexical applications.

// Priority-based command handling
editor.registerCommand(
  KEY_ENTER_COMMAND,
  (event) => {
    if (someSpecialCondition) {
      // Handle the command and prevent other handlers
      doSpecialAction();
      return true;
    }
    // Let other handlers process the command
    return false;
  },
  COMMAND_PRIORITY_HIGH
);

// Conditional command listening
editor.registerCommand(
  PASTE_COMMAND,
  (event) => {
    const selection = $getSelection();
    if ($isRangeSelection(selection)) {
      // Handle paste in range selection
      handlePaste(event, selection);
      return true;
    }
    return false;
  },
  COMMAND_PRIORITY_NORMAL
);

// Custom command with complex payload
const CUSTOM_FORMAT_COMMAND = createCommand<{
  format: TextFormatType;
  range?: { start: number; end: number };
  style?: string;
}>('CUSTOM_FORMAT');

editor.registerCommand(
  CUSTOM_FORMAT_COMMAND,
  ({ format, range, style }) => {
    // Apply custom formatting logic
    return true;
  },
  COMMAND_PRIORITY_NORMAL
);

The command system is the backbone of Lexical's event handling, providing a clean and extensible way to respond to user interactions and implement editor functionality. Commands can be intercepted, modified, or completely overridden by registering listeners with appropriate priorities.