@tiptap/react 2.6.6 → 2.7.0

package/dist/packages/core/src/types.d.ts

@@ -1,6 +1,6 @@
-import { Mark as ProseMirrorMark, Node as ProseMirrorNode, NodeType, ParseOptions } from '@tiptap/pm/model';
+import { Mark as ProseMirrorMark, Node as ProseMirrorNode, NodeType, ParseOptions, Slice } from '@tiptap/pm/model';
 import { EditorState, Transaction } from '@tiptap/pm/state';
-import { Decoration, EditorProps, EditorView, NodeView } from '@tiptap/pm/view';
+import { Decoration, EditorProps, EditorView, NodeView, NodeViewConstructor } from '@tiptap/pm/view';
 import { Editor } from './Editor.js';
 import { Extension } from './Extension.js';
 import { Commands, ExtensionConfig, MarkConfig, NodeConfig } from './index.js';
@@ -79,7 +79,24 @@ export interface EditorOptions {
     };
     enableInputRules: EnableRules;
     enablePasteRules: EnableRules;
-    enableCoreExtensions: boolean;
+    /**
+     * Determines whether core extensions are enabled.
+     *
+     * If set to `false`, all core extensions will be disabled.
+     * To disable specific core extensions, provide an object where the keys are the extension names and the values are `false`.
+     * Extensions not listed in the object will remain enabled.
+     *
+     * @example
+     * // Disable all core extensions
+     * enabledCoreExtensions: false
+     *
+     * @example
+     * // Disable only the keymap core extension
+     * enabledCoreExtensions: { keymap: false }
+     *
+     * @default true
+     */
+    enableCoreExtensions?: boolean | Partial<Record<'editable' | 'clipboardTextSerializer' | 'commands' | 'focusEvents' | 'keymap' | 'tabindex', false>>;
     /**
      * If `true`, the editor will check the content for errors on initialization.
      * Emitting the `contentError` event if the content is invalid.
@@ -100,6 +117,8 @@ export interface EditorOptions {
     onFocus: (props: EditorEvents['focus']) => void;
     onBlur: (props: EditorEvents['blur']) => void;
     onDestroy: (props: EditorEvents['destroy']) => void;
+    onPaste: (e: ClipboardEvent, slice: Slice) => void;
+    onDrop: (e: DragEvent, slice: Slice, moved: boolean) => void;
 }
 export type HTMLContent = string;
 export type JSONContent = {
@@ -170,19 +189,18 @@ export type ValuesOf<T> = T[keyof T];
 export type KeysWithTypeOf<T, Type> = {
     [P in keyof T]: T[P] extends Type ? P : never;
 }[keyof T];
+export type Simplify<T> = {
+    [KeyType in keyof T]: T[KeyType];
+} & {};
 export type DecorationWithType = Decoration & {
     type: NodeType;
 };
-export type NodeViewProps = {
-    editor: Editor;
-    node: ProseMirrorNode;
-    decorations: DecorationWithType[];
+export type NodeViewProps = Simplify<Omit<NodeViewRendererProps, 'decorations'> & {
+    decorations: readonly DecorationWithType[];
     selected: boolean;
-    extension: Node;
-    getPos: () => number;
     updateAttributes: (attributes: Record<string, any>) => void;
     deleteNode: () => void;
-};
+}>;
 export interface NodeViewRendererOptions {
     stopEvent: ((props: {
         event: Event;
@@ -196,14 +214,16 @@ export interface NodeViewRendererOptions {
     contentDOMElementTag: string;
 }
 export type NodeViewRendererProps = {
+    node: Parameters<NodeViewConstructor>[0];
+    view: Parameters<NodeViewConstructor>[1];
+    getPos: () => number;
+    decorations: Parameters<NodeViewConstructor>[3];
+    innerDecorations: Parameters<NodeViewConstructor>[4];
     editor: Editor;
-    node: ProseMirrorNode;
-    getPos: (() => number) | boolean;
-    HTMLAttributes: Record<string, any>;
-    decorations: Decoration[];
     extension: Node;
+    HTMLAttributes: Record<string, any>;
 };
-export type NodeViewRenderer = (props: NodeViewRendererProps) => NodeView | {};
+export type NodeViewRenderer = (props: NodeViewRendererProps) => NodeView;
 export type AnyCommands = Record<string, (...args: any[]) => Command>;
 export type UnionCommands<T = Command> = UnionToIntersection<ValuesOf<Pick<Commands<T>, KeysWithTypeOf<Commands<T>, {}>>>>;
 export type RawCommands = {

package/dist/packages/react/src/ReactNodeViewRenderer.d.ts

@@ -1,16 +1,95 @@
-import { NodeViewRenderer, NodeViewRendererOptions } from '@tiptap/core';
-import { Node as ProseMirrorNode } from '@tiptap/pm/model';
-import { Decoration } from '@tiptap/pm/view';
+import { Editor, NodeView, NodeViewProps, NodeViewRenderer, NodeViewRendererOptions } from '@tiptap/core';
+import { Node, Node as ProseMirrorNode } from '@tiptap/pm/model';
+import { Decoration, DecorationSource } from '@tiptap/pm/view';
+import { ComponentType } from 'react';
+import { ReactRenderer } from './ReactRenderer.js';
 export interface ReactNodeViewRendererOptions extends NodeViewRendererOptions {
+    /**
+     * This function is called when the node view is updated.
+     * It allows you to compare the old node with the new node and decide if the component should update.
+     */
     update: ((props: {
         oldNode: ProseMirrorNode;
-        oldDecorations: Decoration[];
+        oldDecorations: readonly Decoration[];
+        oldInnerDecorations: DecorationSource;
         newNode: ProseMirrorNode;
-        newDecorations: Decoration[];
+        newDecorations: readonly Decoration[];
+        innerDecorations: DecorationSource;
         updateProps: () => void;
     }) => boolean) | null;
