@blocknote/core 0.11.2 → 0.12.0

package/src/extensions/SuggestionMenu/SuggestionPlugin.ts

@@ -0,0 +1,353 @@
+import { findParentNode } from "@tiptap/core";
+import { EditorState, Plugin, PluginKey } from "prosemirror-state";
+import { Decoration, DecorationSet, EditorView } from "prosemirror-view";
+
+import type { BlockNoteEditor } from "../../editor/BlockNoteEditor";
+import { BlockSchema, InlineContentSchema, StyleSchema } from "../../schema";
+import { UiElementPosition } from "../../extensions-shared/UiElementPosition";
+import { EventEmitter } from "../../util/EventEmitter";
+
+const findBlock = findParentNode((node) => node.type.name === "blockContainer");
+
+export type SuggestionMenuState = UiElementPosition & {
+  query: string;
+};
+
+class SuggestionMenuView<
+  BSchema extends BlockSchema,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> {
+  private state?: SuggestionMenuState;
+  public emitUpdate: (triggerCharacter: string) => void;
+
+  pluginState: SuggestionPluginState;
+
+  constructor(
+    private readonly editor: BlockNoteEditor<BSchema, I, S>,
+    emitUpdate: (menuName: string, state: SuggestionMenuState) => void
+  ) {
+    this.pluginState = undefined;
+
+    this.emitUpdate = (menuName: string) => {
+      if (!this.state) {
+        throw new Error("Attempting to update uninitialized suggestions menu");
+      }
+
+      emitUpdate(menuName, this.state);
+    };
+
+    document.addEventListener("scroll", this.handleScroll);
+  }
+
+  handleScroll = () => {
+    if (this.state?.show) {
+      const decorationNode = document.querySelector(
+        `[data-decoration-id="${this.pluginState!.decorationId}"]`
+      );
+      this.state.referencePos = decorationNode!.getBoundingClientRect();
+      this.emitUpdate(this.pluginState!.triggerCharacter!);
+    }
+  };
+
+  update(view: EditorView, prevState: EditorState) {
+    const prev: SuggestionPluginState =
+      suggestionMenuPluginKey.getState(prevState);
+    const next: SuggestionPluginState = suggestionMenuPluginKey.getState(
+      view.state
+    );
+
+    // See how the state changed
+    const started = prev === undefined && next !== undefined;
+    const stopped = prev !== undefined && next === undefined;
+    const changed = prev !== undefined && next !== undefined;
+
+    // Cancel when suggestion isn't active
+    if (!started && !changed && !stopped) {
+      return;
+    }
+
+    this.pluginState = stopped ? prev : next;
+
+    if (stopped || !this.editor.isEditable) {
+      this.state!.show = false;
+      this.emitUpdate(this.pluginState!.triggerCharacter);
+
+      return;
+    }
+
+    const decorationNode = document.querySelector(
+      `[data-decoration-id="${this.pluginState!.decorationId}"]`
+    );
+
+    if (this.editor.isEditable) {
+      this.state = {
+        show: true,
+        referencePos: decorationNode!.getBoundingClientRect(),
+        query: this.pluginState!.query,
+      };
+
+      this.emitUpdate(this.pluginState!.triggerCharacter!);
+    }
+  }
+
+  destroy() {
+    document.removeEventListener("scroll", this.handleScroll);
+  }
+
+  closeMenu = () => {
+    this.editor._tiptapEditor.view.dispatch(
+      this.editor._tiptapEditor.view.state.tr.setMeta(
+        suggestionMenuPluginKey,
+        null
+      )
+    );
+  };
+
+  clearQuery = () => {
+    if (this.pluginState === undefined) {
+      return;
+    }
+
+    this.editor._tiptapEditor
+      .chain()
+      .focus()
+      .deleteRange({
+        from:
+          this.pluginState.queryStartPos! -
+          (this.pluginState.fromUserInput
+            ? this.pluginState.triggerCharacter!.length
+            : 0),
+        to: this.editor._tiptapEditor.state.selection.from,
+      })
+      .run();
+  };
+}
+
+type SuggestionPluginState =
+  | {
+      triggerCharacter: string;
+      fromUserInput: boolean;
+      queryStartPos: number;
+      query: string;
+      decorationId: string;
+    }
+  | undefined;
+
+export const suggestionMenuPluginKey = new PluginKey("SuggestionMenuPlugin");
+
+/**
+ * A ProseMirror plugin for suggestions, designed to make '/'-commands possible as well as mentions.
+ *
+ * This is basically a simplified version of TipTap's [Suggestions](https://github.com/ueberdosis/tiptap/tree/db92a9b313c5993b723c85cd30256f1d4a0b65e1/packages/suggestion) plugin.
+ *
+ * This version is adapted from the aforementioned version in the following ways:
+ * - This version supports generic items instead of only strings (to allow for more advanced filtering for example)
+ * - This version hides some unnecessary complexity from the user of the plugin.
+ * - This version handles key events differently
+ */
+export class SuggestionMenuProseMirrorPlugin<
+  BSchema extends BlockSchema,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> extends EventEmitter<any> {
+  private view: SuggestionMenuView<BSchema, I, S> | undefined;
+  public readonly plugin: Plugin;
+
+  private triggerCharacters: string[] = [];
+
+  constructor(editor: BlockNoteEditor<BSchema, I, S>) {
+    super();
+    const triggerCharacters = this.triggerCharacters;
+    this.plugin = new Plugin({
+      key: suggestionMenuPluginKey,
+
+      view: () => {
+        this.view = new SuggestionMenuView<BSchema, I, S>(
+          editor,
+          (triggerCharacter, state) => {
+            this.emit(`update ${triggerCharacter}`, state);
+          }
+        );
+        return this.view;
+      },
+
+      state: {
+        // Initialize the plugin's internal state.
+        init(): SuggestionPluginState {
+          return undefined;
+        },
+
+        // Apply changes to the plugin state from an editor transaction.
+        apply(transaction, prev, _oldState, newState): SuggestionPluginState {
+          // TODO: More clearly define which transactions should be ignored.
+          if (transaction.getMeta("orderedListIndexing") !== undefined) {
+            return prev;
+          }
+
+          // Either contains the trigger character if the menu should be shown,
+          // or null if it should be hidden.
+          const suggestionPluginTransactionMeta: {
+            triggerCharacter: string;
+            fromUserInput?: boolean;
+          } | null = transaction.getMeta(suggestionMenuPluginKey);
+
+          // Only opens a menu of no menu is already open
+          if (
+            typeof suggestionPluginTransactionMeta === "object" &&
+            suggestionPluginTransactionMeta !== null &&
+            prev === undefined
+          ) {
+            return {
+              triggerCharacter:
+                suggestionPluginTransactionMeta.triggerCharacter,
+              fromUserInput:
+                suggestionPluginTransactionMeta.fromUserInput !== false,
+              queryStartPos: newState.selection.from,
+              query: "",
+              decorationId: `id_${Math.floor(Math.random() * 0xffffffff)}`,
+            };
+          }
+
+          // Checks if the menu is hidden, in which case it doesn't need to be hidden or updated.
+          if (prev === undefined) {
+            return prev;
+          }
+
+          // Checks if the menu should be hidden.
+          if (
+            // Highlighting text should hide the menu.
+            newState.selection.from !== newState.selection.to ||
+            // Transactions with plugin metadata should hide the menu.
+            suggestionPluginTransactionMeta === null ||
+            // Certain mouse events should hide the menu.
+            // TODO: Change to global mousedown listener.
+            transaction.getMeta("focus") ||
+            transaction.getMeta("blur") ||
+            transaction.getMeta("pointer") ||
+            // Moving the caret before the character which triggered the menu should hide it.
+            (prev.triggerCharacter !== undefined &&
+              newState.selection.from < prev.queryStartPos!)
+          ) {
+            return undefined;
+          }
+
+          const next = { ...prev };
+
+          // Updates the current query.
+          next.query = newState.doc.textBetween(
+            prev.queryStartPos!,
+            newState.selection.from
+          );
+
+          return next;
+        },
+      },
+
+      props: {
+        handleKeyDown(view, event) {
+          const suggestionPluginState: SuggestionPluginState = (
+            this as Plugin
+          ).getState(view.state);
+
+          if (
+            triggerCharacters.includes(event.key) &&
+            suggestionPluginState === undefined
+          ) {
+            event.preventDefault();
+
+            view.dispatch(
+              view.state.tr
+                .insertText(event.key)
+                .scrollIntoView()
+                .setMeta(suggestionMenuPluginKey, {
+                  triggerCharacter: event.key,
+                })
+            );
+
+            return true;
+          }
+
+          return false;
+        },
+
+        // Setup decorator on the currently active suggestion.
+        decorations(state) {
+          const suggestionPluginState: SuggestionPluginState = (
+            this as Plugin
+          ).getState(state);
+
+          if (suggestionPluginState === undefined) {
+            return null;
+          }
+
+          // If the menu was opened programmatically by another extension, it may not use a trigger character. In this
+          // case, the decoration is set on the whole block instead, as the decoration range would otherwise be empty.
+          if (!suggestionPluginState.fromUserInput) {
+            const blockNode = findBlock(state.selection);
+            if (blockNode) {
+              return DecorationSet.create(state.doc, [
+                Decoration.node(
+                  blockNode.pos,
+                  blockNode.pos + blockNode.node.nodeSize,
+                  {
+                    nodeName: "span",
+                    class: "bn-suggestion-decorator",
+                    "data-decoration-id": suggestionPluginState.decorationId,
+                  }
+                ),
+              ]);
+            }
+          }
+          // Creates an inline decoration around the trigger character.
+          return DecorationSet.create(state.doc, [
+            Decoration.inline(
+              suggestionPluginState.queryStartPos! -
+                suggestionPluginState.triggerCharacter!.length,
+              suggestionPluginState.queryStartPos!,
+              {
+                nodeName: "span",
+                class: "bn-suggestion-decorator",
+                "data-decoration-id": suggestionPluginState.decorationId,
+              }
+            ),
+          ]);
+        },
+      },
+    });
+  }
+
+  public onUpdate(
+    triggerCharacter: string,
+    callback: (state: SuggestionMenuState) => void
+  ) {
+    if (!this.triggerCharacters.includes(triggerCharacter)) {
+      this.addTriggerCharacter(triggerCharacter);
+    }
+    // TODO: be able to remove the triggerCharacter
+    return this.on(`update ${triggerCharacter}`, callback);
+  }
+
+  addTriggerCharacter = (triggerCharacter: string) => {
+    this.triggerCharacters.push(triggerCharacter);
+  };
+
+  // TODO: Should this be called automatically when listeners are removed?
+  removeTriggerCharacter = (triggerCharacter: string) => {
+    this.triggerCharacters = this.triggerCharacters.filter(
+      (c) => c !== triggerCharacter
+    );
+  };
+
+  closeMenu = () => this.view!.closeMenu();
+
+  clearQuery = () => this.view!.clearQuery();
+}
+
+export function createSuggestionMenu<
+  BSchema extends BlockSchema,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+>(editor: BlockNoteEditor<BSchema, I, S>, triggerCharacter: string) {
+  editor.suggestionMenus.addTriggerCharacter(triggerCharacter);
+}

