@blocknote/core 0.33.0 → 0.35.0

package/types/src/api/nodeUtil.d.ts

@@ -16,31 +16,14 @@ export declare function isNodeBlock(node: Node): boolean;
  * This attributes the changes to a specific source.
  */
 export type BlockChangeSource = {
-    /**
-     * When an event is triggered by the local user, the source is "local".
-     * This is the default source.
-     */
     type: "local";
 } | {
-    /**
-     * When an event is triggered by a paste operation, the source is "paste".
-     */
     type: "paste";
 } | {
-    /**
-     * When an event is triggered by a drop operation, the source is "drop".
-     */
     type: "drop";
 } | {
-    /**
-     * When an event is triggered by an undo or redo operation, the source is "undo" or "redo".
-     * @note Y.js undo/redo are not differentiated.
-     */
     type: "undo" | "redo" | "undo-redo";
 } | {
-    /**
-     * When an event is triggered by a remote user, the source is "remote".
-     */
     type: "yjs-remote";
 };
 export type BlocksChanged<BSchema extends BlockSchema = DefaultBlockSchema, ISchema extends InlineContentSchema = DefaultInlineContentSchema, SSchema extends StyleSchema = DefaultStyleSchema> = Array<{
@@ -61,14 +44,29 @@ export type BlocksChanged<BSchema extends BlockSchema = DefaultBlockSchema, ISch
 } | {
     type: "update";
     /**
-     * The block before the update.
+     * The previous block.
+     */
+    prevBlock: Block<BSchema, ISchema, SSchema>;
+} | {
+    type: "move";
+    /**
+     * The affected block.
+     */
+    block: Block<BSchema, ISchema, SSchema>;
+    /**
+     * The block before the move.
      */
     prevBlock: Block<BSchema, ISchema, SSchema>;
+    /**
+     * The previous parent block (if it existed).
+     */
+    prevParent?: Block<BSchema, ISchema, SSchema>;
+    /**
+     * The current parent block (if it exists).
+     */
+    currentParent?: Block<BSchema, ISchema, SSchema>;
 })>;
 /**
  * Get the blocks that were changed by a transaction.
- * @param transaction The transaction to get the changes from.
- * @param editor The editor to get the changes from.
- * @returns The blocks that were changed by the transaction.
  */
 export declare function getBlocksChangedByTransaction<BSchema extends BlockSchema = DefaultBlockSchema, ISchema extends InlineContentSchema = DefaultInlineContentSchema, SSchema extends StyleSchema = DefaultStyleSchema>(transaction: Transaction, appendedTransactions?: Transaction[]): BlocksChanged<BSchema, ISchema, SSchema>;

package/types/src/api/parsers/markdown/detectMarkdown.test.d.ts

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

package/types/src/blocks/defaultBlockTypeGuards.d.ts

@@ -1,15 +1,21 @@
 import { CellSelection } from "prosemirror-tables";
 import type { BlockNoteEditor } from "../editor/BlockNoteEditor.js";
-import { BlockFromConfig, BlockSchema, FileBlockConfig, InlineContentSchema, StyleSchema } from "../schema/index.js";
+import { BlockConfig, BlockFromConfig, BlockSchema, FileBlockConfig, InlineContentConfig, InlineContentSchema, StyleSchema } from "../schema/index.js";
 import { Block, DefaultBlockSchema, DefaultInlineContentSchema } from "./defaultBlocks.js";
 import { defaultProps } from "./defaultProps.js";
 import { Selection } from "prosemirror-state";
 export declare function checkDefaultBlockTypeInSchema<BlockType extends keyof DefaultBlockSchema, I extends InlineContentSchema, S extends StyleSchema>(blockType: BlockType, editor: BlockNoteEditor<any, I, S>): editor is BlockNoteEditor<{
     [K in BlockType]: DefaultBlockSchema[BlockType];
 }, I, S>;
+export declare 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>;
 export declare function checkDefaultInlineContentTypeInSchema<InlineContentType extends keyof DefaultInlineContentSchema, B extends BlockSchema, S extends StyleSchema>(inlineContentType: InlineContentType, editor: BlockNoteEditor<B, any, S>): editor is BlockNoteEditor<B, {
     [K in InlineContentType]: DefaultInlineContentSchema[InlineContentType];
 }, S>;
