SunEditor Documentation

SunEditor uses a class-based plugin system where different base classes determine the UI behavior and required lifecycle methods of your plugin. Choose the base class that matches your intended user interaction:

Not every selectable component needs to be a full plugin. For lightweight components that only require basic actions like deletion (e.g., pageBreak), you can use a Component Launcher.

A launcher is a stand-in for a plugin that is registered directly as a component-checker in the pluginManager.

Key Rules for Launchers:

• Hook-name contract: A launcher must use the same hook names as a full plugin: componentDestroy, componentSelect, and componentDeselect.
• When to use: Use a launcher when the component has no UI beyond basic actions (like delete). Promote to a full plugin only if the component needs a Controller or complex actions, as a Controller can only be owned by a full plugin instance.

// Example of a component-checker returning a launcher
this.#componentCheckers.push((element) => {
    if (!element || !dom.utils.hasClass(element, 'se-page-break')) return null;
    /** @type {SunEditor.ComponentLauncher} */
    const launcher = {
        componentDestroy: (target) => {
            /* remove + refocus + history.push */
        },
    };
    return { target: element, launcher };
});

SunEditor uses a layered architecture centered around a Dependency Injection (DI) container called the CoreKernel. This design allows the editor to remain zero-dependency (no external frameworks like React or jQuery) while managing complex state and logic through a centralized system.

High-Level Layers

1. Factory Entry Point (suneditor.js): Validates options and target elements to create the editor instance.
2. Facade (editor.js): The main Editor class that orchestrates initialization, plugin lifecycles, and multi-root management. It exposes a minimal public API and the $ (Deps) object for deep access.
3. CoreKernel (L1): The central orchestrator containing:
   • Store: Manages internal state and editing mode.
   • $ (Deps bag): A single object containing all dependencies shared with consumers.
   • L2 Config Providers: Handles context, options, instance checks, and event management.
   • L3 Business Logic: Divided into dom (selection, formatting), shell (components, history, plugins), and panel (toolbar, menus).
   • L4 Event Orchestrator: Manages the flow from handlers to reducers, rules, executors, and effects.

graph TD
    User[User Code] --> Factory[suneditor.js]
    Factory --> Facade[editor.js]
    Facade --> Kernel[CoreKernel - L1]

    subgraph Core Kernel
        Kernel --> Store[Store - State]
        Kernel --> Config[L2 Config Providers]
        Kernel --> Logic[L3 Business Logic]
        Kernel --> Event[L4 Event Orchestrator]
    end

    Logic --> DOM[dom - Selection, Format ...]
    Logic --> Shell[shell - Component, History ...]
    Logic --> Panel[panel - Toolbar, Menu, Viewer]

    Event --> Handlers
    Event --> Reducers
    Event --> Rules
    Event --> Executor[Actions - Executor]
    Event --> Effects

All plugins interact with the editor through this.$, which is the Dependency Bag (Deps bag).

Important: this.$ is not the Kernel itself; it is the dependency context provided by the Kernel. It contains all the services, configuration, and DOM logic required for plugin operation.

Core Service Categories:

• Config: Access global options, frameOptions, context, and localization/icons via this.$.lang and this.$.icons.
• DOM Logic: Manipulate the editor using this.$.selection, this.$.html, this.$.format, this.$.inline, and this.$.nodeTransform.
• Shell Logic: Manage lifecycle and state via this.$.pluginManager, this.$.commandDispatcher, this.$.history (undo/redo), and this.$.ui.
• Panel Logic: Control the this.$.toolbar, this.$.menu, and this.$.viewer.
• Services: Use this.$.eventManager for events, this.$.store for state, and this.$.facade to access the public editor API.

SunEditor is a modular WYSIWYG editor built with vanilla JavaScript (ES2022+) and no runtime dependencies. It uses a central orchestration model to manage state, configuration, and features.

Core Components

• Kernel (CoreKernel): The central runtime container responsible for initialization, dependency injection (DI), and managing the lifecycle.
• Deps ($): A shared dependency bag (accessible via kernel.$ or this.$) that contains all services. Note: The Deps object is not the Kernel itself.
• Store: The central runtime state management (e.g., tracking mode, focus, and selection cache).
• Config: Manages context providers, option providers, and event management.
• Logic: Handles DOM operations (selection, formatting), shell operations (history, focus), and Panel UI (toolbar, menus).
• Event: A Redux-like orchestration system using actions, handlers, reducers, and effects.
• Plugins & Modules: Features like image or video are implemented as plugins, while structural components like Modal or ColorPicker are implemented as modules.