Selection API

Example: Selection Normalization Flow

// 1. User selects text → DOM Range
const domRange = selection.getRangeAt(0);

// 2. Convert DOM Range to model path
const modelPath = domRangeToModelPath(domRange);
// Result: [{ block: 0, offset: 5 }, { block: 0, offset: 10 }]

// 3. Normalize: ensure path is valid in current model
const normalizedPath = normalizePath(modelPath, editorModel);

// 4. Store in model
editorModel.selection = normalizedPath;

// 5. When model changes, convert back to DOM
const newDomRange = modelPathToDomRange(normalizedPath, editorModel);
selection.removeAllRanges();
selection.addRange(newDomRange);

ProseMirror has a dedicated NodeSelection class that explicitly represents node selections:

    // Detect node selection from DOM Range
const range = selection.getRangeAt(0);
if (range.startContainer.nodeType === Node.ELEMENT_NODE) {
  // Find the ProseMirror node and position
  const pos = editorView.posAtDOM(range.startContainer, 0);
  const $pos = editorView.state.doc.resolve(pos);
  const node = $pos.nodeAfter || $pos.nodeBefore;
  
  if (node && node.isAtom) { // Images, embeds, etc.
    // Create NodeSelection
    const nodeSelection = NodeSelection.create(
      editorView.state.doc,
      $pos.pos
    );
    
    // Apply selection
    const tr = editorView.state.tr.setSelection(nodeSelection);
    editorView.dispatch(tr);
  }
}
  

• Separate class: NodeSelection is distinct from TextSelection.
• Atom nodes: Only "atom" nodes (images, embeds, etc.) can be node-selected, not regular block nodes.
• Position-based: Uses document positions, not paths like Slate.

Key Takeaway

Even though the browser's Range API represents node selections uniformly (using element nodes and child indices), each editor framework converts this to its own internal representation. The conversion strategy depends on:

• The editor's data model structure (path-based, position-based, block-based)
• Whether the editor distinguishes between text and node selections
• Which nodes are selectable (all nodes vs. only atom/void nodes)
• How the editor handles selection restoration after DOM mutations