wip: feat: comments #1376

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

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 26, 2025 5:07pm
blocknote-website	✅ Ready (Inspect)	Visit Preview	Feb 26, 2025 5:07pm

nperez0111 · 2025-02-27T09:42:13Z

packages/ariakit/src/ariakitStyles.css

+}
+
+/* https://ariakit.org/components/hovercard */
+/*.bn-ak-button {*/


nperez0111 · 2025-02-27T09:43:44Z

packages/ariakit/src/style.css

-.bn-toolbar.bn-ak-toolbar {
-  overflow-x: auto;
-  max-width: 100vw;
+.bn-ak-toolbar {


I assume that we don't care about the max-width anymore? That would cause it from overflowing on small screens.

nperez0111 · 2025-02-27T09:45:56Z

packages/core/src/extensions/Comments/CommentsPlugin.ts

+   * Store the positions of all threads in the document.
+   * this can be used later to implement a floating sidebar
+   */
+  threadPositions: Map<string, { from: number; to: number }>;


I'm working on some bugs in the suggestion plugin that will be related to this. It isn't safe to store positions like this. Would likely also need to keep around a relative position as well. But, we can figure this out later

nperez0111 · 2025-02-27T09:49:10Z

packages/core/src/extensions/Comments/CommentsPlugin.ts

+            tr.removeMark(trimmedFrom, trimmedTo, markType);
+            tr.addMark(
+              trimmedFrom,
+              trimmedTo,
+              markType.create({
+                ...mark.attrs,
+                orphan: isOrphan,
+              })
+            );


Can't this just be that you update the mark attr instead of removing & re-applying it?

nvm, I see there isn't an easy API for that. I just remember a step specifically for updating markattrs but isn't exposed on transactions for some reason

nperez0111 · 2025-02-27T09:52:46Z

packages/core/src/extensions/Comments/CommentsPlugin.ts

+
+    editor.onCreate(() => {
+      this.updateMarksFromThreads(this.threadStore.getThreads());
+      editor.onSelectionChange(() => {


Feels weird to register this after the create hook, why not just register in the constructor separately?

nperez0111 · 2025-02-27T09:53:29Z

packages/core/src/extensions/Comments/CommentsPlugin.ts

+    // Note: Plugins are currently not destroyed when the editor is destroyed.
+    // We should unsubscribe from the threadStore when the editor is destroyed.
+    this.threadStore.subscribe(this.updateMarksFromThreads);


Yea, we need an API for this

nperez0111 · 2025-02-27T09:56:40Z

packages/core/package.json

@@ -105,6 +105,7 @@
    "@types/emoji-mart": "^3.0.14",
    "@types/hast": "^3.0.0",
    "@types/uuid": "^8.3.4",
+    "@hocuspocus/provider": "^2.15.2",


I think this is peerOptional no?
https://stackoverflow.com/questions/62047806/how-do-i-set-a-peer-dependency-optional#66228639

TS might care for someone who imports it

nperez0111 · 2025-02-27T10:06:05Z

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

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


This is weird. Can we describe why this is needed, it also feels like it should not be handled by React, because it is being derived from the editor state?

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

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

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

Fixed badge styles on docs

953aefa

vercel bot deployed to Preview – blocknote February 25, 2025 17:26 View deployment

Fixed badge click handler

46101a0

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

vercel bot deployed to Preview – blocknote February 25, 2025 17:44 View deployment

Added remaining UX fixes from Mantine to Ariakit/ShadCN

ab00b5d

vercel bot deployed to Preview – blocknote February 25, 2025 18:42 View deployment

vercel bot deployed to Preview – blocknote-website February 25, 2025 18:49 View deployment

Externalized strings

38a670d

vercel bot deployed to Preview – blocknote February 26, 2025 16:17 View deployment

vercel bot deployed to Preview – blocknote-website February 26, 2025 16:23 View deployment

matthewlipski added 2 commits February 26, 2025 17:28

Small styling fix

8d8ebec

Merge branch 'main' into feature/comments

6744b26

vercel bot deployed to Preview – blocknote-website February 26, 2025 16:34 View deployment

vercel bot deployed to Preview – blocknote February 26, 2025 16:38 View deployment

matthewlipski added 3 commits February 26, 2025 17:38

Small styling fix

a7a5656

Fix lint

ebfb4da

Fixed side menu regression issue

9944ca7

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

vercel bot deployed to Preview – blocknote February 26, 2025 17:07 View deployment

nperez0111 reviewed Feb 27, 2025

View reviewed changes

packages/ariakit/src/ariakitStyles.css

}

/* https://ariakit.org/components/hovercard */

/*.bn-ak-button {*/

Copy link

Contributor

nperez0111 Feb 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Needed?

nperez0111 reviewed Feb 27, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

wip: feat: comments #1376

wip: feat: comments #1376

YousefED commented Jan 16, 2025 •

edited by matthewlipski

Loading

vercel bot commented Jan 16, 2025 •

edited

Loading

nperez0111 Feb 27, 2025

nperez0111 Feb 27, 2025

nperez0111 Feb 27, 2025

nperez0111 Feb 27, 2025

nperez0111 Feb 27, 2025

nperez0111 Feb 27, 2025

nperez0111 Feb 27, 2025

nperez0111 Feb 27, 2025

nperez0111 Feb 27, 2025

nperez0111 Feb 27, 2025

nperez0111 Feb 27, 2025

wip: feat: comments #1376

Are you sure you want to change the base?

wip: feat: comments #1376

Conversation

YousefED commented Jan 16, 2025 • edited by matthewlipski Loading

ThreadStores

YjsThreadStore

RESTYjsThreadStore

TipTap

LiveBlocks (later)

TODO

Yjs next steps

To fix later

vercel bot commented Jan 16, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

YousefED commented Jan 16, 2025 •

edited by matthewlipski

Loading

vercel bot commented Jan 16, 2025 •

edited

Loading