+    /**
+     * The tag name of the element wrapping the React component.
+     */
     as?: string;
+    /**
+     * The class name of the element wrapping the React component.
+     */
     className?: string;
-    attrs?: Record<string, string>;
+    /**
+     * Attributes that should be applied to the element wrapping the React component.
+     * If this is a function, it will be called each time the node view is updated.
+     * If this is an object, it will be applied once when the node view is mounted.
+     */
+    attrs?: Record<string, string> | ((props: {
+        node: ProseMirrorNode;
+        HTMLAttributes: Record<string, any>;
+    }) => Record<string, string>);
 }
-export declare function ReactNodeViewRenderer(component: any, options?: Partial<ReactNodeViewRendererOptions>): NodeViewRenderer;
+export declare class ReactNodeView<Component extends ComponentType<NodeViewProps> = ComponentType<NodeViewProps>, NodeEditor extends Editor = Editor, Options extends ReactNodeViewRendererOptions = ReactNodeViewRendererOptions> extends NodeView<Component, NodeEditor, Options> {
+    /**
+     * The renderer instance.
+     */
+    renderer: ReactRenderer<unknown, NodeViewProps>;
+    /**
+     * The element that holds the rich-text content of the node.
+     */
+    contentDOMElement: HTMLElement | null;
+    /**
+     * Setup the React component.
+     * Called on initialization.
+     */
+    mount(): void;
+    /**
+     * Return the DOM element.
+     * This is the element that will be used to display the node view.
+     */
+    get dom(): HTMLElement;
+    /**
+     * Return the content DOM element.
+     * This is the element that will be used to display the rich-text content of the node.
+     */
+    get contentDOM(): HTMLElement | null;
+    /**
+     * On editor selection update, check if the node is selected.
+     * If it is, call `selectNode`, otherwise call `deselectNode`.
+     */
+    handleSelectionUpdate(): void;
+    /**
+     * On update, update the React component.
+     * To prevent unnecessary updates, the `update` option can be used.
+     */
+    update(node: Node, decorations: readonly Decoration[], innerDecorations: DecorationSource): boolean;
+    /**
+     * Select the node.
+     * Add the `selected` prop and the `ProseMirror-selectednode` class.
+     */
+    selectNode(): void;
+    /**
+     * Deselect the node.
+     * Remove the `selected` prop and the `ProseMirror-selectednode` class.
+     */
+    deselectNode(): void;
+    /**
+     * Destroy the React component instance.
+     */
+    destroy(): void;
+    /**
+     * Update the attributes of the top-level element that holds the React component.
+     * Applying the attributes defined in the `attrs` option.
+     */
+    updateElementAttributes(): void;
+}
+/**
+ * Create a React node view renderer.
+ */
+export declare function ReactNodeViewRenderer(component: ComponentType<NodeViewProps>, options?: Partial<ReactNodeViewRendererOptions>): NodeViewRenderer;