+export declare 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>;
 export declare function checkBlockIsDefaultType<BlockType extends keyof DefaultBlockSchema, I extends InlineContentSchema, S extends StyleSchema>(blockType: BlockType, block: Block<any, I, S>, editor: BlockNoteEditor<any, I, S>): block is BlockFromConfig<DefaultBlockSchema[BlockType], I, S>;
 export declare function checkBlockIsFileBlock<B extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema>(block: Block<any, I, S>, editor: BlockNoteEditor<B, I, S>): block is BlockFromConfig<FileBlockConfig, I, S>;
 export declare function checkBlockIsFileBlockWithPreview<B extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema>(block: Block<any, I, S>, editor: BlockNoteEditor<B, I, S>): block is BlockFromConfig<FileBlockConfig & {

package/types/src/editor/BlockNoteEditor.d.ts

@@ -45,8 +45,11 @@ export type BlockNoteEditorOptions<BSchema extends BlockSchema, ISchema extends
     animations?: boolean;
     /**
      * 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.
          */
@@ -78,7 +81,13 @@ export type BlockNoteEditorOptions<BSchema extends BlockSchema, ISchema extends
      * Options for code blocks.
      */
     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;
     };
     /**
@@ -86,21 +95,34 @@ export type BlockNoteEditorOptions<BSchema extends BlockSchema, ISchema extends
      *
      * @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>;
+    /**
+     * 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`
      */
-    domAttributes: Partial<BlockNoteDOMAttributes>;
     dropCursor?: (opts: {
         editor: BlockNoteEditor<NoInfer<BSchema>, NoInfer<ISchema>, NoInfer<SSchema>>;
         color?: string | false;
@@ -119,15 +141,24 @@ export type BlockNoteEditorOptions<BSchema extends BlockSchema, ISchema extends
         levels?: (1 | 2 | 3 | 4 | 5 | 6)[];
     };
     /**
-     * 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<NoInfer<BSchema>, NoInfer<ISchema>, NoInfer<SSchema>>[];
+    initialContent?: PartialBlock<NoInfer<BSchema>, NoInfer<ISchema>, NoInfer<SSchema>>[];
     /**
      * @deprecated, provide placeholders via dictionary instead
+     * @internal
      */
-    placeholders: Record<string | "default" | "emptyDocument", string | undefined>;
+    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
@@ -163,8 +194,19 @@ export type BlockNoteEditorOptions<BSchema extends BlockSchema, ISchema extends
      * implementing custom protocols / schemes
      * @returns The URL that's
      */
-    resolveFileUrl: (url: string) => Promise<string>;
-    resolveUsers: (userIds: string[]) => Promise<User[]>;
+    resolveFileUrl?: (url: string) => Promise<string>;
+    /**
+     * 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>;
     /**
      * A flag indicating whether to set an HTML ID for every block
@@ -176,29 +218,18 @@ export type BlockNoteEditorOptions<BSchema extends BlockSchema, ISchema extends
      */
     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"
+     * 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"
      */
-    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"
-     */
-    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?: {
         /**
@@ -226,6 +257,11 @@ export type BlockNoteEditorOptions<BSchema extends BlockSchema, ISchema extends
          */
         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;
     /**
      * The `uploadFile` method is what the editor uses when files need to be uploaded (for example when selecting an image to upload).
@@ -235,18 +271,21 @@ export type BlockNoteEditorOptions<BSchema extends BlockSchema, ISchema extends
      *
      * @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: (file: File, blockId?: string) => Promise<string | Record<string, any>>;
+    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<string, {
+    _extensions?: Record<string, {
         plugin: Plugin;
         priority?: number;
     } | ((editor: BlockNoteEditor<any, any, any>) => {
@@ -254,17 +293,20 @@ export type BlockNoteEditorOptions<BSchema extends BlockSchema, ISchema extends
         priority?: number;
     })>;
     /**
-     * Register
+     * Register extensions to the editor.
+     *
+     * @internal
      */
-    extensions: Array<BlockNoteExtension | BlockNoteExtensionFactory>;
+    extensions?: Array<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
+     * @internal
      */
-    _headless: boolean;
+    _headless?: boolean;
 };
 export declare class BlockNoteEditor<BSchema extends BlockSchema = DefaultBlockSchema, ISchema extends InlineContentSchema = DefaultInlineContentSchema, SSchema extends StyleSchema = DefaultStyleSchema> extends EventEmitter<{
     create: void;
@@ -716,6 +758,17 @@ export declare class BlockNoteEditor<BSchema extends BlockSchema = DefaultBlockS
         name: string;
         color: string;
     }): void;
+    /**
+     * Registers a callback which will be called before any change is applied to the editor, allowing you to cancel the change.
+     */
+    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;
     /**
      * A callback function that runs whenever the editor's contents change.
      *

package/types/src/editor/BlockNoteExtensions.d.ts

@@ -28,7 +28,6 @@ type ExtensionOptions<BSchema extends BlockSchema, I extends InlineContentSchema
     dropCursor: (opts: any) => Plugin;
     placeholders: Record<string | "default" | "emptyDocument", string | undefined>;
     tabBehavior?: "prefer-navigate-ui" | "prefer-indent";
-    sideMenuDetection: "viewport" | "editor";
     comments?: {
         threadStore: ThreadStore;
     };

package/types/src/exporter/Exporter.d.ts

@@ -39,5 +39,5 @@ export declare abstract class Exporter<B extends BlockSchema, I extends InlineCo
     mapInlineContent(inlineContent: InlineContent<I, S>): RI;
     transformInlineContent(inlineContentArray: InlineContent<I, S>[]): RI[];
     abstract transformStyledText(styledText: StyledText<S>): TS;
-    mapBlock(block: BlockFromConfig<B[keyof B], I, S>, nestingLevel: number, numberedListIndex: number): Promise<RB>;
+    mapBlock(block: BlockFromConfig<B[keyof B], I, S>, nestingLevel: number, numberedListIndex: number, children?: Array<Awaited<RB>>): Promise<RB>;
 }

package/types/src/exporter/mapping.d.ts

@@ -5,7 +5,7 @@ import type { Exporter } from "./Exporter.js";
  * Defines a mapping from all block types with a schema to a result type `R`.
  */
 export type BlockMapping<B extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema, RB, RI> = {
-    [K in keyof B]: (block: BlockFromConfigNoChildren<B[K], I, S>, exporter: Exporter<any, any, any, RB, RI, any, any>, nestingLevel: number, numberedListIndex?: number) => RB | Promise<RB>;
+    [K in keyof B]: (block: BlockFromConfigNoChildren<B[K], I, S>, exporter: Exporter<any, any, any, RB, RI, any, any>, nestingLevel: number, numberedListIndex?: number, children?: Array<Awaited<RB>>) => RB | Promise<RB>;
 };
 /**
  * Defines a mapping from all inline content types with a schema to a result type R.

package/types/src/extensions/BlockChange/BlockChangePlugin.d.ts

@@ -0,0 +1,15 @@
+import { Transaction } from "prosemirror-state";
+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 declare class BlockChangePlugin extends BlockNoteExtension {
+    static key(): string;
+    private beforeChangeCallbacks;
+    constructor();
+    subscribe(callback: (context: {
+        getChanges: () => BlocksChanged<any, any, any>;
+        tr: Transaction;
+    }) => boolean | void): () => void;
+}

package/types/src/extensions/SideMenu/SideMenuPlugin.d.ts

@@ -13,7 +13,6 @@ export type SideMenuState<BSchema extends BlockSchema, I extends InlineContentSc
  */
 export declare class SideMenuView<BSchema extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema> implements PluginView {
     private readonly editor;
-    private readonly sideMenuDetection;
     private readonly pmView;
     state?: SideMenuState<BSchema, I, S>;
     readonly emitUpdate: (state: SideMenuState<BSchema, I, S>) => void;
@@ -21,11 +20,9 @@ export declare class SideMenuView<BSchema extends BlockSchema, I extends InlineC
     private hoveredBlock;
     menuFrozen: boolean;
     isDragOrigin: boolean;
-    constructor(editor: BlockNoteEditor<BSchema, I, S>, sideMenuDetection: "viewport" | "editor", pmView: EditorView, emitUpdate: (state: SideMenuState<BSchema, I, S>) => void);
+    constructor(editor: BlockNoteEditor<BSchema, I, S>, pmView: EditorView, emitUpdate: (state: SideMenuState<BSchema, I, S>) => void);
     updateState: (state: SideMenuState<BSchema, I, S>) => void;
     updateStateFromMousePos: () => void;
-    onDrop: (event: DragEvent) => void;
-    onDragEnd: () => void;
     /**
      * If a block is being dragged, ProseMirror usually gets the context of what's
      * being dragged from `view.dragging`, which is automatically set when a
@@ -46,14 +43,58 @@ export declare class SideMenuView<BSchema extends BlockSchema, I extends InlineC
      */
     onDragStart: (event: DragEvent) => void;
     /**
-     * If the event is outside the editor contents,
-     * we dispatch a fake event, so that we can still drop the content
-     * when dragging / dropping to the side of the editor
+     * Finds the closest editor visually to the given coordinates
+     */
+    private findClosestEditorElement;
+    /**
+     * This dragover event handler listens at the document level,
+     * and is trying to handle dragover events for all editors.
+     *
+     * It specifically is trying to handle the following cases:
+     *  - If the dragover event is within the bounds of any editor, then it does nothing
+     *  - If the dragover event is outside the bounds of any editor, but close enough (within DISTANCE_TO_CONSIDER_EDITOR_BOUNDS) to the closest editor,
+     *    then it dispatches a synthetic dragover event to the closest editor (which will trigger the drop-cursor to be shown on that editor)
+     *  - If the dragover event is outside the bounds of the current editor, then it will dispatch a synthetic dragleave event to the current editor
+     *    (which will trigger the drop-cursor to be removed from the current editor)
+     *
+     * The synthetic event is a necessary evil because we do not control prosemirror-dropcursor to be able to show the drop-cursor within the range we want
      */
     onDragOver: (event: DragEvent) => void;
+    /**
+     * Closes the drop-cursor for the current editor
+     */
+    private closeDropCursor;
+    /**
+     * It is surprisingly difficult to determine the information we need to know about a drag event
+     *
+     * This function is trying to determine the following:
+     *  - Whether the current editor instance is the drop point
+     *  - Whether the current editor instance is the drag origin
+     *  - Whether the drop event is within the bounds of the current editor instance
+     */
+    getDragEventContext: (event: DragEvent) => {
+        isDropPoint: boolean;
+        isDropWithinEditorBounds: boolean;
+        isDragOrigin: boolean;
+    } | undefined;
+    /**
+     * The drop event handler listens at the document level,
+     * and handles drop events for all editors.
+     *
+     * It specifically handles the following cases:
+     *  - If we are both the drag origin and drop point:
+     *    - Let normal drop handling take over
+     *  - If we are the drop point but not the drag origin:
+     *    - Collapse selection to prevent PM from deleting unrelated content
+     *    - If drop event is outside our editor bounds, dispatch synthetic drop event to our editor
+     *  - If we are the drag origin but not the drop point:
+     *    - Delete the dragged content from our editor after a delay
+     */
+    onDrop: (event: DragEvent) => void;
+    onDragEnd: (event: DragEvent) => void;
     onKeyDown: (_event: KeyboardEvent) => void;
     onMouseMove: (event: MouseEvent) => void;
-    private createSyntheticEvent;
+    private dispatchSyntheticEvent;
     onScroll: () => void;
     update(_view: EditorView, prevState: EditorState): void;
     destroy(): void;
@@ -63,7 +104,7 @@ export declare class SideMenuProsemirrorPlugin<BSchema extends BlockSchema, I ex
     private readonly editor;
     static key(): string;
     view: SideMenuView<BSchema, I, S> | undefined;
-    constructor(editor: BlockNoteEditor<BSchema, I, S>, sideMenuDetection: "viewport" | "editor");
+    constructor(editor: BlockNoteEditor<BSchema, I, S>);
     onUpdate(callback: (state: SideMenuState<BSchema, I, S>) => void): () => void;
     /**
      * Handles drag & drop events for blocks.

package/types/src/schema/inlineContent/types.d.ts

@@ -4,12 +4,16 @@ import { StyleSchema, Styles } from "../styles/types.js";
 export type CustomInlineContentConfig = {
     type: string;
     content: "styled" | "none";
+    draggable?: boolean;
     readonly propSchema: PropSchema;
 };
 export type InlineContentConfig = CustomInlineContentConfig | "text" | "link";
 export type InlineContentImplementation<T extends InlineContentConfig> = T extends "link" | "text" ? undefined : {
     node: Node;
 };
+export type InlineContentSchemaWithInlineContent<IType extends string, C extends InlineContentConfig> = {
+    [k in IType]: C;
+};
 export type InlineContentSpec<T extends InlineContentConfig> = {
     config: T;
     implementation: InlineContentImplementation<T>;