@blocknote/core 0.4.0 → 0.4.2

package/package.json

@@ -3,7 +3,7 @@
   "homepage": "https://github.com/yousefed/blocknote",
   "private": false,
   "license": "MPL-2.0",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "files": [
     "dist",
     "types",
@@ -106,5 +106,5 @@
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
-  "gitHead": "aa88219581e5427fd86c759b827ffc2b2f3af99b"
+  "gitHead": "14086236a83e42c1de7e4d9910e6348218e78a98"
 }

package/src/BlockNoteEditor.ts

@@ -7,14 +7,15 @@ import styles from "./editor.module.css";
 import { defaultSlashCommands, SlashCommand } from "./extensions/SlashMenu";
 
 export type BlockNoteEditorOptions = {
+  // TODO: Figure out if enableBlockNoteExtensions/disableHistoryExtension are needed and document them.
   enableBlockNoteExtensions: boolean;
   disableHistoryExtension: boolean;
   uiFactories: UiFactories;
   slashCommands: SlashCommand[];
   parentElement: HTMLElement;
   editorDOMAttributes: Record<string, string>;
-  onUpdate: () => void;
-  onCreate: () => void;
+  onUpdate: (editor: BlockNoteEditor) => void;
+  onCreate: (editor: BlockNoteEditor) => void;
 
   // tiptap options, undocumented
   _tiptapOptions: any;
@@ -47,10 +48,10 @@ export class BlockNoteEditor extends EditorAPI {
       ...blockNoteTipTapOptions,
       ...options._tiptapOptions,
       onUpdate: () => {
-        options.onUpdate?.();
+        options.onUpdate?.(this);
       },
       onCreate: () => {
-        options.onCreate?.();
+        options.onCreate?.(this);
       },
       extensions:
         options.enableBlockNoteExtensions === false

package/src/BlockNoteExtensions.ts

@@ -1,16 +1,16 @@
 import { Extensions, extensions } from "@tiptap/core";
 
-import Bold from "@tiptap/extension-bold";
-import Code from "@tiptap/extension-code";
-import DropCursor from "@tiptap/extension-dropcursor";
-import GapCursor from "@tiptap/extension-gapcursor";
-import HardBreak from "@tiptap/extension-hard-break";
+import { Bold } from "@tiptap/extension-bold";
+import { Code } from "@tiptap/extension-code";
+import { Dropcursor } from "@tiptap/extension-dropcursor";
+import { Gapcursor } from "@tiptap/extension-gapcursor";
+import { HardBreak } from "@tiptap/extension-hard-break";
 import { History } from "@tiptap/extension-history";
-import Italic from "@tiptap/extension-italic";
+import { Italic } from "@tiptap/extension-italic";
 import { Link } from "@tiptap/extension-link";
-import Strike from "@tiptap/extension-strike";
-import Text from "@tiptap/extension-text";
-import Underline from "@tiptap/extension-underline";
+import { Strike } from "@tiptap/extension-strike";
+import { Text } from "@tiptap/extension-text";
+import { Underline } from "@tiptap/extension-underline";
 import { BackgroundColorExtension } from "./extensions/BackgroundColor/BackgroundColorExtension";
 import { BackgroundColorMark } from "./extensions/BackgroundColor/BackgroundColorMark";
 import { blocks } from "./extensions/Blocks";
@@ -53,7 +53,7 @@ export const getBlockNoteExtensions = (opts: {
     extensions.Tabindex,
 
     // DevTools,
-    GapCursor,
+    Gapcursor,
 
     // DropCursor,
     Placeholder.configure({
@@ -87,7 +87,7 @@ export const getBlockNoteExtensions = (opts: {
     // custom blocks:
     ...blocks,
 
-    DropCursor.configure({ width: 5, color: "#ddeeff" }),
+    Dropcursor.configure({ width: 5, color: "#ddeeff" }),
     History,
     // This needs to be at the bottom of this list, because Key events (such as enter, when selecting a /command),
     // should be handled before Enter handlers in other components like splitListItem

package/src/api/Editor.ts

@@ -1,7 +1,11 @@
 import { Editor as TiptapEditor } from "@tiptap/core";
 import { Node } from "prosemirror-model";
 import { getBlockInfoFromPos } from "../extensions/Blocks/helpers/getBlockInfoFromPos";
-import { Block, PartialBlock } from "../extensions/Blocks/api/blockTypes";
+import {
+  Block,
+  BlockIdentifier,
+  PartialBlock,
+} from "../extensions/Blocks/api/blockTypes";
 import { TextCursorPosition } from "../extensions/Blocks/api/cursorPositionTypes";
 import { nodeToBlock } from "./nodeConversions/nodeConversions";
 import {
@@ -24,9 +28,10 @@ export class Editor {
   ) {}
 
   /**
-   * Gets a list of all top-level blocks that are in the editor.
+   * Gets a snapshot of all top-level blocks that are in the editor.
+   * @returns An array containing a snapshot of all top-level (non-nested) blocks in the editor.
    */
-  public get allBlocks(): Block[] {
+  public get topLevelBlocks(): Block[] {
     const blocks: Block[] = [];
 
     this.tiptapEditor.state.doc.firstChild!.descendants((node) => {
@@ -39,7 +44,82 @@ export class Editor {
   }
 
   /**
-   * Gets information regarding the position of the text cursor in the editor.
+   * Retrieves a snapshot of an existing block from the editor.
+   * @param block 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(block: BlockIdentifier): Block | undefined {
+    const id = typeof block === "string" ? block : block.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, 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. Stops traversal if the callback
+   * returns false;
+   * @param callback The callback to execute for each block.
+   * @param reverse Whether the blocks should be traversed in reverse order.
+   */
+  public forEachBlock(
+    callback: (block: Block) => boolean,
+    reverse: boolean = false
+  ): void {
+    let stop = false;
+
+    function helper(blocks: Block[]) {
+      if (reverse) {
+        for (const block of blocks.reverse()) {
+          helper(block.children);
+
+          if (stop) {
+            return;
+          }
+
+          stop = !callback(block);
+
+          if (stop) {
+            return;
+          }
+        }
+      } else {
+        for (const block of blocks) {
+          stop = !callback(block);
+
+          if (stop) {
+            return;
+          }
+
+          helper(block.children);
+
+          if (stop) {
+            return;
+          }
+        }
+      }
+    }
+
+    helper(this.topLevelBlocks);
+  }
+
+  /**
+   * Gets a snapshot of the text cursor position within the editor.
+   * @returns A snapshot of the text cursor position.
    */
   public get textCursorPosition(): TextCursorPosition {
     const { node } = getBlockInfoFromPos(
@@ -97,7 +177,7 @@ export class Editor {
   }
 
   /**
-   * Executes a callback function whenever the editor's content changes.
+   * Executes a callback function whenever the editor's contents change.
    * @param callback The callback function to execute.
    */
   public onContentChange(callback: () => void) {
@@ -109,6 +189,7 @@ export class Editor {
    * 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.
+   * @returns An HTML representation of the blocks.
    */
   public async blocksToHTML(blocks: Block[]): Promise<string> {
     return blocksToHTML(blocks, this.tiptapEditor.schema);
@@ -117,6 +198,7 @@ export class Editor {
   /**
    * Creates a list of blocks from an HTML string.
    * @param htmlString The HTML string to create a list of blocks from.
+   * @returns A list of blocks parsed from the HTML string.
    */
   public async HTMLToBlocks(htmlString: string): Promise<Block[]> {
     return HTMLToBlocks(htmlString, this.tiptapEditor.schema);
@@ -125,8 +207,9 @@ export class Editor {
   /**
    * 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.
+   * un-nested, and certain styles are removed.
    * @param blocks The list of blocks to serialize into Markdown.
+   * @returns A Markdown representation of the blocks.
    */
   public async blocksToMarkdown(blocks: Block[]): Promise<string> {
     return blocksToMarkdown(blocks, this.tiptapEditor.schema);
@@ -135,6 +218,7 @@ export class Editor {
   /**
    * Creates a list of blocks from a Markdown string.
    * @param markdownString The Markdown string to create a list of blocks from.
+   * @returns A list of blocks parsed from the Markdown string.
    */
   public async markdownToBlocks(markdownString: string): Promise<Block[]> {
     return markdownToBlocks(markdownString, this.tiptapEditor.schema);