feat: Comments

docs/components/example/styles.css

@@ -1,34 +1,38 @@
 :focus-visible {
-    box-shadow: unset !important;
+  box-shadow: unset !important;
 }
 
 .demo .nextra-code-block pre {
-    background-color: transparent !important;
-    margin: 0 !important;
-    padding: 0 !important;
+  background-color: transparent !important;
+  margin: 0 !important;
+  padding: 0 !important;
 }
 
 .demo .nextra-code-block code > span {
-    padding: 0 !important;
+  padding: 0 !important;
 }
 
-.demo .bn-container,
+.demo .bn-container:not(.bn-comment-editor),
 .demo .bn-editor {
-    height: 100%;
+  height: 100%;
+}
+
+.demo .bn-container:not(.bn-comment-editor) .bn-editor {
+  height: 100%;
 }
 
 .demo .bn-editor {
-    overflow: auto;
-    padding-block: 1rem;
+  overflow: auto;
+  padding-block: 1rem;
 }
 
 .demo-contents a {
-    color: revert;
-    text-decoration: revert;
+  color: revert;
+  text-decoration: revert;
 }
 
 .demo code.bn-inline-content {
-    font-size: 1em;
-    line-height: 1.5;
-    display: block;
-}
+  font-size: 1em;
+  line-height: 1.5;
+  display: block;
+}

docs/next.config.mjs

@@ -123,6 +123,11 @@ const nextConfig = withAnalyzer(
         destination: "/examples/basic/default-blocks",
         permanent: true,
       },
