@blocknote/core 0.24.1 → 0.25.0

package/types/src/comments/threadstore/ThreadStore.d.ts

@@ -0,0 +1,121 @@
+import { CommentBody, CommentData, ThreadData } from "../types.js";
+import { ThreadStoreAuth } from "./ThreadStoreAuth.js";
+/**
+ * ThreadStore is an abstract class that defines the interface
+ * to read / add / update / delete threads and comments.
+ */
+export declare abstract class ThreadStore {
+    readonly auth: ThreadStoreAuth;
+    constructor(auth: ThreadStoreAuth);
+    /**
+     * A "thread" in the ThreadStore only contains information about the content
+     * of the thread / comments. It does not contain information about the position.
+     *
+     * This function can be implemented to store the thread in the document (by creating a mark)
+     * If not implemented, default behavior will apply (creating the mark via TipTap)
+     * See CommentsPlugin.ts for more details.
+     */
+    abstract addThreadToDocument?(options: {
+        threadId: string;
+        selection: {
+            prosemirror: {
+                head: number;
+                anchor: number;
+            };
+            yjs: {
+                head: any;
+                anchor: any;
+            };
+        };
+    }): Promise<void>;
+    /**
+     * Creates a new thread with an initial comment.
+     */
+    abstract createThread(options: {
+        initialComment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        metadata?: any;
+    }): Promise<ThreadData>;
+    /**
+     * Adds a comment to a thread.
+     */
+    abstract addComment(options: {
+        comment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        threadId: string;
+    }): Promise<CommentData>;
+    /**
+     * Updates a comment in a thread.
+     */
+    abstract updateComment(options: {
+        comment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        threadId: string;
+        commentId: string;
+    }): Promise<void>;
+    /**
+     * Deletes a comment from a thread.
+     */
+    abstract deleteComment(options: {
+        threadId: string;
+        commentId: string;
+    }): Promise<void>;
+    /**
+     * Deletes a thread.
+     */
+    abstract deleteThread(options: {
+        threadId: string;
+    }): Promise<void>;
+    /**
+     * Marks a thread as resolved.
+     */
+    abstract resolveThread(options: {
+        threadId: string;
+    }): Promise<void>;
+    /**
+     * Marks a thread as unresolved.
+     */
+    abstract unresolveThread(options: {
+        threadId: string;
+    }): Promise<void>;
+    /**
+     * Adds a reaction to a comment.
+     *
+     * Auth: should be possible by anyone with comment access
+     */
+    abstract addReaction(options: {
+        threadId: string;
+        commentId: string;
+        emoji: string;
+    }): Promise<void>;
+    /**
+     * Deletes a reaction from a comment.
+     *
+     * Auth: should be possible by the reaction author
+     */
+    abstract deleteReaction(options: {
+        threadId: string;
+        commentId: string;
+        emoji: string;
+    }): Promise<void>;
+    /**
+     * Retrieve data for a specific thread.
+     */
+    abstract getThread(threadId: string): ThreadData;
+    /**
+     * Retrieve all threads.
+     */
+    abstract getThreads(): Map<string, ThreadData>;
+    /**
+     * Subscribe to changes in the thread store.
+     *
+     * @returns a function to unsubscribe from the thread store
+     */
+    abstract subscribe(cb: (threads: Map<string, ThreadData>) => void): () => void;
+}

package/types/src/comments/threadstore/ThreadStoreAuth.d.ts

@@ -0,0 +1,12 @@
+import { CommentData, ThreadData } from "../types.js";
+export declare abstract class ThreadStoreAuth {
+    abstract canCreateThread(): boolean;
+    abstract canAddComment(thread: ThreadData): boolean;
+    abstract canUpdateComment(comment: CommentData): boolean;
+    abstract canDeleteComment(comment: CommentData): boolean;
+    abstract canDeleteThread(thread: ThreadData): boolean;
+    abstract canResolveThread(thread: ThreadData): boolean;
+    abstract canUnresolveThread(thread: ThreadData): boolean;
+    abstract canAddReaction(comment: CommentData, emoji?: string): boolean;
+    abstract canDeleteReaction(comment: CommentData, emoji?: string): boolean;
+}

