@domternal/react 0.8.0 → 0.9.0

package/dist/index.d.ts

@@ -1,8 +1,7 @@
 import * as react from 'react';
 import { DependencyList, ReactNode, HTMLAttributes, Ref, RefObject, KeyboardEvent, ElementType, RefCallback } from 'react';
-import { AnyExtension, Content, FocusPosition, Editor, JSONContent, IconSet, ToolbarLayoutEntry, BubbleMenuOptions, FloatingMenuItemsOverride } from '@domternal/core';
+import { AnyExtension, Content, FocusPosition, Editor, JSONContent, IconSet, ToolbarLayoutEntry, BubbleMenuOptions, FloatingMenuOptions, FloatingMenuItemsOverride, FloatingMenuKeymap } from '@domternal/core';
 export { AnyExtension, Content, Editor, FocusPosition, GenerateHTMLOptions, GenerateJSONOptions, GenerateTextOptions, JSONContent, generateHTML, generateJSON, generateText } from '@domternal/core';
-import { FloatingMenuOptions, FloatingMenuKeymap } from '@domternal/extension-block-menu';
 
 declare const DEFAULT_EXTENSIONS: AnyExtension[];
 interface UseEditorOptions {
@@ -17,10 +16,12 @@ interface UseEditorOptions {
     /** Output format for content comparison. @default 'html' */
     outputFormat?: 'html' | 'json';
     /**
-     * Set to false to delay editor creation to useEffect (SSR-safe).
-     * When false, the editor will be null during server-side rendering
-     * and created only after the component mounts in the browser.
-     * @default true
+     * Create the editor synchronously during the first render so `editor`
+     * is available immediately, with no null flash on first paint. The view
+     * starts in a detached element and is adopted into the mount point by
+     * the mount effect. Client-only: the default defers creation to a mount
+     * effect, which never runs during server-side rendering.
+     * @default false
      */
     immediatelyRender?: boolean;
     /** Called when the editor instance is created. */
@@ -60,12 +61,12 @@ interface UseEditorOptions {
  * return <div className="dm-editor"><div ref={editorRef} /></div>;
  * ```
  *
- * @example SSR-safe usage (Next.js)
+ * @example Editor available on the very first render (client-only apps)
  * ```tsx
  * const { editor, editorRef } = useEditor({
  *   extensions,
  *   content,
- *   immediatelyRender: false,
+ *   immediatelyRender: true,
  * });
  * ```
  *
@@ -238,14 +239,22 @@ interface DomternalProps extends UseEditorOptions {
  * </Domternal>
  * ```
  *
- * @example SSR-safe with loading state
+ * @example Loading state (shown during SSR and until the editor exists)
  * ```tsx
- * <Domternal extensions={extensions} immediatelyRender={false}>
+ * <Domternal extensions={extensions}>
  *   <Domternal.Loading>Loading editor...</Domternal.Loading>
  *   <Domternal.Toolbar />
  *   <Domternal.Content />
  * </Domternal>
  * ```
+ *
+ * @example Editor on the very first render (client-only apps)
+ * ```tsx
+ * <Domternal extensions={extensions} immediatelyRender>
+ *   <Domternal.Toolbar />
+ *   <Domternal.Content />
+ * </Domternal>
+ * ```
  */
 declare function Domternal({ children, deps, ...options }: DomternalProps): ReactNode;
 declare namespace Domternal {

package/dist/index.js

@@ -1,8 +1,7 @@
 import { createContext, forwardRef, useImperativeHandle, useRef, useEffect, useState, useMemo, useCallback, useSyncExternalStore, useContext, Fragment, useLayoutEffect, createElement } from 'react';
-import { Editor, Document, Paragraph, Text, BaseKeymap, History, positionFloatingOnce, PluginKey, FloatingMenuController, defaultIcons, positionFloating, ToolbarController, defaultBubbleContexts, createBubbleMenuPlugin } from '@domternal/core';
+import { Editor, Document, Paragraph, Text, BaseKeymap, History, positionFloatingOnce, PluginKey, createFloatingMenuPlugin, FloatingMenuController, defaultIcons, positionFloating, ToolbarController, defaultBubbleContexts, createBubbleMenuPlugin } from '@domternal/core';
 export { Editor, generateHTML, generateJSON, generateText } from '@domternal/core';
 import { jsxs, jsx, Fragment as Fragment$1 } from 'react/jsx-runtime';
-import { createFloatingMenuPlugin } from '@domternal/extension-block-menu';
 import { createPortal } from 'react-dom';
 import { createRoot } from 'react-dom/client';
 
@@ -14,9 +13,9 @@ function useEditor(options = {}, deps) {
     content = "",
     editable = true,
     autofocus = false,
-    outputFormat = "html"
+    outputFormat = "html",
+    immediatelyRender = false
   } = options;
-  const [editor, setEditor] = useState(null);
   const editorRef = useRef(null);
   const instanceRef = useRef(null);
   const pendingContentRef = useRef(null);
@@ -45,7 +44,7 @@ function useEditor(options = {}, deps) {
       callbacksRef.current.onBlur?.({ editor: ed, event });
     });
   }
-  function createEditorInstance(element, initialContent, focus) {
+  function buildEditorInstance(element, initialContent, focus) {
     const ed = new Editor({
       element,
       extensions: [...DEFAULT_EXTENSIONS, ...extensions],
@@ -57,6 +56,10 @@ function useEditor(options = {}, deps) {
     instanceRef.current = ed;
     extensionsRef.current = extensions;
     depsRef.current = deps;
+    return ed;
+  }
+  function createEditorInstance(element, initialContent, focus) {
+    const ed = buildEditorInstance(element, initialContent, focus);
     setEditor(ed);
     callbacksRef.current.onCreate?.(ed);
     return ed;
@@ -71,7 +74,30 @@ function useEditor(options = {}, deps) {
     instanceRef.current = null;
     setEditor(null);
   }
+  const [editor, setEditor] = useState(() => {
+    if (!immediatelyRender) return null;
+    if (typeof window === "undefined") {
+      throw new Error(
+        "[@domternal/react] immediatelyRender: true creates the editor during render, which cannot work during server-side rendering. Remove the option for SSR; the editor is then created after mount."
+      );
+    }
+    if (instanceRef.current && !instanceRef.current.isDestroyed) {
+      return instanceRef.current;
+    }
+    return buildEditorInstance(document.createElement("div"), content, autofocus);
+  });
   useEffect(() => {
+    const existing = instanceRef.current;
+    if (existing && !existing.isDestroyed) {
+      const mount = editorRef.current;
+      if (mount && existing.view.dom.parentElement !== mount) {
+        mount.appendChild(existing.view.dom);
+      }
+      callbacksRef.current.onCreate?.(existing);
+      return () => {
+        destroyCurrentEditor();
+      };
+    }
     const element = editorRef.current ?? document.createElement("div");
     const initialContent = pendingContentRef.current ?? content;
     pendingContentRef.current = null;