package/src/extensions/{SlashMenu/defaultSlashMenuItems.ts → SuggestionMenu/getDefaultSlashMenuItems.ts}

@@ -1,15 +1,14 @@
-import { defaultBlockSchema } from "../../blocks/defaultBlocks";
-import type { BlockNoteEditor } from "../../editor/BlockNoteEditor";
+import { Block, PartialBlock } from "../../blocks/defaultBlocks";
+import { checkDefaultBlockTypeInSchema } from "../../blocks/defaultBlockTypeGuards";
+import { BlockNoteEditor } from "../../editor/BlockNoteEditor";
 import {
-  Block,
   BlockSchema,
   InlineContentSchema,
-  PartialBlock,
-  StyleSchema,
   isStyledTextInlineContent,
+  StyleSchema,
 } from "../../schema";
-import { imageToolbarPluginKey } from "../ImageToolbar/ImageToolbarPlugin";
-import { BaseSlashMenuItem } from "./BaseSlashMenuItem";
+import { formatKeyboardShortcut } from "../../util/browser";
+import { DefaultSuggestionItem } from "./DefaultSuggestionItem";
 
 // Sets the editor's text cursor position to the next content editable block,
 // so either a block with inline content or a table. The last block is always a
@@ -21,11 +20,11 @@ function setSelectionToNextContentEditableBlock<
   S extends StyleSchema
 >(editor: BlockNoteEditor<BSchema, I, S>) {
   let block = editor.getTextCursorPosition().block;
-  let contentType = editor.blockSchema[block.type].content;
+  let contentType = editor.schema.blockSchema[block.type].content;
 
   while (contentType === "none") {
     block = editor.getTextCursorPosition().nextBlock!;
-    contentType = editor.blockSchema[block.type].content as
+    contentType = editor.schema.blockSchema[block.type].content as
       | "inline"
       | "table"
       | "none";
@@ -37,7 +36,7 @@ function setSelectionToNextContentEditableBlock<
 // updates the current block instead of inserting a new one below. If the new
 // block doesn't contain editable content, the cursor is moved to the next block
 // that does.
-function insertOrUpdateBlock<
+export function insertOrUpdateBlock<
   BSchema extends BlockSchema,
   I extends InlineContentSchema,
   S extends StyleSchema
@@ -74,94 +73,106 @@ function insertOrUpdateBlock<
   return insertedBlock;
 }
 
-export const getDefaultSlashMenuItems = <
+export function getDefaultSlashMenuItems<
   BSchema extends BlockSchema,
   I extends InlineContentSchema,
   S extends StyleSchema
->(
-  schema: BSchema = defaultBlockSchema as unknown as BSchema
-) => {
-  const slashMenuItems: BaseSlashMenuItem<BSchema, I, S>[] = [];
-
-  if ("heading" in schema && "level" in schema.heading.propSchema) {
-    // Command for creating a level 1 heading
-    if (schema.heading.propSchema.level.values?.includes(1)) {
-      slashMenuItems.push({
-        name: "Heading",
-        aliases: ["h", "heading1", "h1"],
-        execute: (editor) =>
+>(editor: BlockNoteEditor<BSchema, I, S>) {
+  const items: DefaultSuggestionItem[] = [];
+
+  if (checkDefaultBlockTypeInSchema("heading", editor)) {
+    items.push(
+      {
+        title: "Heading 1",
+        onItemClick: () => {
           insertOrUpdateBlock(editor, {
             type: "heading",
             props: { level: 1 },
-          } as PartialBlock<BSchema, I, S>),
-      });
-    }
-
-    // Command for creating a level 2 heading
-    if (schema.heading.propSchema.level.values?.includes(2)) {
-      slashMenuItems.push({
-        name: "Heading 2",
-        aliases: ["h2", "heading2", "subheading"],
-        execute: (editor) =>
+          });
+        },
+        subtext: "Used for a top-level heading",
+        badge: formatKeyboardShortcut("Mod-Alt-1"),
+        aliases: ["h", "heading1", "h1"],
+        group: "Headings",
+      },
+      {
+        title: "Heading 2",
+        onItemClick: () => {
           insertOrUpdateBlock(editor, {
             type: "heading",
             props: { level: 2 },
-          } as PartialBlock<BSchema, I, S>),
-      });
-    }
-
-    // Command for creating a level 3 heading
-    if (schema.heading.propSchema.level.values?.includes(3)) {
-      slashMenuItems.push({
-        name: "Heading 3",
-        aliases: ["h3", "heading3", "subheading"],
-        execute: (editor) =>
+          });
+        },
+        subtext: "Used for key sections",
+        badge: formatKeyboardShortcut("Mod-Alt-2"),
+        aliases: ["h2", "heading2", "subheading"],
+        group: "Headings",
+      },
+      {
+        title: "Heading 3",
+        onItemClick: () => {
           insertOrUpdateBlock(editor, {
             type: "heading",
             props: { level: 3 },
-          } as PartialBlock<BSchema, I, S>),
-      });
-    }
+          });
+        },
+        subtext: "Used for subsections and group headings",
+        badge: formatKeyboardShortcut("Mod-Alt-3"),
+        aliases: ["h3", "heading3", "subheading"],
+        group: "Headings",
+      }
+    );
   }
 
