@domternal/core 0.11.1 → 0.12.0

package/README.md

@@ -3,42 +3,93 @@
 [![Version](https://img.shields.io/npm/v/@domternal/core.svg)](https://www.npmjs.com/package/@domternal/core)
 [![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/domternal/domternal/blob/main/LICENSE)
 
-A lightweight, extensible rich text editor toolkit built on <u>[ProseMirror](https://prosemirror.net/)</u>. Framework-agnostic headless core with first-class Angular, React, Vue, and Vanilla wrappers.
-Use it headless with vanilla JS/TS, add the built-in toolbar and theme, or drop in ready-made framework components. Fully tree-shakeable, import only what you use, unused extensions are stripped from your bundle.
+The framework-agnostic editor engine of [Domternal](https://domternal.dev), built on
+[ProseMirror](https://prosemirror.net/). It provides the headless `Editor` class, the
+extension system (`Extension`, `Node`, `Mark`), a chainable command API, and the
+built-in nodes, marks, and behaviors (paragraph, heading, lists, tasks, links,
+inline formatting, history, keymaps) bundled as `StarterKit`. Use it directly with
+vanilla JS/TS, or as the runtime under the Angular, React, Vue, and Vanilla wrappers.
+Every export is tree-shakeable, so unused extensions are stripped from your bundle.
 
 ## Links
 
-<u>[Website](https://domternal.dev)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[Documentation](https://domternal.dev/v1/introduction)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp;
-<u>[StackBlitz (Angular)](https://stackblitz.com/edit/domternal-angular-full-example)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[StackBlitz (React)](https://stackblitz.com/edit/domternal-react-full-example)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[StackBlitz (Vue)](https://stackblitz.com/edit/domternal-vue-full-example)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[StackBlitz (Vanilla TS)](https://stackblitz.com/edit/domternal-vanilla-full-example)</u>
+<u>[Website](https://domternal.dev)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[Documentation](https://domternal.dev/v1/getting-started)</u> &nbsp;&nbsp;&nbsp;•&nbsp;&nbsp;&nbsp; <u>[Live examples](https://domternal.dev/examples)</u>
 
-## Features
+## Install
 
-See <u>[Packages & Bundle Size](https://domternal.dev/v1/packages)</u> for a full breakdown of all packages and what each one includes.
+```bash
+pnpm add @domternal/core
+```
 
-- **Headless core** - use with any framework or vanilla JS/TS
-- **Angular components** - editor, toolbar, bubble menu, floating menu, emoji picker, notion color picker (signals, OnPush, zoneless-ready)
-- **React components** - composable `Domternal` component, toolbar, bubble menu, floating menu, emoji picker, notion color picker, custom node views (React 18+)
-- **Vue components** - composable `Domternal` component, `useEditor`/`useEditorState` composables, toolbar, bubble menu, floating menu, emoji picker, notion color picker, custom node views (Vue 3.3+)
-- **Vanilla wrapper** - framework-free class-based API for Astro, Svelte, Solid, plain HTML, and Web Components - editor, toolbar, bubble menu, floating menu, emoji picker, notion color picker
-- **Notion-style block UX** - drag-to-reorder, block context menu, slash command, smart paste, keyboard reorder, floating Table of Contents
-- **70+ extensions across 16 packages** - nodes, marks, and behavior extensions
-- **125+ chainable commands** - `editor.chain().focus().toggleBold().run()`
-- **Full table support** - cell merging, column resize, row/column controls, cell toolbar, all free and MIT licensed
-- **Tree-shakeable** - import only what you use, your bundler strips the rest
-- **~44 KB gzipped** (own code), <u>[see Packages](https://domternal.dev/v1/packages)</u> for full bundle breakdown with ProseMirror
-- **TypeScript first** - 100% typed, zero `any`
-- **15,000+ tests** - 4,000+ unit and 11,000+ E2E across 230+ Playwright specs and 4 demo apps
-- **Light and dark theme** - 120+ CSS custom properties for full visual control
-- **Inline styles export** - `getHTML({ styled: true })` produces inline CSS ready for email clients, CMS, and Google Docs
-- **SSR helpers** - `generateHTML`, `generateJSON`, `generateText` for server-side rendering
+`linkedom` is an optional peer dependency: install it only if you call the SSR
+helpers (`generateHTML`, `generateJSON`, `generateText`) outside a browser.
 
-## Documentation
+```bash
+pnpm add linkedom
+```
 
-- <u>[Getting Started](https://domternal.dev/v1/getting-started)</u> - install and create your first editor
-- <u>[Introduction](https://domternal.dev/v1/introduction)</u> - core concepts, architecture, and design decisions
-- <u>[Packages & Bundle Size](https://domternal.dev/v1/packages)</u> - what each package includes and bundle size breakdown
-- <u>[Blog](https://domternal.dev/blog)</u>
+## Usage
 
-## License
+```ts
+import { Editor, StarterKit } from '@domternal/core';
 
-<u>[MIT](https://github.com/domternal/domternal/blob/main/LICENSE)</u>
+const editor = new Editor({
+  element: document.getElementById('editor')!,
+  extensions: [StarterKit],
+  content: '<p>Hello <strong>world</strong></p>',
+  onUpdate: ({ editor }) => {
+    console.log(editor.getJSON());
+  },
+});
+
+// Chainable command API
+editor.chain().focus().toggleBold().run();
+
+// Read content
+const html = editor.getHTML();
+const json = editor.getJSON();
+
+// Tear down
+editor.destroy();
+```
+
+The engine ships no styles. Import [`@domternal/theme`](https://www.npmjs.com/package/@domternal/theme) for ready-made light/dark editor styling, or supply your own CSS.
+
+`StarterKit` bundles the common nodes, marks, and behaviors; each entry can be
+configured or disabled individually.
+
+```ts
+StarterKit.configure({
+  codeBlock: false,                  // disable an extension
+  heading: { levels: [1, 2, 3] },    // configure an extension
+  link: { openOnClick: false },
+});
+```
+
+To trim the bundle further, skip `StarterKit` and compose only the extensions you
+need:
+
+```ts
+import { Editor, Document, Paragraph, Text, Bold, History } from '@domternal/core';
+
+const editor = new Editor({
+  element: document.getElementById('editor')!,
+  extensions: [Document, Paragraph, Text, Bold, History],
+});
+```
+
+## SSR
+
+The `generateHTML`, `generateJSON`, and `generateText` helpers render content
+without an editor instance, for example on the server.
+
+```ts
+import { generateHTML, StarterKit } from '@domternal/core';
+
+const html = generateHTML(
+  { type: 'doc', content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Hi' }] }] },
+  [StarterKit],
+);
+```
+
+`generateJSON(html, extensions)` does the reverse (HTML to doc JSON) and `generateText` extracts plain text.

package/dist/index.cjs

@@ -217,6 +217,14 @@ function inputRulesPlugin({ rules }) {
   return plugin;
 }
 
+// src/ExtensionConfigurationError.ts
+var ExtensionConfigurationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ExtensionConfigurationError";
+  }
+};
+
 // src/helpers/callOrReturn.ts
 function callOrReturn(value, context, ...args) {
   if (typeof value === "function") {
@@ -845,6 +853,9 @@ var ExtensionManager = class {
       }
       return result;
     } catch (error) {
+      if (error instanceof ExtensionConfigurationError) {
+        throw error;
+      }
       const errorObj = error instanceof Error ? error : new Error(String(error));
       this.editor.emit?.("error", { error: errorObj, context });
       return void 0;
@@ -3460,7 +3471,7 @@ function normalizeColor(color) {
 }
 
 // src/Editor.ts
-var Editor = class extends EventEmitter {
+var Editor = class _Editor extends EventEmitter {
   /**
    * Editor configuration options
    */
@@ -3493,6 +3504,10 @@ var Editor = class extends EventEmitter {
    * Timer for autofocus (cleared on destroy to prevent memory leaks)
    */
   _autofocusTimer = null;
+  /**
+   * True while EditorView's constructor runs; see buildViewDispatch.
+   */
+  _isViewConstructing = false;
   /**
    * Creates a new Editor instance
    *
@@ -3912,6 +3927,9 @@ var Editor = class extends EventEmitter {
    * Creates the editor instance
    */
   createEditor() {
+    this.on("error", (props) => {
+      this.options.onError?.(props);
+    });
     this.emit("beforeCreate", { editor: this });
     this.options.onBeforeCreate?.({ editor: this });
     this._extensionManager = new ExtensionManager(
@@ -3951,9 +3969,10 @@ var Editor = class extends EventEmitter {
     });
     const element = this.options.element ?? document.createElement("div");
     const nodeViews = this._extensionManager.nodeViews;
+    this._isViewConstructing = true;
     this.view = new view.EditorView(element, {
       state: state$1,
-      dispatchTransaction: this.dispatchTransaction.bind(this),
+      dispatchTransaction: _Editor.buildViewDispatch(this),
       editable: () => this.options.editable ?? true,
       attributes: () => ({
         role: "textbox",
@@ -3980,6 +3999,7 @@ var Editor = class extends EventEmitter {
         }
       }
     });
+    this._isViewConstructing = false;
     this.emit("mount", { editor: this, view: this.view });
     this.options.onMount?.({ editor: this, view: this.view });
     this.commandManager = new CommandManager(this);
@@ -3991,13 +4011,28 @@ var Editor = class extends EventEmitter {
         }
       }, 0);
     }
-    this.on("error", (props) => {
-      this.options.onError?.(props);
-    });
     this.emit("create", { editor: this });
     this.options.onCreate?.({ editor: this });
     this._extensionManager.callOnCreate();
   }
+  /**
+   * Builds the dispatchTransaction prop. Plugin views can dispatch synchronously
+   * inside EditorView's constructor, before `editor.view` is assigned; ProseMirror
+   * binds the prop to the view, so the instance is captured early (plugin code
+   * such as appendTransaction may read `editor.view` during the apply) and the
+   * transaction is applied directly, like the default dispatch, skipping events:
+   * it is initial state, not an update.
+   */
+  static buildViewDispatch(editor) {
+    return function(transaction) {
+      if (editor._isViewConstructing) {
+        editor.view ??= this;
+        this.updateState(this.state.apply(transaction));
+        return;
+      }
+      editor.dispatchTransaction(transaction);
+    };
+  }
   /**
    * Handles ProseMirror transactions
    */
@@ -10539,6 +10574,7 @@ exports.Dropcursor = Dropcursor;
 exports.Editor = Editor;
 exports.EventEmitter = EventEmitter;
 exports.Extension = Extension;
+exports.ExtensionConfigurationError = ExtensionConfigurationError;
 exports.ExtensionManager = ExtensionManager;
 exports.FLOATING_MENU_META = FLOATING_MENU_META;
 exports.FLOATING_MENU_NO_FOCUS = FLOATING_MENU_NO_FOCUS;