package/dist/packages/react/src/ReactRenderer.d.ts

@@ -25,13 +25,6 @@ export interface ReactRendererOptions {
      * @example 'foo bar'
      */
     className?: string;
-    /**
-     * The attributes of the element.
-     * @type {Record<string, string>}
-     * @default {}
-     * @example { 'data-foo': 'bar' }
-     */
-    attrs?: Record<string, string>;
 }
 type ComponentType<R, P> = React.ComponentClass<P> | React.FunctionComponent<P> | React.ForwardRefExoticComponent<React.PropsWithoutRef<P> & React.RefAttributes<R>>;
 /**
@@ -45,17 +38,33 @@ type ComponentType<R, P> = React.ComponentClass<P> | React.FunctionComponent<P>
  *   as: 'span',
  * })
 */
-export declare class ReactRenderer<R = unknown, P = unknown> {
+export declare class ReactRenderer<R = unknown, P extends Record<string, any> = {}> {
     id: string;
     editor: Editor;
     component: any;
     element: Element;
-    props: Record<string, any>;
+    props: P;
     reactElement: React.ReactNode;
     ref: R | null;
-    constructor(component: ComponentType<R, P>, { editor, props, as, className, attrs, }: ReactRendererOptions);
+    /**
+     * Immediately creates element and renders the provided React component.
+     */
+    constructor(component: ComponentType<R, P>, { editor, props, as, className, }: ReactRendererOptions);
+    /**
+     * Render the React component.
+     */
     render(): void;
+    /**
+     * Re-renders the React component with new props.
+     */
     updateProps(props?: Record<string, any>): void;
+    /**
+     * Destroy the React component.
+     */
     destroy(): void;
+    /**
+     * Update the attributes of the element that holds the React component.
+     */
+    updateAttributes(attributes: Record<string, string>): void;
 }
 export {};

package/dist/packages/react/src/useEditorState.d.ts

@@ -14,9 +14,31 @@ export type UseEditorStateOptions<TSelectorResult, TEditor extends Editor | null
     selector: (context: EditorStateSnapshot<TEditor>) => TSelectorResult;
     /**
      * A custom equality function to determine if the editor should re-render.
-     * @default `(a, b) => a === b`
+     * @default `deepEqual` from `fast-deep-equal`
      */
     equalityFn?: (a: TSelectorResult, b: TSelectorResult | null) => boolean;
 };
