Editor

Framework-agnostic, ProseMirror-backed rich text editor runtime for composing emails, documents, blog posts, and articles with support for modern block schemas (tables, task lists, callouts, code blocks), markdown shortcuts, and headless React extensions.

Capabilities

• ProseMirror Core Engine: Full EditorState, EditorView, transactions, and step-based undo/redo history.
• Rich Schema: Paragraphs, Headings (H1–H6), Blockquotes, Code Blocks with syntax languages, Task Lists (task_list, task_item), Tables (table, table_row, table_cell, table_header), Callout boxes (info, warning, tip, danger), Horizontal rules, Embeds (images, videos, math formulas), and text styling.
• Markdown & Paste Shortcuts:
  • On-type markdown input rules (# , ## , * , 1. , > , ---, [ ] ).
  • Smart paste rules for URL auto-linking and markdown conversion.
• Multi-Representation Transforms: Bidirectional conversions between ProseMirror AST, sanitized HTML (via DOMPurify), Markdown, and JSON AST.
• Headless UI & React Adapters: Pre-built floating toolbar (useFloatingToolbar) and slash command menu (useSlashMenu) hooks.

AI Agent Quick Reference

Core Exports

| Export | Type | Description | | --- | --- | --- | | createEditor(config?: EditorConfig): EditorInstance | Function | Instantiates a new framework-agnostic editor engine. | | createDomAdapter(editor: EditorInstance, element: HTMLElement): { destroy: () => void } | Function | Binds the Editor core instance to a DOM element. | | mountRichTextEditor(options: MountRichTextEditorOptions): MountedRichTextEditor | Function | Mounts rich text DOM editor with toolbar. | | exportRepresentation(doc: EditorDocument, format: ContentFormat): EditorExport | Function | Transforms editor document into HTML, Markdown, or JSON. | | importRepresentation(input: EditorInput, doc: EditorDocument): CommandResult | Function | Parses raw HTML or Markdown into editor document. | | RichEditorAdapter | React Component | React wrapper that renders the editor UI adapter. | | useEditorAdapter(config: EditorConfig): EditorInstance | React Hook | Custom hook to manage React-based editor integration. | | useFloatingToolbar(editor?: EditorInstance) | React Hook | Hook for floating bubble formatting toolbar. | | useSlashMenu(editor?: EditorInstance, options?: UseSlashMenuOptions) | React Hook | Hook for slash / block insert menu. | | EditorProvider / useEditor / useEditorState | Context & Hooks | React Context provider and state subscription hooks. |

Core Types

• EditorInstance:
  • execute(command: string, params?: any): CommandResult
  • export(format: ContentFormat): EditorExport
  • import(input: EditorInput): CommandResult
  • getState(): EditorState
  • getSchema(): Schema
  • getView(): EditorView | null
  • getDocument(): EditorDocument
  • dispatch(tr: Transaction): void
  • isMarkActive(name: string): boolean
  • getActiveBlockType(): string
  • on(event: "change" | "selectionchange", cb: () => void): () => void
  • destroy(): void
• ContentFormat: "html" | "markdown" | "rich" | "json"

Basic Usage (Framework-Neutral)

import { createEditor } from "@azlib/editor";

const editor = createEditor({
  initialContent: {
    format: "markdown",
    payload: "# Hello editor\nThis is **bold** text.\n\n- [x] Task completed",
  },
  onChange: (doc) => {
    console.log("Document updated:", doc.content.richText);
  },
});

// Run formatting commands
editor.execute("bold");
editor.execute("insertTable", { rows: 3, cols: 3 });
editor.execute("callout", { type: "tip" });

// Export content
const html = editor.export("html");
const markdown = editor.export("markdown");
const json = editor.export("json");

React Usage

import {
  EditorProvider,
  RichEditorAdapter,
  useEditorAdapter,
  useFloatingToolbar,
  useSlashMenu,
} from "@azlib/editor";

function MyEditorComponent() {
  const editor = useEditorAdapter({
    initialContent: {
      format: "markdown",
      payload: "# Documentation\nType `/` to insert blocks.",
    },
  });

  const { isOpen: isToolbarOpen, position: toolbarPos } = useFloatingToolbar(editor);
  const { isOpen: isSlashOpen, items: slashItems, selectItem } = useSlashMenu(editor);

  return (
    <EditorProvider editor={editor}>
      <div className="relative border rounded-lg p-4">
        <RichEditorAdapter editor={editor} />
      </div>
    </EditorProvider>
  );
}

Behavioral Gotchas

• HTML Sanitization: HTML imports/exports are sanitized automatically with DOMPurify to prevent XSS payloads.
• Instance Cleanup: Always call .destroy() on the framework-agnostic editor instance or the DOM adapter to release listeners and avoid memory leaks.