Slate Operations

/**
 * Find nodes matching the specified criteria
 * @param editor - Editor instance
 * @param options - Search criteria and options
 * @returns Array of matching node entries
 */
function findNode<T extends TNode>(
  editor: TEditor,
  options?: FindNodeOptions
): TNodeEntry<T> | undefined;

interface FindNodeOptions {
  /** Function to match nodes */
  match?: (node: TNode, path: TPath) => boolean;
  
  /** Starting location for search */
  at?: TLocation;
  
  /** Search mode */
  mode?: 'all' | 'highest' | 'lowest';
  
  /** Whether to include root editor node */
  universal?: boolean;
  
  /** Reverse search direction */
  reverse?: boolean;
  
  /** Maximum depth to search */
  voids?: boolean;
}

/**
 * Get node entry at the specified location
 * @param editor - Editor instance
 * @param at - Location to get node from
 * @returns Node entry at location
 */
function getNodeEntry<T extends TNode>(
  editor: TEditor,
  at: TLocation
): TNodeEntry<T> | undefined;

/**
 * Get multiple nodes matching criteria
 * @param editor - Editor instance
 * @param options - Search criteria
 * @returns Generator of matching node entries
 */
function getNodes<T extends TNode>(
  editor: TEditor,
  options?: GetNodesOptions
): Generator<TNodeEntry<T>, void, undefined>;

interface GetNodesOptions extends FindNodeOptions {
  /** Pass through options to Slate's nodes method */
  pass?: (entry: TNodeEntry) => boolean;
}

import { findNode, getNodes } from "@udecode/plate-common";

// Find a specific node type
const paragraphNode = findNode(editor, {
  match: (node) => node.type === 'p'
});

// Get all text nodes
const textNodes = Array.from(getNodes(editor, {
  match: (node) => node.text !== undefined
}));

/**
 * Check if node is an element
 * @param node - Node to check
 * @returns True if node is an element
 */
function isElement(node: TNode): node is TElement;

/**
 * Check if node is a text node
 * @param node - Node to check
 * @returns True if node is a text node
 */
function isText(node: TNode): node is TText;

/**
 * Check if node is an editor
 * @param node - Node to check
 * @returns True if node is an editor
 */
function isEditor(node: TNode): node is TEditor;

/**
 * Check if some node matches criteria
 * @param editor - Editor instance
 * @param options - Search criteria
 * @returns True if any node matches
 */
function someNode(
  editor: TEditor,
  options: FindNodeOptions
): boolean;

/**
 * Insert nodes at the specified location
 * @param editor - Editor instance
 * @param nodes - Nodes to insert
 * @param options - Insertion options
 */
function insertNodes<T extends TNode>(
  editor: TEditor,
  nodes: T | T[],
  options?: InsertNodesOptions
): void;

interface InsertNodesOptions {
  /** Location to insert at */
  at?: TLocation;
  
  /** Insert mode */
  mode?: 'highest' | 'lowest';
  
  /** Whether to hang selection */
  hanging?: boolean;
  
  /** Whether to select inserted content */
  select?: boolean;
  
  /** Whether to allow void nodes */
  voids?: boolean;
}

/**
 * Insert text at the current selection
 * @param editor - Editor instance
 * @param text - Text to insert
 */
function insertText(
  editor: TEditor,
  text: string
): void;

/**
 * Insert a break (new line) at current selection
 * @param editor - Editor instance
 */
function insertBreak(editor: TEditor): void;

/**
 * Remove nodes matching criteria
 * @param editor - Editor instance
 * @param options - Removal criteria
 */
function removeNodes(
  editor: TEditor,
  options?: RemoveNodesOptions
): void;

interface RemoveNodesOptions {
  /** Location to remove from */
  at?: TLocation;
  
  /** Function to match nodes for removal */
  match?: (node: TNode, path: TPath) => boolean;
  
  /** Removal mode */
  mode?: 'highest' | 'lowest';
  
  /** Whether to allow void nodes */
  voids?: boolean;
  
  /** Whether to hang selection */
  hanging?: boolean;
}

/**
 * Delete content in the current selection
 * @param editor - Editor instance
 * @param options - Deletion options
 */
function deleteSelection(
  editor: TEditor,
  options?: DeleteOptions
): void;

interface DeleteOptions {
  /** Deletion direction */
  direction?: 'forward' | 'backward';
  
  /** Delete unit */
  unit?: 'character' | 'word' | 'line' | 'block';
  
  /** Distance to delete */
  distance?: number;
}