+/**
+ * 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 declare 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 declare function useEditorState<TSelectorResult>(options: UseEditorStateOptions<TSelectorResult, Editor | null>): TSelectorResult | null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tiptap/react",
   "description": "React components for tiptap",
-  "version": "2.6.6",
+  "version": "2.7.0",
   "homepage": "https://tiptap.dev",
   "keywords": [
     "tiptap",
@@ -29,22 +29,23 @@
     "dist"
   ],
   "dependencies": {
-    "@tiptap/extension-bubble-menu": "^2.6.6",
-    "@tiptap/extension-floating-menu": "^2.6.6",
+    "@tiptap/extension-bubble-menu": "^2.7.0",
+    "@tiptap/extension-floating-menu": "^2.7.0",
     "@types/use-sync-external-store": "^0.0.6",
+    "fast-deep-equal": "^3",
     "use-sync-external-store": "^1.2.2"
   },
   "devDependencies": {
-    "@tiptap/core": "^2.6.6",
-    "@tiptap/pm": "^2.6.6",
+    "@tiptap/core": "^2.7.0",
+    "@tiptap/pm": "^2.7.0",
     "@types/react": "^18.2.14",
     "@types/react-dom": "^18.2.6",
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
   },
   "peerDependencies": {
-    "@tiptap/core": "^2.6.6",
-    "@tiptap/pm": "^2.6.6",
+    "@tiptap/core": "^2.7.0-pre.0",
+    "@tiptap/pm": "^2.7.0-pre.0",
     "react": "^17.0.0 || ^18.0.0",
     "react-dom": "^17.0.0 || ^18.0.0"
   },

package/src/ReactNodeViewRenderer.tsx

@@ -1,55 +1,90 @@
 import {
   DecorationWithType,
   Editor,
+  getRenderedAttributes,
   NodeView,
   NodeViewProps,
   NodeViewRenderer,
   NodeViewRendererOptions,
-  NodeViewRendererProps,
 } from '@tiptap/core'
-import { Node as ProseMirrorNode } from '@tiptap/pm/model'
-import { Decoration, NodeView as ProseMirrorNodeView } from '@tiptap/pm/view'
-import React from 'react'
+import { Node, Node as ProseMirrorNode } from '@tiptap/pm/model'
+import { Decoration, DecorationSource, NodeView as ProseMirrorNodeView } from '@tiptap/pm/view'
+import React, { ComponentType } from 'react'
 
 import { EditorWithContentComponent } from './Editor.js'
 import { ReactRenderer } from './ReactRenderer.js'
 import { ReactNodeViewContext, ReactNodeViewContextProps } from './useReactNodeView.js'
 
 export interface ReactNodeViewRendererOptions extends NodeViewRendererOptions {
+  /**
+   * This function is called when the node view is updated.
+   * It allows you to compare the old node with the new node and decide if the component should update.
+   */
   update:
     | ((props: {
-        oldNode: ProseMirrorNode
-        oldDecorations: Decoration[]
-        newNode: ProseMirrorNode
-        newDecorations: Decoration[]
-        updateProps: () => void
+        oldNode: ProseMirrorNode;
+        oldDecorations: readonly Decoration[];
+        oldInnerDecorations: DecorationSource;
+        newNode: ProseMirrorNode;
+        newDecorations: readonly Decoration[];
+        innerDecorations: DecorationSource;
+        updateProps: () => void;
       }) => boolean)
-    | null
-  as?: string
-  className?: string
-  attrs?: Record<string, string>
+    | null;
+  /**
+   * The tag name of the element wrapping the React component.
+   */
+  as?: string;
+  /**
+   * The class name of the element wrapping the React component.
+   */
+  className?: string;
+  /**
+   * Attributes that should be applied to the element wrapping the React component.
+   * If this is a function, it will be called each time the node view is updated.
+   * If this is an object, it will be applied once when the node view is mounted.
+   */
+  attrs?:
+    | Record<string, string>
+    | ((props: {
+        node: ProseMirrorNode;
+        HTMLAttributes: Record<string, any>;
+      }) => Record<string, string>);
 }
 