package/types/src/comments/threadstore/TipTapThreadStore.d.ts

@@ -0,0 +1,97 @@
+import type { TiptapCollabProvider } from "@hocuspocus/provider";
+import { CommentBody, ThreadData } from "../types.js";
+import { ThreadStore } from "./ThreadStore.js";
+import { ThreadStoreAuth } from "./ThreadStoreAuth.js";
+/**
+ * The `TiptapThreadStore` integrates with Tiptap's collaboration provider for comment management.
+ * You can pass a `TiptapCollabProvider` to the constructor which takes care of storing the comments.
+ *
+ * Under the hood, this actually works similarly to the `YjsThreadStore` implementation. (comments are stored in the Yjs document)
+ */
+export declare class TiptapThreadStore extends ThreadStore {
+    private readonly userId;
+    private readonly provider;
+    constructor(userId: string, provider: TiptapCollabProvider, auth: ThreadStoreAuth);
+    /**
+     * Creates a new thread with an initial comment.
+     */
+    createThread(options: {
+        initialComment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        metadata?: any;
+    }): Promise<ThreadData>;
+    addThreadToDocument: undefined;
+    /**
+     * Adds a comment to a thread.
+     */
+    addComment(options: {
+        comment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        threadId: string;
+    }): Promise<CommentBody>;
+    /**
+     * Updates a comment in a thread.
+     */
+    updateComment(options: {
+        comment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        threadId: string;
+        commentId: string;
+    }): Promise<void>;
+    private tiptapCommentToCommentData;
+    private tiptapThreadToThreadData;
+    /**
+     * Deletes a comment from a thread.
+     */
+    deleteComment(options: {
+        threadId: string;
+        commentId: string;
+    }): Promise<void>;
+    /**
+     * Deletes a thread.
+     */
+    deleteThread(options: {
+        threadId: string;
+    }): Promise<void>;
+    /**
+     * Marks a thread as resolved.
+     */
+    resolveThread(options: {
+        threadId: string;
+    }): Promise<void>;
+    /**
+     * Marks a thread as unresolved.
+     */
+    unresolveThread(options: {
+        threadId: string;
+    }): Promise<void>;
+    /**
+     * Adds a reaction to a comment.
+     *
+     * Auth: should be possible by anyone with comment access
+     */
+    addReaction(options: {
+        threadId: string;
+        commentId: string;
+        emoji: string;
+    }): Promise<void>;
+    /**
+     * Deletes a reaction from a comment.
+     *
+     * Auth: should be possible by the reaction author
+     */
+    deleteReaction(options: {
+        threadId: string;
+        commentId: string;
+        emoji: string;
+    }): Promise<void>;
+    getThread(threadId: string): ThreadData;
+    getThreads(): Map<string, ThreadData>;
+    subscribe(cb: (threads: Map<string, ThreadData>) => void): () => void;
+}

package/types/src/comments/threadstore/yjs/RESTYjsThreadStore.d.ts

@@ -0,0 +1,83 @@
+import * as Y from "yjs";
+import { CommentBody } from "../../types.js";
+import { ThreadStoreAuth } from "../ThreadStoreAuth.js";
+import { YjsThreadStoreBase } from "./YjsThreadStoreBase.js";
+/**
+ * This is a REST-based implementation of the YjsThreadStoreBase.
+ * It Reads data directly from the underlying document (same as YjsThreadStore),
+ * but for Writes, it sends data to a REST API that should:
+ * - check the user has the correct permissions to make the desired changes
+ * - apply the updates to the underlying Yjs document
+ *
+ * (see https://github.com/TypeCellOS/BlockNote-demo-nextjs-hocuspocus)
+ *
+ * The reason we still use the Yjs document as underlying storage is that it makes it easy to
+ * sync updates in real-time to other collaborators.
+ * (but technically, you could also implement a different storage altogether
+ * and not store the thread related data in the Yjs document)
+ */
+export declare class RESTYjsThreadStore extends YjsThreadStoreBase {
+    private readonly BASE_URL;
+    private readonly headers;
+    constructor(BASE_URL: string, headers: Record<string, string>, threadsYMap: Y.Map<any>, auth: ThreadStoreAuth);
+    private doRequest;
+    addThreadToDocument: (options: {
+        threadId: string;
+        selection: {
+            prosemirror: {
+                head: number;
+                anchor: number;
+            };
+            yjs: {
+                head: any;
+                anchor: any;
+            };
+        };
+    }) => Promise<any>;
+    createThread: (options: {
+        initialComment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        metadata?: any;
+    }) => Promise<any>;
+    addComment: (options: {
+        comment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        threadId: string;
+    }) => Promise<any>;
+    updateComment: (options: {
+        comment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        threadId: string;
+        commentId: string;
+    }) => Promise<any>;
+    deleteComment: (options: {
+        threadId: string;
+        commentId: string;
+        softDelete?: boolean;
+    }) => Promise<any>;
+    deleteThread: (options: {
+        threadId: string;
+    }) => Promise<any>;
+    resolveThread: (options: {
+        threadId: string;
+    }) => Promise<any>;
+    unresolveThread: (options: {
+        threadId: string;
+    }) => Promise<any>;
+    addReaction: (options: {
+        threadId: string;
+        commentId: string;
+        emoji: string;
+    }) => Promise<any>;
+    deleteReaction: (options: {
+        threadId: string;
+        commentId: string;
+        emoji: string;
+    }) => Promise<any>;
+}

