@blockslides/react 0.1.0

package/src/menus/FloatingMenu.tsx

@@ -0,0 +1,69 @@
+import type { FloatingMenuPluginProps } from '@blockslides/extension-floating-menu'
+import { FloatingMenuPlugin } from '@blockslides/extension-floating-menu'
+import { useCurrentEditor } from '@blockslides/react'
+import React, { useEffect, useRef } from 'react'
+import { createPortal } from 'react-dom'
+
+type Optional<T, K extends keyof T> = Pick<Partial<T>, K> & Omit<T, K>
+
+export type FloatingMenuProps = Omit<Optional<FloatingMenuPluginProps, 'pluginKey'>, 'element' | 'editor'> & {
+  editor: FloatingMenuPluginProps['editor'] | null
+  options?: FloatingMenuPluginProps['options']
+} & React.HTMLAttributes<HTMLDivElement>
+
+export const FloatingMenu = React.forwardRef<HTMLDivElement, FloatingMenuProps>(
+  ({ pluginKey = 'floatingMenu', editor, appendTo, shouldShow = null, options, children, ...restProps }, ref) => {
+    const menuEl = useRef(document.createElement('div'))
+
+    if (typeof ref === 'function') {
+      ref(menuEl.current)
+    } else if (ref) {
+      ref.current = menuEl.current
+    }
+
+    const { editor: currentEditor } = useCurrentEditor()
+
+    useEffect(() => {
+      const floatingMenuElement = menuEl.current
+
+      floatingMenuElement.style.visibility = 'hidden'
+      floatingMenuElement.style.position = 'absolute'
+
+      if (editor?.isDestroyed || (currentEditor as any)?.isDestroyed) {
+        return
+      }
+
+      const attachToEditor = editor || currentEditor
+
+      if (!attachToEditor) {
+        console.warn(
+          'FloatingMenu component is not rendered inside of an editor component or does not have editor prop.',
+        )
+        return
+      }
+
+      const plugin = FloatingMenuPlugin({
+        editor: attachToEditor,
+        element: floatingMenuElement,
+        pluginKey,
+        appendTo,
+        shouldShow,
+        options,
+      })
+
+      attachToEditor.registerPlugin(plugin)
+
+      return () => {
+        attachToEditor.unregisterPlugin(pluginKey)
+        window.requestAnimationFrame(() => {
+          if (floatingMenuElement.parentNode) {
+            floatingMenuElement.parentNode.removeChild(floatingMenuElement)
+          }
+        })
+      }
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [editor, currentEditor, appendTo, pluginKey, shouldShow, options])
+
+    return createPortal(<div {...restProps}>{children}</div>, menuEl.current)
+  },
+)

package/src/menus/index.ts

@@ -0,0 +1,2 @@
+export * from './BubbleMenu.js'
+export * from './FloatingMenu.js'

package/src/types.ts

@@ -0,0 +1,6 @@
+import type { NodeViewProps as CoreNodeViewProps } from "@blockslides/core";
+import type React from "react";
+
+export type ReactNodeViewProps<T = HTMLElement> = CoreNodeViewProps & {
+  ref: React.RefObject<T | null>;
+};

package/src/useEditor.ts

@@ -0,0 +1,405 @@
+import { type EditorOptions, Editor } from "@blockslides/core";
+import type { DependencyList, MutableRefObject } from "react";
+import { useDebugValue, useEffect, useRef, useState } from "react";
+import { useSyncExternalStore } from "use-sync-external-store/shim/index.js";
+
+import { useEditorState } from "./useEditorState.js";
+
+// @ts-ignore
+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 false
+   */
+  shouldRerenderOnTransaction?: boolean;
+};
+
+/**
+ * This class handles the creation, destruction, and re-creation of the editor instance.
+ */
+class EditorInstanceManager {
+  /**
+   * The current editor instance.
+   */
+  private editor: Editor | null = null;
+
+  /**
+   * The most recent options to apply to the editor.
+   */
+  private options: MutableRefObject<UseEditorOptions>;
+
+  /**
+   * The subscriptions to notify when the editor instance
+   * has been created or destroyed.
+   */
+  private subscriptions = new Set<() => void>();
+
+  /**
+   * A timeout to destroy the editor if it was not mounted within a time frame.
+   */
+  private scheduledDestructionTimeout:
+    | ReturnType<typeof setTimeout>
+    | undefined;
+
+  /**
+   * Whether the editor has been mounted.
+   */
+  private isComponentMounted = false;
+
+  /**
+   * The most recent dependencies array.
+   */
+  private previousDeps: DependencyList | null = null;
+
+  /**
+   * The unique instance ID. This is used to identify the editor instance. And will be re-generated for each new instance.
+   */
+  public instanceId = "";
+
+  constructor(options: MutableRefObject<UseEditorOptions>) {
+    this.options = options;
+    this.subscriptions = new Set<() => void>();
+    this.setEditor(this.getInitialEditor());
+    this.scheduleDestroy();
+
+    this.getEditor = this.getEditor.bind(this);
+    this.getServerSnapshot = this.getServerSnapshot.bind(this);
+    this.subscribe = this.subscribe.bind(this);
+    this.refreshEditorInstance = this.refreshEditorInstance.bind(this);
+    this.scheduleDestroy = this.scheduleDestroy.bind(this);
+    this.onRender = this.onRender.bind(this);
+    this.createEditor = this.createEditor.bind(this);
+  }
+
+  private setEditor(editor: Editor | null) {
+    this.editor = editor;
+    this.instanceId = Math.random().toString(36).slice(2, 9);
+
+    // Notify all subscribers that the editor instance has been created
+    this.subscriptions.forEach((cb) => cb());
+  }
+
+  private getInitialEditor() {
+    if (this.options.current.immediatelyRender === undefined) {
+      if (isSSR || isNext) {
+        if (isDev) {
+          /**
+           * Throw an error in development, to make sure the developer is aware that the editor cannot be SSR'd
+           * and that they need to set `immediatelyRender` to `false` to avoid hydration mismatches.
+           */
+          throw new Error(
+            "Editor 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 this.createEditor();
+    }
+
+    if (this.options.current.immediatelyRender && isSSR && isDev) {
+      // Warn in development, to make sure the developer is aware that the editor cannot be SSR'd, set `immediatelyRender` to `false` to avoid hydration mismatches.
+      throw new Error(
+        "Editor 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 (this.options.current.immediatelyRender) {
+      return this.createEditor();
+    }
+
+    return null;
+  }
+
+  /**
+   * Create a new editor instance. And attach event listeners.
+   */
+  private createEditor(): Editor {
+    const optionsToApply: Partial<EditorOptions> = {
+      ...this.options.current,
+      // Always call the most recent version of the callback function by default
+      onBeforeCreate: (...args) =>
+        this.options.current.onBeforeCreate?.(...args),
+      onBlur: (...args) => this.options.current.onBlur?.(...args),
+      onCreate: (...args) => this.options.current.onCreate?.(...args),
+      onDestroy: (...args) => this.options.current.onDestroy?.(...args),
+      onFocus: (...args) => this.options.current.onFocus?.(...args),
+      onSelectionUpdate: (...args) =>
+        this.options.current.onSelectionUpdate?.(...args),
+      onTransaction: (...args) => this.options.current.onTransaction?.(...args),
+      onUpdate: (...args) => this.options.current.onUpdate?.(...args),
+      onContentError: (...args) =>
+        this.options.current.onContentError?.(...args),
+      onDrop: (...args) => this.options.current.onDrop?.(...args),
+      onPaste: (...args) => this.options.current.onPaste?.(...args),
+      onDelete: (...args) => this.options.current.onDelete?.(...args),
+    };
+    const editor = new Editor(optionsToApply);
+
+    // no need to keep track of the event listeners, they will be removed when the editor is destroyed
+
+    return editor;
+  }
+
+  /**
+   * Get the current editor instance.
+   */
+  getEditor(): Editor | null {
+    return this.editor;
+  }
+
+  /**
+   * Always disable the editor on the server-side.
+   */
+  getServerSnapshot(): null {
+    return null;
+  }
+
+  /**
+   * Subscribe to the editor instance's changes.
+   */
+  subscribe(onStoreChange: () => void) {
+    this.subscriptions.add(onStoreChange);
+
+    return () => {
+      this.subscriptions.delete(onStoreChange);
+    };
+  }
+
+  static compareOptions(a: UseEditorOptions, b: UseEditorOptions) {
+    return (Object.keys(a) as (keyof UseEditorOptions)[]).every((key) => {
+      if (
+        [
+          "onCreate",
+          "onBeforeCreate",
+          "onDestroy",
+          "onUpdate",
+          "onTransaction",
+          "onFocus",
+          "onBlur",
+          "onSelectionUpdate",
+          "onContentError",
+          "onDrop",
+          "onPaste",
+        ].includes(key)
+      ) {
+        // we don't want to compare callbacks, they are always different and only registered once
+        return true;
+      }
+
+      // We often encourage putting extensions inlined in the options object, so we will do a slightly deeper comparison here
+      if (key === "extensions" && a.extensions && b.extensions) {
+        if (a.extensions.length !== b.extensions.length) {
+          return false;
+        }
+        return a.extensions.every((extension, index) => {
+          if (extension !== b.extensions?.[index]) {
+            return false;
+          }
+          return true;
+        });
+      }
+      if (a[key] !== b[key]) {
+        // if any of the options have changed, we should update the editor options
+        return false;
+      }
+      return true;
+    });
+  }
+
+  /**
+   * On each render, we will create, update, or destroy the editor instance.
+   * @param deps The dependencies to watch for changes
+   * @returns A cleanup function
+   */
+  onRender(deps: DependencyList) {
+    // The returned callback will run on each render
+    return () => {
+      this.isComponentMounted = true;
+      // Cleanup any scheduled destructions, since we are currently rendering
+      clearTimeout(this.scheduledDestructionTimeout);
+
+      if (this.editor && !this.editor.isDestroyed && deps.length === 0) {
+        // if the editor does exist & deps are empty, we don't need to re-initialize the editor generally
+        if (
+          !EditorInstanceManager.compareOptions(
+            this.options.current,
+            this.editor.options
+          )
+        ) {
+          // But, the options are different, so we need to update the editor options
+          // Still, this is faster than re-creating the editor
+          this.editor.setOptions({
+            ...this.options.current,
+            editable: this.editor.isEditable,
+          });
+        }
+      } else {
+        // When the editor:
+        // - does not yet exist
+        // - is destroyed
+        // - the deps array changes
+        // We need to destroy the editor instance and re-initialize it
+        this.refreshEditorInstance(deps);
+      }
+
+      return () => {
+        this.isComponentMounted = false;
+        this.scheduleDestroy();
+      };
+    };
+  }
+
+  /**
+   * Recreate the editor instance if the dependencies have changed.
+   */
+  private refreshEditorInstance(deps: DependencyList) {
+    if (this.editor && !this.editor.isDestroyed) {
+      // Editor instance already exists
+      if (this.previousDeps === null) {
+        // If lastDeps has not yet been initialized, reuse the current editor instance
+        this.previousDeps = deps;
+        return;
+      }
+      const depsAreEqual =
+        this.previousDeps.length === deps.length &&
+        this.previousDeps.every((dep, index) => dep === deps[index]);
+
+      if (depsAreEqual) {
+        // deps exist and are equal, no need to recreate
+        return;
+      }
+    }
+
+    if (this.editor && !this.editor.isDestroyed) {
+      // Destroy the editor instance if it exists
+      this.editor.destroy();
+    }
+
+    this.setEditor(this.createEditor());
+
+    // Update the lastDeps to the current deps
+    this.previousDeps = deps;
+  }
+
+  /**
+   * Schedule the destruction of the editor instance.
+   * This will only destroy the editor if it was not mounted on the next tick.
+   * This is to avoid destroying the editor instance when it's actually still mounted.
+   */
+  private scheduleDestroy() {
+    const currentInstanceId = this.instanceId;
+    const currentEditor = this.editor;
+
+    // Wait two ticks to see if the component is still mounted
+    this.scheduledDestructionTimeout = setTimeout(() => {
+      if (this.isComponentMounted && this.instanceId === currentInstanceId) {
+        // If still mounted on the following tick, with the same instanceId, do not destroy the editor
+        if (currentEditor) {
+          // just re-apply options as they might have changed
+          currentEditor.setOptions(this.options.current);
+        }
+        return;
+      }
+      if (currentEditor && !currentEditor.isDestroyed) {
+        currentEditor.destroy();
+        if (this.instanceId === currentInstanceId) {
+          this.setEditor(null);
+        }
+      }
+      // This allows the effect to run again between ticks
+      // which may save us from having to re-create the editor
+    }, 1);
+  }
+}
+
+/**
+ * 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: false },
+  deps?: DependencyList
+): Editor | null;
+
+/**
+ * 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,
+  deps?: DependencyList
+): Editor;
+
+export function useEditor(
+  options: UseEditorOptions = {},
+  deps: DependencyList = []
+): Editor | null {
+  const mostRecentOptions = useRef(options);
+
+  mostRecentOptions.current = options;
+
+  const [instanceManager] = useState(
+    () => new EditorInstanceManager(mostRecentOptions)
+  );
+
+  const editor = useSyncExternalStore(
+    instanceManager.subscribe,
+    instanceManager.getEditor,
+    instanceManager.getServerSnapshot
+  );
+
+  useDebugValue(editor);
+
+  // This effect will handle creating/updating the editor instance
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  useEffect(instanceManager.onRender(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 ||
+        options.shouldRerenderOnTransaction === undefined
+      ) {
+        // 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 editor;
+}

package/src/useEditorState.ts

@@ -0,0 +1,188 @@
+import type { Editor } from "@blockslides/core";
+import deepEqual from "fast-deep-equal/es6/react.js";
+import { useDebugValue, useEffect, useLayoutEffect, useState } from "react";
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector.js";
+
+const useIsomorphicLayoutEffect =
+  typeof window !== "undefined" ? useLayoutEffect : useEffect;
+
+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 `deepEqual` from `fast-deep-equal`
+   */
+  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.
+ */
+class EditorStateManager<TEditor extends Editor | null = Editor | null> {
+  private transactionNumber = 0;
+
+  private lastTransactionNumber = 0;
+
+  private lastSnapshot: EditorStateSnapshot<TEditor>;
+
+  private editor: TEditor;
+
+  private subscribers = new Set<() => void>();
+
+  constructor(initialEditor: TEditor) {
+    this.editor = initialEditor;
+    this.lastSnapshot = { editor: initialEditor, transactionNumber: 0 };
+
+    this.getSnapshot = this.getSnapshot.bind(this);
+    this.getServerSnapshot = this.getServerSnapshot.bind(this);
+    this.watch = this.watch.bind(this);
+    this.subscribe = this.subscribe.bind(this);
+  }
+
+  /**
+   * Get the current editor instance.
+   */
+  getSnapshot(): EditorStateSnapshot<TEditor> {
+    if (this.transactionNumber === this.lastTransactionNumber) {
+      return this.lastSnapshot;
+    }
+    this.lastTransactionNumber = this.transactionNumber;
+    this.lastSnapshot = {
+      editor: this.editor,
+      transactionNumber: this.transactionNumber,
+    };
+    return this.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): () => void {
+    this.subscribers.add(callback);
+    return () => {
+      this.subscribers.delete(callback);
+    };
+  }
+
+  /**
+   * Watch the editor instance for changes.
+   */
+  watch(nextEditor: Editor | null): undefined | (() => void) {
+    this.editor = nextEditor as TEditor;
+
+    if (this.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 = () => {
+        this.transactionNumber += 1;
+        this.subscribers.forEach((callback) => callback());
+      };
+
+      const currentEditor = this.editor;
+
+      currentEditor.on("transaction", fn);
+      return () => {
+        currentEditor.off("transaction", fn);
+      };
+    }
+
+    return undefined;
+  }
+}
+
+/**
+ * This hook allows you to watch for changes on the editor instance.
+ * It will allow you to select a part of the editor state and re-render the component when it changes.
+ * @example
+ * ```tsx
+ * const editor = useEditor({...options})
+ * const { currentSelection } = useEditorState({
+ *  editor,
+ *  selector: snapshot => ({ currentSelection: snapshot.editor.state.selection }),
+ * })
+ */
+export function useEditorState<TSelectorResult>(
+  options: UseEditorStateOptions<TSelectorResult, Editor>
+): TSelectorResult;
+/**
+ * This hook allows you to watch for changes on the editor instance.
+ * It will allow you to select a part of the editor state and re-render the component when it changes.
+ * @example
+ * ```tsx
+ * const editor = useEditor({...options})
+ * const { currentSelection } = useEditorState({
+ *  editor,
+ *  selector: snapshot => ({ currentSelection: snapshot.editor.state.selection }),
+ * })
+ */
+export function useEditorState<TSelectorResult>(
+  options: UseEditorStateOptions<TSelectorResult, Editor | null>
+): TSelectorResult | null;
+
+/**
+ * This hook allows you to watch for changes on the editor instance.
+ * It will allow you to select a part of the editor state and re-render the component when it changes.
+ * @example
+ * ```tsx
+ * const editor = useEditor({...options})
+ * const { currentSelection } = useEditorState({
+ *  editor,
+ *  selector: snapshot => ({ currentSelection: snapshot.editor.state.selection }),
+ * })
+ */
+export function useEditorState<TSelectorResult>(
+  options:
+    | UseEditorStateOptions<TSelectorResult, Editor>
+    | UseEditorStateOptions<TSelectorResult, Editor | null>
+): TSelectorResult | null {
+  const [editorStateManager] = useState(
+    () => new EditorStateManager(options.editor)
+  );
+
+  // Using the `useSyncExternalStore` hook to sync the editor instance with the component state
+  const selectedState = useSyncExternalStoreWithSelector(
+    editorStateManager.subscribe,
+    editorStateManager.getSnapshot,
+    editorStateManager.getServerSnapshot,
+    options.selector as UseEditorStateOptions<
+      TSelectorResult,
+      Editor | null
+    >["selector"],
+    options.equalityFn ?? deepEqual
+  );
+
+  useIsomorphicLayoutEffect(() => {
+    return editorStateManager.watch(options.editor);
+  }, [options.editor, editorStateManager]);
+
+  useDebugValue(selectedState);
+
+  return selectedState;
+}

package/src/useReactNodeView.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react'
+import { createContext, createElement, useContext } from 'react'
+
+export interface ReactNodeViewContextProps {
+  onDragStart?: (event: DragEvent) => void
+  nodeViewContentRef?: (element: HTMLElement | null) => void
+  /**
+   * This allows you to add children into the NodeViewContent component.
+   * This is useful when statically rendering the content of a node view.
+   */
+  nodeViewContentChildren?: ReactNode
+}
+
+export const ReactNodeViewContext = createContext<ReactNodeViewContextProps>({
+  onDragStart: () => {
+    // no-op
+  },
+  nodeViewContentChildren: undefined,
+  nodeViewContentRef: () => {
+    // no-op
+  },
+})
+
+export const ReactNodeViewContentProvider = ({ children, content }: { children: ReactNode; content: ReactNode }) => {
+  return createElement(ReactNodeViewContext.Provider, { value: { nodeViewContentChildren: content } }, children)
+}
+
+export const useReactNodeView = () => useContext(ReactNodeViewContext)