# portabletext/editor architecture

> Architecture diagram of the GitHub repository portabletext/editor, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/portabletext/editor
- Repository: https://github.com/portabletext/editor

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External UI
    UI["User UI<br/>(React)"]:::external

    %% Editor Core
    subgraph "Editor Core"
        PT["PortableTextEditor<br/>(React Component)"]:::core
        EProv["EditorProvider<br/>(editor-provider.tsx)"]:::core
        EContext["editor-context.tsx"]:::core
        EActor["editor-actor-context.ts"]:::core
        EM["editor-machine.ts<br/>(State Machine)"]:::core
        RE["index.ts<br/>(Entry Point)"]:::core
    end

    %% Behavior Layer
    subgraph "Behavior Layer"
        BA["Behavior Actions<br/>(behavior-actions/*.ts)"]:::behavior
        HB["High-level Behaviors<br/>(behaviors/*.ts)"]:::behavior
        BEExp["Behaviors Exports<br/>(_exports/index.ts)"]:::behavior
    end

    %% Plugin Pipeline
    subgraph "Plugin Pipeline"
        CP["createWith* Plugins<br/>(editor/plugins)"]:::plugin
        WPl["with-plugins.ts"]:::plugin
        PCore["Core Plugins<br/>(plugins/*.tsx)"]:::plugin
        PExp["Plugins Exports<br/>(_exports/index.ts)"]:::plugin
    end

    %% Conversion Layer
    subgraph "Conversion Layer"
        CBT["Portable-Text Converter<br/>(converter.portable-text.ts)"]:::converter
        CHTML["HTML Converter<br/>(converter.text-html.ts)"]:::converter
        CPlain["Plain-Text Converter<br/>(converter.text-plain.ts)"]:::converter
        CCore["Converters Core<br/>(converters.core.ts & converter.types.ts)"]:::converter
    end

    %% Selectors & Utilities
    subgraph "Selectors & Utilities"
        SelF["Selectors<br/>(selectors/*.ts)"]:::utils
        SExp["Selectors Exports<br/>(_exports/index.ts)"]:::utils
        IntU["Internal Utils<br/>(internal-utils/*)"]:::utils
        Util["Misc Utilities<br/>(utils/*.ts)"]:::utils
        UExp["Utilities Exports<br/>(_exports/index.ts)"]:::utils
    end

    %% Hooks & Helpers
    subgraph "Hooks & Helpers"
        H1["usePortableTextEditor<br/>(hooks)"]:::utils
        H2["usePortableTextEditorSelection<br/>(hooks)"]:::utils
        H3["Key Generator & get-value"]:::utils
    end

    %% Types & Schema
    subgraph "Types & Schema"
        TTypes["Types<br/>(types/*.ts)"]:::utils
        Schema["editor-schema.ts"]:::utils
        Legacy["legacy-schema.ts"]:::utils
    end

    %% Relationships
    UI --> PT
    PT --> EM
    EM --> HB
    HB --> BA
    BA --> EM
    PT --> CP
    CP --> WPl
    WPl --> CP
    CP --> PCore
    PCore --> CP
    PT --> CBT
    PT --> CHTML
    PT --> CPlain
    CBT --> CCore
    CHTML --> CCore
    CPlain --> CCore
    UI --> SelF
    SelF --> UI
    IntU --> EM
    IntU --> BA
    H1 --> PT
    H2 --> PT
    H3 --> PT
    TTypes --> PT
    Schema --> PT
    Legacy --> PT

    %% Click Events
    click PT "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/PortableTextEditor.tsx"
    click EProv "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/editor-provider.tsx"
    click EContext "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/editor-context.tsx"
    click EActor "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/editor-actor-context.ts"
    click EM "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/editor-machine.ts"
    click RE "https://github.com/portabletext/editor/blob/main/packages/editor/src/index.ts"
    click BA "https://github.com/portabletext/editor/blob/main/packages/editor/src/behavior-actions/*.ts"
    click HB "https://github.com/portabletext/editor/blob/main/packages/editor/src/behaviors/*.ts"
    click BEExp "https://github.com/portabletext/editor/blob/main/packages/editor/src/behaviors/_exports/index.ts"
    click CP "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/plugins/createWith*.ts"
    click WPl "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/plugins/with-plugins.ts"
    click PCore "https://github.com/portabletext/editor/blob/main/packages/editor/src/plugins/*.tsx"
    click PExp "https://github.com/portabletext/editor/blob/main/packages/editor/src/plugins/_exports/index.ts"
    click CBT "https://github.com/portabletext/editor/blob/main/packages/editor/src/converters/converter.portable-text.ts"
    click CHTML "https://github.com/portabletext/editor/blob/main/packages/editor/src/converters/converter.text-html.ts"
    click CPlain "https://github.com/portabletext/editor/blob/main/packages/editor/src/converters/converter.text-plain.ts"
    click CCore "https://github.com/portabletext/editor/blob/main/packages/editor/src/converters/converters.core.ts"
    click SelF "https://github.com/portabletext/editor/blob/main/packages/editor/src/selectors/*.ts"
    click SExp "https://github.com/portabletext/editor/blob/main/packages/editor/src/selectors/_exports/index.ts"
    click IntU "https://github.com/portabletext/editor/tree/main/packages/editor/src/internal-utils/*"
    click Util "https://github.com/portabletext/editor/blob/main/packages/editor/src/utils/*.ts"
    click UExp "https://github.com/portabletext/editor/blob/main/packages/editor/src/utils/_exports/index.ts"
    click H1 "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/hooks/usePortableTextEditor.ts"
    click H2 "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/hooks/usePortableTextEditorSelection.tsx"
    click H3 "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/key-generator.ts"
    click H3 "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/get-value.ts"
    click TTypes "https://github.com/portabletext/editor/blob/main/packages/editor/src/types/*.ts"
    click Schema "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/editor-schema.ts"
    click Legacy "https://github.com/portabletext/editor/blob/main/packages/editor/src/editor/legacy-schema.ts"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085;
    classDef behavior fill:#d4edda,stroke:#155724,color:#155724;
    classDef plugin fill:#fff3cd,stroke:#856404,color:#856404;
    classDef converter fill:#e2ccf0,stroke:#5e3783,color:#5e3783;
    classDef utils fill:#f2f2f2,stroke:#666666,color:#333333;
    classDef external fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
```
