How portabletext/editor works
Project type and purpose
• Type: A modular, client-side JavaScript/TypeScript library (NPM package) implementing a portable text editor with behavior-driven editing actions.
• Purpose: Expose a reusable <PortableTextEditor> component and API, plus an editor-state machine, plugin pipeline, behaviors for key commands, converters for import/export, and utility functions.
File structure
• Top-level “packages/editor”: the main library
• Subdirectories:
– src/editor → React components, context providers, editor machine
– src/behavior-actions → low-level action implementations (insert, delete, move, etc.)
– src/behaviors → high-level behaviors mapping user events to actions
– src/plugins → plugin factory functions (hotkeys, undo/redo, schema enforcement, etc.)
– src/converters → serialization/deserialization (HTML, plain text, portable-text)
– src/selectors → read-only helper functions for inspecting selection, decorators, etc.
– src/internal-utils → core algorithms: patch/apply, slate conversions, selection math
– src/utils → miscellaneous helper functions
• Tests live alongside in src/__tests__, tests/, and gherkin specs.
Key insights from README
• Editor exposes a PortableTextEditor React component and hooks (usePortableTextEditor)
• Behavior model driven by a finite-state machine (editor-machine.ts)
• Plug-in system layered on top of Slate editors (createWith*)
• Converters let you round-trip between HTML/plain text and the JSON “block” format.
Main components
A. Editor Core
– PortableTextEditor (React component)
– EditorProvider / context
– editor-machine (state machine orchestrating events → behaviors)
B. Behavior Layer
– Behavior Actions (insert, delete, select, etc.)
– Behavior Definitions (.behaviors files)
C. Plugin Pipeline
– createWithHotKeys, createWithUndoRedo, createWithSchemaTypes, etc.
– Plugins register event listeners, intercept commands, extend API
D. Conversion Layer
– converter.text-html / converter.text-plain / converter.portable-text
E. Selectors & Utilities
– selector.* functions (get-value, is-active-annotation…)
– internal-utils (patch/apply, slate-to-blocks, selection math)
F. External Dependencies
– React, Slate, immer (for patches), Portable Text types, EventEmitters
Relationships & data flow
• User UI (React) dispatches UI events → PortableTextEditor → dispatch to editor-machine
• editor-machine sends events to Behavior Layer → Behavior Actions mutate Slate editor state
• Plugin Pipeline wraps the Slate editor instance, intercepting events, adding listeners
• Conversion Layer serializes/deserializes value for import/export
• Selectors read from the editor value/selection to drive UI state (toolbar buttons, formatting)
• internal-utils apply patch streams and compute diffs between value snapshots
Architectural patterns & principles
• State Machine (XState-style): Clear separation between events and state transitions
• Plugin/Decorator Pattern: Layers of “createWith…” to assemble final editor instance
• Functional, immutable updates via patches (applyPatch)
• Modularization by responsibility: behaviors vs. actions vs. selectors