@blocknote/core 0.33.0 → 0.35.0

package/src/blocks/defaultBlockTypeGuards.ts

@@ -1,9 +1,11 @@
 import { CellSelection } from "prosemirror-tables";
 import type { BlockNoteEditor } from "../editor/BlockNoteEditor.js";
 import {
+  BlockConfig,
   BlockFromConfig,
   BlockSchema,
   FileBlockConfig,
+  InlineContentConfig,
   InlineContentSchema,
   StyleSchema,
 } from "../schema/index.js";
@@ -35,6 +37,20 @@ export function checkDefaultBlockTypeInSchema<
   );
 }
 
+export function checkBlockTypeInSchema<
+  BlockType extends string,
+  Config extends BlockConfig,
+>(
+  blockType: BlockType,
+  blockConfig: Config,
+  editor: BlockNoteEditor<any, any, any>,
+): editor is BlockNoteEditor<{ [T in BlockType]: Config }, any, any> {
+  return (
+    blockType in editor.schema.blockSchema &&
+    editor.schema.blockSchema[blockType] === blockConfig
+  );
+}
+
 export function checkDefaultInlineContentTypeInSchema<
   InlineContentType extends keyof DefaultInlineContentSchema,
   B extends BlockSchema,
@@ -54,6 +70,20 @@ export function checkDefaultInlineContentTypeInSchema<
   );
 }
 
+export function checkInlineContentTypeInSchema<
+  InlineContentType extends string,
+  Config extends InlineContentConfig,
+>(
+  inlineContentType: InlineContentType,
+  inlineContentConfig: Config,
+  editor: BlockNoteEditor<any, any, any>,
+): editor is BlockNoteEditor<any, { [T in InlineContentType]: Config }, any> {
+  return (
+    inlineContentType in editor.schema.inlineContentSchema &&
+    editor.schema.inlineContentSchema[inlineContentType] === inlineContentConfig
+  );
+}
+
 export function checkBlockIsDefaultType<
   BlockType extends keyof DefaultBlockSchema,
   I extends InlineContentSchema,

package/src/editor/BlockNoteEditor.ts

@@ -120,6 +120,7 @@ import { EventEmitter } from "../util/EventEmitter.js";
 import { BlockNoteExtension } from "./BlockNoteExtension.js";
 
 import "../style.css";
+import { BlockChangePlugin } from "../extensions/BlockChange/BlockChangePlugin.js";
 
 /**
  * A factory function that returns a BlockNoteExtension
@@ -155,8 +156,11 @@ export type BlockNoteEditorOptions<
 
   /**
    * When enabled, allows for collaboration between multiple users.
+   * See [Real-time Collaboration](https://www.blocknotejs.org/docs/advanced/real-time-collaboration) for more info.
+   *
+   * @remarks `CollaborationOptions`
    */
