@domternal/react 0.7.5 → 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 {
@@ -448,8 +457,8 @@ interface ReactNodeViewProps {
     node: PMNode;
     /** Whether this node is selected via NodeSelection. */
     selected: boolean;
-    /** Get the document position of this node. */
-    getPos: () => number;
+    /** Get the document position of this node. Returns `undefined` once the node is no longer in the document. */
+    getPos: () => number | undefined;
     /** Update the node's attributes. */
     updateAttributes: (attrs: Record<string, unknown>) => void;
     /** Delete this node from the document. */
@@ -460,7 +469,7 @@ interface ReactNodeViewProps {
         options: Record<string, unknown>;
     };
     /** ProseMirror decorations applied to this node. */
-    decorations: unknown[];
+    decorations: readonly unknown[];
 }
 interface ReactNodeViewRendererOptions {
     /** Wrapper element tag. @default 'div' for block, 'span' for inline */
@@ -493,12 +502,12 @@ interface ReactNodeViewRendererOptions {
  * }
  * ```
  */
-declare function ReactNodeViewRenderer(component: React.ComponentType<ReactNodeViewProps>, options?: ReactNodeViewRendererOptions): (node: PMNode, view: unknown, getPos: () => number, decorations: unknown[]) => ReactNodeView;
+declare function ReactNodeViewRenderer(component: React.ComponentType<ReactNodeViewProps>, options?: ReactNodeViewRendererOptions): (node: PMNode, view: unknown, getPos: () => number | undefined, decorations: readonly unknown[]) => ReactNodeView;
 interface ReactNodeViewInit {
     editor: Editor;
     node: PMNode;
-    getPos: () => number;
-    decorations: unknown[];
+    getPos: () => number | undefined;
+    decorations: readonly unknown[];
     extension: {
         name: string;
         options: Record<string, unknown>;
@@ -517,11 +526,14 @@ declare class ReactNodeView {
     private selected;
     constructor(component: React.ComponentType<ReactNodeViewProps>, init: ReactNodeViewInit, options: ReactNodeViewRendererOptions);
     private render;
-    update(node: PMNode, decorations: unknown[]): boolean;
+    update(node: PMNode, decorations: readonly unknown[]): boolean;
     selectNode(): void;
     deselectNode(): void;
     destroy(): void;
-    ignoreMutation(mutation: MutationRecord): boolean;
+    ignoreMutation(mutation: MutationRecord | {
+        type: 'selection';
+        target: Node;
+    }): boolean;
     stopEvent(): boolean;
 }
 

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;
@@ -2621,12 +2647,14 @@ var ReactNodeView = class {
       decorations: this.decorations,
       updateAttributes: (attrs) => {
         const pos = this.getPos();
+        if (pos === void 0) return;
         const { tr } = this.editor.view.state;
         tr.setNodeMarkup(pos, void 0, { ...this.node.attrs, ...attrs });
         this.editor.view.dispatch(tr);
       },
       deleteNode: () => {
         const pos = this.getPos();
+        if (pos === void 0) return;
         const { tr } = this.editor.view.state;
         tr.delete(pos, pos + this.node.nodeSize);
         this.editor.view.dispatch(tr);