editor: The Editor

The entire editing side: EditorCore (configuration and node factory), EditorComponent (the React component and its tree operations), the plugin system, the Slate node utilities, and the editor state hooks.

EditorCore

EditorCore is the entry object of the editing side: constructed once at startup and shared from then on. Its three constructor arguments match the usage in tutorial chapter 3:

new EditorCore({
    renderers: EditorRendererDict,           // {group: {first-concept name: renderer}, ...}
    default_renderers: EditorDefaultRendererDict, // one default renderer per node kind
    printer: Printer,                        // concept definitions are queried from here
})

Its methods fall into two groups. One is the node factory (the create_ family): create new nodes by second-class concept name, with idx and placeholder children filled in automatically; use these rather than hand-written object literals when constructing document content programmatically. The other group is queries: concept lists, renderers, and the associated printer.

EditorComponent

The editor's React component (a class component). In practice you usually mount its wrapper DefaultEditorComponent (see the defaults page); the two share one set of props:

interface EditorComponentProps {
    editorcore: EditorCore
    plugin?: EditorPlugin                 // custom plugins, stacked on top of the built-ins
    init_rootchildren?: AbstractNode["children"]        // initial document content
    init_rootproperty?: Omit<AbstractNode, "children">  // initial root properties
    onUpdate?: (v: any) => void           // called on every tree update
    onKeyDown? / onKeyUp?: (e) => void    // keyboard event callbacks
    onFocusChange?: (editor?) => void     // called when the cursor position changes
}

Tree operations

The following methods also live on EditorComponent (mixed in; the source is in treeopmixin). They are concept-level wrappers over Slate's Transforms, and they are what plugins and custom buttons mostly deal with:

Editor renderers

An editor renderer is at bottom just a React component, receiving the editor, the node, and the child content:

type EditorRenderer<NT extends Node = Node> =
    (props: EditorRendererProps<NT>) => React.ReactElement

interface EditorRendererProps<NT> {
    editor: EditorComponent
    node: NT
    children: React.ReactNode   // content supplied by Slate; the renderer must output it
}

This is the raw form of an editor renderer. It is rarely written by hand; the factory functions of the default implementation generate renderers with buttons and parameter editing already handled.

The plugin system

A plugin is a function that wraps the Slate editor:

type EditorPlugin =
    (editor: EditorComponent, slate: SlateReact.ReactEditor) => SlateReact.ReactEditor

A plugin receives the editor and the Slate editor object and returns the modified Slate editor, matching the plugin pattern of the Slate ecosystem. How to write one is covered in tutorial chapter 7. Related exports:

• with_ytext_plugins: the built-in plugin chain, applied automatically when the editor component mounts; you never call it yourself. It contains nine plugins: meta-parameter application (inline and void node handling), four child-constraint plugins, and repair plugins for relation, abstract nodes and parameters.
• set_normalize_status({initializing?, pasting?}) and get_normalize_status(key): read and write the normalization state. The tree passes through intermediate states while a document loads or a paste is processed; custom plugins should skip their checks while initializing is true, or they will interfere with loading.

Slate node utilities

Functions for inspecting Slate nodes in plugins and buttons, all prefixed slate_:

Editor state hooks

For components outside the editor (a toolbar placed elsewhere on the page, say) that need to track editor state: