feat: Multiplayer API and homepage collaboration (#200)

* upgrade tiptap and node/npm

* upgrade node in ci

* fix collab api and add partykit to homepage (wip)

* wip

* make homepage collaborative

* fix typing at start of line

* add docs

* Fixed text alignment styling with flexbox

* Fixed text alignment styling with flexbox

* Fixed text alignment styling with flexbox

* Fixed text alignment styling with flexbox

* Copy/paste tests are now skipped for WebKit

* Copy/paste tests are now skipped for WebKit

* Updated firefox colors snapshot

---------

Co-authored-by: Matthew Lipski <matthewlipski@gmail.com>

Author: YousefED

package-lock.json

@@ -80,8 +80,8 @@
     "unified": "^10.1.2",
     "uuid": "^8.3.2",
     "y-prosemirror": "1.0.20",
-    "y-protocols": "1.0.5",
-    "yjs": "13.5.44"
+    "y-protocols": "^1.0.5",
+    "yjs": "^13.6.1"
   },
   "devDependencies": {
     "@types/hast": "^2.3.4",

packages/core/package.json

@@ -2,6 +2,7 @@ import { Editor, EditorOptions } from "@tiptap/core";
 import { Node } from "prosemirror-model";
 // import "./blocknote.css";
 import { Editor as TiptapEditor } from "@tiptap/core/dist/packages/core/src/Editor";
+import * as Y from "yjs";
 import {
   insertBlocks,
   removeBlocks,
@@ -23,12 +24,12 @@ import {
   BlockIdentifier,
   PartialBlock,
 } from "./extensions/Blocks/api/blockTypes";
+import { TextCursorPosition } from "./extensions/Blocks/api/cursorPositionTypes";
 import {
   ColorStyle,
   Styles,
   ToggledStyle,
 } from "./extensions/Blocks/api/inlineContentTypes";
-import { TextCursorPosition } from "./extensions/Blocks/api/cursorPositionTypes";
 import { Selection } from "./extensions/Blocks/api/selectionTypes";
 import { getBlockInfoFromPos } from "./extensions/Blocks/helpers/getBlockInfoFromPos";
 import {
@@ -37,9 +38,9 @@ import {
 } from "./extensions/SlashMenu";
 
 export type BlockNoteEditorOptions = {
-  // TODO: Figure out if enableBlockNoteExtensions/disableHistoryExtension are needed and document them.
+  // TODO: Figure out if enableBlockNoteExtensions is needed and document them.
   enableBlockNoteExtensions: boolean;
-  disableHistoryExtension: boolean;
+
   /**
    * UI element factories for creating a custom UI, including custom positioning
    * & rendering.
@@ -97,6 +98,31 @@ export type BlockNoteEditorOptions = {
    */
   theme: "light" | "dark";
 
+  /**
+   * When enabled, allows for collaboration between multiple users.
+   */
+  collaboration: {
+    /**
+     * The Yjs XML fragment that's used for collaboration.
+     */
+    fragment: Y.XmlFragment;
+    /**
+     * The user info for the current user that's shown to other collaborators.
+     */
+    user: {
+      name: string;
+      color: string;
+    };
+    /**
+     * A Yjs provider (used for awareness / cursor information)
+     */
+    provider: any;
+    /**
+     * Optional function to customize how cursors of users are rendered
+     */
+    renderCursor?: (user: any) => HTMLElement;
+  };
+
   // tiptap options, undocumented
   _tiptapOptions: any;
 };
@@ -119,23 +145,20 @@ export class BlockNoteEditor {
     this._tiptapEditor.view.focus();
   }
 
-  constructor(options: Partial<BlockNoteEditorOptions> = {}) {
+  constructor(private readonly options: Partial<BlockNoteEditorOptions> = {}) {
     // apply defaults
     options = {
       defaultStyles: true,
       ...options,
     };
 
-    const blockNoteExtensions = getBlockNoteExtensions({
+    const extensions = getBlockNoteExtensions({
       editor: this,
       uiFactories: options.uiFactories || {},
       slashCommands: options.slashCommands || defaultSlashMenuItems,
+      collaboration: options.collaboration,
     });
 
-    let extensions = options.disableHistoryExtension
-      ? blockNoteExtensions.filter((e) => e.name !== "history")
-      : blockNoteExtensions;
-
     const tiptapOptions: EditorOptions = {
       // TODO: This approach to setting initial content is "cleaner" but requires the PM editor schema, which is only
       //  created after initializing the TipTap editor. Not sure it's feasible.
@@ -644,4 +667,16 @@ export class BlockNoteEditor {
   public async markdownToBlocks(markdown: string): Promise<Block[]> {
     return markdownToBlocks(markdown, this._tiptapEditor.schema);
   }
+
+  /**
+   * Updates the user info for the current user that's shown to other collaborators.
+   */
+  public updateCollaborationUserInfo(user: { name: string; color: string }) {
+    if (!this.options.collaboration) {
+      throw new Error(
+        "Cannot update collaboration user info when collaboration is disabled."
+      );
+    }
+    this._tiptapEditor.commands.updateUser(user);
+  }
 }

packages/core/src/BlockNoteEditor.ts

@@ -4,6 +4,8 @@ import { BlockNoteEditor } from "./BlockNoteEditor";
 
 import { Bold } from "@tiptap/extension-bold";
 import { Code } from "@tiptap/extension-code";
+import Collaboration from "@tiptap/extension-collaboration";
+import CollaborationCursor from "@tiptap/extension-collaboration-cursor";
 import { Dropcursor } from "@tiptap/extension-dropcursor";
 import { Gapcursor } from "@tiptap/extension-gapcursor";
 import { HardBreak } from "@tiptap/extension-hard-break";
@@ -13,6 +15,8 @@ import { Link } from "@tiptap/extension-link";
 import { Strike } from "@tiptap/extension-strike";
 import { Text } from "@tiptap/extension-text";
 import { Underline } from "@tiptap/extension-underline";
+import * as Y from "yjs";
+import styles from "./editor.module.css";
 import { BackgroundColorExtension } from "./extensions/BackgroundColor/BackgroundColorExtension";
 import { BackgroundColorMark } from "./extensions/BackgroundColor/BackgroundColorMark";
 import { blocks } from "./extensions/Blocks";
@@ -46,6 +50,15 @@ export const getBlockNoteExtensions = (opts: {
   editor: BlockNoteEditor;
   uiFactories: UiFactories;
   slashCommands: BaseSlashMenuItem[];
+  collaboration?: {
+    fragment: Y.XmlFragment;
+    user: {
+      name: string;
+      color: string;
+    };
+    provider: any;
+    renderCursor?: (user: any) => HTMLElement;
+  };
 }) => {
   const ret: Extensions = [
     extensions.ClipboardTextSerializer,
@@ -90,12 +103,48 @@ export const getBlockNoteExtensions = (opts: {
     ...blocks,
 
     Dropcursor.configure({ width: 5, color: "#ddeeff" }),
-    History,
     // This needs to be at the bottom of this list, because Key events (such as enter, when selecting a /command),
     // should be handled before Enter handlers in other components like splitListItem
     TrailingNode,
   ];
 
+  if (opts.collaboration) {
+    ret.push(
+      Collaboration.configure({
+        fragment: opts.collaboration.fragment,
+      })
+    );
+    const defaultRender = (user: { color: string; name: string }) => {
+      const cursor = document.createElement("span");
+
+      cursor.classList.add(styles["collaboration-cursor__caret"]);
+      cursor.setAttribute("style", `border-color: ${user.color}`);
+
+      const label = document.createElement("span");
+
+      label.classList.add(styles["collaboration-cursor__label"]);
+      label.setAttribute("style", `background-color: ${user.color}`);
+      label.insertBefore(document.createTextNode(user.name), null);
+
+      const nonbreakingSpace1 = document.createTextNode("\u2060");
+      const nonbreakingSpace2 = document.createTextNode("\u2060");
+      cursor.insertBefore(nonbreakingSpace1, null);
+      cursor.insertBefore(label, null);
+      cursor.insertBefore(nonbreakingSpace2, null);
+      return cursor;
+    };
+    ret.push(
+      CollaborationCursor.configure({
+        user: opts.collaboration.user,
+        render: opts.collaboration.renderCursor || defaultRender,
+        provider: opts.collaboration.provider,
+      })
+    );
+  } else {
+    // disable history extension when collaboration is enabled as Yjs takes care of undo / redo
+    ret.push(History);
+  }
+
   if (opts.uiFactories.blockSideMenuFactory) {
     ret.push(
       DraggableBlocksExtension.configure({

packages/core/src/BlockNoteExtensions.ts

@@ -38,9 +38,12 @@ Tippy popups that are appended to document.body directly
 .defaultStyles h3,
 .defaultStyles li {
   all: unset !important;
+  flex-grow: 1 !important;
   margin: 0;
   padding: 0;
   font-size: inherit;
+  /* min width to make sure cursor is always visible */
+  min-width: 2px !important;
 }
 
 .defaultStyles {
@@ -54,16 +57,43 @@ Tippy popups that are appended to document.body directly
 }
 
 [data-theme="light"] {
-  background-color: #FFFFFF;
+  background-color: #ffffff;
   color: #444444;
 }
 
 [data-theme="dark"] {
   background-color: #444444;
-  color: #DDDDDD;
+  color: #dddddd;
 }
 
 .dragPreview {
   position: absolute;
   top: -1000px;
 }
+
+/* Give a remote user a caret */
+.collaboration-cursor__caret {
+  border-left: 1px solid #0d0d0d;
+  border-right: 1px solid #0d0d0d;
+  margin-left: -1px;
+  margin-right: -1px;
+  pointer-events: none;
+  position: relative;
+  word-break: normal;
+}
+
+/* Render the username above the caret */
+.collaboration-cursor__label {
+  border-radius: 3px 3px 3px 0;
+  color: #0d0d0d;
+  font-size: 12px;
+  font-style: normal;
+  font-weight: 600;
+  left: -1px;
+  line-height: normal;
+  padding: 0.1rem 0.3rem;
+  position: absolute;
+  top: -1.4em;
+  user-select: none;
+  white-space: nowrap;
+}

packages/core/src/editor.module.css

@@ -10,7 +10,11 @@ BASIC STYLES
 .blockContent {
   padding: 3px 0;
   transition: font-size 0.2s;
-  /* display: inline-block; */
+  /*
+  because the content elements are display: block
+  we use flex to position them next to list markers
+  */
+  display: flex;
 }
 
 .blockContent::before {
@@ -40,13 +44,17 @@ NESTED BLOCKS
   transition: all 0.2s 0.1s;
 }
 
-[data-theme="light"] .blockGroup .blockGroup
-> .blockOuter:not([data-prev-depth-changed])::before {
-  border-left: 1px solid #CCCCCC;
+[data-theme="light"]
+  .blockGroup
+  .blockGroup
+  > .blockOuter:not([data-prev-depth-changed])::before {
+  border-left: 1px solid #cccccc;
 }
 
-[data-theme="dark"] .blockGroup .blockGroup
-> .blockOuter:not([data-prev-depth-changed])::before {
+[data-theme="dark"]
+  .blockGroup
+  .blockGroup
+  > .blockOuter:not([data-prev-depth-changed])::before {
   border-left: 1px solid #999999;
 }
 
@@ -217,10 +225,6 @@ NESTED BLOCKS
 
 /* PLACEHOLDERS*/
 
-.blockContent > :first-child {
-  display: inline;
-}
-
 .blockContent.isEmpty > :first-child:before,
 .blockContent.isFilter > :first-child:before {
   /*float: left; */
@@ -234,7 +238,7 @@ NESTED BLOCKS
 
 [data-theme="light"] .blockContent.isEmpty > :first-child:before,
 .blockContent.isFilter > :first-child:before {
-  color: #CCCCCC;
+  color: #cccccc;
 }
 
 [data-theme="dark"] .blockContent.isEmpty > :first-child:before,

packages/core/src/extensions/Blocks/nodes/Block.module.css

@@ -67,14 +67,14 @@ const SIDEBAR_DEFAULT = [
     text: "Advanced",
     collapsed: true,
     items: [
-      {
-        text: "Without React (vanilla JS)",
-        link: "/docs/vanilla-js",
-      },
       {
         text: "Real-time collaboration",
         link: "/docs/real-time-collaboration",
       },
+      {
+        text: "Without React (vanilla JS)",
+        link: "/docs/vanilla-js",
+      },
     ],
   },
 

packages/website/docs/.vitepress/config.ts

@@ -1,3 +1,3 @@
 .editor {
-  height: 600px;
+  height: 500px;
 }