+      {
+        source: "/docs/advanced/real-time-collaboration",
+        destination: "/docs/collaboration",
+        permanent: true,
+      },
     ],
     experimental: {
       externalDir: true,

docs/pages/docs/_meta.json

@@ -6,6 +6,7 @@
   "styling-theming": "Styling & Theming",
   "ui-components": "UI Components",
   "custom-schemas": "Custom Schemas",
+  "collaboration": "Collaboration",
   "advanced": "Advanced",
   "discord-link": {
     "title": "Community ↗",

docs/pages/docs/collaboration.mdx

@@ -0,0 +1,11 @@
+---
+title: Collaboration
+description: Learn how to create multiplayer experiences with BlockNote
+---
+
+# Collaboration (advanced)
+
+BlockNote supports multi-user collaborative document editing.
+
+- [Real-time collaboration](/docs/collaboration/real-time-collaboration)
+- [Comments](/docs/collaboration/comments)

docs/pages/docs/collaboration/_meta.json

@@ -0,0 +1,4 @@
+{
+  "real-time-collaboration": "Real-time collaboration",
+  "comments": "Comments"
+}

docs/pages/docs/collaboration/comments.mdx

@@ -0,0 +1,138 @@
+---
+title: Comments
+description: Learn how to enable comments in your BlockNote editor
+imageTitle: Comments
+---
+
+import { Example } from "@/components/example";
+
+# Comments
+
+BlockNote supports Comments, Comment Threads (replies) and emoji reactions out of the box.
+
+To enable comments in your editor, you need to:
+
+- provide a `resolveUsers` so BlockNote can retrieve and display user information (names and avatars).
+- provide a `ThreadStore` so BlockNote can store and retrieve comment threads.
+- enable real-time collaboration (see [Real-time collaboration](/docs/collaboration/real-time-collaboration))
+
+```tsx
+const editor = useCreateBlockNote({
+  resolveUsers: async (userIds: string[]) => {
+    // return user information for the given userIds (see below)
+  },
+  comments: {
+    threadStore: yourThreadStore, // see below
+  },
+  // ...
+  collaboration: {
+    // ... // see real-time collaboration docs
+  },
+});
+```
+
+**Demo**
+
+<Example name="collaboration/comments" />
+
+## ThreadStores
+
+A ThreadStore is used to store and retrieve comment threads. BlockNote is backend agnostic, so you can use any database or backend to store the threads.
+BlockNote comes with several built-in ThreadStore implementations:
+
+### `YjsThreadStore`
+
+The `YjsThreadStore` provides direct Yjs-based storage for comments, storing thread data directly in the Yjs document. This implementation is ideal for simple collaborative setups where all users have write access to the document.
+
+```tsx
+import { YjsThreadStore } from "@blocknote/core";
+
+const threadStore = new YjsThreadStore(
+  userId, // The active user's ID
+  yDoc.getMap("threads"), // Y.Map to store threads
+  new DefaultThreadStoreAuth(userId, "editor"), // Authorization information, see below
+);
+```
+
+_Note: While this is the easiest to implement, it requires users to have write access to the Yjs document to leave comments. Also, without proper server-side validation, any user could technically modify other users' comments._
+
+### `RESTYjsThreadStore`
+
+The `RESTYjsThreadStore` combines Yjs storage with a REST API backend, providing secure comment management while maintaining real-time collaboration. This implementation is ideal when you have strong authentication requirements, but is a little more work to set up.
+
+In this implementation, data is written to the Yjs document via a REST API which can handle access control. Data is still retrieved from the Yjs document directly (after it's been updated by the REST API), this way all comment information automatically syncs between clients using the existing collaboration provider.
+
+```tsx
+import { RESTYjsThreadStore, DefaultThreadStoreAuth } from "@blocknote/core";
+
+const threadStore = new RESTYjsThreadStore(
+  "https://api.example.com/comments", // Base URL for the REST API
+  {
+    Authorization: "Bearer your-token", // Optional headers to add to requests
+  },
+  yDoc.getMap("threads"), // Y.Map to retrieve commend data from
+  new DefaultThreadStoreAuth(userId, "editor"), // Authorization rules (see below)
+);
+```
+
+An example implementation of the REST API can be found in the [example repository](https://github.com/TypeCellOS/BlockNote-demo-nextjs-hocuspocus).
+
+_Note: Because writes are executed via a REST API, the `RESTYjsThreadStore` is not suitable for local-first applications that should be able to add and edit comments offline._
+
+### `TiptapThreadStore`
+
+The `TiptapThreadStore` integrates with Tiptap's collaboration provider for comment management. This implementation is designed specifically for use with Tiptap's collaborative editing features.
+
+```tsx
+import { TiptapThreadStore, DefaultThreadStoreAuth } from "@blocknote/core";
+import { TiptapCollabProvider } from "@hocuspocus/provider";
+
+// Create a TiptapCollabProvider (you probably have this already)
+const provider = new TiptapCollabProvider({
+  name: "test",
+  baseUrl: "https://collab.yourdomain.com",
+  appId: "test",
+  document: doc,
+});
+
+// Create a TiptapThreadStore
+const threadStore = new TiptapThreadStore(
+  userId, // The active user's ID
+  provider, // Tiptap collaboration provider
+  new DefaultThreadStoreAuth(userId, "editor"), // Authorization rules (see below)
+);
+```
+
+### ThreadStoreAuth
+
+The `ThreadStoreAuth` class defines the authorization rules for interacting with comments. Every ThreadStore implementation requires a `ThreadStoreAuth` instance. BlockNote uses the `ThreadStoreAuth` instance to deterine which interactions are allowed for the current user (for example, whether they can create a new comment, edit or delete a comment, etc.).
+
+The `DefaultThreadStoreAuth` class provides a basic implementation of the `ThreadStoreAuth` class. It takes a user ID and a role ("comment" or "editor") and implements the rules. See the [source code](https://github.com/TypeCellOS/BlockNote/blob/main/packages/core/src/extensions/Comments/threadstore/DefaultThreadStoreAuth.ts) for more details.
+
+_Note: The `ThreadStoreAuth` only used to show / hide options in the UI. To secure comment related data, you still need to implement your own server-side validation (e.g. using `RESTYjsThreadStore` and a secure REST API)._
+
+## `resolveUsers` function
+
+When a user interacts with a comment, the data is stored in the ThreadStore, along with the active user ID (as specified when initiating the ThreadStore).
+
+To display comments, BlockNote needs to retrieve user information (such as the username and avatar) based on the user ID. To do this, you need to provide a `resolveUsers` function in the editor options.
+
+This function is called with an array of user IDs, and should return an array of `User` objects in the same order.
+
+```tsx
+type User = {
+  id: string;
+  username: string;
+  avatarUrl: string;
+};
+
+async function myResolveUsers(userIds: string[]): Promise<User[]> {
+  // fetch user information from your database / backend
+  // and return an array of User objects
+
+  return await callYourBackend(userIds); //
+
+  // Return a list of users
+  return users;
+}
+```

docs/pages/docs/editor-basics/setup.mdx

@@ -21,6 +21,7 @@ function useCreateBlockNote(
 type BlockNoteEditorOptions = {
   animations?: boolean;
   collaboration?: CollaborationOptions;
+  comments?: CommentsConfig;
   defaultStyles?: boolean;
   dictionary?: Dictionary;
   disableExtensions?: string[];
@@ -50,6 +51,8 @@ The hook takes two optional parameters:
 
 `collaboration`: Options for enabling real-time collaboration. See [Real-time Collaboration](/docs/advanced/real-time-collaboration) for more info.
 
+`comments`: Configuration for the comments feature, requires a `threadStore`. See [Comments](/docs/collaboration/comments) for more.
+
 `defaultStyles`: Whether to use the default font and reset the styles of `<p>`, `<li>`, `<h1>`, etc. elements that are used in BlockNote. Defaults to true if undefined.
 
 `dictionary`: Provide strings for localization. See the [Localization / i18n example](/examples/basic/localization) and [Custom Placeholders](/examples/basic/custom-placeholder).
@@ -62,15 +65,17 @@ The hook takes two optional parameters:
 
 `initialContent:` The content that should be in the editor when it's created, represented as an array of [Partial Blocks](/docs/manipulating-blocks#partial-blocks).
 
-`resolveFileUrl:` An async function that fetches the download URL of a file from an initial URL.
+`resolveFileUrl:` Function to resolve file URLs for display/download. Useful for creating authenticated URLs or implementing custom protocols.
+
+`resolveUsers`: Function to resolve user information for comments. See [Comments](/docs/collaboration/comments) for more.
 
 `schema`: The editor schema if you want to extend your editor with custom blocks, styles, or inline content [Custom Schemas](/docs/custom-schemas).
 
 `setIdAttribute`: Whether to render an `id` HTML attribute on blocks as well as a `data-id` attribute. Defaults to `false`.
 
 `sideMenuDetection`: Determines whether the mouse cursor position is locked to the editor bounding box for showing the [Block Side Menu](/docs/ui-components/side-menu) and block drag & drop. When set to `viewport`, the Side Menu will be shown next to the nearest block to the cursor, regardless of where it is in the viewport. Dropping blocks will also be locked to the editor bounding box. Otherwise, the Side Menu will only be shown when the cursor is within the editor bounds, and blocks can only be dropped when hovering the editor. In order to use multiple editors, must be set to `editor`. Defaults to `viewport`.
 
-`tabBehavior`: Determines whether pressing the tab key should navigate the UI for keyboard accessibility or indent the current block. Defaults to `prefer-navigate-ui`.
+`tabBehavior`: Determines whether pressing the tab key should navigate toolbars for keyboard accessibility. When set to `"prefer-navigate-ui`, the user can navigate toolbars using Tab. Pressing Escape re-focuses the editor, and Tab now indents blocks. `"prefer-indent"` causes Tab to always indent blocks. Defaults to `prefer-navigate-ui`.
 
 `trailingBlock`: An option which user can pass with `false` value to disable the automatic creation of a trailing new block on the next line when the user types or edits any block. Defaults to `true` if undefined.
 
@@ -125,6 +130,7 @@ export type BlockNoteViewProps = {
   emojiPicker?: boolean;
   filePanel?: boolean;
   tableHandles?: boolean;
+  comments?: boolean;
   children?:
 } & HTMLAttributes<HTMLDivElement>;
 ```
@@ -153,6 +159,8 @@ export type BlockNoteViewProps = {
 
 `tableHandles`: Whether the Table Handles should be enabled.
 
+`comments`: Whether the default comments UI feature should be enabled.
+
 `children`: Pass child elements to the `BlockNoteView` to create or customize toolbars, menus, or other UI components. See [UI Components](/docs/ui-components) for more.
 
 Additional props passed are forwarded to the HTML `div` element BlockNote renders internally.

examples/01-basic/01-minimal/App.tsx

@@ -5,7 +5,7 @@ import { useCreateBlockNote } from "@blocknote/react";
 
 export default function App() {
   // Creates a new editor instance.
-  const editor = useCreateBlockNote();
+  const editor = useCreateBlockNote({});
 
   // Renders the editor instance using a React component.
   return <BlockNoteView editor={editor} />;

examples/01-basic/02-block-objects/App.tsx

@@ -1,8 +1,8 @@
 import { Block } from "@blocknote/core";
 import "@blocknote/core/fonts/inter.css";
-import { useCreateBlockNote } from "@blocknote/react";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
+import { useCreateBlockNote } from "@blocknote/react";
 import { useState } from "react";
 
 import "./styles.css";

examples/07-collaboration/01-partykit/README.md

@@ -6,5 +6,5 @@ In this example, we use PartyKit to let multiple users collaborate on a single B
 
 **Relevant Docs:**
 
-- [PartyKit](/docs/advanced/real-time-collaboration#partykit)
 - [Editor Setup](/docs/editor-basics/setup)
+- [PartyKit](/docs/collaboration/real-time-collaboration#partykit)

examples/07-collaboration/02-liveblocks/App.tsx

@@ -1,7 +1,7 @@
 import "@blocknote/core/fonts/inter.css";
-import { useCreateBlockNote } from "@blocknote/react";
 import { BlockNoteView } from "@blocknote/mantine";
 import "@blocknote/mantine/style.css";
+import { useCreateBlockNote } from "@blocknote/react";
 import { createClient } from "@liveblocks/client";
 import LiveblocksProvider from "@liveblocks/yjs";
 import * as Y from "yjs";

examples/07-collaboration/02-liveblocks/README.md

@@ -6,5 +6,5 @@ In this example, we use Liveblocks to let multiple users collaborate on a single
 
 **Relevant Docs:**
 
-- [Liveblocks](/docs/advanced/real-time-collaboration#liveblocks)
 - [Editor Setup](/docs/editor-basics/setup)
+- [Liveblocks](/docs/collaboration/real-time-collaboration#liveblocks)

examples/07-collaboration/03-y-sweet/README.md

@@ -6,5 +6,6 @@ In this example, we use Y-Sweet to let multiple users collaborate on a single Bl
 
 **Relevant Docs:**
 
-- [Y-Sweet on Jamsocket](https://docs.jamsocket.com/y-sweet/tutorials/blocknote)
 - [Editor Setup](/docs/editor-basics/setup)
+- [Real-time collaboration](/docs/collaboration/real-time-collaboration)
+- [Y-Sweet on Jamsocket](https://docs.jamsocket.com/y-sweet/tutorials/blocknote)

examples/07-collaboration/04-comments/.bnexample.json

@@ -0,0 +1,10 @@
+{
+  "playground": true,
+  "docs": true,
+  "author": "yousefed",
+  "tags": ["Advanced", "Comments", "Collaboration"],
+  "dependencies": {
+    "@y-sweet/react": "^0.6.3",
+    "@mantine/core": "^7.10.1"
+  }
+}