@tiptap/react 2.5.0-pre.8 → 3.0.0

package/src/useEditor.ts

@@ -1,12 +1,45 @@
 import { EditorOptions } from '@tiptap/core'
 import {
-  DependencyList,
-  useEffect,
-  useRef,
-  useState,
+  DependencyList, useDebugValue, useEffect, useRef, useState,
 } from 'react'
 
 import { Editor } from './Editor.js'
+import { useEditorState } from './useEditorState.js'
+
+const isDev = process.env.NODE_ENV !== 'production'
+const isSSR = typeof window === 'undefined'
+const isNext = isSSR || Boolean(typeof window !== 'undefined' && (window as any).next)
+
+/**
+ * The options for the `useEditor` hook.
+ */
+export type UseEditorOptions = Partial<EditorOptions> & {
+  /**
+   * Whether to render the editor on the first render.
+   * If client-side rendering, set this to `true`.
+   * If server-side rendering, set this to `false`.
+   * @default true
+   */
+  immediatelyRender?: boolean;
+  /**
+   * Whether to re-render the editor on each transaction.
+   * This is legacy behavior that will be removed in future versions.
+   * @default true
+   */
+  shouldRerenderOnTransaction?: boolean;
+};
+
+/**
+ * This hook allows you to create an editor instance.
+ * @param options The editor options
+ * @param deps The dependencies to watch for changes
+ * @returns The editor instance
+ * @example const editor = useEditor({ extensions: [...] })
+ */
+export function useEditor(
+  options: UseEditorOptions & { immediatelyRender: true },
+  deps?: DependencyList
+): Editor;
 
 /**
  * This hook allows you to create an editor instance.
@@ -15,9 +48,68 @@ import { Editor } from './Editor.js'
  * @returns The editor instance
  * @example const editor = useEditor({ extensions: [...] })
  */
