@blocknote/core 0.1.0-alpha.3

package/src/shared/plugins/suggestion/SuggestionPlugin.ts

@@ -0,0 +1,365 @@
+import { Editor, Range } from "@tiptap/core";
+import { escapeRegExp, groupBy } from "lodash";
+import { Plugin, PluginKey, Selection } from "prosemirror-state";
+import { Decoration, DecorationSet } from "prosemirror-view";
+import { findBlock } from "../../../extensions/Blocks/helpers/findBlock";
+import SuggestionItem from "./SuggestionItem";
+
+import createRenderer, {
+  SuggestionRendererProps,
+} from "./SuggestionListReactRenderer";
+
+export type SuggestionPluginOptions<T extends SuggestionItem> = {
+  /**
+   * The name of the plugin.
+   *
+   * Used for ensuring that the plugin key is unique when more than one instance of the SuggestionPlugin is used.
+   */
+  pluginKey: PluginKey;
+
+  /**
+   * The TipTap editor.
+   */
+  editor: Editor;
+
+  /**
+   * The character that should trigger the suggestion menu to pop up (e.g. a '/' for commands)
+   */
+  char: string;
+
+  /**
+   * The callback that gets executed when an item is selected by the user.
+   *
+   * **NOTE:** The command text is not removed automatically from the editor by this plugin,
+   * this should be done manually. The `editor` and `range` properties passed
+   * to the callback function might come in handy when doing this.
+   */
+  onSelectItem?: (props: { item: T; editor: Editor; range: Range }) => void;
+
+  /**
+   * A function that should supply the plugin with items to suggest, based on a certain query string.
+   */
+  items?: (query: string) => T[];
+
+  allow?: (props: { editor: Editor; range: Range }) => boolean;
+};
+
+export type MenuType = "slash" | "drag";
+
+/**
+ * Finds a command: a specified character (e.g. '/') followed by a string of characters (all characters except the specified character are allowed).
+ * Returns the string following the specified character or undefined if no command was found.
+ *
+ * @param char the character that indicates the start of a command
+ * @param selection the selection (only works if the selection is empty; i.e. is a blinking cursor).
+ * @returns an object containing the matching word (excluding the specified character) and the range of the match (including the specified character) or undefined if there is no match.
+ */
+export function findCommandBeforeCursor(
+  char: string,
+  selection: Selection
+): { range: Range; query: string } | undefined {
+  if (!selection.empty) {
+    return undefined;
+  }
+
+  // get the text before the cursor as a node
+  const node = selection.$anchor.nodeBefore;
+  if (!node || !node.text) {
+    return undefined;
+  }
+
+  // regex to match anything between with the specified char (e.g. '/') and the end of text (which is the end of selection)
+  const regex = new RegExp(`${escapeRegExp(char)}([^${escapeRegExp(char)}]*)$`);
+  const match = node.text.match(regex);
+
+  if (!match) {
+    return undefined;
+  }
+
+  return {
+    query: match[1],
+    range: {
+      from: selection.$anchor.pos - match[1].length - char.length,
+      to: selection.$anchor.pos,
+    },
+  };
+}
+
+/**
+ * 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
+ *
+ * @param options options for configuring the plugin
+ * @returns the prosemirror plugin
+ */
+export function createSuggestionPlugin<T extends SuggestionItem>({
+  pluginKey,
+  editor,
+  char,
+  onSelectItem: selectItemCallback = () => {},
+  items = () => [],
+}: SuggestionPluginOptions<T>) {
+  // Assertions
+  if (char.length !== 1) {
+    throw new Error("'char' should be a single character");
+  }
+
+  const renderer = createRenderer<T>(editor);
+
+  // Plugin key is passed in parameter so it can be exported and used in draghandle
+  return new Plugin({
+    key: pluginKey,
+
+    filterTransaction(transaction) {
+      // prevent blurring when clicking with the mouse inside the popup menu
+      const blurMeta = transaction.getMeta("blur");
+      if (blurMeta?.event.relatedTarget) {
+        const c = renderer.getComponent();
+        if (c?.contains(blurMeta.event.relatedTarget)) {
+          return false;
+        }
+      }
+      return true;
+    },
+
+    view() {
+      return {
+        update: async (view, prevState) => {
+          const prev = this.key?.getState(prevState);
+          const next = this.key?.getState(view.state);
+
+          // See how the state changed
+          const started = !prev.active && next.active;
+          const stopped = prev.active && !next.active;
+          const changed = !started && !stopped && prev.query !== next.query;
+
+          // Cancel when suggestion isn't active
+          if (!started && !changed && !stopped) {
+            return;
+          }
+
+          const state = stopped ? prev : next;
+          const decorationNode = document.querySelector(
+            `[data-decoration-id="${state.decorationId}"]`
+          );
+
+          const groups: { [groupName: string]: T[] } = groupBy(
+            state.items,
+            "groupName"
+          );
+
+          const deactivate = () => {
+            view.dispatch(
+              view.state.tr.setMeta(pluginKey, { deactivate: true })
+            );
+          };
+
+          const rendererProps: SuggestionRendererProps<T> = {
+            groups: changed || started ? groups : {},
+            count: state.items.length,
+            onSelectItem: (item: T) => {
+              deactivate();
+              selectItemCallback({
+                item,
+                editor,
+                range: state.range,
+              });
+            },
+            // virtual node for popper.js or tippy.js
+            // this can be used for building popups without a DOM node
+            clientRect: decorationNode
+              ? () => decorationNode.getBoundingClientRect()
+              : null,
+            onClose: () => {
+              deactivate();
+              renderer.onExit?.(rendererProps);
+            },
+          };
+
+          if (stopped) {
+            renderer.onExit?.(rendererProps);
+          }
+
+          if (changed) {
+            renderer.onUpdate?.(rendererProps);
+          }
+
+          if (started) {
+            renderer.onStart?.(rendererProps);
+          }
+        },
+      };
+    },
+
+    state: {
+      // Initialize the plugin's internal state.
+      init() {
+        return {
+          active: false,
+          range: {} as any, // TODO
+          query: null as string | null,
+          notFoundCount: 0,
+          items: [] as T[],
+          type: "slash",
+          decorationId: null as string | null,
+        };
+      },
+
+      // Apply changes to the plugin state from a view transaction.
+      apply(transaction, prev, _oldState, _newState) {
+        const { selection } = transaction;
+        const next = { ...prev };
+
+        if (
+          // only show popup if selection is a blinking cursor
+          selection.from === selection.to &&
+          // deactivate popup from view (e.g.: choice has been made or esc has been pressed)
+          !transaction.getMeta(pluginKey)?.deactivate &&
+          // deactivate because a mouse event occurs (user clicks somewhere else in the document)
+          !transaction.getMeta("focus") &&
+          !transaction.getMeta("blur") &&
+          !transaction.getMeta("pointer")
+        ) {
+          // Reset active state if we just left the previous suggestion range (e.g.: key arrows moving before /)
+          if (prev.active && selection.from <= prev.range.from) {
+            next.active = false;
+          } else if (transaction.getMeta(pluginKey)?.activate) {
+            // Start showing suggestions. activate has been set after typing a "/" (or whatever the specified character is), so let's create the decoration and initialize
+            const newDecorationId = `id_${Math.floor(
+              Math.random() * 0xffffffff
+            )}`;
+            next.decorationId = newDecorationId;
+            next.range = {
+              from: selection.from - 1,
+              to: selection.to,
+            };
+            next.query = "";
+            next.active = true;
+            next.type = transaction.getMeta(pluginKey)?.type;
+          } else if (prev.active) {
+            // Try to match against where our cursor currently is
+            // if the type is slash we get the command after the character
+            // otherwise we get the whole query
+            const match = findCommandBeforeCursor(
+              prev.type === "slash" ? char : "",
+              selection
+            );
+            if (!match) {
+              throw new Error("active but no match (suggestions)");
+            }
+
+            next.range = match.range;
+            next.active = true;
+            next.decorationId = prev.decorationId;
+            next.query = match.query;
+          }
+        } else {
+          next.active = false;
+        }
+
+        if (next.active) {
+          next.items = items(next.query!);
+          if (next.items.length) {
+            next.notFoundCount = 0;
+          } else {
+            // Update the "notFoundCount",
+            // which indicates how many characters have been typed after showing no results
+            if (next.range.to > prev.range.to) {
+              // Text has been entered (selection moved to right), but still no items found, update Count
+              next.notFoundCount = prev.notFoundCount + 1;
+            } else {
+              // No text has been entered in this tr, keep not found count
+              // (e.g.: user hits backspace after no results)
+              next.notFoundCount = prev.notFoundCount;
+            }
+          }
+
+          if (next.notFoundCount > 3) {
+            next.active = false;
+          }
+        }
+
+        // Make sure to empty the range if suggestion is inactive
+        if (!next.active) {
+          next.decorationId = null;
+          next.range = {};
+          next.query = null;
+          next.notFoundCount = 0;
+          next.items = [];
+        }
+
+        return next;
+      },
+    },
+
+    props: {
+      handleKeyDown(view, event) {
+        const { active } = (this as Plugin).getState(view.state);
+
+        if (!active) {
+          // activate the popup on 'char' keypress (e.g. '/')
+          if (event.key === char) {
+            view.dispatch(
+              view.state.tr
+                .insertText(char)
+                .scrollIntoView()
+                .setMeta(pluginKey, { activate: true, type: "slash" })
+            );
+            // return true to cancel the original event, as we insert / ourselves
+            return true;
+          }
+          return false;
+        }
+
+        // pass the key event onto the renderer (to handle arrow keys, enter and escape)
+        // return true if the event got handled by the renderer or false otherwise
+        return renderer.onKeyDown?.(event) || false;
+      },
+
+      // Setup decorator on the currently active suggestion.
+      decorations(state) {
+        const { active, range, decorationId, type } = (this as Plugin).getState(
+          state
+        );
+
+        if (!active) {
+          return null;
+        }
+
+        // If type in meta is drag, create decoration node that wraps block
+        // Because the block does not have content yet (slash menu has the '/' in its content),
+        // so we can't use an inline decoration.
+        if (type === "drag") {
+          const blockNode = findBlock(state.selection);
+          if (blockNode) {
+            return DecorationSet.create(state.doc, [
+              Decoration.node(
+                blockNode.pos,
+                blockNode.pos + blockNode.node.nodeSize,
+                {
+                  nodeName: "span",
+                  class: "suggestion-decorator",
+                  "data-decoration-id": decorationId,
+                }
+              ),
+            ]);
+          }
+        }
+        // Create inline decoration that wraps / or whatever the specified character is
+        return DecorationSet.create(state.doc, [
+          Decoration.inline(range.from, range.to, {
+            nodeName: "span",
+            class: "suggestion-decorator",
+            "data-decoration-id": decorationId,
+          }),
+        ]);
+      },
+    },
+  });
+}