-  collaboration: {
+  collaboration?: {
     /**
      * The Yjs XML fragment that's used for collaboration.
      */
@@ -190,7 +194,13 @@ export type BlockNoteEditorOptions<
    */
   codeBlock?: CodeBlockOptions;
 
-  comments: {
+  /**
+   * Configuration for the comments feature, requires a `threadStore`.
+   *
+   * See [Comments](https://www.blocknotejs.org/docs/features/collaboration/comments) for more info.
+   * @remarks `CommentsOptions`
+   */
+  comments?: {
     threadStore: ThreadStore;
   };
 
@@ -199,25 +209,38 @@ export type BlockNoteEditorOptions<
    *
    * @default true
    */
-  defaultStyles: boolean;
+  defaultStyles?: boolean;
 
   /**
    * A dictionary object containing translations for the editor.
+   *
+   * See [Localization / i18n](https://www.blocknotejs.org/docs/advanced/localization) for more info.
+   *
+   * @remarks `Dictionary` is a type that contains all the translations for the editor.
    */
   dictionary?: Dictionary & Record<string, any>;
 
   /**
    * Disable internal extensions (based on keys / extension name)
+   *
+   * @note Advanced
    */
-  disableExtensions: string[];
+  disableExtensions?: string[];
 
   /**
    * An object containing attributes that should be added to HTML elements of the editor.
    *
+   * See [Adding DOM Attributes](https://www.blocknotejs.org/docs/theming#adding-dom-attributes) for more info.
+   *
    * @example { editor: { class: "my-editor-class" } }
+   * @remarks `Record<string, Record<string, string>>`
    */
-  domAttributes: Partial<BlockNoteDOMAttributes>;
+  domAttributes?: Partial<BlockNoteDOMAttributes>;
 
+  /**
+   * A replacement indicator to use when dragging and dropping blocks. Uses the [ProseMirror drop cursor](https://github.com/ProseMirror/prosemirror-dropcursor), or a modified version when [Column Blocks](https://www.blocknotejs.org/docs/document-structure#column-blocks) are enabled.
+   * @remarks `() => Plugin`
+   */
   dropCursor?: (opts: {
     editor: BlockNoteEditor<
       NoInfer<BSchema>,
@@ -242,9 +265,13 @@ export type BlockNoteEditorOptions<
   };
 
   /**
-   * The content that should be in the editor when it's created, represented as an array of partial block objects.
+   * The content that should be in the editor when it's created, represented as an array of {@link PartialBlock} objects.
+   *
+   * See [Partial Blocks](https://www.blocknotejs.org/docs/editor-api/manipulating-blocks#partial-blocks) for more info.
+   *
+   * @remarks `PartialBlock[]`
    */
-  initialContent: PartialBlock<
+  initialContent?: PartialBlock<
     NoInfer<BSchema>,
     NoInfer<ISchema>,
     NoInfer<SSchema>
@@ -252,14 +279,19 @@ export type BlockNoteEditorOptions<
 
   /**
    * @deprecated, provide placeholders via dictionary instead
+   * @internal
    */
-  placeholders: Record<
+  placeholders?: Record<
     string | "default" | "emptyDocument",
     string | undefined
   >;
 
   /**
    * Custom paste handler that can be used to override the default paste behavior.
+   *
+   * See [Paste Handling](https://www.blocknotejs.org/docs/advanced/paste-handling) for more info.
+   *
+   * @remarks `PasteHandler`
    * @returns The function should return `true` if the paste event was handled, otherwise it should return `false` if it should be canceled or `undefined` if it should be handled by another handler.
    *
    * @example
@@ -296,10 +328,21 @@ export type BlockNoteEditorOptions<
    * implementing custom protocols / schemes
    * @returns The URL that's
    */
-  resolveFileUrl: (url: string) => Promise<string>;
+  resolveFileUrl?: (url: string) => Promise<string>;
 
-  resolveUsers: (userIds: string[]) => Promise<User[]>;
+  /**
+   * Resolve user information for comments.
+   *
+   * See [Comments](https://www.blocknotejs.org/docs/features/collaboration/comments) for more info.
+   */
+  resolveUsers?: (userIds: string[]) => Promise<User[]>;
 
+  /**
+   * The schema of the editor. The schema defines which Blocks, InlineContent, and Styles are available in the editor.
+   *
+   * See [Custom Schemas](https://www.blocknotejs.org/docs/custom-schemas) for more info.
+   * @remarks `BlockNoteSchema`
+   */
   schema: BlockNoteSchema<BSchema, ISchema, SSchema>;
 
   /**
@@ -313,31 +356,19 @@ export type BlockNoteEditorOptions<
   setIdAttribute?: boolean;
 
   /**
-   * 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,
-   what should happen when a user has selected multiple blocks while a toolbar
-   is open:
-   - `"prefer-navigate-ui"`: Change focus to the toolbar. The user needs to
-   first press `Escape` to close the toolbar, and can then indent multiple
-   blocks. Better for keyboard accessibility.
-   - `"prefer-indent"`: Regardless of whether toolbars are open, indent the
-   selection of blocks. In this case, it's not possible to navigate toolbars
-   with the keyboard.
-
-   @default "prefer-navigate-ui"
+   * Determines behavior when pressing Tab (or Shift-Tab) while multiple blocks are selected and a toolbar is open.
+   * - `"prefer-navigate-ui"`: Changes focus to the toolbar. User must press Escape to close toolbar before indenting blocks. Better for keyboard accessibility.
+   * - `"prefer-indent"`: Always indents selected blocks, regardless of toolbar state. Keyboard navigation of toolbars not possible.
+   * @default "prefer-navigate-ui"
    */
-  tabBehavior: "prefer-navigate-ui" | "prefer-indent";
+  tabBehavior?: "prefer-navigate-ui" | "prefer-indent";
 
   /**
    * Allows enabling / disabling features of tables.
+   *
+   * See [Tables](https://www.blocknotejs.org/docs/editor-basics/document-structure#tables) for more info.
+   *
+   * @remarks `TableConfig`
    */
   tables?: {
     /**
@@ -366,6 +397,11 @@ export type BlockNoteEditorOptions<
     headers?: boolean;
   };
 
+  /**
+   * 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.
+   *
+   * @default true
+   */
   trailingBlock?: boolean;
 
   /**
@@ -376,23 +412,26 @@ export type BlockNoteEditorOptions<
    *
    * @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)
+   * @remarks `(file: File) => Promise<UploadFileResult>`
    */
-  uploadFile: (
+  uploadFile?: (
     file: File,
     blockId?: string,
   ) => Promise<string | Record<string, any>>;
 
   /**
    * additional tiptap options, undocumented
+   * @internal
    */
-  _tiptapOptions: Partial<EditorOptions>;
+  _tiptapOptions?: Partial<EditorOptions>;
 
   /**
    * (experimental) add extra extensions to the editor
    *
    * @deprecated, should use `extensions` instead
+   * @internal
    */
-  _extensions: Record<
+  _extensions?: Record<
     string,
     | { plugin: Plugin; priority?: number }
     | ((editor: BlockNoteEditor<any, any, any>) => {
@@ -402,9 +441,11 @@ export type BlockNoteEditorOptions<
   >;
 
   /**
-   * Register
+   * Register extensions to the editor.
+   *
+   * @internal
    */
-  extensions: Array<BlockNoteExtension | BlockNoteExtensionFactory>;
+  extensions?: Array<BlockNoteExtension | BlockNoteExtensionFactory>;
 
   /**
    * Boolean indicating whether the editor is in headless mode.
@@ -412,8 +453,9 @@ export type BlockNoteEditorOptions<
    * 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
+   * @internal
    */
-  _headless: boolean;
+  _headless?: boolean;
 };
 
 const blockNoteTipTapOptions = {
@@ -639,7 +681,6 @@ export class BlockNoteEditor<
       dropCursor: this.options.dropCursor ?? dropCursor,
       placeholders: newOptions.placeholders,
       tabBehavior: newOptions.tabBehavior,
-      sideMenuDetection: newOptions.sideMenuDetection || "viewport",
       comments: newOptions.comments,
       pasteHandler: newOptions.pasteHandler,
     });
@@ -1606,6 +1647,32 @@ export class BlockNoteEditor<
     (this.extensions["yCursorPlugin"] as CursorPlugin).updateUser(user);
   }
 
+  /**
+   * Registers a callback which will be called before any change is applied to the editor, allowing you to cancel the change.
+   */
+  public onBeforeChange(
+    /**
+     * If the callback returns `false`, the change will be canceled & not applied to the editor.
+     */
+    callback: (
+      editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
+      context: {
+        getChanges: () => BlocksChanged<BSchema, ISchema, SSchema>;
+        tr: Transaction;
+      },
+    ) => boolean | void,
+  ): () => void {
+    if (this.headless) {
+      return () => {
+        // noop
+      };
+    }
+
+    return (this.extensions["blockChange"] as BlockChangePlugin).subscribe(
+      (context) => callback(this, context),
+    );
+  }
+
   /**
    * A callback function that runs whenever the editor's contents change.
    *

package/src/editor/BlockNoteExtensions.ts

@@ -11,6 +11,7 @@ import { createPasteFromClipboardExtension } from "../api/clipboard/fromClipboar
 import { createCopyToClipboardExtension } from "../api/clipboard/toClipboard/copyExtension.js";
 import type { ThreadStore } from "../comments/index.js";
 import { BackgroundColorExtension } from "../extensions/BackgroundColor/BackgroundColorExtension.js";
+import { BlockChangePlugin } from "../extensions/BlockChange/BlockChangePlugin.js";
 import { CursorPlugin } from "../extensions/Collaboration/CursorPlugin.js";
 import { SyncPlugin } from "../extensions/Collaboration/SyncPlugin.js";
 import { UndoPlugin } from "../extensions/Collaboration/UndoPlugin.js";
@@ -90,7 +91,6 @@ type ExtensionOptions<
     string | undefined
   >;
   tabBehavior?: "prefer-navigate-ui" | "prefer-indent";
-  sideMenuDetection: "viewport" | "editor";
   comments?: {
     threadStore: ThreadStore;
   };
@@ -133,10 +133,7 @@ export const getBlockNoteExtensions = <
     opts.editor,
   );
   ret["linkToolbar"] = new LinkToolbarProsemirrorPlugin(opts.editor);
-  ret["sideMenu"] = new SideMenuProsemirrorPlugin(
-    opts.editor,
-    opts.sideMenuDetection,
-  );
+  ret["sideMenu"] = new SideMenuProsemirrorPlugin(opts.editor);
   ret["suggestionMenus"] = new SuggestionMenuProseMirrorPlugin(opts.editor);
   ret["filePanel"] = new FilePanelProsemirrorPlugin(opts.editor as any);
   ret["placeholder"] = new PlaceholderPlugin(opts.editor, opts.placeholders);
@@ -150,6 +147,7 @@ export const getBlockNoteExtensions = <
   }
 
   ret["nodeSelectionKeyboard"] = new NodeSelectionKeyboardPlugin();
+  ret["blockChange"] = new BlockChangePlugin();
 
   ret["showSelection"] = new ShowSelectionPlugin(opts.editor);
 

package/src/exporter/Exporter.ts

@@ -90,12 +90,14 @@ export abstract class Exporter<
     block: BlockFromConfig<B[keyof B], I, S>,
     nestingLevel: number,
     numberedListIndex: number,
+    children?: Array<Awaited<RB>>,
   ) {
     return this.mappings.blockMapping[block.type](
       block,
       this,
       nestingLevel,
       numberedListIndex,
+      children,
     );
   }
 }

package/src/exporter/mapping.ts

@@ -27,6 +27,7 @@ export type BlockMapping<
     exporter: Exporter<any, any, any, RB, RI, any, any>,
     nestingLevel: number,
     numberedListIndex?: number,
+    children?: Array<Awaited<RB>>,
   ) => RB | Promise<RB>;
 };
 

package/src/extensions/BlockChange/BlockChangePlugin.ts

@@ -0,0 +1,66 @@
+import { Plugin, Transaction } from "prosemirror-state";
+import { getBlocksChangedByTransaction } from "../../api/nodeUtil.js";
+import { BlockNoteExtension } from "../../editor/BlockNoteExtension.js";
+import { BlocksChanged } from "../../index.js";
+
+/**
+ * This plugin can filter transactions before they are applied to the editor, but with a higher-level API than `filterTransaction` from prosemirror.
+ */
+export class BlockChangePlugin extends BlockNoteExtension {
+  public static key() {
+    return "blockChange";
+  }
+
+  private beforeChangeCallbacks: ((context: {
+    getChanges: () => BlocksChanged<any, any, any>;
+    tr: Transaction;
+  }) => boolean | void)[] = [];
+
+  constructor() {
+    super();
+
+    this.addProsemirrorPlugin(
+      new Plugin({
+        filterTransaction: (tr) => {
+          let changes:
+            | ReturnType<typeof getBlocksChangedByTransaction>
+            | undefined = undefined;
+
+          return this.beforeChangeCallbacks.reduce((acc, cb) => {
+            if (acc === false) {
+              // We only care that we hit a `false` result, so we can stop iterating.
+              return acc;
+            }
+            return (
+              cb({
+                getChanges() {
+                  if (changes) {
+                    return changes;
+                  }
+                  changes = getBlocksChangedByTransaction(tr);
+                  return changes;
+                },
+                tr,
+              }) !== false
+            );
+          }, true);
+        },
+      }),
+    );
+  }
+
+  public subscribe(
+    callback: (context: {
+      getChanges: () => BlocksChanged<any, any, any>;
+      tr: Transaction;
+    }) => boolean | void,
+  ) {
+    this.beforeChangeCallbacks.push(callback);
+
+    return () => {
+      this.beforeChangeCallbacks = this.beforeChangeCallbacks.filter(
+        (cb) => cb !== callback,
+      );
+    };
+  }
+}

package/src/extensions/Collaboration/ForkYDocPlugin.ts

@@ -101,7 +101,7 @@ export class ForkYDocPlugin extends BlockNoteExtension<{
       return;
     }
 
-    const originalFragment = this.collaboration.fragment;
+    const originalFragment = this.collaboration?.fragment;
 
     if (!originalFragment) {
       throw new Error("No fragment to fork from");