/**
 * Set properties on nodes matching criteria
 * @param editor - Editor instance
 * @param properties - Properties to set
 * @param options - Selection criteria
 */
function setNodes<T extends Partial<TNode>>(
  editor: TEditor,
  properties: T,
  options?: SetNodesOptions
): void;

interface SetNodesOptions {
  /** Location to apply changes */
  at?: TLocation;
  
  /** Function to match nodes */
  match?: (node: TNode, path: TPath) => boolean;
  
  /** Transformation mode */
  mode?: 'all' | 'highest' | 'lowest';
  
  /** Whether to allow void nodes */
  voids?: boolean;
  
  /** Whether to hang selection */
  hanging?: boolean;
  
  /** Whether to split nodes */
  split?: boolean;
}

/**
 * Unset properties on nodes
 * @param editor - Editor instance
 * @param properties - Properties to unset
 * @param options - Selection criteria
 */
function unsetNodes(
  editor: TEditor,
  properties: string[],
  options?: SetNodesOptions
): void;

/**
 * Split nodes at the specified location
 * @param editor - Editor instance
 * @param options - Split options
 */
function splitNodes(
  editor: TEditor,
  options?: SplitNodesOptions
): void;

interface SplitNodesOptions {
  /** Location to split at */
  at?: TLocation;
  
  /** Function to match nodes for splitting */
  match?: (node: TNode, path: TPath) => boolean;
  
  /** Split mode */
  mode?: 'highest' | 'lowest';
  
  /** Whether to split always */
  always?: boolean;
  
  /** Split height */
  height?: number;
  
  /** Whether to allow void nodes */
  voids?: boolean;
}

/**
 * Merge nodes at the specified location
 * @param editor - Editor instance
 * @param options - Merge options
 */
function mergeNodes(
  editor: TEditor,
  options?: MergeNodesOptions
): void;

interface MergeNodesOptions {
  /** Location to merge at */
  at?: TLocation;
  
  /** Function to match nodes for merging */
  match?: (node: TNode, path: TPath) => boolean;
  
  /** Whether to allow void nodes */
  voids?: boolean;
}

/**
 * Get path to a specific node
 * @param editor - Editor instance
 * @param node - Node to find path for
 * @returns Path to the node
 */
function getPath(
  editor: TEditor,
  node: TNode
): TPath;

/**
 * Find path matching criteria
 * @param editor - Editor instance
 * @param options - Search criteria
 * @returns Matching path
 */
function findPath(
  editor: TEditor,
  options: FindNodeOptions
): TPath | undefined;

/**
 * Get next path from current path
 * @param editor - Editor instance
 * @param path - Current path
 * @returns Next path
 */
function getNextPath(
  editor: TEditor,
  path: TPath
): TPath | undefined;

/**
 * Get previous path from current path
 * @param editor - Editor instance
 * @param path - Current path
 * @returns Previous path
 */
function getPreviousPath(
  editor: TEditor,
  path: TPath
): TPath | undefined;

/**
 * Get range at specified location
 * @param editor - Editor instance
 * @param at - Location to get range from
 * @returns Range at location
 */
function getRange(
  editor: TEditor,
  at: TLocation
): TRange;

/**
 * Get range from start of block to current selection
 * @param editor - Editor instance
 * @returns Range from block start
 */
function getRangeFromBlockStart(
  editor: TEditor
): TRange | undefined;

/**
 * Check if selection is collapsed (empty)
 * @param selection - Selection to check
 * @returns True if selection is collapsed
 */
function isCollapsed(selection: TRange | null): boolean;

/**
 * Check if selection is expanded (has content)
 * @param selection - Selection to check
 * @returns True if selection is expanded
 */
function isExpanded(selection: TRange | null): boolean;

/**
 * Get text content from range
 * @param editor - Editor instance
 * @param at - Range or location to get text from
 * @returns Text content
 */
function getText(
  editor: TEditor,
  at?: TLocation
): string;

/**
 * Path represents a sequence of indices to navigate the node tree
 */
type TPath = number[];

/**
 * Point represents a specific location in a text node
 */
interface TPoint {
  path: TPath;
  offset: number;
}

/**
 * Range represents a selection between two points
 */
interface TRange {
  anchor: TPoint;
  focus: TPoint;
}

/**
 * Location can be a Path, Point, or Range
 */
type TLocation = TPath | TPoint | TRange;

/**
 * Node entry is a tuple of node and its path
 */
type TNodeEntry<T extends TNode = TNode> = [T, TPath];

/**
 * Operation represents a low-level change to the editor
 */
interface TOperation {
  type: string;
  [key: string]: any;
}