Merge remote-tracking branch 'origin/main' into feature/odt-export

Author: YousefED

.github/workflows/build.yml

@@ -30,13 +30,6 @@ jobs:
             ${{ runner.os }}-build-
             ${{ runner.os }}-
 
-      - name: cache playwright
-        id: playwright-cache
-        uses: actions/cache@v4
-        with:
-          path: ~/.cache/ms-playwright
-          key: pw-new-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
-
       - name: Install Dependencies
         run: npm install
 
@@ -45,40 +38,44 @@ jobs:
 
       - name: Lint packages
         run: npm run lint
-        env:
-          CI: true
 
       - name: Build packages
         run: npm run build
-        env:
-          CI: true
 
       - name: Run unit tests
         run: npm run test
-        env:
-          CI: true
 
-      - name: Run server
-        run: npm run start:built & npx wait-on http://localhost:3000
-        env:
-          CI: true
+      - name: Upload webpack stats artifact (editor)
+        uses: relative-ci/agent-upload-artifact-action@v2
+        with:
+          webpackStatsFile: ./playground/dist/webpack-stats.json
+          artifactName: relative-ci-artifacts-editor
+  playwright:
+    name: "Playwright Tests"
+    runs-on: ubuntu-latest
+    container:
+      image: mcr.microsoft.com/playwright:v1.49.1-noble
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: lts/*
+      - run: apt-get update && apt-get install -y build-essential libcairo2-dev libpango1.0-dev libjpeg-dev libgif-dev librsvg2-dev
+      - name: Install dependencies
+        run: npm ci
 
-      - name: Install Playwright
-        run: npm run install-playwright
+      - name: Build packages
+        run: npm run build
 
-      - name: Run Playwright tests
-        working-directory: ./tests
-        run: npx playwright test
+      - name: Run server and Playwright tests
+        run: |
+          npm run start:built > /dev/null & 
+          npx wait-on http://localhost:3000
+          cd tests && HOME=/root npx playwright test
 
       - uses: actions/upload-artifact@v4
         if: always()
         with:
           name: playwright-report
           path: tests/playwright-report/
           retention-days: 30
-
-      - name: Upload webpack stats artifact (editor)
-        uses: relative-ci/agent-upload-artifact-action@v2
-        with:
-          webpackStatsFile: ./playground/dist/webpack-stats.json
-          artifactName: relative-ci-artifacts-editor

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docs",
-  "version": "0.24.1",
+  "version": "0.24.2",
   "private": true,
   "scripts": {
     "dev": "next dev",
@@ -9,12 +9,12 @@
     "lint": "next lint"
   },
   "dependencies": {
-    "@blocknote/ariakit": "^0.24.1",
-    "@blocknote/core": "^0.24.1",
-    "@blocknote/mantine": "^0.24.1",
-    "@blocknote/react": "^0.24.1",
-    "@blocknote/shadcn": "^0.24.1",
-    "@blocknote/xl-multi-column": "^0.24.1",
+    "@blocknote/ariakit": "^0.24.2",
+    "@blocknote/core": "^0.24.2",
+    "@blocknote/mantine": "^0.24.2",
+    "@blocknote/react": "^0.24.2",
+    "@blocknote/shadcn": "^0.24.2",
+    "@blocknote/xl-multi-column": "^0.24.2",
     "@headlessui/react": "^1.7.18",
     "@heroicons/react": "^2.1.4",
     "@mantine/core": "^7.10.1",

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;
+}
+```