-class ReactNodeView extends NodeView<
-  React.FunctionComponent,
-  Editor,
-  ReactNodeViewRendererOptions
-> {
-  renderer!: ReactRenderer
-
+export class ReactNodeView<
+  Component extends ComponentType<NodeViewProps> = ComponentType<NodeViewProps>,
+  NodeEditor extends Editor = Editor,
+  Options extends ReactNodeViewRendererOptions = ReactNodeViewRendererOptions,
+> extends NodeView<Component, NodeEditor, Options> {
+  /**
+   * The renderer instance.
+   */
+  renderer!: ReactRenderer<unknown, NodeViewProps>
+
+  /**
+   * The element that holds the rich-text content of the node.
+   */
   contentDOMElement!: HTMLElement | null
 
+  /**
+   * Setup the React component.
+   * Called on initialization.
+   */
   mount() {
-    const props: NodeViewProps = {
+    const props = {
       editor: this.editor,
       node: this.node,
-      decorations: this.decorations,
+      decorations: this.decorations as DecorationWithType[],
+      innerDecorations: this.innerDecorations,
+      view: this.view,
       selected: false,
       extension: this.extension,
+      HTMLAttributes: this.HTMLAttributes,
       getPos: () => this.getPos(),
       updateAttributes: (attributes = {}) => this.updateAttributes(attributes),
       deleteNode: () => this.deleteNode(),
-    }
+    } satisfies NodeViewProps
 
     if (!(this.component as any).displayName) {
       const capitalizeFirstChar = (string: string): string => {
@@ -69,13 +104,15 @@ class ReactNodeView extends NodeView<
     const Component = this.component
     // For performance reasons, we memoize the provider component
     // And all of the things it requires are declared outside of the component, so it doesn't need to re-render
-    const ReactNodeViewProvider: React.FunctionComponent = React.memo(componentProps => {
-      return (
-        <ReactNodeViewContext.Provider value={context}>
-          {React.createElement(Component, componentProps)}
-        </ReactNodeViewContext.Provider>
-      )
-    })
+    const ReactNodeViewProvider: React.FunctionComponent<NodeViewProps> = React.memo(
+      componentProps => {
+        return (
+          <ReactNodeViewContext.Provider value={context}>
+            {React.createElement(Component, componentProps)}
+          </ReactNodeViewContext.Provider>
+        )
+      },
+    )
 
     ReactNodeViewProvider.displayName = 'ReactNodeView'
 
@@ -88,6 +125,7 @@ class ReactNodeView extends NodeView<
     }
 
     if (this.contentDOMElement) {
+      this.contentDOMElement.dataset.nodeViewContentReact = ''
       // For some reason the whiteSpace prop is not inherited properly in Chrome and Safari
       // With this fix it seems to work fine
       // See: https://github.com/ueberdosis/tiptap/issues/1197
@@ -110,10 +148,15 @@ class ReactNodeView extends NodeView<
       props,
       as,
       className: `node-${this.node.type.name} ${className}`.trim(),
-      attrs: this.options.attrs,
     })
+
+    this.updateElementAttributes()
   }
 
+  /**
+   * Return the DOM element.
+   * This is the element that will be used to display the node view.
+   */
   get dom() {
     if (
       this.renderer.element.firstElementChild
@@ -125,6 +168,10 @@ class ReactNodeView extends NodeView<
     return this.renderer.element as HTMLElement
   }
 
+  /**
+   * Return the content DOM element.
+   * This is the element that will be used to display the rich-text content of the node.
+   */
   get contentDOM() {
     if (this.node.isLeaf) {
       return null
@@ -133,10 +180,19 @@ class ReactNodeView extends NodeView<
     return this.contentDOMElement
   }
 
+  /**
+   * On editor selection update, check if the node is selected.
+   * If it is, call `selectNode`, otherwise call `deselectNode`.
+   */
   handleSelectionUpdate() {
     const { from, to } = this.editor.state.selection
+    const pos = this.getPos()
+
+    if (typeof pos !== 'number') {
+      return
+    }
 
-    if (from <= this.getPos() && to >= this.getPos() + this.node.nodeSize) {
+    if (from <= pos && to >= pos + this.node.nodeSize) {
       if (this.renderer.props.selected) {
         return
       }
@@ -151,9 +207,20 @@ class ReactNodeView extends NodeView<
     }
   }
 
-  update(node: ProseMirrorNode, decorations: DecorationWithType[]) {
-    const updateProps = (props?: Record<string, any>) => {
+  /**
+   * On update, update the React component.
+   * To prevent unnecessary updates, the `update` option can be used.
+   */
+  update(
+    node: Node,
+    decorations: readonly Decoration[],
+    innerDecorations: DecorationSource,
+  ): boolean {
+    const rerenderComponent = (props?: Record<string, any>) => {
       this.renderer.updateProps(props)
+      if (typeof this.options.attrs === 'function') {
+        this.updateElementAttributes()
+      }
     }
 
     if (node.type !== this.node.type) {
@@ -163,31 +230,44 @@ class ReactNodeView extends NodeView<
     if (typeof this.options.update === 'function') {
       const oldNode = this.node
       const oldDecorations = this.decorations
+      const oldInnerDecorations = this.innerDecorations
 
       this.node = node
       this.decorations = decorations
+      this.innerDecorations = innerDecorations
 
       return this.options.update({
         oldNode,
         oldDecorations,
         newNode: node,
         newDecorations: decorations,
-        updateProps: () => updateProps({ node, decorations }),
+        oldInnerDecorations,
+        innerDecorations,
+        updateProps: () => rerenderComponent({ node, decorations, innerDecorations }),
       })
     }
 
-    if (node === this.node && this.decorations === decorations) {
+    if (
+      node === this.node
+      && this.decorations === decorations
+      && this.innerDecorations === innerDecorations
+    ) {
       return true
     }
 
     this.node = node
     this.decorations = decorations
+    this.innerDecorations = innerDecorations
 
-    updateProps({ node, decorations })
+    rerenderComponent({ node, decorations, innerDecorations })
 
     return true
   }
 
+  /**
+   * Select the node.
+   * Add the `selected` prop and the `ProseMirror-selectednode` class.
+   */
   selectNode() {
     this.renderer.updateProps({
       selected: true,
@@ -195,6 +275,10 @@ class ReactNodeView extends NodeView<
     this.renderer.element.classList.add('ProseMirror-selectednode')
   }
 
+  /**
+   * Deselect the node.
+   * Remove the `selected` prop and the `ProseMirror-selectednode` class.
+   */
   deselectNode() {
     this.renderer.updateProps({
       selected: false,
@@ -202,25 +286,52 @@ class ReactNodeView extends NodeView<
     this.renderer.element.classList.remove('ProseMirror-selectednode')
   }
 
+  /**
+   * Destroy the React component instance.
+   */
   destroy() {
     this.renderer.destroy()
     this.editor.off('selectionUpdate', this.handleSelectionUpdate)
     this.contentDOMElement = null
   }
+
+  /**
+   * Update the attributes of the top-level element that holds the React component.
+   * Applying the attributes defined in the `attrs` option.
+   */
+  updateElementAttributes() {
+    if (this.options.attrs) {
+      let attrsObj: Record<string, string> = {}
+
+      if (typeof this.options.attrs === 'function') {
+        const extensionAttributes = this.editor.extensionManager.attributes
+        const HTMLAttributes = getRenderedAttributes(this.node, extensionAttributes)
+
+        attrsObj = this.options.attrs({ node: this.node, HTMLAttributes })
+      } else {
+        attrsObj = this.options.attrs
+      }
+
+      this.renderer.updateAttributes(attrsObj)
+    }
+  }
 }
 
+/**
+ * Create a React node view renderer.
+ */
 export function ReactNodeViewRenderer(
-  component: any,
+  component: ComponentType<NodeViewProps>,
   options?: Partial<ReactNodeViewRendererOptions>,
 ): NodeViewRenderer {
-  return (props: NodeViewRendererProps) => {
+  return props => {
     // try to get the parent component
     // this is important for vue devtools to show the component hierarchy correctly
     // maybe it’s `undefined` because <editor-content> isn’t rendered yet
     if (!(props.editor as EditorWithContentComponent).contentComponent) {
-      return {}
+      return {} as unknown as ProseMirrorNodeView
     }
 
-    return new ReactNodeView(component, props, options) as unknown as ProseMirrorNodeView
+    return new ReactNodeView(component, props, options)
   }
 }