@handlewithcare/react-prosemirror 2.7.0 → 2.8.0-tiptap.10

package/README.md

@@ -9,6 +9,17 @@
 
 [![Join the chat at https://gitter.im/nytimes/react-prosemirror](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/nytimes/react-prosemirror?utm_source=badge&utm_medium=badge&utm_content=badge)
 
+## What happened to `@nytimes/react-prosemirror`?
+
+On Jan. 17, 2025, the maintainers of the `@nytimes/react-prosemirror` library
+decided fork the v2 release into its own project. It had been developed entirely
+by one developer, @smoores-dev, who had not worked for NYT in years, and was
+struggling to move the project at the speed he desired.
+
+This project is that fork, and all future development on the React-based
+ProseMirror renderer will happen in this repository, published as
+`@handlewithcare/react-prosemirror` on NPM.
+
 ## Installation
 
 _Note_: React ProseMirror releases are coupled to specific prosemirror-view
@@ -77,6 +88,8 @@ import "prosemirror-view/style/prosemirror.css";
     - [`useEditorEventCallback`](#useeditoreventcallback)
     - [`useEditorEventListener`](#useeditoreventlistener)
   - [Building node views with React](#building-node-views-with-react)
+- [What's new in v2?](#whats-new-in-v2)
+  - [API changes](#api-changes)
 - [API](#api)
   - [`ProseMirror`](#prosemirror)
   - [`ProseMirrorDoc`](#prosemirrordoc)
@@ -92,7 +105,6 @@ import "prosemirror-view/style/prosemirror.css";
   - [`widget`](#widget)
   - [`reorderSiblings`](#reordersiblings)
     - [When should I use this?](#when-should-i-use-this)
-- [Migrations](#migrations)
 - [Looking for someone to collaborate with?](#looking-for-someone-to-collaborate-with)
 
 <!-- tocstop -->
@@ -454,6 +466,64 @@ function ProseMirrorEditor() {
 }
 ```
 
+## What's new in v2?
+
+The v2 release constitutes a significant re-write of the library.
+
+Previously, React ProseMirror relied on ProseMirror's EditorView to manage the
+DOM for the editor. To integrate it with React, we used React
+[portals](https://react.dev/reference/react-dom/createPortal) to render
+components into ProseMirror-managed DOM nodes, and a
+[useLayoutEffect](https://react.dev/reference/react/useLayoutEffect) to sync
+state updates with the EditorView instance.
+
+This approach provided some challenges. First, portals have to be rendered into
+existing, stable DOM nodes, so all React-based custom node views ended up
+wrapped in extra HTML elements. This made styling and producing valid DOM more
+challenging than it should be, and introduced corner cases in browser
+contenteditable implementations. Second, we induced a double render for every
+ProseMirror update, and during the first render, React-based custom node views
+will be rendered with the previous state. This is technically another form of
+the state tearing that this library was designed to prevent, as all _other_
+React components will be rendered with the new state!
+
+To overcome these challenges, the new release moves rendering responsibility
+entirely into React. We disabled the EditorView's DOM update cycle, and
+implemented the same update algorithm that prosemirror-view uses with React
+components. The result is a more idiomatic, React-based library, which doesn't
+have any of the issues of the original implementation.
+
+### API changes
+
+- The [`ProseMirror`](#prosemirror) component API has changed slightly:
+  - Instead of passing a `mount` prop with a ref to a child element, users must
+    render a [`ProseMirrorDoc`](#prosemirrordoc) component as a child of the
+    `ProseMirror` component.
+  - The `nodeViews` prop no longer matches the ProseMirror API. Instead,
+    `nodeViews` should be a map from node type name to React components, each of
+    which must take [`NodeViewComponentProps`](#nodeviewcomponentprops) as
+    props. This map should be memoized, or defined outside the React component
+    entirely.
+  - To pass standard ProseMirror node view constructors, use the
+    `customNodeViews` prop
+- The API that React-based node views must implement has changed:
+  - There is no longer any need to provide a ProseMirror node view constructor
+    function. React-based node views are now just React components that accept
+    `NodeViewComponentProps` as props.
+  - Props related to the ProseMirror node, such as the node itself, the `getPos`
+    function, and decorations, now live in the `nodeProps` property. All other
+    props _must_ be spread onto the root element of the node view component,
+    aside from `children`, which may be rendered anywhere in the component, as
+    appropriate.
+  - All node view components must forward their ref to the root element of the
+    component.
+  - To implement features that would normally live in the node view spec, there
+    are new hooks, such as [`useStopEvent`](#usestopevent) and
+    [`useSelectNode`](#useselectnode)
+- There is a new export, [`widget`](#widget), which behaves similarly to
+  `Decoration.widget` from `prosemirror-view`, but takes a React component
+  instead of a `toDOM` method.
+
 ## API
 
 ### `ProseMirror`
@@ -735,10 +805,6 @@ properly track the new positions for the reordered nodes, allowing it to reuse
 the same keys. This prevents any issues that could be caused by unexpected
 component remounts.
 
-## Migrations
-
-- [Migrating from v1 to v2](migration-guides/v2.md)
-
 ## Looking for someone to collaborate with?
 
 Reach out to [Handle with Care](https://handlewithcare.dev/#get-in-touch)! We're

package/dist/cjs/StaticEditorView.js

@@ -27,6 +27,9 @@ let StaticEditorView = class StaticEditorView {
     get state() {
         return this.props.state;
     }
+    get isDestroyed() {
+        return false;
+    }
     setProps(props) {
         return this.update({
             ...this.props,

package/dist/cjs/tiptap/TiptapEditor.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "TiptapEditor", {
+    enumerable: true,
+    get: function() {
+        return TiptapEditor;
+    }
+});
+const _core = require("@tiptap/core");
+const _prosemirrorstate = require("prosemirror-state");
+const _StaticEditorView = require("../StaticEditorView.js");
+let TiptapEditor = class TiptapEditor extends _core.Editor {
+    constructor(options = {}){
+        super({
+            ...options,
+            element: null
+        });
+    }
+    get view() {
+        return(// @ts-expect-error private property
+        this.editorView ?? new _StaticEditorView.StaticEditorView({
+            state: _prosemirrorstate.EditorState.create({
+                schema: this.extensionManager.schema
+            }),
+            ...this.options.editorProps,
+            attributes: {
+                role: "textbox",
+                ...this.extensionManager.attributes
+            }
+        }));
+    }
+};

package/dist/cjs/tiptap/TiptapEditorContent.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "TiptapEditorContent", {
+    enumerable: true,
+    get: function() {
+        return TiptapEditorContent;
+    }
+});
+const _react = /*#__PURE__*/ _interop_require_wildcard(require("react"));
+const _reactdom = require("react-dom");
+const _ProseMirrorDoc = require("../components/ProseMirrorDoc.js");
+const _useEditorEffect = require("../hooks/useEditorEffect.js");
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interop_require_wildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {
+        __proto__: null
+    };
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+/**
+ * This component renders all of the editor's registered "React renderers".
+ */ const Portals = (param)=>{
+    let { contentComponent } = param;
+    const renderers = (0, _react.useSyncExternalStore)(contentComponent.subscribe, contentComponent.getSnapshot, contentComponent.getServerSnapshot);
+    return /*#__PURE__*/ _react.default.createElement(_react.default.Fragment, null, Object.values(renderers));
+};
+function getInstance() {
+    const subscribers = new Set();
+    let renderers = {};
+    return {
+        /**
+     * Subscribe to the editor instance's changes.
+     */ subscribe (callback) {
+            subscribers.add(callback);
+            return ()=>{
+                subscribers.delete(callback);
+            };
+        },
+        getSnapshot () {
+            return renderers;
+        },
+        getServerSnapshot () {
+            return renderers;
+        },
+        /**
+     * Adds a new React Renderer to the editor.
+     */ setRenderer (id, renderer) {
+            renderers = {
+                ...renderers,
+                [id]: /*#__PURE__*/ (0, _reactdom.createPortal)(renderer.reactElement, renderer.element, id)
+            };
+            subscribers.forEach((subscriber)=>subscriber());
+        },
+        /**
+     * Removes a React Renderer from the editor.
+     */ removeRenderer (id) {
+            const nextRenderers = {
+                ...renderers
+            };
+            delete nextRenderers[id];
+            renderers = nextRenderers;
+            subscribers.forEach((subscriber)=>subscriber());
+        }
+    };
+}
+function TiptapEditorContent(param) {
+    let { editor: editorProp, ...props } = param;
+    const editor = editorProp;
+    (0, _useEditorEffect.useEditorEffect)((view)=>{
+        if (editor.view === view) {
+            return;
+        }
+        // @ts-expect-error private property
+        editor.editorView = view;
+        editor.contentComponent = getInstance();
+        // @ts-expect-error private method
+        editor.injectCSS();
+        const dom = view.dom;
+        dom.editor = editor;
+        setTimeout(()=>{
+            if (editor.isDestroyed) {
+                return;
+            }
+            editor.commands.focus(editor.options.autofocus);
+            editor.emit("create", {
+                editor
+            });
+            editor.isInitialized = true;
+        });
+        return ()=>{
+            editor.isInitialized = false;
+            editor.contentComponent = null;
+        };
+    }, [
+        editor
+    ]);
+    return /*#__PURE__*/ _react.default.createElement(_react.default.Fragment, null, /*#__PURE__*/ _react.default.createElement(_ProseMirrorDoc.ProseMirrorDoc, props), editor?.contentComponent && /*#__PURE__*/ _react.default.createElement(Portals, {
+        contentComponent: editor.contentComponent
+    }));
+}

package/dist/cjs/tiptap/TiptapEditorView.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "TiptapEditorView", {
+    enumerable: true,
+    get: function() {
+        return TiptapEditorView;
+    }
+});
+const _react = require("@tiptap/react");
+const _react1 = /*#__PURE__*/ _interop_require_wildcard(require("react"));
+const _ProseMirror = require("../components/ProseMirror.js");
+const _useForceUpdate = require("../hooks/useForceUpdate.js");
+function _getRequireWildcardCache(nodeInterop) {
+    if (typeof WeakMap !== "function") return null;
+    var cacheBabelInterop = new WeakMap();
+    var cacheNodeInterop = new WeakMap();
+    return (_getRequireWildcardCache = function(nodeInterop) {
+        return nodeInterop ? cacheNodeInterop : cacheBabelInterop;
+    })(nodeInterop);
+}
+function _interop_require_wildcard(obj, nodeInterop) {
+    if (!nodeInterop && obj && obj.__esModule) {
+        return obj;
+    }
+    if (obj === null || typeof obj !== "object" && typeof obj !== "function") {
+        return {
+            default: obj
+        };
+    }
+    var cache = _getRequireWildcardCache(nodeInterop);
+    if (cache && cache.has(obj)) {
+        return cache.get(obj);
+    }
+    var newObj = {
+        __proto__: null
+    };
+    var hasPropertyDescriptor = Object.defineProperty && Object.getOwnPropertyDescriptor;
+    for(var key in obj){
+        if (key !== "default" && Object.prototype.hasOwnProperty.call(obj, key)) {
+            var desc = hasPropertyDescriptor ? Object.getOwnPropertyDescriptor(obj, key) : null;
+            if (desc && (desc.get || desc.set)) {
+                Object.defineProperty(newObj, key, desc);
+            } else {
+                newObj[key] = obj[key];
+            }
+        }
+    }
+    newObj.default = obj;
+    if (cache) {
+        cache.set(obj, newObj);
+    }
+    return newObj;
+}
+function TiptapEditorView(param) {
+    let { editor, nodeViews, children } = param;
+    const forceUpdate = (0, _useForceUpdate.useForceUpdate)();
+    const dispatchTransaction = (0, _react1.useCallback)((tr)=>{
+        // @ts-expect-error calling private method
+        editor.dispatchTransaction(tr);
+        // Tiptap's dispatchTransaction doesn't trigger
+        // a re-render, so we need to manually force
+        // one to ensure that React stays in sync.
+        forceUpdate();
+    }, [
+        editor,
+        forceUpdate
+    ]);
+    const initialEditorProps = {
+        ...editor.options.editorProps,
+        attributes: {
+            role: "textbox",
+            ...editor.options.editorProps?.attributes
+        }
+    };
+    const { nodeViews: customNodeViews, markViews } = editor.isDestroyed ? {
+        nodeViews: undefined,
+        markViews: undefined
+    } : editor.view.props;
+    const contextValue = (0, _react1.useMemo)(()=>({
+            editor
+        }), [
+        editor
+    ]);
+    return /*#__PURE__*/ _react1.default.createElement(_ProseMirror.ProseMirror, {
+        className: "tiptap",
+        ...initialEditorProps,
+        markViews: markViews,
+        nodeViews: nodeViews,
+        customNodeViews: customNodeViews,
+        state: editor.isDestroyed || editor.state.plugins.length ? editor.state : editor.state.reconfigure({
+            plugins: editor.extensionManager.plugins
+        }),
+        dispatchTransaction: dispatchTransaction
+    }, /*#__PURE__*/ _react1.default.createElement(_react.EditorContext.Provider, {
+        value: contextValue
+    }, children));
+}

package/dist/cjs/tiptap/extensions/ReactProseMirror.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "ReactProseMirror", {
+    enumerable: true,
+    get: function() {
+        return ReactProseMirror;
+    }
+});
+const _core = require("@tiptap/core");
+const _reactKeys = require("../../plugins/reactKeys.js");
+const ReactProseMirror = _core.Extension.create({
+    name: "@handlewithcare/react-prosemirror/reactKeys",
+    addProseMirrorPlugins () {
+        return [
+            (0, _reactKeys.reactKeys)()
+        ];
+    }
+});

package/dist/cjs/tiptap/hooks/useTiptapEditor.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "useTiptapEditor", {
+    enumerable: true,
+    get: function() {
+        return useTiptapEditor;
+    }
+});
+const _react = require("@tiptap/react");
+const _StaticEditorView = require("../../StaticEditorView.js");
+function useTiptapEditor(options, deps) {
+    const editor = (0, _react.useEditor)({
+        ...options,
+        element: null
+    }, deps);
+    // @ts-expect-error private property
+    editor.editorView ??= new _StaticEditorView.StaticEditorView({
+        // @ts-expect-error private property
+        state: editor.editorState,
+        ...editor.options.editorProps,
+        attributes: {
+            role: "textbox",
+            ...editor.extensionManager.attributes
+        }
+    });
+    return editor;
+}

package/dist/cjs/tiptap/hooks/useTiptapEditorEffect.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "useTiptapEditorEffect", {
+    enumerable: true,
+    get: function() {
+        return useTiptapEditorEffect;
+    }
+});
+const _react = require("@tiptap/react");
+const _react1 = require("react");
+const _ReactEditorView = require("../../ReactEditorView.js");
+const _EditorContext = require("../../contexts/EditorContext.js");
+const _useEditorEffect = require("../../hooks/useEditorEffect.js");
+function useTiptapEditorEffect(effect, dependencies) {
+    const { view } = (0, _react1.useContext)(_EditorContext.EditorContext);
+    const { editor } = (0, _react.useCurrentEditor)();
+    (0, _useEditorEffect.useEditorEffect)(()=>{
+        if (editor?.view instanceof _ReactEditorView.ReactEditorView && view instanceof _ReactEditorView.ReactEditorView) {
+            return effect(editor);
+        }
+    // The rules of hooks want to be able to statically
+    // verify the dependencies for the effect, but this will
+    // have already happened at the call-site.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, dependencies && [
+        editor,
+        view,
+        ...dependencies
+    ]);
+}

package/dist/cjs/tiptap/hooks/useTiptapEditorEventCallback.js

@@ -0,0 +1,35 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+Object.defineProperty(exports, "useTiptapEditorEventCallback", {
+    enumerable: true,
+    get: function() {
+        return useTiptapEditorEventCallback;
+    }
+});
+const _react = require("@tiptap/react");
+const _react1 = require("react");
+const _useEditorEffect = require("../../hooks/useEditorEffect.js");
+function assertEditor(editor) {
+    if (editor) return;
+    throw new DOMException("Tiptap Editor is not initialized", "InvalidStateError");
+}
+function useTiptapEditorEventCallback(callback) {
+    const ref = (0, _react1.useRef)(callback);
+    const { editor } = (0, _react.useCurrentEditor)();
+    (0, _useEditorEffect.useEditorEffect)(()=>{
+        ref.current = callback;
+    }, [
+        callback
+    ]);
+    return (0, _react1.useCallback)(function() {
+        for(var _len = arguments.length, args = new Array(_len), _key = 0; _key < _len; _key++){
+            args[_key] = arguments[_key];
+        }
+        assertEditor(editor);
+        return ref.current(editor, ...args);
+    }, [
+        editor
+    ]);
+}

package/dist/cjs/tiptap/index.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+function _export(target, all) {
+    for(var name in all)Object.defineProperty(target, name, {
+        enumerable: true,
+        get: all[name]
+    });
+}
+_export(exports, {
+    ReactProseMirror: function() {
+        return _ReactProseMirror.ReactProseMirror;
+    },
+    TiptapEditor: function() {
+        return _TiptapEditor.TiptapEditor;
+    },
+    TiptapEditorContent: function() {
+        return _TiptapEditorContent.TiptapEditorContent;
+    },
+    TiptapEditorView: function() {
+        return _TiptapEditorView.TiptapEditorView;
+    },
+    tiptapNodeView: function() {
+        return _tiptapNodeView.tiptapNodeView;
+    },
+    useTiptapEditor: function() {
+        return _useTiptapEditor.useTiptapEditor;
+    },
+    useTiptapEditorEffect: function() {
+        return _useTiptapEditorEffect.useTiptapEditorEffect;
+    },
+    useTiptapEditorEventCallback: function() {
+        return _useTiptapEditorEventCallback.useTiptapEditorEventCallback;
+    }
+});
+const _tiptapNodeView = require("./tiptapNodeView.js");
+const _TiptapEditorView = require("./TiptapEditorView.js");
+const _TiptapEditorContent = require("./TiptapEditorContent.js");
+const _useTiptapEditorEffect = require("./hooks/useTiptapEditorEffect.js");
+const _useTiptapEditorEventCallback = require("./hooks/useTiptapEditorEventCallback.js");
+const _TiptapEditor = require("./TiptapEditor.js");
+const _useTiptapEditor = require("./hooks/useTiptapEditor.js");
+const _ReactProseMirror = require("./extensions/ReactProseMirror.js");