Slash Menu Commands Customization (#113)

* update v

* wip poc

* poc

* api poc

* Implemented basic block retrieval API functions

* tiny fixes

* Added marks API support, block conversion/insertion functions, and WIP markdown conversion

* Changed markdown parsing to use remark

* Added API support for serializing blocks to HTML and Markdown

* General cleanup & refactor

* Implemented PR feedback

* Added documentation to API functions

* Added basic HTML/Markdown conversion test cases and fixed some bugs

* Added more HTML/Markdown conversion test cases

* Fixed comments

* Added HTML/Markdown conversion test snapshots

* Small changes

* initial website

* Added text content for several sections

* Added API functions to update and remove blocks, improved distinction between `Block` and `BlockSpec` types

* Added "Accessing Blocks", "BlockSpec Objects" sections and other changes

* Finished text content for Introduction to Blocks

* Finished text content for Introduction

* Finished text content for Quickstart

* Finished text content for Manipulating Blocks

* Small change to Block Types

* update homepage

* update site

* Changes to most pages' text content and added live demos

* Added remaining unit tests

* sandpack vertical

* add vanilla js docs

* comment

* temp expose api

* Changed `BlockSpec` to `PartialBlock` and improved error messages

* add draggable to vanillajs example

* Added `replaceBlock` function, updated others.

* Added global props

* Fixed node conversion tests & snapshots

* Fixed format conversion tests & snapshots

* Fixed block manipulation tests & snapshots

* Commented out failing format conversion tests

* Fixed build failures

* Fixed list item parsing issue

* Changed API file structure

* Moved type import to dev dependencies

* Added `PartialBlock` and `replaceBlocks()` text

* changes to intro

* fix lockfile

* Updated editor API docs

* make api accessible via editor, hide tiptap initialization options (#106)

* make api accessible via editor, hide tiptap initialization options

* remove comment

* Fixed tests

* Fixed tests

* small renames + expose domElement

* improve block types

* Small fix to PartialBlock type

* Removed logs

* add comments about waitForEditor

---------

Co-authored-by: Matthew Lipski <[email protected]>

* add comment

* clean up timeout

* small cleanup

* rename to InlineContent

* Simplified text

* doc improvements

* Finished block types and other changes

* doc updates

* fix handlers and padding

* Added text cursor and inline content text

* General doc fixes

* doc suggestions

* unset css for heading

* Added customizing editor and small changes

* Removed generic inline content definition

* small doc fixes

* Changed styles structure

* Updated test screenshots

* Added React slash menu items

* Added icon to `ReactSlashMenuItem`

* Updated suggestion/slash menu item definitions and default commands

* small improvements

* Merged `EditorFunctions` and `BlockNoteEditor`

* Deleted `EditorFunctions` and updated docs

* Updated test screenshot

* Small changes

---------

Co-authored-by: yousefed <[email protected]>

Author: matthewlipski

examples/vanilla/src/ui/blockSideMenuFactory.ts

@@ -35,7 +35,6 @@ export const blockSideMenuFactory: BlockSideMenuFactory = (staticParams) => {
         container.style.display = "block";
       }
 
-      console.log("show blockmenu", params);
       container.style.top = params.referenceRect.y + "px";
       container.style.left =
         params.referenceRect.x - container.offsetWidth + "px";

examples/vanilla/src/ui/hyperlinkToolbarFactory.ts

@@ -43,7 +43,6 @@ export const hyperlinkToolbarFactory: HyperlinkToolbarFactory = (
         container.style.display = "block";
       }
 
-      console.log("show", params);
       container.style.top = params.referenceRect.y + "px";
       container.style.left = params.referenceRect.x + "px";
     },

examples/vanilla/src/ui/slashMenuFactory.ts

@@ -1,11 +1,11 @@
-import { SlashMenuItem, SuggestionsMenuFactory } from "@blocknote/core";
+import { BaseSlashMenuItem, SuggestionsMenuFactory } from "@blocknote/core";
 import { createButton } from "./util";
 
 /**
  * This menu is drawn when the cursor is moved to a hyperlink (using the keyboard),
  * or when the mouse is hovering over a hyperlink
  */
-export const slashMenuFactory: SuggestionsMenuFactory<SlashMenuItem> = (
+export const slashMenuFactory: SuggestionsMenuFactory<BaseSlashMenuItem> = (
   staticParams
 ) => {
   const container = document.createElement("div");
@@ -17,8 +17,8 @@ export const slashMenuFactory: SuggestionsMenuFactory<SlashMenuItem> = (
   document.body.appendChild(container);
 
   function updateItems(
-    items: SlashMenuItem[],
-    onClick: (item: SlashMenuItem) => void,
+    items: BaseSlashMenuItem[],
+    onClick: (item: BaseSlashMenuItem) => void,
     selected: number
   ) {
     container.innerHTML = "";
@@ -49,7 +49,6 @@ export const slashMenuFactory: SuggestionsMenuFactory<SlashMenuItem> = (
         container.style.display = "block";
       }
 
-      console.log("show", params);
       container.style.top = params.referenceRect.y + "px";
       container.style.left = params.referenceRect.x + "px";
     },

packages/core/src/BlockNoteEditor.ts

@@ -1,17 +1,37 @@
 import { Editor, EditorOptions } from "@tiptap/core";
-
+import { Node } from "prosemirror-model";
 // import "./blocknote.css";
-import { Editor as EditorAPI } from "./api/Editor";
+import { Block, PartialBlock } from "./extensions/Blocks/api/blockTypes";
 import { getBlockNoteExtensions, UiFactories } from "./BlockNoteExtensions";
 import styles from "./editor.module.css";
-import { defaultSlashCommands, SlashCommand } from "./extensions/SlashMenu";
+import {
+  defaultSlashMenuItems,
+  BaseSlashMenuItem,
+} from "./extensions/SlashMenu";
+import { Editor as TiptapEditor } from "@tiptap/core/dist/packages/core/src/Editor";
+import { nodeToBlock } from "./api/nodeConversions/nodeConversions";
+import { TextCursorPosition } from "./extensions/Blocks/api/cursorPositionTypes";
+import { getBlockInfoFromPos } from "./extensions/Blocks/helpers/getBlockInfoFromPos";
+import { getNodeById } from "./api/util/nodeUtil";
+import {
+  insertBlocks,
+  updateBlock,
+  removeBlocks,
+  replaceBlocks,
+} from "./api/blockManipulation/blockManipulation";
+import {
+  blocksToHTML,
+  HTMLToBlocks,
+  blocksToMarkdown,
+  markdownToBlocks,
+} from "./api/formatConversions/formatConversions";
 
 export type BlockNoteEditorOptions = {
   // TODO: Figure out if enableBlockNoteExtensions/disableHistoryExtension are needed and document them.
   enableBlockNoteExtensions: boolean;
   disableHistoryExtension: boolean;
   uiFactories: UiFactories;
-  slashCommands: SlashCommand[];
+  slashCommands: BaseSlashMenuItem[];
   parentElement: HTMLElement;
   editorDOMAttributes: Record<string, string>;
   onUpdate: (editor: BlockNoteEditor) => void;
@@ -27,17 +47,19 @@ const blockNoteTipTapOptions = {
   enableCoreExtensions: false,
 };
 
-export class BlockNoteEditor extends EditorAPI {
-  public readonly _tiptapEditor: Editor & { contentComponent: any };
+export class BlockNoteEditor {
+  public readonly _tiptapEditor: TiptapEditor & { contentComponent: any };
+  private blockCache = new WeakMap<Node, Block>();
 
   public get domElement() {
     return this._tiptapEditor.view.dom as HTMLDivElement;
   }
 
   constructor(options: Partial<BlockNoteEditorOptions> = {}) {
     const blockNoteExtensions = getBlockNoteExtensions({
+      editor: this,
       uiFactories: options.uiFactories || {},
-      slashCommands: options.slashCommands || defaultSlashCommands,
+      slashCommands: options.slashCommands || defaultSlashMenuItems,
     });
 
     let extensions = options.disableHistoryExtension
@@ -69,10 +91,210 @@ export class BlockNoteEditor extends EditorAPI {
       },
     };
 
-    const _tiptapEditor = new Editor(tiptapOptions) as Editor & {
+    this._tiptapEditor = new Editor(tiptapOptions) as Editor & {
       contentComponent: any;
     };
-    super(_tiptapEditor);
-    this._tiptapEditor = _tiptapEditor;
+  }
+
+  /**
+   * Gets a list of all top-level blocks that are in the editor.
+   */
+  public get topLevelBlocks(): Block[] {
+    const blocks: Block[] = [];
+
+    this._tiptapEditor.state.doc.firstChild!.descendants((node) => {
+      blocks.push(nodeToBlock(node, this.blockCache));
+
+      return false;
+    });
+
+    return blocks;
+  }
+
+  /**
+   * 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.
+   * @param reverse Whether the blocks should be traversed in reverse order.
+   */
+  public allBlocks(
+    callback: (block: Block) => void,
+    reverse: boolean = false
+  ): void {
+    function helper(blocks: Block[]) {
+      if (reverse) {
+        for (const block of blocks.reverse()) {
+          helper(block.children);
+          callback(block);
+        }
+      } else {
+        for (const block of blocks) {
+          callback(block);
+          helper(block.children);
+        }
+      }
+    }
+
+    helper(this.topLevelBlocks);
+  }
+
+  /**
+   * Gets information regarding the position of the text cursor in the editor.
+   */
+  public getTextCursorPosition(): TextCursorPosition {
+    const { node, depth, startPos, endPos } = getBlockInfoFromPos(
+      this._tiptapEditor.state.doc,
+      this._tiptapEditor.state.selection.from
+    )!;
+
+    // Index of the current blockContainer node relative to its parent blockGroup.
+    const nodeIndex = this._tiptapEditor.state.doc
+      .resolve(endPos)
+      .index(depth - 1);
+    // Number of the parent blockGroup's child blockContainer nodes.
+    const numNodes = this._tiptapEditor.state.doc
+      .resolve(endPos + 1)
+      .node().childCount;
+
+    // Gets previous blockContainer node at the same nesting level, if the current node isn't the first child.
+    let prevNode: Node | undefined = undefined;
+    if (nodeIndex > 0) {
+      prevNode = this._tiptapEditor.state.doc.resolve(startPos - 2).node();
+    }
+
+    // Gets next blockContainer node at the same nesting level, if the current node isn't the last child.
+    let nextNode: Node | undefined = undefined;
+    if (nodeIndex < numNodes - 1) {
+      nextNode = this._tiptapEditor.state.doc.resolve(endPos + 2).node();
+    }
+
+    return {
+      block: nodeToBlock(node, this.blockCache),
+      prevBlock:
+        prevNode === undefined
+          ? undefined
+          : nodeToBlock(prevNode, this.blockCache),
+      nextBlock:
+        nextNode === undefined
+          ? undefined
+          : nodeToBlock(nextNode, this.blockCache),
+    };
+  }
+
+  public setTextCursorPosition(
+    block: Block,
+    placement: "start" | "end" = "start"
+  ) {
+    const { posBeforeNode } = getNodeById(
+      block.id,
+      this._tiptapEditor.state.doc
+    );
+    const { startPos, contentNode } = getBlockInfoFromPos(
+      this._tiptapEditor.state.doc,
+      posBeforeNode + 2
+    )!;
+
+    if (placement === "start") {
+      this._tiptapEditor.commands.setTextSelection(startPos + 1);
+    } else {
+      this._tiptapEditor.commands.setTextSelection(
+        startPos + contentNode.nodeSize - 1
+      );
+    }
+  }
+
+  /**
+   * 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.
+   */
+  public insertBlocks(
+    blocksToInsert: PartialBlock[],
+    blockToInsertAt: Block,
+    placement: "before" | "after" | "nested" = "before"
+  ): void {
+    insertBlocks(
+      blocksToInsert,
+      blockToInsertAt,
+      placement,
+      this._tiptapEditor
+    );
+  }
+
+  /**
+   * Updates a block in the editor to the given specification.
+   * @param blockToUpdate The block that should be updated.
+   * @param updatedBlock The specification that the block should be updated to.
+   */
+  public updateBlock(blockToUpdate: Block, updatedBlock: PartialBlock) {
+    updateBlock(blockToUpdate, updatedBlock, 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.
+   */
+  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.
+   * @param blocksToRemove An array of blocks that should be replaced.
+   * @param blocksToInsert An array of blocks to replace the old ones with.
+   */
+  public replaceBlocks(
+    blocksToRemove: Block[],
+    blocksToInsert: PartialBlock[]
+  ) {
+    replaceBlocks(blocksToRemove, blocksToInsert, this._tiptapEditor);
+  }
+
+  /**
+   * 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.
+   */
+  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.
+   */
+  public async HTMLToBlocks(htmlString: string): Promise<Block[]> {
+    return HTMLToBlocks(htmlString, 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.
+   */
+  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.
+   */
+  public async markdownToBlocks(markdownString: string): Promise<Block[]> {
+    return markdownToBlocks(markdownString, this._tiptapEditor.schema);
   }
 }

packages/core/src/BlockNoteExtensions.ts

@@ -1,5 +1,7 @@
 import { Extensions, extensions } from "@tiptap/core";
 
+import { BlockNoteEditor } from "./BlockNoteEditor";
+
 import { Bold } from "@tiptap/extension-bold";
 import { Code } from "@tiptap/extension-code";
 import { Dropcursor } from "@tiptap/extension-dropcursor";
@@ -22,8 +24,8 @@ import { FormattingToolbarFactory } from "./extensions/FormattingToolbar/Formatt
 import HyperlinkMark from "./extensions/HyperlinkToolbar/HyperlinkMark";
 import { HyperlinkToolbarFactory } from "./extensions/HyperlinkToolbar/HyperlinkToolbarFactoryTypes";
 import { Placeholder } from "./extensions/Placeholder/PlaceholderExtension";
-import { SlashCommand, SlashMenuExtension } from "./extensions/SlashMenu";
-import { SlashMenuItem } from "./extensions/SlashMenu/SlashMenuItem";
+import { SlashMenuExtension } from "./extensions/SlashMenu";
+import { BaseSlashMenuItem } from "./extensions/SlashMenu";
 import { TextAlignmentExtension } from "./extensions/TextAlignment/TextAlignmentExtension";
 import { TextColorExtension } from "./extensions/TextColor/TextColorExtension";
 import { TextColorMark } from "./extensions/TextColor/TextColorMark";
@@ -34,16 +36,17 @@ import { SuggestionsMenuFactory } from "./shared/plugins/suggestion/SuggestionsM
 export type UiFactories = Partial<{
   formattingToolbarFactory: FormattingToolbarFactory;
   hyperlinkToolbarFactory: HyperlinkToolbarFactory;
-  slashMenuFactory: SuggestionsMenuFactory<SlashMenuItem>;
+  slashMenuFactory: SuggestionsMenuFactory<BaseSlashMenuItem>;
   blockSideMenuFactory: BlockSideMenuFactory;
 }>;
 
 /**
  * Get all the Tiptap extensions BlockNote is configured with by default
  */
 export const getBlockNoteExtensions = (opts: {
+  editor: BlockNoteEditor;
   uiFactories: UiFactories;
-  slashCommands: SlashCommand[];
+  slashCommands: BaseSlashMenuItem[];
 }) => {
   const ret: Extensions = [
     extensions.ClipboardTextSerializer,
@@ -123,6 +126,7 @@ export const getBlockNoteExtensions = (opts: {
   if (opts.uiFactories.slashMenuFactory) {
     ret.push(
       SlashMenuExtension.configure({
+        editor: opts.editor,
         commands: opts.slashCommands,
         slashMenuFactory: opts.uiFactories.slashMenuFactory,
       })