@blocknote/core 0.34.0 → 0.36.0

package/src/editor/BlockNoteEditor.ts

@@ -156,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.
      */
@@ -191,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;
   };
 
@@ -200,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>,
@@ -243,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>
@@ -253,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
@@ -297,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>;
 
   /**
@@ -314,22 +356,19 @@ export type BlockNoteEditorOptions<
   setIdAttribute?: boolean;
 
   /**
-   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?: {
     /**
@@ -358,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;
 
   /**
@@ -368,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>) => {
@@ -394,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.
@@ -404,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 = {
@@ -1600,7 +1650,7 @@ export class BlockNoteEditor<
   /**
    * Registers a callback which will be called before any change is applied to the editor, allowing you to cancel the change.
    */
-  public beforeChange(
+  public onBeforeChange(
     /**
      * If the callback returns `false`, the change will be canceled & not applied to the editor.
      */

package/src/editor/editor.css

@@ -148,25 +148,16 @@ Tippy popups that are appended to document.body directly
   transition: all 0.2s;
 }
 
-/* .tableWrapper {
-  padding
-} */
-
 .bn-editor [data-content-type="table"] .tableWrapper {
-  position: relative;
-  top: -16px;
-  left: -16px;
-  /* padding: 16px; */
-  min-width: calc(100% + 16px);
-  padding-bottom: 16px;
+  /* Size of + buttons to add rows/columns. */
+  --bn-table-widget-size: 22px;
+  /* Size of table handles, divided by 2 since half the element is in the cell. */
+  --bn-table-handle-size: calc(18px / 2);
   overflow-y: hidden;
-}
-
-.bn-editor [data-content-type="table"] .tableWrapper-inner {
-  /* position: relative; */
-  /* top: -16px;
-  left: -16px; */
-  padding: 16px;
+  padding: var(--bn-table-handle-size) var(--bn-table-widget-size)
+    var(--bn-table-widget-size) var(--bn-table-handle-size);
+  position: relative;
+  width: 100%;
 }
 
 /* table related: */

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");

package/src/extensions/FormattingToolbar/FormattingToolbarPlugin.ts

@@ -1,5 +1,11 @@
 import { isNodeSelection, isTextSelection, posToDOMRect } from "@tiptap/core";
-import { EditorState, Plugin, PluginKey, PluginView } from "prosemirror-state";
+import {
+  EditorState,
+  Plugin,
+  PluginKey,
+  PluginView,
+  TextSelection,
+} from "prosemirror-state";
 import { EditorView } from "prosemirror-view";
 
 import type { BlockNoteEditor } from "../../editor/BlockNoteEditor.js";
@@ -198,6 +204,56 @@ export class FormattingToolbarView implements PluginView {
       // e.g. the download file button, should still be accessible. Therefore,
       // logic for hiding when the editor is non-editable is handled
       // individually in each button.
+      const newReferencePos = this.getSelectionBoundingBox();
+
+      // Workaround to ensure the correct reference position when rendering
+      // React components. Without this, e.g. updating styles on React inline
+      // content causes the formatting toolbar to be in the wrong place. We
+      // know the component has not yet rendered if the reference position has
+      // zero dimensions.
+      if (
+        newReferencePos.x === 0 ||
+        newReferencePos.y === 0 ||
+        newReferencePos.height === 0
+      ) {
+        // Updates the reference position again following the render.
+        queueMicrotask(() => {
+          const nextState = {
+            show: true,
+            referencePos: this.getSelectionBoundingBox(),
+          };
+
+          this.state = nextState;
+          this.emitUpdate();
+
+          // For some reason, while the selection doesn't actually change and
+          // remains correct, it visually appears to be collapsed. This forces
+          // a ProseMirror view update, which fixes the issue.
+          view.dispatch(
+            view.state.tr.setSelection(
+              TextSelection.create(
+                view.state.doc,
+                view.state.selection.from + 1,
+                view.state.selection.to,
+              ),
+            ),
+          );
+          // 2 separate `dispatch` calls are needed, else ProseMirror realizes
+          // that the transaction is a no-op and doesn't update the view.
+          view.dispatch(
+            view.state.tr.setSelection(
+              TextSelection.create(
+                view.state.doc,
+                view.state.selection.from - 1,
+                view.state.selection.to,
+              ),
+            ),
+          );
+        });
+
+        return;
+      }
+
       const nextState = {
         show: true,
         referencePos: this.getSelectionBoundingBox(),

package/src/extensions/SideMenu/SideMenuPlugin.ts

@@ -242,21 +242,11 @@ export class SideMenuView<
 
     this.hoveredBlock = block.node;
 
-    // Gets the block's content node, which lets to ignore child blocks when determining the block menu's position.
-    // TODO: needed?
-    const blockContent = block.node.firstChild as HTMLElement;
-
-    if (!blockContent) {
-      return;
-    }
-
-    // TODO: needed?
-
     // Shows or updates elements.
     if (this.editor.isEditable) {
-      const blockContentBoundingBox = blockContent.getBoundingClientRect();
+      const blockContentBoundingBox = block.node.getBoundingClientRect();
       const column = block.node.closest("[data-node-type=column]");
-      this.updateState({
+      this.state = {
         show: true,
         referencePos: new DOMRect(
           column
@@ -275,7 +265,8 @@ export class SideMenuView<
         block: this.editor.getBlock(
           this.hoveredBlock!.getAttribute("data-id")!,
         )!,
-      });
+      };
+      this.updateState(this.state);
     }
   };
 
@@ -435,9 +426,9 @@ export class SideMenuView<
     // We need to check if there is text content that is being dragged (select some text & just drag it)
     const textContentIsBeingDragged =
       !event.dataTransfer?.types.includes("blocknote/html") &&
-      Boolean(this.pmView.dragging);
+      !!this.pmView.dragging;
     // This is the side menu drag from this plugin
-    const sideMenuIsBeingDragged = Boolean(this.isDragOrigin);
+    const sideMenuIsBeingDragged = !!this.isDragOrigin;
     // Tells us that the current editor instance has a drag ongoing (either text or side menu)
     const isDragOrigin = textContentIsBeingDragged || sideMenuIsBeingDragged;
 
@@ -498,21 +489,19 @@ export class SideMenuView<
     }
     const { isDropPoint, isDropWithinEditorBounds, isDragOrigin } = context;
 
-    if (!isDropWithinEditorBounds) {
+    if (!isDropWithinEditorBounds && isDropPoint) {
       // Any time that the drop event is outside of the editor bounds (but still close to an editor instance)
       // We dispatch a synthetic event that is in the bounds of the editor instance, to have the correct drop point
       this.dispatchSyntheticEvent(event);
     }
 
-    if (isDropPoint && isDragOrigin) {
-      // The current instance is both the drop point and the drag origin
-      // no-op, normal drop handling will take over
-      return;
-    }
-
     if (isDropPoint) {
-      // The current instance is the drop point, but not the drag origin
+      // The current instance is the drop point
 
+      if (this.pmView.dragging) {
+        // Do not collapse selection when text content is being dragged
+        return;
+      }
       // Because the editor selection is unrelated to the dragged content, we
       // don't want PM to delete its content. Therefore, we collapse the
       // selection.

package/src/i18n/locales/ar.ts

@@ -182,6 +182,9 @@ export const ar: Dictionary = {
       add_button_text: "إضافة ملف",
     },
   },
+  toggle_blocks: {
+    add_block_button: "تبديل فارغ. انقر لإضافة كتلة.",
+  },
   // from react package:
   side_menu: {
     add_block_label: "إضافة محتوي",

package/src/i18n/locales/de.ts

@@ -217,6 +217,10 @@ export const de: Dictionary = {
       add_button_text: "Datei hinzufügen",
     },
   },
+  toggle_blocks: {
+    add_block_button:
+      "Leerer aufklappbarer Bereich. Klicken, um einen Block hinzuzufügen.",
+  },
   side_menu: {
     add_block_label: "Block hinzufügen",
     drag_handle_label: "Blockmenü öffnen",

package/src/i18n/locales/en.ts

@@ -197,6 +197,9 @@ export const en = {
       add_button_text: "Add file",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Empty toggle. Click to add a block.",
+  },
   // from react package:
   side_menu: {
     add_block_label: "Add block",

package/src/i18n/locales/es.ts

@@ -197,6 +197,9 @@ export const es: Dictionary = {
       add_button_text: "Agregar archivo",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Toggle vacío. Haz clic para añadir un bloque.",
+  },
   side_menu: {
     add_block_label: "Agregar bloque",
     drag_handle_label: "Abrir menú de bloque",

package/src/i18n/locales/fr.ts

@@ -243,6 +243,9 @@ export const fr: Dictionary = {
       add_button_text: "Ajouter un fichier",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Toggle vide. Cliquez pour ajouter un bloc.",
+  },
   // from react package:
   side_menu: {
     add_block_label: "Ajouter un bloc",

package/src/i18n/locales/he.ts

@@ -199,6 +199,9 @@ export const he: Dictionary = {
       add_button_text: "הוסף קובץ",
     },
   },
+  toggle_blocks: {
+    add_block_button: "מתג ריק. לחץ כדי להוסיף בלוק.",
+  },
   side_menu: {
     add_block_label: "הוסף בלוק",
     drag_handle_label: "פתח תפריט בלוק",

package/src/i18n/locales/hr.ts

@@ -210,6 +210,9 @@ export const hr: Dictionary = {
       add_button_text: "Dodaj datoteku",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Prazan sklopivi blok. Klikni da dodaš sadržaj.",
+  },
   // from react package:
   side_menu: {
     add_block_label: "Dodaj blok",

package/src/i18n/locales/is.ts

@@ -211,6 +211,9 @@ export const is: Dictionary = {
       add_button_text: "Bæta við skrá",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Tóm fellilína. Smelltu til að bæta við blokk.",
+  },
   side_menu: {
     add_block_label: "Bæta við blokki",
     drag_handle_label: "Opna blokkarvalmynd",

package/src/i18n/locales/it.ts

@@ -219,6 +219,9 @@ export const it: Dictionary = {
       add_button_text: "Aggiungi file",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Toggle vuoto. Clicca per aggiungere un blocco.",
+  },
   // from react package:
   side_menu: {
     add_block_label: "Aggiungi blocco",

package/src/i18n/locales/ja.ts

@@ -237,6 +237,9 @@ export const ja: Dictionary = {
       add_button_text: "ファイルを追加",
     },
   },
+  toggle_blocks: {
+    add_block_button: "空のトグルです。クリックしてブロックを追加。",
+  },
   // from react package:
   side_menu: {
     add_block_label: "ブロックを追加",

package/src/i18n/locales/ko.ts

@@ -42,7 +42,7 @@ export const ko: Dictionary = {
       title: "접을 수 있는 제목1",
       subtext: "내용을 표시하거나 숨길 수 있는 섹션 제목(대)",
       aliases: ["h", "제목1", "h1", "대제목", "접기", "토글"],
-      group: "제목",
+      group: "소제목",
     },
     toggle_heading_2: {
       title: "접을 수 있는 제목2",
@@ -210,6 +210,9 @@ export const ko: Dictionary = {
       add_button_text: "파일 추가",
     },
   },
+  toggle_blocks: {
+    add_block_button: "비어 있는 토글입니다. 클릭하여 블록을 추가하세요.",
+  },
   // from react package:
   side_menu: {
     add_block_label: "블록 추가",

package/src/i18n/locales/nl.ts

@@ -198,6 +198,9 @@ export const nl: Dictionary = {
       add_button_text: "Bestand toevoegen",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Lege uitklapper. Klik om een blok toe te voegen.",
+  },
   // from react package:
   side_menu: {
     add_block_label: "Nieuw blok",

package/src/i18n/locales/no.ts

@@ -216,6 +216,9 @@ export const no: Dictionary = {
       add_button_text: "Legg til fil",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Tomt toggle. Klikk for å legge til en blokk.",
+  },
   side_menu: {
     add_block_label: "Legg til blokk",
     drag_handle_label: "Åpne blokkmeny",

package/src/i18n/locales/pl.ts

@@ -188,6 +188,10 @@ export const pl: Dictionary = {
       add_button_text: "Dodaj plik",
     },
   },
+  toggle_blocks: {
+    add_block_button:
+      "Brak bloków do rozwinięcia. Kliknij, aby dodać pierwszego.",
+  },
   side_menu: {
     add_block_label: "Dodaj blok",
     drag_handle_label: "Otwórz menu bloków",

package/src/i18n/locales/pt.ts

@@ -189,6 +189,9 @@ export const pt: Dictionary = {
       add_button_text: "Adicionar arquivo",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Toggle vazio. Clique para adicionar um bloco.",
+  },
   // from react package:
   side_menu: {
     add_block_label: "Adicionar bloco",

package/src/i18n/locales/ru.ts

@@ -240,6 +240,9 @@ export const ru: Dictionary = {
       add_button_text: "Добавить файл",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Пустой переключатель. Нажмите, чтобы добавить блок.",
+  },
   // from react package:
   side_menu: {
     add_block_label: "Добавить блок",

package/src/i18n/locales/sk.ts

@@ -197,6 +197,9 @@ export const sk = {
       add_button_text: "Pridať súbor",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Prázdne prepínanie. Kliknite pre pridanie bloku.",
+  },
   side_menu: {
     add_block_label: "Pridať blok",
     drag_handle_label: "Otvoriť menu bloku",

package/src/i18n/locales/uk.ts

@@ -222,6 +222,9 @@ export const uk: Dictionary = {
       add_button_text: "Додати файл",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Порожній перемикач. Натисніть, щоб додати блок.",
+  },
   // from react package:
   side_menu: {
     add_block_label: "Додати блок",

package/src/i18n/locales/vi.ts

@@ -196,6 +196,9 @@ export const vi: Dictionary = {
       add_button_text: "Thêm tệp",
     },
   },
+  toggle_blocks: {
+    add_block_button: "Toggle trống. Nhấp để thêm khối.",
+  },
   // từ gói phản ứng:
   side_menu: {
     add_block_label: "Thêm khối",

package/src/i18n/locales/zh-tw.ts

@@ -238,6 +238,9 @@ export const zhTW: Dictionary = {
       add_button_text: "新增檔案",
     },
   },
+  toggle_blocks: {
+    add_block_button: "空的切換區。點擊新增區塊。",
+  },
   // from react package:
   side_menu: {
     add_block_label: "新增區塊",

package/src/i18n/locales/zh.ts

@@ -238,6 +238,9 @@ export const zh: Dictionary = {
       add_button_text: "添加文件",
     },
   },
+  toggle_blocks: {
+    add_block_button: "空的切换区。点击添加区块。",
+  },
   // from react package:
   side_menu: {
     add_block_label: "添加块",