@blocknote/core 0.4.3 → 0.4.4

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://github.com/yousefed/blocknote",
   "private": false,
   "license": "MPL-2.0",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "files": [
     "dist",
     "types",
@@ -106,5 +106,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "gitHead": "4f578e0a8676b815316bdeb978cd4748d948868c"
+  "gitHead": "9d8f356669e7f644ee437aad0df07b4cc37a0083"
 }

package/src/BlockNoteEditor.ts

@@ -1,7 +1,11 @@
 import { Editor, EditorOptions } from "@tiptap/core";
 import { Node } from "prosemirror-model";
 // import "./blocknote.css";
-import { Block, PartialBlock } from "./extensions/Blocks/api/blockTypes";
+import {
+  Block,
+  BlockIdentifier,
+  PartialBlock,
+} from "./extensions/Blocks/api/blockTypes";
 import { getBlockNoteExtensions, UiFactories } from "./BlockNoteExtensions";
 import styles from "./editor.module.css";
 import {
@@ -34,8 +38,9 @@ export type BlockNoteEditorOptions = {
   slashCommands: BaseSlashMenuItem[];
   parentElement: HTMLElement;
   editorDOMAttributes: Record<string, string>;
-  onUpdate: (editor: BlockNoteEditor) => void;
-  onCreate: (editor: BlockNoteEditor) => void;
+  onEditorCreate: (editor: BlockNoteEditor) => void;
+  onEditorContentChange: (editor: BlockNoteEditor) => void;
+  onTextCursorPositionChange: (editor: BlockNoteEditor) => void;
 
   // tiptap options, undocumented
   _tiptapOptions: any;
@@ -69,11 +74,14 @@ export class BlockNoteEditor {
     const tiptapOptions: EditorOptions = {
       ...blockNoteTipTapOptions,
       ...options._tiptapOptions,
+      onCreate: () => {
+        options.onEditorCreate?.(this);
+      },
       onUpdate: () => {
-        options.onUpdate?.(this);
+        options.onEditorContentChange?.(this);
       },
-      onCreate: () => {
-        options.onCreate?.(this);
+      onSelectionUpdate: () => {
+        options.onTextCursorPositionChange?.(this);
       },
       extensions:
         options.enableBlockNoteExtensions === false
@@ -97,7 +105,8 @@ export class BlockNoteEditor {
   }
 
   /**
-   * Gets a list of all top-level blocks that are in the editor.
+   * Gets a snapshot of all top-level (non-nested) blocks in the editor.
+   * @returns A snapshot of all top-level (non-nested) blocks in the editor.
    */
   public get topLevelBlocks(): Block[] {
     const blocks: Block[] = [];
@@ -112,12 +121,40 @@ export class BlockNoteEditor {
   }
 
   /**
-   * Traverses all blocks in the editor, including all nested blocks, and executes a callback for each. The traversal is
-   * depth-first, which is the same order as blocks appear in the editor by y-coordinate.
-   * @param callback The callback to execute for each block.
+   * Gets a snapshot of an existing block from the editor.
+   * @param blockIdentifier The identifier of an existing block that should be retrieved.
+   * @returns The block that matches the identifier, or `undefined` if no matching block was found.
+   */
+  public getBlock(blockIdentifier: BlockIdentifier): Block | undefined {
+    const id =
+      typeof blockIdentifier === "string"
+        ? blockIdentifier
+        : blockIdentifier.id;
+    let newBlock: Block | undefined = undefined;
+
+    this._tiptapEditor.state.doc.firstChild!.descendants((node) => {
+      if (typeof newBlock !== "undefined") {
+        return false;
+      }
+
+      if (node.type.name !== "blockContainer" || node.attrs.id !== id) {
+        return true;
+      }
+
+      newBlock = nodeToBlock(node, this.blockCache);
+
+      return false;
+    });
+
+    return newBlock;
+  }
+
+  /**
+   * Traverses all blocks in the editor depth-first, and executes a callback for each.
+   * @param callback The callback to execute for each block. Returning `false` stops the traversal.
    * @param reverse Whether the blocks should be traversed in reverse order.
    */
-  public allBlocks(
+  public forEachBlock(
     callback: (block: Block) => void,
     reverse: boolean = false
   ): void {
@@ -139,7 +176,8 @@ export class BlockNoteEditor {
   }
 
   /**
-   * Gets information regarding the position of the text cursor in the editor.
+   * Gets a snapshot of the current text cursor position.
+   * @returns A snapshot of the current text cursor position.
    */
   public getTextCursorPosition(): TextCursorPosition {
     const { node, depth, startPos, endPos } = getBlockInfoFromPos(
@@ -181,14 +219,19 @@ export class BlockNoteEditor {
     };
   }
 
+  /**
+   * Sets the text cursor position to the start or end of an existing block. Throws an error if the target block could
+   * not be found.
+   * @param targetBlock The identifier of an existing block that the text cursor should be moved to.
+   * @param placement Whether the text cursor should be placed at the start or end of the block.
+   */
   public setTextCursorPosition(
-    block: Block,
+    targetBlock: BlockIdentifier,
     placement: "start" | "end" = "start"
   ) {
-    const { posBeforeNode } = getNodeById(
-      block.id,
-      this._tiptapEditor.state.doc
-    );
+    const id = typeof targetBlock === "string" ? targetBlock : targetBlock.id;
+
+    const { posBeforeNode } = getNodeById(id, this._tiptapEditor.state.doc);
     const { startPos, contentNode } = getBlockInfoFromPos(
       this._tiptapEditor.state.doc,
       posBeforeNode + 2
@@ -204,48 +247,46 @@ export class BlockNoteEditor {
   }
 
   /**
-   * Inserts multiple blocks before, after, or nested inside an existing block in the editor.
-   * @param blocksToInsert An array of blocks to insert.
-   * @param blockToInsertAt An existing block, marking where the new blocks should be inserted at.
-   * @param placement Determines whether the blocks should be inserted just before, just after, or nested inside the
-   * existing block.
+   * Inserts new blocks into the editor. If a block's `id` is undefined, BlockNote generates one automatically. Throws an
+   * error if the reference block could not be found.
+   * @param blocksToInsert An array of partial blocks that should be inserted.
+   * @param referenceBlock An identifier for an existing block, at which the new blocks should be inserted.
+   * @param placement Whether the blocks should be inserted just before, just after, or nested inside the
+   * `referenceBlock`. Inserts the blocks at the start of the existing block's children if "nested" is used.
    */
   public insertBlocks(
     blocksToInsert: PartialBlock[],
-    blockToInsertAt: Block,
+    referenceBlock: BlockIdentifier,
     placement: "before" | "after" | "nested" = "before"
   ): void {
-    insertBlocks(
-      blocksToInsert,
-      blockToInsertAt,
-      placement,
-      this._tiptapEditor
-    );
+    insertBlocks(blocksToInsert, referenceBlock, placement, this._tiptapEditor);
   }
 
   /**
-   * Updates a block in the editor to the given specification.
+   * Updates an existing block in the editor. Since updatedBlock is a PartialBlock object, some fields might not be
+   * defined. These undefined fields are kept as-is from the existing block. Throws an error if the block to update could
+   * not be found.
    * @param blockToUpdate The block that should be updated.
-   * @param updatedBlock The specification that the block should be updated to.
+   * @param update A partial block which defines how the existing block should be changed.
    */
-  public updateBlock(blockToUpdate: Block, updatedBlock: PartialBlock) {
-    updateBlock(blockToUpdate, updatedBlock, this._tiptapEditor);
+  public updateBlock(blockToUpdate: Block, update: PartialBlock) {
+    updateBlock(blockToUpdate, update, this._tiptapEditor);
   }
 
   /**
-   * Removes multiple blocks from the editor. Throws an error if any of the blocks could not be found.
-   * @param blocksToRemove An array of blocks that should be removed.
+   * Removes existing blocks from the editor. Throws an error if any of the blocks could not be found.
+   * @param blocksToRemove An array of identifiers for existing blocks that should be removed.
    */
   public removeBlocks(blocksToRemove: Block[]) {
     removeBlocks(blocksToRemove, this._tiptapEditor);
   }
 
   /**
-   * Replaces multiple blocks in the editor with several other blocks. If the provided blocks to remove are not adjacent
-   * to each other, the new blocks are inserted at the position of the first block in the array. Throws an error if any
-   * of the blocks could not be found.
+   * Replaces existing blocks in the editor with new blocks. If the blocks that should be removed are not adjacent or
+   * are at different nesting levels, `blocksToInsert` will be inserted at the position of the first block in
+   * `blocksToRemove`. Throws an error if any of the blocks to remove could not be found.
    * @param blocksToRemove An array of blocks that should be replaced.
-   * @param blocksToInsert An array of blocks to replace the old ones with.
+   * @param blocksToInsert An array of partial blocks to replace the old ones with.
    */
   public replaceBlocks(
     blocksToRemove: Block[],
@@ -255,46 +296,44 @@ export class BlockNoteEditor {
   }
 
   /**
-   * Executes a callback function whenever the editor's content changes.
-   * @param callback The callback function to execute.
-   */
-  public onContentChange(callback: () => void) {
-    this._tiptapEditor.on("update", callback);
-  }
-
-  /**
-   * Serializes a list of blocks into an HTML string. The output is not the same as what's rendered by the editor, and
-   * is simplified in order to better conform to HTML standards. Block structuring elements are removed, children of
-   * blocks which aren't list items are lifted out of them, and list items blocks are wrapped in `ul`/`ol` tags.
-   * @param blocks The list of blocks to serialize into HTML.
+   * Serializes blocks into an HTML string. To better conform to HTML standards, children of blocks which aren't list
+   * items are un-nested in the output HTML.
+   * @param blocks An array of blocks that should be serialized into HTML.
+   * @returns The blocks, serialized as an HTML string.
    */
   public async blocksToHTML(blocks: Block[]): Promise<string> {
     return blocksToHTML(blocks, this._tiptapEditor.schema);
   }
 
   /**
-   * Creates a list of blocks from an HTML string.
-   * @param htmlString The HTML string to create a list of blocks from.
+   * Parses blocks from an HTML string. Tries to create `Block` objects out of any HTML block-level elements, and
+   * `InlineNode` objects from any HTML inline elements, though not all element types are recognized. If BlockNote
+   * doesn't recognize an HTML element's tag, it will parse it as a paragraph or plain text.
+   * @param html The HTML string to parse blocks from.
+   * @returns The blocks parsed from the HTML string.
    */
-  public async HTMLToBlocks(htmlString: string): Promise<Block[]> {
-    return HTMLToBlocks(htmlString, this._tiptapEditor.schema);
+  public async HTMLToBlocks(html: string): Promise<Block[]> {
+    return HTMLToBlocks(html, this._tiptapEditor.schema);
   }
 
   /**
-   * Serializes a list of blocks into a Markdown string. The output is simplified as Markdown does not support all
-   * features of BlockNote. Block structuring elements are removed, children of blocks which aren't list items are
-   * lifted out of them, and certain styles are removed.
-   * @param blocks The list of blocks to serialize into Markdown.
+   * Serializes blocks into a Markdown string. The output is simplified as Markdown does not support all features of
+   * BlockNote - children of blocks which aren't list items are un-nested and certain styles are removed.
+   * @param blocks An array of blocks that should be serialized into Markdown.
+   * @returns The blocks, serialized as a Markdown string.
    */
   public async blocksToMarkdown(blocks: Block[]): Promise<string> {
     return blocksToMarkdown(blocks, this._tiptapEditor.schema);
   }
 
   /**
-   * Creates a list of blocks from a Markdown string.
-   * @param markdownString The Markdown string to create a list of blocks from.
+   * Creates a list of blocks from a Markdown string. Tries to create `Block` and `InlineNode` objects based on
+   * Markdown syntax, though not all symbols are recognized. If BlockNote doesn't recognize a symbol, it will parse it
+   * as text.
+   * @param markdown The Markdown string to parse blocks from.
+   * @returns The blocks parsed from the Markdown string.
    */
-  public async markdownToBlocks(markdownString: string): Promise<Block[]> {
-    return markdownToBlocks(markdownString, this._tiptapEditor.schema);
+  public async markdownToBlocks(markdown: string): Promise<Block[]> {
+    return markdownToBlocks(markdown, this._tiptapEditor.schema);
   }
 }

package/src/api/formatConversions/formatConversions.ts

@@ -38,11 +38,11 @@ export async function blocksToHTML(
 }
 
 export async function HTMLToBlocks(
-  htmlString: string,
+  html: string,
   schema: Schema
 ): Promise<Block[]> {
   const htmlNode = document.createElement("div");
-  htmlNode.innerHTML = htmlString.trim();
+  htmlNode.innerHTML = html.trim();
 
   const parser = DOMParser.fromSchema(schema);
   const parentNode = parser.parse(htmlNode);
@@ -72,7 +72,7 @@ export async function blocksToMarkdown(
 }
 
 export async function markdownToBlocks(
-  markdownString: string,
+  markdown: string,
   schema: Schema
 ): Promise<Block[]> {
   const htmlString = await unified()
@@ -80,7 +80,7 @@ export async function markdownToBlocks(
     .use(remarkGfm)
     .use(remarkRehype)
     .use(rehypeStringify)
-    .process(markdownString);
+    .process(markdown);
 
   return HTMLToBlocks(htmlString.value as string, schema);
 }

package/src/extensions/Blocks/nodes/BlockContainer.ts

@@ -110,10 +110,10 @@ export const BlockContainer = Node.create<IBlock>({
 
           return true;
         },
-      // Deletes a block at a given position and sets the selection to where the block was.
+      // Deletes a block at a given position.
       BNDeleteBlock:
         (posInBlock) =>
-        ({ state, view, dispatch }) => {
+        ({ state, dispatch }) => {
           const blockInfo = getBlockInfoFromPos(state.doc, posInBlock);
           if (blockInfo === undefined) {
             return false;
@@ -123,10 +123,89 @@ export const BlockContainer = Node.create<IBlock>({
 
           if (dispatch) {
             state.tr.deleteRange(startPos, endPos);
-            state.tr.setSelection(
-              new TextSelection(state.doc.resolve(startPos + 1))
+          }
+
+          return true;
+        },
+      // Updates a block at a given position.
+      BNUpdateBlock:
+        (posInBlock, block) =>
+        ({ state, dispatch }) => {
+          const blockInfo = getBlockInfoFromPos(state.doc, posInBlock);
+          if (blockInfo === undefined) {
+            return false;
+          }
+
+          const { startPos, endPos, node, contentNode } = blockInfo;
+
+          if (dispatch) {
+            // Adds blockGroup node with child blocks if necessary.
+            if (block.children !== undefined) {
+              const childNodes = [];
+
+              // Creates ProseMirror nodes for each child block, including their descendants.
+              for (const child of block.children) {
+                childNodes.push(blockToNode(child, state.schema));
+              }
+
+              // Checks if a blockGroup node already exists.
+              if (node.childCount === 2) {
+                // Replaces all child nodes in the existing blockGroup with the ones created earlier.
+                state.tr.replace(
+                  startPos + contentNode.nodeSize + 1,
+                  endPos - 1,
+                  new Slice(Fragment.from(childNodes), 0, 0)
+                );
+              } else {
+                // Inserts a new blockGroup containing the child nodes created earlier.
+                state.tr.insert(
+                  startPos + contentNode.nodeSize,
+                  state.schema.nodes["blockGroup"].create({}, childNodes)
+                );
+              }
+            }
+
+            // Replaces the blockContent node's content if necessary.
+            if (block.content !== undefined) {
+              let content: PMNode[] = [];
+
+              // Checks if the provided content is a string or InlineContent[] type.
+              if (typeof block.content === "string") {
+                // Adds a single text node with no marks to the content.
+                content.push(state.schema.text(block.content));
+              } else {
+                // Adds a text node with the provided styles converted into marks to the content, for each InlineContent
+                // object.
+                content = inlineContentToNodes(block.content, state.schema);
+              }
+
+              // Replaces the contents of the blockContent node with the previously created text node(s).
+              state.tr.replace(
+                startPos + 1,
+                startPos + contentNode.nodeSize - 1,
+                new Slice(Fragment.from(content), 0, 0)
+              );
+            }
+
+            // Changes the blockContent node type and adds the provided props as attributes. Also preserves all existing
+            // attributes that are compatible with the new type.
+            state.tr.setNodeMarkup(
+              startPos,
+              block.type === undefined
+                ? undefined
+                : state.schema.nodes[block.type],
+              {
+                ...contentNode.attrs,
+                ...block.props,
+              }
             );
-            view.focus();
+
+            // Adds all provided props as attributes to the parent blockContainer node too, and also preserves existing
+            // attributes.
+            state.tr.setNodeMarkup(startPos - 1, undefined, {
+              ...node.attrs,
+              ...block.props,
+            });
           }
 
           return true;
@@ -283,112 +362,6 @@ export const BlockContainer = Node.create<IBlock>({
 
           return true;
         },
-      // Updates a block to the given specification.
-      BNUpdateBlock:
-        (posInBlock, block) =>
-        ({ state, dispatch }) => {
-          const blockInfo = getBlockInfoFromPos(state.doc, posInBlock);
-          if (blockInfo === undefined) {
-            return false;
-          }
-
-          const { startPos, endPos, node, contentNode } = blockInfo;
-
-          if (dispatch) {
-            // Adds blockGroup node with child blocks if necessary.
-            if (block.children !== undefined) {
-              const childNodes = [];
-
-              // Creates ProseMirror nodes for each child block, including their descendants.
-              for (const child of block.children) {
-                childNodes.push(blockToNode(child, state.schema));
-              }
-
-              // Checks if a blockGroup node already exists.
-              if (node.childCount === 2) {
-                // Replaces all child nodes in the existing blockGroup with the ones created earlier.
-                state.tr.replace(
-                  startPos + contentNode.nodeSize + 1,
-                  endPos - 1,
-                  new Slice(Fragment.from(childNodes), 0, 0)
-                );
-              } else {
-                // Inserts a new blockGroup containing the child nodes created earlier.
-                state.tr.insert(
-                  startPos + contentNode.nodeSize,
-                  state.schema.nodes["blockGroup"].create({}, childNodes)
-                );
-              }
-            }
-
-            // Replaces the blockContent node's content if necessary.
-            if (block.content !== undefined) {
-              let content: PMNode[] = [];
-
-              // Checks if the provided content is a string or InlineContent[] type.
-              if (typeof block.content === "string") {
-                // Adds a single text node with no marks to the content.
-                content.push(state.schema.text(block.content));
-              } else {
-                // Adds a text node with the provided styles converted into marks to the content, for each InlineContent
-                // object.
-                content = inlineContentToNodes(block.content, state.schema);
-              }
-
-              // Replaces the contents of the blockContent node with the previously created text node(s).
-              state.tr.replace(
-                startPos + 1,
-                startPos + contentNode.nodeSize - 1,
-                new Slice(Fragment.from(content), 0, 0)
-              );
-            }
-
-            // Changes the block type and adds the provided props as node attributes. Also preserves all existing node
-            // attributes that are compatible with the new type.
-            state.tr.setNodeMarkup(
-              startPos,
-              block.type === undefined
-                ? undefined
-                : state.schema.nodes[block.type],
-              {
-                ...contentNode.attrs,
-                ...block.props,
-              }
-            );
-          }
-
-          return true;
-        },
-      // Updates a block to the given specification if it's empty, otherwise creates a new block from that specification
-      // below it.
-      BNCreateOrUpdateBlock:
-        (posInBlock, block) =>
-        ({ state, chain }) => {
-          const blockInfo = getBlockInfoFromPos(state.doc, posInBlock);
-          if (blockInfo === undefined) {
-            return false;
-          }
-
-          const { node, startPos, endPos } = blockInfo;
-
-          if (node.textContent.length === 0) {
-            const oldBlockContentPos = startPos + 1;
-
-            return chain()
-              .BNUpdateBlock(posInBlock, block)
-              .setTextSelection(oldBlockContentPos)
-              .run();
-          } else {
-            const newBlockInsertionPos = endPos + 1;
-            const newBlockContentPos = newBlockInsertionPos + 1;
-
-            return chain()
-              .BNCreateBlock(newBlockInsertionPos)
-              .BNUpdateBlock(newBlockContentPos, block)
-              .setTextSelection(newBlockContentPos)
-              .run();
-          }
-        },
     };
   },