-export const useEditor = (options: Partial<EditorOptions> = {}, deps: DependencyList = []) => {
-  const editorRef = useRef<Editor | null>(null)
-  const [, forceUpdate] = useState({})
+export function useEditor(
+  options?: UseEditorOptions,
+  deps?: DependencyList
+): Editor | null;
+
+export function useEditor(
+  options: UseEditorOptions = {},
+  deps: DependencyList = [],
+): Editor | null {
+  const isMounted = useRef(false)
+  const [editor, setEditor] = useState(() => {
+    if (options.immediatelyRender === undefined) {
+      if (isSSR || isNext) {
+        // TODO in the next major release, we should throw an error here
+        if (isDev) {
+          /**
+           * Throw an error in development, to make sure the developer is aware that tiptap cannot be SSR'd
+           * and that they need to set `immediatelyRender` to `false` to avoid hydration mismatches.
+           */
+          console.warn(
+            'Tiptap Error: SSR has been detected, please set `immediatelyRender` explicitly to `false` to avoid hydration mismatches.',
+          )
+        }
+
+        // Best faith effort in production, run the code in the legacy mode to avoid hydration mismatches and errors in production
+        return null
+      }
+
+      // Default to immediately rendering when client-side rendering
+      return new Editor(options)
+    }
+
+    if (options.immediatelyRender && isSSR && isDev) {
+      // Warn in development, to make sure the developer is aware that tiptap cannot be SSR'd, set `immediatelyRender` to `false` to avoid hydration mismatches.
+      throw new Error(
+        'Tiptap Error: SSR has been detected, and `immediatelyRender` has been set to `true` this is an unsupported configuration that may result in errors, explicitly set `immediatelyRender` to `false` to avoid hydration mismatches.',
+      )
+    }
+
+    if (options.immediatelyRender) {
+      return new Editor(options)
+    }
+
+    return null
+  })
+
+  useDebugValue(editor)
+
+  // This effect will handle creating/updating the editor instance
+  useEffect(() => {
+    let editorInstance: Editor | null = editor
+
+    if (!editorInstance) {
+      editorInstance = new Editor(options)
+      // instantiate the editor if it doesn't exist
+      // for ssr, this is the first time the editor is created
+      setEditor(editorInstance)
+    } else {
+      // if the editor does exist, update the editor options accordingly
+      editorInstance.setOptions(options)
+    }
+  }, deps)
 
   const {
     onBeforeCreate,
@@ -44,96 +136,127 @@ export const useEditor = (options: Partial<EditorOptions> = {}, deps: Dependency
   // This effect will handle updating the editor instance
   // when the event handlers change.
   useEffect(() => {
-    if (!editorRef.current) {
+    if (!editor) {
       return
     }
 
     if (onBeforeCreate) {
-      editorRef.current.off('beforeCreate', onBeforeCreateRef.current)
-      editorRef.current.on('beforeCreate', onBeforeCreate)
+      editor.off('beforeCreate', onBeforeCreateRef.current)
+      editor.on('beforeCreate', onBeforeCreate)
 
       onBeforeCreateRef.current = onBeforeCreate
     }
 
     if (onBlur) {
-      editorRef.current.off('blur', onBlurRef.current)
-      editorRef.current.on('blur', onBlur)
+      editor.off('blur', onBlurRef.current)
+      editor.on('blur', onBlur)
 
       onBlurRef.current = onBlur
     }
 
     if (onCreate) {
-      editorRef.current.off('create', onCreateRef.current)
-      editorRef.current.on('create', onCreate)
+      editor.off('create', onCreateRef.current)
+      editor.on('create', onCreate)
 
       onCreateRef.current = onCreate
     }
 
     if (onDestroy) {
-      editorRef.current.off('destroy', onDestroyRef.current)
-      editorRef.current.on('destroy', onDestroy)
+      editor.off('destroy', onDestroyRef.current)
+      editor.on('destroy', onDestroy)
 
       onDestroyRef.current = onDestroy
     }
 
     if (onFocus) {
-      editorRef.current.off('focus', onFocusRef.current)
-      editorRef.current.on('focus', onFocus)
+      editor.off('focus', onFocusRef.current)
+      editor.on('focus', onFocus)
 
       onFocusRef.current = onFocus
     }
 
     if (onSelectionUpdate) {
-      editorRef.current.off('selectionUpdate', onSelectionUpdateRef.current)
-      editorRef.current.on('selectionUpdate', onSelectionUpdate)
+      editor.off('selectionUpdate', onSelectionUpdateRef.current)
+      editor.on('selectionUpdate', onSelectionUpdate)
 
       onSelectionUpdateRef.current = onSelectionUpdate
     }
 
     if (onTransaction) {
-      editorRef.current.off('transaction', onTransactionRef.current)
-      editorRef.current.on('transaction', onTransaction)
+      editor.off('transaction', onTransactionRef.current)
+      editor.on('transaction', onTransaction)
 
       onTransactionRef.current = onTransaction
     }
 
     if (onUpdate) {
-      editorRef.current.off('update', onUpdateRef.current)
-      editorRef.current.on('update', onUpdate)
+      editor.off('update', onUpdateRef.current)
+      editor.on('update', onUpdate)
 
       onUpdateRef.current = onUpdate
     }
 
     if (onContentError) {
-      editorRef.current.off('contentError', onContentErrorRef.current)
-      editorRef.current.on('contentError', onContentError)
+      editor.off('contentError', onContentErrorRef.current)
+      editor.on('contentError', onContentError)
 
       onContentErrorRef.current = onContentError
     }
-  }, [onBeforeCreate, onBlur, onCreate, onDestroy, onFocus, onSelectionUpdate, onTransaction, onUpdate, editorRef.current])
+  }, [
+    onBeforeCreate,
+    onBlur,
+    onCreate,
+    onDestroy,
+    onFocus,
+    onSelectionUpdate,
+    onTransaction,
+    onUpdate,
+    onContentError,
+    editor,
+  ])
 
+  /**
+   * Destroy the editor instance when the component completely unmounts
+   * As opposed to the cleanup function in the effect above, this will
+   * only be called when the component is removed from the DOM, since it has no deps.
+   * */
   useEffect(() => {
-    let isMounted = true
-
-    const editor = new Editor(options)
-
-    editorRef.current = editor
+    isMounted.current = true
+    return () => {
+      isMounted.current = false
+      if (editor) {
+        // We need to destroy the editor asynchronously to avoid memory leaks
+        // because the editor instance is still being used in the component.
 
-    editorRef.current.on('transaction', () => {
-      requestAnimationFrame(() => {
-        requestAnimationFrame(() => {
-          if (isMounted) {
-            forceUpdate({})
+        setTimeout(() => {
+          // re-use the editor instance if it hasn't been destroyed yet
+          // and the component is still mounted
+          // otherwise, asynchronously destroy the editor instance
+          if (!isMounted.current && !editor.isDestroyed) {
+            editor.destroy()
           }
         })
-      })
-    })
-
-    return () => {
-      isMounted = false
-      editor.destroy()
+      }
     }
-  }, deps)
+  }, [])
+
+  // The default behavior is to re-render on each transaction
+  // This is legacy behavior that will be removed in future versions
+  useEditorState({
+    editor,
+    selector: ({ transactionNumber }) => {
+      if (options.shouldRerenderOnTransaction === false) {
+        // This will prevent the editor from re-rendering on each transaction
+        return null
+      }
+
+      // This will avoid re-rendering on the first transaction when `immediatelyRender` is set to `true`
+      if (options.immediatelyRender && transactionNumber === 0) {
+        return 0
+      }
+      return transactionNumber + 1
+    },
+  })
 
-  return editorRef.current
+  return editor
 }

package/src/useEditorState.ts

@@ -0,0 +1,125 @@
+import { useDebugValue, useEffect, useState } from 'react'
+import { useSyncExternalStoreWithSelector } from 'use-sync-external-store/shim/with-selector'
+
+import type { Editor } from './Editor.js'
+
+export type EditorStateSnapshot<TEditor extends Editor | null = Editor | null> = {
+  editor: TEditor;
+  transactionNumber: number;
+};
+export type UseEditorStateOptions<
+  TSelectorResult,
+  TEditor extends Editor | null = Editor | null,
+> = {
+  /**
+   * The editor instance.
+   */
+  editor: TEditor;
+  /**
+   * A selector function to determine the value to compare for re-rendering.
+   */
+  selector: (context: EditorStateSnapshot<TEditor>) => TSelectorResult;
+  /**
+   * A custom equality function to determine if the editor should re-render.
+   * @default `(a, b) => a === b`
+   */
+  equalityFn?: (a: TSelectorResult, b: TSelectorResult | null) => boolean;
+};
+
+/**
+ * To synchronize the editor instance with the component state,
+ * we need to create a separate instance that is not affected by the component re-renders.
+ */
+function makeEditorStateInstance<TEditor extends Editor | null = Editor | null>(initialEditor: TEditor) {
+  let transactionNumber = 0
+  let lastTransactionNumber = 0
+  let lastSnapshot: EditorStateSnapshot<TEditor> = { editor: initialEditor, transactionNumber: 0 }
+  let editor = initialEditor
+  const subscribers = new Set<() => void>()
+
+  const editorInstance = {
+    /**
+     * Get the current editor instance.
+     */
+    getSnapshot(): EditorStateSnapshot<TEditor> {
+      if (transactionNumber === lastTransactionNumber) {
+        return lastSnapshot
+      }
+      lastTransactionNumber = transactionNumber
+      lastSnapshot = { editor, transactionNumber }
+      return lastSnapshot
+    },
+    /**
+     * Always disable the editor on the server-side.
+     */
+    getServerSnapshot(): EditorStateSnapshot<null> {
+      return { editor: null, transactionNumber: 0 }
+    },
+    /**
+     * Subscribe to the editor instance's changes.
+     */
+    subscribe(callback: () => void) {
+      subscribers.add(callback)
+      return () => {
+        subscribers.delete(callback)
+      }
+    },
+    /**
+     * Watch the editor instance for changes.
+     */
+    watch(nextEditor: Editor | null) {
+      editor = nextEditor as TEditor
+
+      if (editor) {
+        /**
+         * This will force a re-render when the editor state changes.
+         * This is to support things like `editor.can().toggleBold()` in components that `useEditor`.
+         * This could be more efficient, but it's a good trade-off for now.
+         */
+        const fn = () => {
+          transactionNumber += 1
+          subscribers.forEach(callback => callback())
+        }
+
+        const currentEditor = editor
+
+        currentEditor.on('transaction', fn)
+        return () => {
+          currentEditor.off('transaction', fn)
+        }
+      }
+    },
+  }
+
+  return editorInstance
+}
+
+export function useEditorState<TSelectorResult>(
+  options: UseEditorStateOptions<TSelectorResult, Editor>
+): TSelectorResult;
+export function useEditorState<TSelectorResult>(
+  options: UseEditorStateOptions<TSelectorResult, Editor | null>
+): TSelectorResult | null;
+
+export function useEditorState<TSelectorResult>(
+  options: UseEditorStateOptions<TSelectorResult, Editor> | UseEditorStateOptions<TSelectorResult, Editor | null>,
+): TSelectorResult | null {
+  const [editorInstance] = useState(() => makeEditorStateInstance(options.editor))
+
+  // Using the `useSyncExternalStore` hook to sync the editor instance with the component state
+  const selectedState = useSyncExternalStoreWithSelector(
+    editorInstance.subscribe,
+    editorInstance.getSnapshot,
+    editorInstance.getServerSnapshot,
+    options.selector as UseEditorStateOptions<TSelectorResult, Editor | null>['selector'],
+    options.equalityFn,
+  )
+
+  useEffect(() => {
+    return editorInstance.watch(options.editor)
+  }, [options.editor])
+
+  useDebugValue(selectedState)
+
+  return selectedState
+}