feat: Comments #1376

YousefED · 2025-01-16T09:31:20Z

💖 This feature is sponsored by DINUM 🇫🇷 and ZenDiS 🇩🇪

This PR adds comments to BlockNote!

We implement several Comment / Thread related components that can be customized similar to other BlockNote components.
The implementation is completely backend agnostic as the storage interface (ThreadStore) is pluggable. This means you can "bring your own provider" if you like.

ThreadStores

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.
The downside of this is that comments require a more advanced permission model than text documents, and Yjs doesn't provide a straightforward way to secure document updates.

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.

We created a separate repository with an example server.

TipTap

We integrate directly with the TiptapCollabProvider with TiptapThreadStore.

LiveBlocks (later)

The UI Components are roughly based on the LiveBlocks open source components. LiveBlocks users will have two different ways to use LiveBlocks:

Use LiveBlocks UI components: this can be done with Feature/liveblocks v2 #1259. This would support all liveblocks functionality (read status, attachments, etc), but the style is a bit different from the other BlockNote components.
Use BlockNote UI components (matching your existing mantine / shadcn / ... version of BlockNote). These are "first-class" supported in BlockNote but miss some features compared to liveblocks (i.e.: read status, attachments, etc). We want to implement a LiveBlocksThreadStore for this, but this work is currently blocked (we can't store BlockNote documents describing comments in LiveBlocks)

TODO

TBD:

table cell, move block, and API operations
accessibility

Yjs next steps

overlapping marks (Yjs)
security of rest store
security of yjs store

To fix later

Important:

prevent outside modifications to the thread Y Map BlockNote-demo-nextjs-hocuspocus#1
comments on images and other block nodes
reposition on window resize
copy comment when cut+paste (optionally also with copy / paste?)
resolving newer comments deletes older already resolved ones at the same place. Probably a larger issue (yjs doesn't deal well with overlapping marks?)
show loading / error states in UI for interacting with comments
TBD: should the thread be deleted when the main (first) comment is removed?
TBD: add server side validation for YjsThreadStore (make sure users can't edit other users comments, etc). To make this work, we'd need to monitor updates in HocusPocus for example

Nice to haves:

closes #695
closes #1109
closes #1148
closes #703
closes #1200

vercel · 2025-01-16T09:31:27Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Updated (UTC)
blocknote	✅ Ready (Inspect)	Visit Preview	Feb 28, 2025 5:06pm
blocknote-website	✅ Ready (Inspect)	Visit Preview	Feb 28, 2025 5:06pm

packages/core/package.json

packages/react/src/components/Comments/FloatingComposerController.tsx

nperez0111 · 2025-02-27T10:09:41Z

packages/react/src/components/Comments/FloatingThreadController.tsx

+  // Positioning with [data-bn-thread-id] attribute is a bit hacky,
+  // we could probably also use the thread position from the plugin state?
+  // for now, this works ok
+  const updateRef = useCallback(() => {
+    if (!state?.selectedThreadId) {
+      return;
+    }
+
+    const el = editor.domElement?.querySelector(
+      `[data-bn-thread-id="${state?.selectedThreadId}"]`
+    );
+    if (el) {
+      setReference(el);
+    }
+  }, [setReference, editor, state?.selectedThreadId]);


Definitely strange, I don't quite understand how this all works

@YousefED can you explain what's happening here? Seems a bit hacky to use querySelector

nperez0111 · 2025-02-27T10:22:08Z

packages/react/src/hooks/useFocusWithin.ts

+  const handleFocusIn = (event: FocusEvent) => {
+    if (!focusedRef.current) {
+      _setFocused(true);
+      onFocus?.(event);
+    }
+  };
+
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const handleFocusOut = (event: FocusEvent) => {
+    if (focusedRef.current && !containsRelatedTarget(event)) {
+      _setFocused(false);
+      onBlur?.(event);
+    }
+  };
+
+  useEffect(() => {
+    const node = ref.current;
+
+    if (node) {
+      node.addEventListener("focusin", handleFocusIn);
+      node.addEventListener("focusout", handleFocusOut);
+
+      return () => {
+        node?.removeEventListener("focusin", handleFocusIn);
+        node?.removeEventListener("focusout", handleFocusOut);
+      };
+    }
+
+    return undefined;
+  }, [handleFocusIn, handleFocusOut]);


I know this was copied over, but just wanted to say that this is strangely wasteful, it constantly adds and removes the event listeners when it doesn't need to

This reverts commit a647ec3.

# Conflicts: # docs/pages/docs/editor-basics/setup.mdx # package-lock.json # packages/core/src/editor/BlockNoteEditor.ts # packages/react/package.json

packages/core/package.json

YousefED · 2025-03-03T11:22:38Z

packages/core/src/editor/BlockNoteEditor.ts

@@ -1431,11 +1368,11 @@ export class BlockNoteEditor<
    );
  }

-  public get ForceSelectionVisible() {
-    return this.showSelectionPlugin.ForceSelectionVisible;
+  public getForceSelectionVisible() {


why not use a getter / setter for this? (like we do for "isEditable")?

@matthewlipski can you add a comment?

YousefED · 2025-03-03T11:26:28Z

packages/react/src/components/Comments/FloatingComposerController.tsx

@@ -32,17 +32,18 @@ export const FloatingComposerController = <
  }

  const comments = editor.comments;
+  useEffect(() => {


was this a code style preference to go from:

useEffect(() => { editor.ForceSelectionVisible = !!state?.pendingComment; }, [editor, state?.pendingComment]);

to

useEffect(() => { comments.onUpdate((state) => editor.setForceSelectionVisible(state.pendingComment) ); }, [comments, editor]);

or does it solve a bug?

In any case, we're not unsubscribing from onUpdate so that would need to be fixed I think

YousefED · 2025-03-03T11:27:19Z

tests/src/end-to-end/theming/theming.test.ts

@@ -48,7 +48,8 @@ test.describe("Check Dark Theme is Automatically Applied", () => {
    await page.keyboard.press("ArrowLeft");

    await page.waitForTimeout(500);
-    expect(await page.screenshot()).toMatchSnapshot("dark-link-toolbar.png");
+    // expect(await page.screenshot()).toMatchSnapshot("dark-link-toolbar.png");


dev leftover?

YousefED added 17 commits November 14, 2024 11:23

wip: better liveblocks support

4d6e252

Merge remote-tracking branch 'origin/main' into feature/liveblocks-v2

dcd7c72

misc fixes

c659253

misc

a03d33f

revert minimal

85521df

simplify setup

e43741a

update config

e0c7f0f

fix

d747238

fix

6ce69ea

markview

a3028c1

cleanup

15c7520

Merge remote-tracking branch 'origin/main' into feature/liveblocks-v2

b8a8d49

wip

1b44296

wip

23275a0

wip

721a4e9

wip

e824c42

misc

f2d4bb8

add threadstore tests

434eafa

vercel bot had a problem deploying to Preview – blocknote-website January 16, 2025 13:52 Failure

vercel bot had a problem deploying to Preview – blocknote January 16, 2025 13:54 Failure

YousefED added 2 commits January 16, 2025 15:02

document recommended auth rules

9d35f72

resolve

58ed7c0

vercel bot had a problem deploying to Preview – blocknote January 16, 2025 15:07 Failure

vercel bot had a problem deploying to Preview – blocknote-website January 16, 2025 15:09 Failure

basic userstore impl

b761e1e

vercel bot had a problem deploying to Preview – blocknote January 16, 2025 19:45 Failure

vercel bot had a problem deploying to Preview – blocknote-website January 16, 2025 19:47 Failure

user auth

5f52147

vercel bot had a problem deploying to Preview – blocknote-website January 16, 2025 21:44 Failure

nperez0111 reviewed Feb 27, 2025

View reviewed changes

packages/core/package.json Outdated Show resolved Hide resolved

nperez0111 reviewed Feb 27, 2025

View reviewed changes

packages/react/src/components/Comments/FloatingComposerController.tsx Outdated Show resolved Hide resolved

nperez0111 reviewed Feb 27, 2025

View reviewed changes

Implemented PR feedback

30003d7

vercel bot deployed to Preview – blocknote February 27, 2025 20:56 View deployment

vercel bot deployed to Preview – blocknote-website February 27, 2025 21:03 View deployment

Implemented PR feedback

f1557b1

vercel bot deployed to Preview – blocknote-website February 27, 2025 21:28 View deployment

vercel bot deployed to Preview – blocknote February 27, 2025 21:32 View deployment

matthewlipski marked this pull request as ready for review February 28, 2025 09:38

Updated emoji picker screenshots

a647ec3

vercel bot deployed to Preview – blocknote February 28, 2025 10:01 View deployment

Revert "Updated emoji picker screenshots"

065c74d

This reverts commit a647ec3.

vercel bot deployed to Preview – blocknote-website February 28, 2025 10:35 View deployment

matthewlipski added 2 commits February 28, 2025 11:37

Merge branch 'main' into feature/comments

f26edd3

Updated package-lock.json

ae534b4

vercel bot deployed to Preview – blocknote February 28, 2025 11:00 View deployment

vercel bot deployed to Preview – blocknote-website February 28, 2025 11:07 View deployment

matthewlipski added 4 commits February 28, 2025 17:19

Merge branch 'main' into feature/comments

9a12826

# Conflicts: # docs/pages/docs/editor-basics/setup.mdx # package-lock.json # packages/core/src/editor/BlockNoteEditor.ts # packages/react/package.json

Fixed no locale

828d13e

Updated package-lock.json

46836e5

Added temp test pass

641a6b8

matthewlipski changed the title ~~wip: feat: comments~~ feat: Comments Feb 28, 2025

matthewlipski merged commit 1822208 into main Feb 28, 2025
5 of 6 checks passed

vercel bot deployed to Preview – blocknote-website February 28, 2025 17:01 View deployment

vercel bot deployed to Preview – blocknote February 28, 2025 17:06 View deployment

YousefED commented Mar 3, 2025

View reviewed changes

packages/core/package.json Show resolved Hide resolved

YousefED commented Mar 3, 2025

View reviewed changes

matthewlipski mentioned this pull request Mar 4, 2025

fix: Comments feedback & flaky test #1481

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Comments #1376

feat: Comments #1376

YousefED commented Jan 16, 2025 •

edited

Loading

vercel bot commented Jan 16, 2025 •

edited

Loading

nperez0111 Feb 27, 2025

matthewlipski Feb 28, 2025

nperez0111 Feb 27, 2025

YousefED Mar 3, 2025

YousefED Mar 4, 2025

YousefED Mar 3, 2025

YousefED Mar 3, 2025

feat: Comments #1376

feat: Comments #1376

Conversation

YousefED commented Jan 16, 2025 • edited Loading

ThreadStores

YjsThreadStore

RESTYjsThreadStore

TipTap

LiveBlocks (later)

TODO

Yjs next steps

To fix later

vercel bot commented Jan 16, 2025 • edited Loading

nperez0111 Feb 27, 2025

Choose a reason for hiding this comment

matthewlipski Feb 28, 2025

Choose a reason for hiding this comment

nperez0111 Feb 27, 2025

Choose a reason for hiding this comment

YousefED Mar 3, 2025

Choose a reason for hiding this comment

YousefED Mar 4, 2025

Choose a reason for hiding this comment

YousefED Mar 3, 2025

Choose a reason for hiding this comment

YousefED Mar 3, 2025

Choose a reason for hiding this comment

YousefED commented Jan 16, 2025 •

edited

Loading

vercel bot commented Jan 16, 2025 •

edited

Loading