@blocknote/core 0.24.2 → 0.25.0

package/src/api/testUtil/partialBlockTestUtil.ts

@@ -1,7 +1,12 @@
 import { Block, PartialBlock } from "../../blocks/defaultBlocks.js";
 import { BlockNoteSchema } from "../../editor/BlockNoteSchema.js";
 import UniqueID from "../../extensions/UniqueID/UniqueID.js";
-import { BlockSchema, TableContent } from "../../schema/blocks/types.js";
+import {
+  BlockSchema,
+  PartialTableCell,
+  TableCell,
+  TableContent,
+} from "../../schema/blocks/types.js";
 import {
   InlineContent,
   InlineContentSchema,
@@ -28,8 +33,16 @@ function textShorthandToStyledText(
 }
 
 function partialContentToInlineContent(
-  content: PartialInlineContent<any, any> | TableContent<any> | undefined
-): InlineContent<any, any>[] | TableContent<any> | undefined {
+  content:
+    | PartialInlineContent<any, any>
+    | PartialTableCell<any, any>
+    | TableContent<any>
+    | undefined
+):
+  | InlineContent<any, any>[]
+  | TableContent<any>
+  | TableCell<any, any>
+  | undefined {
   if (typeof content === "string") {
     return textShorthandToStyledText(content);
   }
@@ -59,6 +72,8 @@ function partialContentToInlineContent(
     return {
       type: "tableContent",
       columnWidths: content.columnWidths,
+      headerRows: content.headerRows,
+      headerCols: content.headerCols,
       rows: content.rows.map((row) => ({
         ...row,
         cells: row.cells.map(
@@ -66,6 +81,18 @@ function partialContentToInlineContent(
         ),
       })),
     };
+  } else if (content?.type === "tableCell") {
+    return {
+      type: "tableCell",
+      content: partialContentToInlineContent(content.content) as any[],
+      props: {
+        backgroundColor: content.props?.backgroundColor ?? "default",
+        textColor: content.props?.textColor ?? "default",
+        textAlignment: content.props?.textAlignment ?? "left",
+        colspan: content.props?.colspan ?? 1,
+        rowspan: content.props?.rowspan ?? 1,
+      },
+    } satisfies TableCell<any, any>;
   }
 
   return content;
@@ -103,7 +130,13 @@ export function partialBlockToBlockForTesting<
       contentType === "inline"
         ? []
         : contentType === "table"
-        ? { type: "tableContent", columnWidths: [], rows: [] }
+        ? {
+            type: "tableContent",
+            columnWidths: undefined,
+            headerRows: undefined,
+            headerCols: undefined,
+            rows: [],
+          }
         : (undefined as any),
     children: [] as any,
     ...partialBlock,
@@ -131,6 +164,8 @@ export function partialBlockToBlockForTesting<
         content?.columnWidths ||
         content?.rows[0]?.cells.map(() => undefined) ||
         [],
+      headerRows: content?.headerRows || undefined,
+      headerCols: content?.headerCols || undefined,
       rows:
         content?.rows.map((row) => ({
           cells: row.cells.map((cell) => partialContentToInlineContent(cell)),

package/src/blocks/TableBlockContent/TableBlockContent.ts

@@ -1,4 +1,3 @@
-import { Node } from "@tiptap/core";
 import { TableCell } from "@tiptap/extension-table-cell";
 import { TableHeader } from "@tiptap/extension-table-header";
 import { TableRow } from "@tiptap/extension-table-row";
@@ -102,12 +101,12 @@ export const TableBlockContent = createStronglyTypedTiptapNode({
       return new BlockNoteTableView(node, EMPTY_CELL_WIDTH, {
         ...(this.options.domAttributes?.blockContent || {}),
         ...HTMLAttributes,
-      }) as NodeView;
+      }) as NodeView; // needs cast, tiptap types (wrongly) doesn't support return tableview here
     };
   },
 });
 
-const TableParagraph = Node.create({
+const TableParagraph = createStronglyTypedTiptapNode({
   name: "tableParagraph",
   group: "tableContent",
   content: "inline*",
@@ -160,10 +159,17 @@ export const Table = createBlockSpecFromStronglyTypedTiptapNode(
     TableExtension,
     TableParagraph,
     TableHeader.extend({
-      content: "tableContent",
+      /**
+       * We allow table headers and cells to have multiple tableContent nodes because
+       * when merging cells, prosemirror-tables will concat the contents of the cells naively.
+       * This would cause that content to overflow into other cells when prosemirror tries to enforce the cell structure.
+       *
+       * So, we manually fix this up when reading back in the `nodeToBlock` and only ever place a single tableContent back into the cell.
+       */
+      content: "tableContent+",
     }),
     TableCell.extend({
-      content: "tableContent",
+      content: "tableContent+",
     }),
     TableRow,
   ]

package/src/blocks/defaultBlockTypeGuards.ts

@@ -1,3 +1,4 @@
+import { CellSelection } from "prosemirror-tables";
 import type { BlockNoteEditor } from "../editor/BlockNoteEditor.js";
 import {
   BlockFromConfig,
@@ -14,6 +15,7 @@ import {
   defaultInlineContentSchema,
 } from "./defaultBlocks.js";
 import { defaultProps } from "./defaultProps.js";
+import { Selection } from "prosemirror-state";
 
 export function checkDefaultBlockTypeInSchema<
   BlockType extends keyof DefaultBlockSchema,
@@ -159,3 +161,9 @@ export function checkBlockHasDefaultProp<
 > {
   return checkBlockTypeHasDefaultProp(prop, block.type, editor);
 }
+
+export function isTableCellSelection(
+  selection: Selection
+): selection is CellSelection {
+  return selection instanceof CellSelection;
+}

package/src/comments/index.ts

@@ -0,0 +1,9 @@
+export * from "./models/User.js";
+export * from "./threadstore/DefaultThreadStoreAuth.js";
+export * from "./threadstore/ThreadStore.js";
+export * from "./threadstore/ThreadStoreAuth.js";
+export * from "./threadstore/TipTapThreadStore.js";
+export * from "./threadstore/yjs/RESTYjsThreadStore.js";
+export * from "./threadstore/yjs/YjsThreadStore.js";
+export * from "./threadstore/yjs/YjsThreadStoreBase.js";
+export * from "./types.js";

package/src/comments/models/User.ts

@@ -0,0 +1,8 @@
+/**
+ * A collaborator of the document.
+ */
+export type User = {
+  id: string;
+  username: string;
+  avatarUrl: string;
+};

package/src/comments/threadstore/DefaultThreadStoreAuth.ts

@@ -0,0 +1,106 @@
+import { CommentData, ThreadData } from "../types.js";
+import { ThreadStoreAuth } from "./ThreadStoreAuth.js";
+
+/*
+ * The DefaultThreadStoreAuth class defines the authorization rules for interacting with comments.
+ * We take a role ("comment" or "editor") and implement the rules.
+ *
+ * This class is then used in the UI to show / hide specific interactions.
+ *
+ * Rules:
+ * - View-only users should not be able to see any comments
+ * - Comment-only users and editors can:
+ * - - create new comments / replies / reactions
+ * - - edit / delete their own comments / reactions
+ * - - resolve / unresolve threads
+ * - Editors can also delete any comment or thread
+ */
+export class DefaultThreadStoreAuth extends ThreadStoreAuth {
+  constructor(
+    private readonly userId: string,
+    private readonly role: "comment" | "editor"
+  ) {
+    super();
+  }
+
+  /**
+   * Auth: should be possible by anyone with comment access
+   */
+  canCreateThread(): boolean {
+    return true;
+  }
+
+  /**
+   * Auth: should be possible by anyone with comment access
+   */
+  canAddComment(_thread: ThreadData): boolean {
+    return true;
+  }
+
+  /**
+   * Auth: should only be possible by the comment author
+   */
+  canUpdateComment(comment: CommentData): boolean {
+    return comment.userId === this.userId;
+  }
+
+  /**
+   * Auth: should be possible by the comment author OR an editor of the document
+   */
+  canDeleteComment(comment: CommentData): boolean {
+    return comment.userId === this.userId || this.role === "editor";
+  }
+
+  /**
+   * Auth: should only be possible by an editor of the document
+   */
+  canDeleteThread(_thread: ThreadData): boolean {
+    return this.role === "editor";
+  }
+
+  /**
+   * Auth: should be possible by anyone with comment access
+   */
+  canResolveThread(_thread: ThreadData): boolean {
+    return true;
+  }
+
+  /**
+   * Auth: should be possible by anyone with comment access
+   */
+  canUnresolveThread(_thread: ThreadData): boolean {
+    return true;
+  }
+
+  /**
+   * Auth: should be possible by anyone with comment access
+   *
+   * Note: will also check if the user has already reacted with the same emoji. TBD: is that a nice design or should this responsibility be outside of auth?
+   */
+  canAddReaction(comment: CommentData, emoji?: string): boolean {
+    if (!emoji) {
+      return true;
+    }
+
+    return !comment.reactions.some(
+      (reaction) =>
+        reaction.emoji === emoji && reaction.userIds.includes(this.userId)
+    );
+  }
+
+  /**
+   * Auth: should be possible by anyone with comment access
+   *
+   * Note: will also check if the user has already reacted with the same emoji. TBD: is that a nice design or should this responsibility be outside of auth?
+   */
+  canDeleteReaction(comment: CommentData, emoji?: string): boolean {
+    if (!emoji) {
+      return true;
+    }
+
+    return comment.reactions.some(
+      (reaction) =>
+        reaction.emoji === emoji && reaction.userIds.includes(this.userId)
+    );
+  }
+}

package/src/comments/threadstore/ThreadStore.ts

@@ -0,0 +1,134 @@
+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 abstract class ThreadStore {
+  public readonly auth: ThreadStoreAuth;
+
+  constructor(auth: ThreadStoreAuth) {
+    this.auth = auth;
+  }
+
+  /**
+   * 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/src/comments/threadstore/ThreadStoreAuth.ts

@@ -0,0 +1,13 @@
+import { CommentData, ThreadData } from "../types.js";
+
+export 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/src/comments/threadstore/TipTapThreadStore.ts

@@ -0,0 +1,292 @@
+import type {
+  TCollabComment,
+  TCollabThread,
+  TiptapCollabProvider,
+} from "@hocuspocus/provider";
+import {
+  CommentBody,
+  CommentData,
+  CommentReactionData,
+  ThreadData,
+} from "../types.js";
+import { ThreadStore } from "./ThreadStore.js";
+import { ThreadStoreAuth } from "./ThreadStoreAuth.js";
+
+type ReactionAsTiptapData = {
+  emoji: string;
+  createdAt: number;
+  userId: string;
+};
+
+/**
+ * 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 class TiptapThreadStore extends ThreadStore {
+  constructor(
+    private readonly userId: string,
+    private readonly provider: TiptapCollabProvider,
+    auth: ThreadStoreAuth // TODO: use?
+  ) {
+    super(auth);
+  }
+
+  /**
+   * Creates a new thread with an initial comment.
+   */
+  public async createThread(options: {
+    initialComment: {
+      body: CommentBody;
+      metadata?: any;
+    };
+    metadata?: any;
+  }): Promise<ThreadData> {
+    let thread = this.provider.createThread({
+      data: options.metadata,
+    });
+
+    thread = this.provider.addComment(thread.id, {
+      content: options.initialComment.body,
+      data: {
+        metadata: options.initialComment.metadata,
+        userId: this.userId,
+      },
+    });
+
+    return this.tiptapThreadToThreadData(thread);
+  }
+
+  // TipTapThreadStore does not support addThreadToDocument
+  public addThreadToDocument = undefined;
+
+  /**
+   * Adds a comment to a thread.
+   */
+  public async addComment(options: {
+    comment: {
+      body: CommentBody;
+      metadata?: any;
+    };
+    threadId: string;
+  }): Promise<CommentBody> {
+    const thread = this.provider.addComment(options.threadId, {
+      content: options.comment.body,
+      data: {
+        metadata: options.comment.metadata,
+        userId: this.userId,
+      },
+    });
+
+    return this.tiptapCommentToCommentData(
+      thread.comments[thread.comments.length - 1]
+    );
+  }
+
+  /**
+   * Updates a comment in a thread.
+   */
+  public async updateComment(options: {
+    comment: {
+      body: CommentBody;
+      metadata?: any;
+    };
+    threadId: string;
+    commentId: string;
+  }) {
+    const comment = this.provider.getThreadComment(
+      options.threadId,
+      options.commentId,
+      true
+    );
+
+    if (!comment) {
+      throw new Error("Comment not found");
+    }
+
+    this.provider.updateComment(options.threadId, options.commentId, {
+      content: options.comment.body,
+      data: {
+        ...comment.data,
+        metadata: options.comment.metadata,
+      },
+    });
+  }
+
+  private tiptapCommentToCommentData(comment: TCollabComment): CommentData {
+    const reactions: CommentReactionData[] = [];
+
+    for (const reaction of (comment.data?.reactions ||
+      []) as ReactionAsTiptapData[]) {
+      const existingReaction = reactions.find(
+        (r) => r.emoji === reaction.emoji
+      );
+      if (existingReaction) {
+        existingReaction.userIds.push(reaction.userId);
+        existingReaction.createdAt = new Date(
+          Math.min(existingReaction.createdAt.getTime(), reaction.createdAt)
+        );
+      } else {
+        reactions.push({
+          emoji: reaction.emoji,
+          createdAt: new Date(reaction.createdAt),
+          userIds: [reaction.userId],
+        });
+      }
+    }
+
+    return {
+      type: "comment",
+      id: comment.id,
+      body: comment.content,
+      metadata: comment.data?.metadata,
+      userId: comment.data?.userId,
+      createdAt: new Date(comment.createdAt),
+      updatedAt: new Date(comment.updatedAt),
+      reactions,
+    };
+  }
+
+  private tiptapThreadToThreadData(thread: TCollabThread): ThreadData {
+    return {
+      type: "thread",
+      id: thread.id,
+      comments: thread.comments.map((comment) =>
+        this.tiptapCommentToCommentData(comment)
+      ),
+      resolved: !!thread.resolvedAt,
+      metadata: thread.data?.metadata,
+      createdAt: new Date(thread.createdAt),
+      updatedAt: new Date(thread.updatedAt),
+    };
+  }
+
+  /**
+   * Deletes a comment from a thread.
+   */
+  public async deleteComment(options: { threadId: string; commentId: string }) {
+    this.provider.deleteComment(options.threadId, options.commentId);
+  }
+
+  /**
+   * Deletes a thread.
+   */
+  public async deleteThread(options: { threadId: string }) {
+    this.provider.deleteThread(options.threadId);
+  }
+
+  /**
+   * Marks a thread as resolved.
+   */
+  public async resolveThread(options: { threadId: string }) {
+    this.provider.updateThread(options.threadId, {
+      resolvedAt: new Date().toISOString(),
+    });
+  }
+
+  /**
+   * Marks a thread as unresolved.
+   */
+  public async unresolveThread(options: { threadId: string }) {
+    this.provider.updateThread(options.threadId, {
+      resolvedAt: null,
+    });
+  }
+
+  /**
+   * Adds a reaction to a comment.
+   *
+   * Auth: should be possible by anyone with comment access
+   */
+  public async addReaction(options: {
+    threadId: string;
+    commentId: string;
+    emoji: string;
+  }) {
+    const comment = this.provider.getThreadComment(
+      options.threadId,
+      options.commentId,
+      true
+    );
+
+    if (!comment) {
+      throw new Error("Comment not found");
+    }
+
+    this.provider.updateComment(options.threadId, options.commentId, {
+      data: {
+        ...comment.data,
+        reactions: [
+          ...((comment.data?.reactions || []) as ReactionAsTiptapData[]),
+          {
+            emoji: options.emoji,
+            createdAt: Date.now(),
+            userId: this.userId,
+          },
+        ],
+      },
+    });
+  }
+
+  /**
+   * Deletes a reaction from a comment.
+   *
+   * Auth: should be possible by the reaction author
+   */
+  public async deleteReaction(options: {
+    threadId: string;
+    commentId: string;
+    emoji: string;
+  }) {
+    const comment = this.provider.getThreadComment(
+      options.threadId,
+      options.commentId,
+      true
+    );
+
+    if (!comment) {
+      throw new Error("Comment not found");
+    }
+
+    this.provider.updateComment(options.threadId, options.commentId, {
+      data: {
+        ...comment.data,
+        reactions: (
+          (comment.data?.reactions || []) as ReactionAsTiptapData[]
+        ).filter(
+          (reaction) =>
+            reaction.emoji !== options.emoji && reaction.userId !== this.userId
+        ),
+      },
+    });
+  }
+
+  public getThread(threadId: string): ThreadData {
+    const thread = this.provider.getThread(threadId);
+
+    if (!thread) {
+      throw new Error("Thread not found");
+    }
+
+    return this.tiptapThreadToThreadData(thread);
+  }
+
+  public getThreads(): Map<string, ThreadData> {
+    return new Map(
+      this.provider
+        .getThreads()
+        .map((thread) => [thread.id, this.tiptapThreadToThreadData(thread)])
+    );
+  }
+
+  public subscribe(cb: (threads: Map<string, ThreadData>) => void): () => void {
+    const newCb = () => {
+      cb(this.getThreads());
+    };
+    this.provider.watchThreads(newCb);
+    return () => {
+      this.provider.unwatchThreads(newCb);
+    };
+  }
+}