package/types/src/comments/threadstore/yjs/YjsThreadStore.d.ts

@@ -0,0 +1,79 @@
+import * as Y from "yjs";
+import { CommentBody, ThreadData } from "../../types.js";
+import { ThreadStoreAuth } from "../ThreadStoreAuth.js";
+import { YjsThreadStoreBase } from "./YjsThreadStoreBase.js";
+/**
+ * This is a Yjs-based implementation of the ThreadStore interface.
+ *
+ * It reads and writes thread / comments information directly to the underlying Yjs Document.
+ *
+ * @important While this is the easiest to add to your app, there are two challenges:
+ * - The user needs to be able to write to the Yjs document to store the information.
+ *   So a user without write access to the Yjs document cannot leave any comments.
+ * - Even with write access, the operations are not secure. Unless your Yjs server
+ *   guards against malicious operations, it's technically possible for one user to make changes to another user's comments, etc.
+ *   (even though these options are not visible in the UI, a malicious user can make unauthorized changes to the underlying Yjs document)
+ */
+export declare class YjsThreadStore extends YjsThreadStoreBase {
+    private readonly userId;
+    constructor(userId: string, threadsYMap: Y.Map<any>, auth: ThreadStoreAuth);
+    private transact;
+    createThread: (options: {
+        initialComment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        metadata?: any;
+    }) => Promise<ThreadData>;
+    addThreadToDocument: undefined;
+    addComment: (options: {
+        comment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        threadId: string;
+    }) => Promise<{
+        type: "comment";
+        id: string;
+        userId: string;
+        createdAt: Date;
+        updatedAt: Date;
+        reactions: import("../../types.js").CommentReactionData[];
+        metadata: any;
+    } & {
+        deletedAt?: undefined;
+        body: any;
+    }>;
+    updateComment: (options: {
+        comment: {
+            body: CommentBody;
+            metadata?: any;
+        };
+        threadId: string;
+        commentId: string;
+    }) => Promise<void>;
+    deleteComment: (options: {
+        threadId: string;
+        commentId: string;
+        softDelete?: boolean | undefined;
+    }) => Promise<void>;
+    deleteThread: (options: {
+        threadId: string;
+    }) => Promise<void>;
+    resolveThread: (options: {
+        threadId: string;
+    }) => Promise<void>;
+    unresolveThread: (options: {
+        threadId: string;
+    }) => Promise<void>;
+    addReaction: (options: {
+        threadId: string;
+        commentId: string;
+        emoji: string;
+    }) => Promise<void>;
+    deleteReaction: (options: {
+        threadId: string;
+        commentId: string;
+        emoji: string;
+    }) => Promise<void>;
+}

package/types/src/comments/threadstore/yjs/YjsThreadStore.test.d.ts

@@ -0,0 +1 @@
+export {};

package/types/src/comments/threadstore/yjs/YjsThreadStoreBase.d.ts

