feat: Comments

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

@@ -20,11 +20,26 @@ function useCreateBlockNote(
 
 type BlockNoteEditorOptions = {
   animations?: boolean;
-  tabBehavior?: "prefer-navigate-ui" | "prefer-indent";
-  sideMenuDetection?: "viewport" | "editor";
-  resolveFileUrl?: (file: File) => Promise<string>;
-  resolveUsers?: (user: string) => Promise<UserInfo>;
+  collaboration?: CollaborationOptions;
   comments?: CommentsConfig;
+  defaultStyles?: boolean;
+  dictionary?: Dictionary;
+  disableExtensions?: string[];
+  domAttributes?: Record<string, string>;
+  dropCursor?: (opts: {
+    editor: BlockNoteEditor;
+    color?: string | false;
+    width?: number;
+    class?: string;
+  }) => Plugin;
+  initialContent?: PartialBlock[];
+  resolveFileUrl: (url: string) => Promise<string>
+  schema?: BlockNoteSchema;
+  setIdAttribute?: boolean;
+  sideMenuDetection?: "viewport" | "editor";
+  tabBehavior?: "prefer-navigate-ui" | "prefer-indent"
+  trailingBlock?: boolean;
+  uploadFile?: (file: File) => Promise<string>;
 };
 ```
 
@@ -36,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).
@@ -48,38 +65,22 @@ 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.
 
 `uploadFile`: A function which handles file uploads and eventually returns the URL to the uploaded file. Used for [Image blocks](/docs/editor-basics/default-schema#image).
 
-`tabBehavior`: How Tab key behaves with multiple blocks selected and toolbar open:
-
-- `"prefer-navigate-ui"`: Focus moves to toolbar. User needs to press `Escape` to close toolbar before indenting blocks. Better for keyboard accessibility.
-- `"prefer-indent"`: Indents blocks regardless of toolbar state. Cannot navigate toolbars with keyboard.
-  Defaults to `"prefer-navigate-ui"`.
-
-`sideMenuDetection`: How the side menu detection works:
-
-- `"viewport"`: Shows menu for block next to mouse cursor
-- `"editor"`: Only shows when hovering editor or menu itself
-  Defaults to `"viewport"`.
-
-`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.
-
-`comments`: Configuration for the comments feature, requires a `threadStore`. See [Comments](/docs/collaboration/comments) for more.
-
 **deps:** Dependency array that's internally passed to `useMemo`. A new editor will only be created when this array changes.
 
 <Callout type="info" emoji={"💡"}>

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/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/README.md

@@ -1,3 +1,13 @@
 # Comments & Threads
 
-TODO
+In this example, you can add comments to the document while collaborating with others. You can also pick user accounts with different permissions, as well as react to, reply to, and resolve existing comments.
+
+**Try it out:** Click the "Add comment" button in the [Formatting Toolbar](/docs/ui-components/formatting-toolbar) to add a comment!
+
+**Relevant Docs:**
+
+- [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)
+- [Comments](/docs/collaboration/comments)
+

packages/ariakit/src/popover/Popover.tsx

@@ -45,7 +45,6 @@ export const Popover = (
 ) => {
   const { children, opened, position, ...rest } = props;
 
-  // @ts-ignore TODO
   assertEmpty(rest);
 
   return (

packages/ariakit/src/style.css

@@ -13,7 +13,8 @@
 
 .bn-ak-toolbar {
   height: fit-content;
-  overflow: visible;
+  overflow: scroll;
+  max-width: 100vw;
 }
 
 .bn-toolbar .bn-ak-button {

packages/ariakit/src/toolbar/ToolbarButton.tsx

@@ -27,14 +27,12 @@ export const ToolbarButton = forwardRef<HTMLButtonElement, ToolbarButtonProps>(
       isDisabled,
       onClick,
       label,
+      variant,
       ...rest
     } = props;
 
     // false, because rest props can be added by ariakit when button is used as a trigger
     // assertEmpty in this case is only used at typescript level, not runtime level
-
-    // TODO
-    // @ts-ignore
     assertEmpty(rest, false);
 
     return (
@@ -57,13 +55,6 @@ export const ToolbarButton = forwardRef<HTMLButtonElement, ToolbarButtonProps>(
               onClick={onClick}
               aria-pressed={isSelected}
               data-selected={isSelected ? "true" : undefined}
-              data-test={
-                // @ts-ignore TODO
-                props.mainTooltip.slice(0, 1).toLowerCase() +
-                // @ts-ignore TODO
-                props.mainTooltip.replace(/\s+/g, "").slice(1)
-              }
-              //   size={"xs"}
               disabled={isDisabled || false}
               ref={ref}
               {...rest}>

packages/core/package.json

@@ -105,7 +105,6 @@
     "@types/emoji-mart": "^3.0.14",
     "@types/hast": "^3.0.0",
     "@types/uuid": "^8.3.4",
-    "@hocuspocus/provider": "^2.15.2",
     "eslint": "^8.10.0",
     "jsdom": "^25.0.1",
     "prettier": "^2.7.1",
@@ -116,6 +115,14 @@
     "vite-plugin-eslint": "^1.8.1",
     "vitest": "^2.0.3"
   },
+  "peerDependencies": {
+    "@hocuspocus/provider": "^2.15.2"
+  },
+  "peerDependenciesMeta": {
+    "hocuspocus/provider": {
+      "optional": true
+    }
+  },
   "eslintConfig": {
     "extends": [
       "../../.eslintrc.js"

packages/core/src/editor/BlockNoteEditor.ts

@@ -125,75 +125,6 @@ export type BlockNoteEditorOptions<
    */
   animations?: boolean;
 
-  /**
-   * Disable internal extensions (based on keys / extension name)
-   */
-  disableExtensions: string[];
-
-  /**
-   * A dictionary object containing translations for the editor.
-   */
-  dictionary?: Dictionary & Record<string, any>;
-
-  /**
-   * @deprecated, provide placeholders via dictionary instead
-   */
-  placeholders: Record<
-    string | "default" | "emptyDocument",
-    string | undefined
-  >;
-
-  /**
-   * An object containing attributes that should be added to HTML elements of the editor.
-   *
-   * @example { editor: { class: "my-editor-class" } }
-   */
-  domAttributes: Partial<BlockNoteDOMAttributes>;
-
-  /**
-   * The content that should be in the editor when it's created, represented as an array of partial block objects.
-   */
-  initialContent: PartialBlock<
-    NoInfer<BSchema>,
-    NoInfer<ISchema>,
-    NoInfer<SSchema>
-  >[];
-  /**
-   * Use default BlockNote font and reset the styles of <p> <li> <h1> elements etc., that are used in BlockNote.
-   *
-   * @default true
-   */
-  defaultStyles: boolean;
-
-  schema: BlockNoteSchema<BSchema, ISchema, SSchema>;
-
-  /**
-   * The `uploadFile` method is what the editor uses when files need to be uploaded (for example when selecting an image to upload).
-   * This method should set when creating the editor as this is application-specific.
-   *
-   * `undefined` means the application doesn't support file uploads.
-   *
-   * @param file The file that should be uploaded.
-   * @returns The URL of the uploaded file OR an object containing props that should be set on the file block (such as an id)
-   */
-  uploadFile: (
-    file: File,
-    blockId?: string
-  ) => Promise<string | Record<string, any>>;
-
-  /**
-   * Resolve a URL of a file block to one that can be displayed or downloaded. This can be used for creating authenticated URL or
-   * implementing custom protocols / schemes
-   * @returns The URL that's
-   */
-  resolveFileUrl: (url: string) => Promise<string>;
-
-  resolveUsers: (userIds: string[]) => Promise<User[]>;
-
-  // TODO: decide "comments" or "threads"?
-  comments: {
-    threadStore: ThreadStore;
-  };
   /**
    * When enabled, allows for collaboration between multiple users.
    */
@@ -226,6 +157,10 @@ export type BlockNoteEditorOptions<
     showCursorLabels?: "always" | "activity";
   };
 
+  comments: {
+    threadStore: ThreadStore;
+  };
+
   /**
    * Use default BlockNote font and reset the styles of <p> <li> <h1> elements etc., that are used in BlockNote.
    *
@@ -285,6 +220,8 @@ export type BlockNoteEditorOptions<
    */
   resolveFileUrl: (url: string) => Promise<string>;
 
+  resolveUsers: (userIds: string[]) => Promise<User[]>;
+
   schema: BlockNoteSchema<BSchema, ISchema, SSchema>;
 
   /**
@@ -1431,11 +1368,11 @@ export class BlockNoteEditor<
     );
   }
 
-  public get ForceSelectionVisible() {
-    return this.showSelectionPlugin.ForceSelectionVisible;
+  public getForceSelectionVisible() {
+    return this.showSelectionPlugin.getEnabled();
   }
 
-  public set ForceSelectionVisible(forceSelectionVisible: boolean) {
-    this.showSelectionPlugin.ForceSelectionVisible = forceSelectionVisible;
+  public setForceSelectionVisible(forceSelectionVisible: boolean) {
+    this.showSelectionPlugin.setEnabled(forceSelectionVisible);
   }
 }

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

@@ -147,6 +147,7 @@ export class CommentsPlugin extends EventEmitter<any> {
     this.threadStore.subscribe(this.updateMarksFromThreads);
 
     editor.onCreate(() => {
+      // Need to wait for TipTap editor state to be initialized
       this.updateMarksFromThreads(this.threadStore.getThreads());
       editor.onSelectionChange(() => {
         if (this.pendingComment) {