package/src/shared/plugins/suggestion/components/SuggestionGroup.module.css

@@ -0,0 +1,45 @@
+.suggestionWrapper {
+  display: flex;
+  flex-flow: row nowrap;
+  justify-content: space-between;
+  white-space: initial;
+  padding: 0px;
+}
+
+.buttonName {
+  font-size: small;
+  margin-bottom: 4px;
+}
+.buttonHint {
+  font-size: smaller;
+  color: rgb(128, 128, 128);
+}
+.buttonShortcut {
+  font-size: x-small;
+  color: rgb(128, 128, 128);
+  background-color: rgba(128, 128, 128, 0.2);
+  vertical-align: top;
+  padding: 3px;
+  border-radius: 3px;
+}
+.iconWrapper {
+  border: 1px solid rgba(128, 128, 128, 0.5);
+  border-radius: 4px;
+  background-color: white;
+  width: 40px;
+  height: 40px;
+  padding: 10px;
+}
+.icon {
+  width: 20px;
+  height: 20px;
+  fill: var(--N800);
+}
+.icon path[fill="none"] {
+  stroke: none;
+}
+
+.selectedIcon path {
+  stroke: var(--N800);
+  stroke-width: 1px;
+}

package/src/shared/plugins/suggestion/components/SuggestionGroup.tsx