-  if ("bulletListItem" in schema) {
-    slashMenuItems.push({
-      name: "Bullet List",
-      aliases: ["ul", "list", "bulletlist", "bullet list"],
-      execute: (editor) =>
+  if (checkDefaultBlockTypeInSchema("numberedListItem", editor)) {
+    items.push({
+      title: "Numbered List",
+      onItemClick: () => {
         insertOrUpdateBlock(editor, {
-          type: "bulletListItem",
-        }),
+          type: "numberedListItem",
+        });
+      },
+      subtext: "Used to display a numbered list",
+      badge: formatKeyboardShortcut("Mod-Shift-7"),
+      aliases: ["ol", "li", "list", "numberedlist", "numbered list"],
+      group: "Basic blocks",
     });
   }
 
-  if ("numberedListItem" in schema) {
-    slashMenuItems.push({
-      name: "Numbered List",
-      aliases: ["li", "list", "numberedlist", "numbered list"],
-      execute: (editor) =>
+  if (checkDefaultBlockTypeInSchema("bulletListItem", editor)) {
+    items.push({
+      title: "Bullet List",
+      onItemClick: () => {
         insertOrUpdateBlock(editor, {
-          type: "numberedListItem",
-        }),
+          type: "bulletListItem",
+        });
+      },
+      subtext: "Used to display an unordered list",
+      badge: formatKeyboardShortcut("Mod-Shift-8"),
+      aliases: ["ul", "li", "list", "bulletlist", "bullet list"],
+      group: "Basic blocks",
     });
   }
 
-  if ("paragraph" in schema) {
-    slashMenuItems.push({
-      name: "Paragraph",
-      aliases: ["p"],
-      execute: (editor) =>
+  if (checkDefaultBlockTypeInSchema("paragraph", editor)) {
+    items.push({
+      title: "Paragraph",
+      onItemClick: () => {
         insertOrUpdateBlock(editor, {
           type: "paragraph",
-        }),
+        });
+      },
+      subtext: "Used for the body of your document",
+      badge: formatKeyboardShortcut("Mod-Alt-0"),
+      aliases: ["p", "paragraph"],
+      group: "Basic blocks",
     });
   }
 
-  if ("table" in schema) {
-    slashMenuItems.push({
-      name: "Table",
-      aliases: ["table"],
-      execute: (editor) => {
+  if (checkDefaultBlockTypeInSchema("table", editor)) {
+    items.push({
+      title: "Table",
+      onItemClick: () => {
         insertOrUpdateBlock(editor, {
           type: "table",
           content: {
@@ -175,14 +186,31 @@ export const getDefaultSlashMenuItems = <
               },
             ],
           },
-        } as PartialBlock<BSchema, I, S>);
+        });
       },
+      subtext: "Used for for tables",
+      aliases: ["table"],
+      group: "Advanced",
+      badge: undefined,
     });
   }
 
-  if ("image" in schema) {
-    slashMenuItems.push({
-      name: "Image",
+  if (checkDefaultBlockTypeInSchema("image", editor)) {
+    items.push({
+      title: "Image",
+      onItemClick: () => {
+        const insertedBlock = insertOrUpdateBlock(editor, {
+          type: "image",
+        });
+
+        // Immediately open the image toolbar
+        editor.prosemirrorView.dispatch(
+          editor._tiptapEditor.state.tr.setMeta(editor.imageToolbar!.plugin, {
+            block: insertedBlock,
+          })
+        );
+      },
+      subtext: "Insert an image",
       aliases: [
         "image",
         "imageUpload",
@@ -194,20 +222,22 @@ export const getDefaultSlashMenuItems = <
         "drive",
         "dropbox",
       ],
-      execute: (editor) => {
-        const insertedBlock = insertOrUpdateBlock(editor, {
-          type: "image",
-        });
-
-        // Immediately open the image toolbar
-        editor._tiptapEditor.view.dispatch(
-          editor._tiptapEditor.state.tr.setMeta(imageToolbarPluginKey, {
-            block: insertedBlock,
-          })
-        );
-      },
+      group: "Media",
     });
   }
 
-  return slashMenuItems;
-};
+  return items;
+}
+
+export function filterSuggestionItems<
+  T extends { title: string; aliases?: readonly string[] }
+>(items: T[], query: string) {
+  return items.filter(
+    ({ title, aliases }) =>
+      title.toLowerCase().startsWith(query.toLowerCase()) ||
+      (aliases &&
+        aliases.filter((alias) =>
+          alias.toLowerCase().startsWith(query.toLowerCase())
+        ).length !== 0)
+  );
+}