@@ -0,0 +1,15 @@
+import * as Y from "yjs";
+import { ThreadData } from "../../types.js";
+import { ThreadStore } from "../ThreadStore.js";
+import { ThreadStoreAuth } from "../ThreadStoreAuth.js";
+/**
+ * This is an abstract class that only implements the READ methods required by the ThreadStore interface.
+ * The data is read from a Yjs Map.
+ */
+export declare abstract class YjsThreadStoreBase extends ThreadStore {
+    protected readonly threadsYMap: Y.Map<any>;
+    constructor(threadsYMap: Y.Map<any>, auth: ThreadStoreAuth);
+    getThread(threadId: string): ThreadData;
+    getThreads(): Map<string, ThreadData>;
+    subscribe(cb: (threads: Map<string, ThreadData>) => void): () => void;
+}

package/types/src/comments/threadstore/yjs/yjsHelpers.d.ts

@@ -0,0 +1,13 @@
+import * as Y from "yjs";
+import { CommentData, ThreadData } from "../../types.js";
+export declare function commentToYMap(comment: CommentData): Y.Map<any>;
+export declare function threadToYMap(thread: ThreadData): Y.Map<unknown>;
+type SingleUserCommentReactionData = {
+    emoji: string;
+    createdAt: Date;
+    userId: string;
+};
+export declare function yMapToReaction(yMap: Y.Map<any>): SingleUserCommentReactionData;
+export declare function yMapToComment(yMap: Y.Map<any>): CommentData;
+export declare function yMapToThread(yMap: Y.Map<any>): ThreadData;
+export {};

package/types/src/comments/types.d.ts

@@ -0,0 +1,109 @@
+/**
+ * The body of a comment. This actually is a BlockNote document (array of blocks)
+ */
+export type CommentBody = any;
+/**
+ * A reaction to a comment.
+ */
+export type CommentReactionData = {
+    /**
+     * The emoji that was reacted to the comment.
+     */
+    emoji: string;
+    /**
+     * The date the first user reacted to the comment with this emoji.
+     */
+    createdAt: Date;
+    /**
+     * The user ids of the users that have reacted to the comment with this emoji
+     */
+    userIds: string[];
+};
+/**
+ * Information about a comment.
+ */
+export type CommentData = {
+    type: "comment";
+    /**
+     * The unique identifier for the comment.
+     */
+    id: string;
+    /**
+     * The user id of the author of the comment.
+     */
+    userId: string;
+    /**
+     * The date when the comment was created.
+     */
+    createdAt: Date;
+    /**
+     * The date when the comment was last updated.
+     */
+    updatedAt: Date;
+    /**
+     * The reactions (emoji reactions) to the comment.
+     */
+    reactions: CommentReactionData[];
+    /**
+     * You can use this store any additional information about the comment.
+     */
+    metadata: any;
+} & ({
+    /**
+     * The date when the comment was deleted. This applies only for "soft deletes",
+     * otherwise the comment is removed entirely.
+     */
+    deletedAt: Date;
+    /**
+     * The body of the comment is undefined if the comment is deleted.
+     */
+    body: undefined;
+} | {
+    /**
+     * In case of a non-deleted comment, this is not set
+     */
+    deletedAt?: never;
+    /**
+     * The body of the comment.
+     */
+    body: CommentBody;
+});
+/**
+ * Information about a thread. A thread holds a list of comments.
+ */
+export type ThreadData = {
+    type: "thread";
+    /**
+     * The unique identifier for the thread.
+     */
+    id: string;
+    /**
+     * The date when the thread was created.
+     */
+    createdAt: Date;
+    /**
+     * The date when the thread was last updated.
+     */
+    updatedAt: Date;
+    /**
+     * The comments in the thread.
+     */
+    comments: CommentData[];
+    /**
+     * Whether the thread has been marked as resolved.
+     */
+    resolved: boolean;
+    /**
+     * The date when the thread was marked as resolved.
+     */
+    resolvedUpdatedAt?: Date;
+    /**
+     * You can use this store any additional information about the thread.
+     */
+    metadata: any;
+    /**
+     * The date when the thread was deleted. (or undefined if it is not deleted)
+     * This only applies for "soft deletes", otherwise the thread is removed entirely.
+     */
+    deletedAt?: Date;
+};