@@ -0,0 +1,134 @@
+import { ButtonItem, Section } from "@atlaskit/menu";
+import React from "react";
+import SuggestionItem from "../SuggestionItem";
+import styles from "./SuggestionGroup.module.css";
+
+const MIN_LEFT_MARGIN = 5;
+
+function SuggestionContent<T extends SuggestionItem>(props: { item: T }) {
+  return (
+    <div className={styles.suggestionWrapper}>
+      <div>
+        <div className={styles.buttonName}>{props.item.name}</div>
+        {props.item.hint && (
+          <div className={styles.buttonHint}>{props.item.hint}</div>
+        )}
+      </div>
+      {props.item.shortcut && (
+        <div>
+          <div className={styles.buttonShortcut}>{props.item.shortcut}</div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function getIcon<T extends SuggestionItem>(
+  item: T,
+  isButtonSelected: boolean
+): JSX.Element | undefined {
+  const Icon = item.icon;
+  return (
+    Icon && (
+      <div className={styles.iconWrapper}>
+        <Icon
+          className={
+            styles.icon + " " + (isButtonSelected ? styles.selectedIcon : "")
+          }
+        />
+      </div>
+    )
+  );
+}
+
+type SuggestionComponentProps<T> = {
+  item: T;
+  index: number;
+  selectedIndex?: number;
+  clickItem: (item: T) => void;
+};
+
+function SuggestionComponent<T extends SuggestionItem>(
+  props: SuggestionComponentProps<T>
+) {
+  let isButtonSelected =
+    props.selectedIndex !== undefined && props.selectedIndex === props.index;
+
+  const buttonRef = React.useRef<HTMLElement>(null);
+  React.useEffect(() => {
+    if (
+      isButtonSelected &&
+      buttonRef.current &&
+      buttonRef.current.getBoundingClientRect().left > MIN_LEFT_MARGIN //TODO: Kinda hacky, fix
+      // This check is needed because initially the menu is initialized somewhere above outside the screen (with left = 1)
+      // scrollIntoView() is called before the menu is set in the right place, and without the check would scroll to the top of the page every time
+    ) {
+      buttonRef.current.scrollIntoView({
+        behavior: "smooth",
+        block: "nearest",
+      });
+    }
+  }, [isButtonSelected]);
+
+  return (
+    <div className={styles.buttonItem}>
+      <ButtonItem
+        isSelected={isButtonSelected} // This is needed to navigate with the keyboard
+        iconBefore={getIcon(props.item, isButtonSelected)}
+        onClick={(_e) => {
+          setTimeout(() => {
+            props.clickItem(props.item);
+          }, 0);
+
+          // e.stopPropagation();
+          // e.preventDefault();
+        }}
+        ref={buttonRef}>
+        <SuggestionContent item={props.item} />
+      </ButtonItem>
+    </div>
+  );
+}
+
+type SuggestionGroupProps<T> = {
+  /**
+   * Name of the group
+   */
+  name: string;
+
+  /**
+   * The list of items
+   */
+  items: T[];
+
+  /**
+   * Index of the selected item in this group; relative to this item group (so 0 refers to the first item in this group)
+   * This should be 'undefined' if none of the items in this group are selected
+   */
+  selectedIndex?: number;
+
+  /**
+   * Callback that gets executed when an item is clicked on.
+   */
+  clickItem: (item: T) => void;
+};
+
+export function SuggestionGroup<T extends SuggestionItem>(
+  props: SuggestionGroupProps<T>
+) {
+  return (
+    <Section title={props.name}>
+      {props.items.map((item, index) => {
+        return (
+          <SuggestionComponent
+            item={item}
+            key={index} // TODO: using index as key is not ideal for performance, better have ids on suggestionItems
+            index={index}
+            selectedIndex={props.selectedIndex}
+            clickItem={props.clickItem}
+          />
+        );
+      })}
+    </Section>
+  );
+}

package/src/shared/plugins/suggestion/components/SuggestionList.module.css

@@ -0,0 +1,10 @@
+.menuList {
+  color: var(--N800);
+  background-color: white;
+  border: 1px solid var(--N40);
+  box-shadow: 0px 4px 8px rgba(9, 30, 66, 0.25),
+    0px 0px 1px rgba(9, 30, 66, 0.31);
+  border-radius: 4px;
+  max-width: 320;
+  margin: 16px auto;
+}

package/src/shared/plugins/suggestion/components/SuggestionList.tsx

@@ -0,0 +1,91 @@
+import { MenuGroup, Section } from "@atlaskit/menu";
+import styles from "./SuggestionList.module.css";
+import rootStyles from "../../../../root.module.css";
+import { SuggestionGroup } from "./SuggestionGroup";
+import SuggestionItem from "../SuggestionItem";
+
+export type SuggestionListProps<T> = {
+  /**
+   * Object containing all suggestion items, grouped by their `groupName`.
+   */
+  groups: {
+    [groupName: string]: T[];
+  };
+
+  /**
+   * The total number of suggestion-items
+   */
+  count: number;
+
+  /**
+   * This callback gets executed whenever an item is clicked on
+   */
+  onSelectItem: (item: T) => void;
+
+  /**
+   * The index of the item that is currently selected (but not yet clicked on)
+   */
+  selectedIndex: number;
+};
+
+/**
+ * Stateless component that renders the suggestion list
+ */
+export function SuggestionList<T extends SuggestionItem>(
+  props: SuggestionListProps<T>
+) {
+  const renderedGroups = [];
+
+  let currentGroupIndex = 0;
+
+  for (const groupName in props.groups) {
+    const items = props.groups[groupName];
+
+    renderedGroups.push(
+      <SuggestionGroup
+        key={groupName}
+        name={groupName}
+        items={items}
+        selectedIndex={
+          props.selectedIndex >= currentGroupIndex
+            ? props.selectedIndex - currentGroupIndex
+            : undefined
+        }
+        clickItem={props.onSelectItem}></SuggestionGroup>
+    );
+
+    currentGroupIndex += items.length;
+  }
+
+  return (
+    <div className={styles.menuList + " " + rootStyles.bnRoot}>
+      <MenuGroup>
+        {renderedGroups.length > 0 ? (
+          renderedGroups
+        ) : (
+          <Section title={"No match found"}> </Section>
+        )}
+      </MenuGroup>
+    </div>
+
+    // doesn't work well yet, maybe https://github.com/atomiks/tippyjs-react/issues/173
+    // We now render the tippy element manually in SuggestionListReactRenderer
+    // <Tippy
+    //   visible={true}
+    //   placement="bottom-start"
+    //   content={
+    //     <div className={styles.menuList}>
+    //       <PopupMenuGroup maxWidth="250px" maxHeight="400px">
+    //         {renderedGroups.length > 0 ? (
+    //           renderedGroups
+    //         ) : (
+    //           <Section title={"No match found"}> </Section>
+    //         )}
+    //       </PopupMenuGroup>
+    //     </div>
+    //   }
+    //   interactive={false}>
+    //   <div></div>
+    // </Tippy>
+  );
+}

package/src/style.css

@@ -0,0 +1,7 @@
+/*
+This is an empty placeholder file, which should NOT contain CSS code.
+It's here so DEV environment doesn't show a 404
+
+- In DEV environment, examples/editor loads this stub file, but actual CSS is loaded from CSS modules directly
+- In PROD environment, the actual dist/style.css file is built from the CSS modules
+*/

package/src/useEditor.ts

@@ -0,0 +1,47 @@
+import { EditorOptions, useEditor as useEditorTiptap } from "@tiptap/react";
+
+import { DependencyList } from "react";
+import { getBlockNoteExtensions } from "./BlockNoteExtensions";
+import styles from "./editor.module.css";
+import rootStyles from "./root.module.css";
+
+type BlockNoteEditorOptions = EditorOptions & {
+  enableBlockNoteExtensions: boolean;
+  disableHistoryExtension: boolean;
+};
+
+const blockNoteExtensions = getBlockNoteExtensions();
+
+const blockNoteOptions = {
+  enableInputRules: true,
+  enablePasteRules: true,
+  enableCoreExtensions: false,
+};
+export const useEditor = (
+  options: Partial<BlockNoteEditorOptions> = {},
+  deps: DependencyList = []
+) => {
+  const extensions = options.disableHistoryExtension
+    ? blockNoteExtensions.filter((e) => e.name !== "history")
+    : blockNoteExtensions;
+
+  const tiptapOptions = {
+    ...blockNoteOptions,
+    ...options,
+    extensions:
+      options.enableBlockNoteExtensions === false
+        ? options.extensions
+        : [...(options.extensions || []), ...extensions],
+    editorProps: {
+      attributes: {
+        ...(options.editorProps?.attributes || {}),
+        class: [
+          styles.bnEditor,
+          rootStyles.bnRoot,
+          (options.editorProps?.attributes as any)?.class || "",
+        ].join(" "),
+      },
+    },
+  };
+  return useEditorTiptap(tiptapOptions, deps);
+};

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />