@blocknote/core 0.24.2 → 0.25.1

package/src/editor/BlockNoteEditor.ts

@@ -3,7 +3,9 @@ import {
   EditorOptions,
   Extension,
   getSchema,
+  isNodeSelection,
   Mark,
+  posToDOMRect,
   Node as TipTapNode,
 } from "@tiptap/core";
 import { Node, Schema } from "prosemirror-model";
@@ -49,9 +51,11 @@ import {
   DefaultStyleSchema,
   PartialBlock,
 } from "../blocks/defaultBlocks.js";
+import type { CommentsPlugin } from "../extensions/Comments/CommentsPlugin.js";
 import { FilePanelProsemirrorPlugin } from "../extensions/FilePanel/FilePanelPlugin.js";
 import { FormattingToolbarProsemirrorPlugin } from "../extensions/FormattingToolbar/FormattingToolbarPlugin.js";
 import { LinkToolbarProsemirrorPlugin } from "../extensions/LinkToolbar/LinkToolbarPlugin.js";
+import { ShowSelectionPlugin } from "../extensions/ShowSelection/ShowSelectionPlugin.js";
 import { SideMenuProsemirrorPlugin } from "../extensions/SideMenu/SideMenuPlugin.js";
 import { SuggestionMenuProseMirrorPlugin } from "../extensions/SuggestionMenu/SuggestionPlugin.js";
 import { TableHandlesProsemirrorPlugin } from "../extensions/TableHandles/TableHandlesPlugin.js";
@@ -90,10 +94,13 @@ import { en } from "../i18n/locales/index.js";
 import { Plugin, Transaction } from "@tiptap/pm/state";
 import { dropCursor } from "prosemirror-dropcursor";
 import { EditorView } from "prosemirror-view";
+import { ySyncPluginKey } from "y-prosemirror";
 import { createInternalHTMLSerializer } from "../api/exporters/html/internalHTMLSerializer.js";
 import { inlineContentToNodes } from "../api/nodeConversions/blockToNode.js";
 import { nodeToBlock } from "../api/nodeConversions/nodeToBlock.js";
+import type { ThreadStore, User } from "../comments/index.js";
 import "../style.css";
+import { EventEmitter } from "../util/EventEmitter.js";
 
 export type BlockNoteExtensionFactory = (
   editor: BlockNoteEditor<any, any, any>
@@ -117,69 +124,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>;
-
   /**
    * When enabled, allows for collaboration between multiple users.
    */
@@ -212,26 +156,72 @@ export type BlockNoteEditorOptions<
     showCursorLabels?: "always" | "activity";
   };
 
+  comments: {
+    threadStore: ThreadStore;
+  };
+
   /**
-   * additional tiptap options, undocumented
+   * Use default BlockNote font and reset the styles of <p> <li> <h1> elements etc., that are used in BlockNote.
+   *
+   * @default true
    */
-  _tiptapOptions: Partial<EditorOptions>;
+  defaultStyles: boolean;
 
   /**
-   * (experimental) add extra prosemirror plugins or tiptap extensions to the editor
+   * A dictionary object containing translations for the editor.
    */
-  _extensions: Record<string, BlockNoteExtension | BlockNoteExtensionFactory>;
+  dictionary?: Dictionary & Record<string, any>;
 
-  trailingBlock?: boolean;
+  /**
+   * Disable internal extensions (based on keys / extension name)
+   */
+  disableExtensions: string[];
 
   /**
-   * Boolean indicating whether the editor is in headless mode.
-   * Headless mode means we can use features like importing / exporting blocks,
-   * but there's no underlying editor (UI) instantiated.
+   * An object containing attributes that should be added to HTML elements of the editor.
    *
-   * You probably don't need to set this manually, but use the `server-util` package instead that uses this option internally
+   * @example { editor: { class: "my-editor-class" } }
    */
-  _headless: boolean;
+  domAttributes: Partial<BlockNoteDOMAttributes>;
+
+  dropCursor?: (opts: {
+    editor: BlockNoteEditor<
+      NoInfer<BSchema>,
+      NoInfer<ISchema>,
+      NoInfer<SSchema>
+    >;
+    color?: string | false;
+    width?: number;
+    class?: string;
+  }) => Plugin;
+
+  /**
+   * 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>
+  >[];
+
+  /**
+   * @deprecated, provide placeholders via dictionary instead
+   */
+  placeholders: Record<
+    string | "default" | "emptyDocument",
+    string | undefined
+  >;
+
+  /**
+   * 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[]>;
+
+  schema: BlockNoteSchema<BSchema, ISchema, SSchema>;
 
   /**
    * A flag indicating whether to set an HTML ID for every block
@@ -243,7 +233,14 @@ export type BlockNoteEditorOptions<
    */
   setIdAttribute?: boolean;
 
-  dropCursor?: (opts: any) => Plugin;
+  /**
+   * The detection mode for showing the side menu - "viewport" always shows the
+   * side menu for the block next to the mouse cursor, while "editor" only shows
+   * it when hovering the editor or the side menu itself.
+   *
+   * @default "viewport"
+   */
+  sideMenuDetection: "viewport" | "editor";
 
   /**
    Select desired behavior when pressing `Tab` (or `Shift-Tab`). Specifically,
@@ -261,13 +258,69 @@ export type BlockNoteEditorOptions<
   tabBehavior: "prefer-navigate-ui" | "prefer-indent";
 
   /**
-   * The detection mode for showing the side menu - "viewport" always shows the
-   * side menu for the block next to the mouse cursor, while "editor" only shows
-   * it when hovering the editor or the side menu itself.
+   * Allows enabling / disabling features of tables.
+   */
+  tables?: {
+    /**
+     * Whether to allow splitting and merging cells within a table.
+     *
+     * @default false
+     */
+    splitCells?: boolean;
+    /**
+     * Whether to allow changing the background color of cells.
+     *
+     * @default false
+     */
+    cellBackgroundColor?: boolean;
+    /**
+     * Whether to allow changing the text color of cells.
+     *
+     * @default false
+     */
+    cellTextColor?: boolean;
+    /**
+     * Whether to allow changing cells into headers.
+     *
+     * @default false
+     */
+    headers?: boolean;
+  };
+
+  trailingBlock?: boolean;
+
+  /**
+   * 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.
    *
-   * @default "viewport"
+   * `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)
    */
-  sideMenuDetection: "viewport" | "editor";
+  uploadFile: (
+    file: File,
+    blockId?: string
+  ) => Promise<string | Record<string, any>>;
+
+  /**
+   * additional tiptap options, undocumented
+   */
+  _tiptapOptions: Partial<EditorOptions>;
+
+  /**
+   * (experimental) add extra prosemirror plugins or tiptap extensions to the editor
+   */
+  _extensions: Record<string, BlockNoteExtension | BlockNoteExtensionFactory>;
+
+  /**
+   * Boolean indicating whether the editor is in headless mode.
+   * Headless mode means we can use features like importing / exporting blocks,
+   * but there's no underlying editor (UI) instantiated.
+   *
+   * You probably don't need to set this manually, but use the `server-util` package instead that uses this option internally
+   */
+  _headless: boolean;
 };
 
 const blockNoteTipTapOptions = {
@@ -280,8 +333,13 @@ export class BlockNoteEditor<
   BSchema extends BlockSchema = DefaultBlockSchema,
   ISchema extends InlineContentSchema = DefaultInlineContentSchema,
   SSchema extends StyleSchema = DefaultStyleSchema
-> {
-  private readonly _pmSchema: Schema;
+> extends EventEmitter<{
+  create: void;
+}> {
+  /**
+   * The underlying prosemirror schema
+   */
+  public readonly pmSchema: Schema;
 
   /**
    * extensions that are added to the editor, can be tiptap extensions or prosemirror plugins
@@ -352,6 +410,9 @@ export class BlockNoteEditor<
     ISchema,
     SSchema
   >;
+  public readonly comments?: CommentsPlugin;
+
+  private readonly showSelectionPlugin: ShowSelectionPlugin;
 
   /**
    * The `uploadFile` method is what the editor uses when files need to be uploaded (for example when selecting an image to upload).
@@ -370,10 +431,18 @@ export class BlockNoteEditor<
   private onUploadEndCallbacks: ((blockId?: string) => void)[] = [];
 
   public readonly resolveFileUrl?: (url: string) => Promise<string>;
-
-  public get pmSchema() {
-    return this._pmSchema;
-  }
+  public readonly resolveUsers?: (userIds: string[]) => Promise<User[]>;
+  /**
+   * Editor settings
+   */
+  public readonly settings: {
+    tables: {
+      splitCells: boolean;
+      cellBackgroundColor: boolean;
+      cellTextColor: boolean;
+      headers: boolean;
+    };
+  };
 
   public static create<
     BSchema extends BlockSchema = DefaultBlockSchema,
@@ -386,6 +455,7 @@ export class BlockNoteEditor<
   protected constructor(
     protected readonly options: Partial<BlockNoteEditorOptions<any, any, any>>
   ) {
+    super();
     const anyOpts = options as any;
     if (anyOpts.onEditorContentChange) {
       throw new Error(
@@ -412,6 +482,14 @@ export class BlockNoteEditor<
     }
 
     this.dictionary = options.dictionary || en;
+    this.settings = {
+      tables: {
+        splitCells: options?.tables?.splitCells ?? false,
+        cellBackgroundColor: options?.tables?.cellBackgroundColor ?? false,
+        cellTextColor: options?.tables?.cellTextColor ?? false,
+        headers: options?.tables?.headers ?? false,
+      },
+    };
 
     // apply defaults
     const newOptions = {
@@ -425,6 +503,12 @@ export class BlockNoteEditor<
       },
     };
 
+    if (newOptions.comments && !newOptions.resolveUsers) {
+      throw new Error("resolveUsers is required when using comments");
+    }
+
+    this.resolveUsers = newOptions.resolveUsers;
+
     // @ts-ignore
     this.schema = newOptions.schema;
     this.blockImplementations = newOptions.schema.blockSpecs;
@@ -447,6 +531,7 @@ export class BlockNoteEditor<
       placeholders: newOptions.placeholders,
       tabBehavior: newOptions.tabBehavior,
       sideMenuDetection: newOptions.sideMenuDetection || "viewport",
+      comments: newOptions.comments,
     });
 
     // add extensions from _tiptapOptions
@@ -469,6 +554,8 @@ export class BlockNoteEditor<
     this.suggestionMenus = this.extensions["suggestionMenus"] as any;
     this.filePanel = this.extensions["filePanel"] as any;
     this.tableHandles = this.extensions["tableHandles"] as any;
+    this.comments = this.extensions["comments"] as any;
+    this.showSelectionPlugin = this.extensions["showSelection"] as any;
 
     if (newOptions.uploadFile) {
       const uploadFile = newOptions.uploadFile;
@@ -500,6 +587,12 @@ export class BlockNoteEditor<
       );
     }
 
+    if (newOptions.comments && !collaborationEnabled) {
+      throw new Error(
+        "Comments are only supported when collaboration is enabled, please set the collaboration option"
+      );
+    }
+
     const initialContent =
       newOptions.initialContent ||
       (collaborationEnabled
@@ -579,17 +672,18 @@ export class BlockNoteEditor<
         view: any;
         contentComponent: any;
       };
-      this._pmSchema = this._tiptapEditor.schema;
+      this.pmSchema = this._tiptapEditor.schema;
     } else {
       // In headless mode, we don't instantiate an underlying TipTap editor,
       // but we still need the schema
-      this._pmSchema = getSchema(tiptapOptions.extensions!);
+      this.pmSchema = getSchema(tiptapOptions.extensions!);
     }
+    this.emit("create");
   }
 
-  dispatch(tr: Transaction) {
+  dispatch = (tr: Transaction) => {
     this._tiptapEditor.dispatch(tr);
-  }
+  };
 
   /**
    * Mount the editor to a parent DOM element. Call mount(undefined) to clean up
@@ -603,10 +697,20 @@ export class BlockNoteEditor<
     this._tiptapEditor.mount(parentElement, contentComponent);
   };
 
+  /**
+   * Get the underlying prosemirror view
+   */
   public get prosemirrorView() {
     return this._tiptapEditor.view;
   }
 
+  /**
+   * Get the underlying prosemirror state
+   */
+  public get prosemirrorState() {
+    return this._tiptapEditor.state;
+  }
+
   public get domElement() {
     return this.prosemirrorView?.dom as HTMLDivElement | undefined;
   }
@@ -655,7 +759,7 @@ export class BlockNoteEditor<
   public get document(): Block<BSchema, ISchema, SSchema>[] {
     const blocks: Block<BSchema, ISchema, SSchema>[] = [];
 
-    this._tiptapEditor.state.doc.firstChild!.descendants((node) => {
+    this.prosemirrorState.doc.firstChild!.descendants((node) => {
       blocks.push(
         nodeToBlock(
           node,
@@ -768,6 +872,8 @@ export class BlockNoteEditor<
   /**
    * Executes a callback whenever the editor's contents change.
    * @param callback The callback to execute.
+   *
+   * @deprecated use `onChange` instead
    */
   public onEditorContentChange(callback: () => void) {
     this._tiptapEditor.on("update", callback);
@@ -776,6 +882,8 @@ export class BlockNoteEditor<
   /**
    * Executes a callback whenever the editor's selection changes.
    * @param callback The callback to execute.
+   *
+   * @deprecated use `onSelectionChange` instead
    */
   public onEditorSelectionChange(callback: () => void) {
     this._tiptapEditor.on("selectionUpdate", callback);
@@ -1217,13 +1325,22 @@ export class BlockNoteEditor<
    * @returns A function to remove the callback.
    */
   public onSelectionChange(
-    callback: (editor: BlockNoteEditor<BSchema, ISchema, SSchema>) => void
+    callback: (editor: BlockNoteEditor<BSchema, ISchema, SSchema>) => void,
+    includeSelectionChangedByRemote?: boolean
   ) {
     if (this.headless) {
       return;
     }
 
-    const cb = () => {
+    const cb = (e: { transaction: Transaction }) => {
+      if (
+        e.transaction.getMeta(ySyncPluginKey) &&
+        !includeSelectionChangedByRemote
+      ) {
+        // selection changed because of a yjs sync (i.e.: other user was typing)
+        // we don't want to trigger the callback in this case
+        return;
+      }
       callback(this);
     };
 
@@ -1234,6 +1351,53 @@ export class BlockNoteEditor<
     };
   }
 
+  /**
+   * A callback function that runs when the editor has been initialized.
+   *
+   * This can be useful for plugins to initialize themselves after the editor has been initialized.
+   */
+  public onCreate(callback: () => void) {
+    this.on("create", callback);
+
+    return () => {
+      this.off("create", callback);
+    };
+  }
+
+  public getSelectionBoundingBox() {
+    if (!this.prosemirrorView) {
+      return undefined;
+    }
+    const state = this.prosemirrorView?.state;
+    const { selection } = state;
+
+    // support for CellSelections
+    const { ranges } = selection;
+    const from = Math.min(...ranges.map((range) => range.$from.pos));
+    const to = Math.max(...ranges.map((range) => range.$to.pos));
+
+    if (isNodeSelection(selection)) {
+      const node = this.prosemirrorView.nodeDOM(from) as HTMLElement;
+      if (node) {
+        return node.getBoundingClientRect();
+      }
+    }
+
+    return posToDOMRect(this.prosemirrorView, from, to);
+  }
+
+  public get isEmpty() {
+    const doc = this.document;
+    // Note: only works for paragraphs as default blocks (but for now this is default in blocknote)
+    // checking prosemirror directly might be faster
+    return (
+      doc.length === 0 ||
+      (doc.length === 1 &&
+        doc[0].type === "paragraph" &&
+        (doc[0].content as any).length === 0)
+    );
+  }
+
   public openSuggestionMenu(
     triggerCharacter: string,
     pluginState?: {
@@ -1260,4 +1424,17 @@ export class BlockNoteEditor<
       })
     );
   }
+
+  // `forceSelectionVisible` determines whether the editor selection is shows
+  // even when the editor is not focused. This is useful for e.g. creating new
+  // links, so the user still sees the affected content when an input field is
+  // focused.
+  // TODO: Reconsider naming?
+  public getForceSelectionVisible() {
+    return this.showSelectionPlugin.getEnabled();
+  }
+
+  public setForceSelectionVisible(forceSelectionVisible: boolean) {
+    this.showSelectionPlugin.setEnabled(forceSelectionVisible);
+  }
 }

package/src/editor/BlockNoteExtensions.ts

@@ -12,6 +12,9 @@ import { createPasteFromClipboardExtension } from "../api/clipboard/fromClipboar
 import { createCopyToClipboardExtension } from "../api/clipboard/toClipboard/copyExtension.js";
 import { BackgroundColorExtension } from "../extensions/BackgroundColor/BackgroundColorExtension.js";
 import { createCollaborationExtensions } from "../extensions/Collaboration/createCollaborationExtensions.js";
+import { CommentMark } from "../extensions/Comments/CommentMark.js";
+import { CommentsPlugin } from "../extensions/Comments/CommentsPlugin.js";
+import type { ThreadStore } from "../comments/index.js";
 import { FilePanelProsemirrorPlugin } from "../extensions/FilePanel/FilePanelPlugin.js";
 import { FormattingToolbarProsemirrorPlugin } from "../extensions/FormattingToolbar/FormattingToolbarPlugin.js";
 import { KeyboardShortcutsExtension } from "../extensions/KeyboardShortcuts/KeyboardShortcutsExtension.js";
@@ -23,6 +26,7 @@ import {
 import { NodeSelectionKeyboardPlugin } from "../extensions/NodeSelectionKeyboard/NodeSelectionKeyboardPlugin.js";
 import { PlaceholderPlugin } from "../extensions/Placeholder/PlaceholderPlugin.js";
 import { PreviousBlockTypePlugin } from "../extensions/PreviousBlockType/PreviousBlockTypePlugin.js";
+import { ShowSelectionPlugin } from "../extensions/ShowSelection/ShowSelectionPlugin.js";
 import { SideMenuProsemirrorPlugin } from "../extensions/SideMenu/SideMenuPlugin.js";
 import { SuggestionMenuProseMirrorPlugin } from "../extensions/SuggestionMenu/SuggestionPlugin.js";
 import { TableHandlesProsemirrorPlugin } from "../extensions/TableHandles/TableHandlesPlugin.js";
@@ -75,6 +79,9 @@ type ExtensionOptions<
   >;
   tabBehavior?: "prefer-navigate-ui" | "prefer-indent";
   sideMenuDetection: "viewport" | "editor";
+  comments?: {
+    threadStore: ThreadStore;
+  };
 };
 
 /**
@@ -126,6 +133,16 @@ export const getBlockNoteExtensions = <
 
   ret["nodeSelectionKeyboard"] = new NodeSelectionKeyboardPlugin();
 
+  ret["showSelection"] = new ShowSelectionPlugin(opts.editor);
+
+  if (opts.comments) {
+    ret["comments"] = new CommentsPlugin(
+      opts.editor,
+      opts.comments.threadStore,
+      CommentMark.name
+    );
+  }
+
   const disableExtensions: string[] = opts.disableExtensions || [];
   for (const ext of disableExtensions) {
     delete ret[ext];
@@ -134,6 +151,8 @@ export const getBlockNoteExtensions = <
   return ret;
 };
 
+let LINKIFY_INITIALIZED = false;
+
 /**
  * Get all the Tiptap extensions BlockNote is configured with by default
  */
@@ -171,7 +190,8 @@ const getTipTapExtensions = <
       inclusive: false,
     }).configure({
       defaultProtocol: DEFAULT_LINK_PROTOCOL,
-      protocols: VALID_LINK_PROTOCOLS,
+      // only call this once if we have multiple editors installed. Or fix https://github.com/ueberdosis/tiptap/issues/5450
+      protocols: LINKIFY_INITIALIZED ? [] : VALID_LINK_PROTOCOLS,
     }),
     ...Object.values(opts.styleSpecs).map((styleSpec) => {
       return styleSpec.implementation.mark.configure({
@@ -246,8 +266,11 @@ const getTipTapExtensions = <
     ...(opts.trailingBlock === undefined || opts.trailingBlock
       ? [TrailingNode]
       : []),
+    ...(opts.comments ? [CommentMark] : []),
   ];
 
+  LINKIFY_INITIALIZED = true;
+
   if (opts.collaboration) {
     tiptapExtensions.push(...createCollaborationExtensions(opts.collaboration));
   } else {

package/src/editor/BlockNoteTipTapEditor.ts

@@ -184,7 +184,11 @@ export class BlockNoteTipTapEditor extends TiptapEditor {
 
     // emit the created event, call here manually because we blocked the default call in the constructor
     // (https://github.com/ueberdosis/tiptap/blob/45bac803283446795ad1b03f43d3746fa54a68ff/packages/core/src/Editor.ts#L117)
-    this.commands.focus(this.options.autofocus);
+    this.commands.focus(
+      this.options.autofocus ||
+        this.options.element.getAttribute("data-bn-autofocus") === "true",
+      { scrollIntoView: false }
+    );
     this.emit("create", { editor: this });
     this.isInitialized = true;
   }