@blocknote/core 0.3.0 → 0.4.0

package/src/api/formatConversions/simplifyBlocksRehypePlugin.ts

@@ -0,0 +1,125 @@
+import { Element as HASTElement, Parent as HASTParent } from "hast";
+import { fromDom } from "hast-util-from-dom";
+
+type SimplifyBlocksOptions = {
+  orderedListItemBlockTypes: Set<string>;
+  unorderedListItemBlockTypes: Set<string>;
+};
+
+/**
+ * Rehype plugin which converts the HTML output string rendered by BlockNote into a simplified structure which better
+ * follows HTML standards. It does several things:
+ * - Removes all block related div elements, leaving only the actual content inside the block.
+ * - Lifts nested blocks to a higher level for all block types that don't represent list items.
+ * - Wraps blocks which represent list items in corresponding ul/ol HTML elements and restructures them to comply
+ * with HTML list structure.
+ * @param options Options for specifying which block types represent ordered and unordered list items.
+ */
+export function simplifyBlocks(options: SimplifyBlocksOptions) {
+  const listItemBlockTypes = new Set<string>([
+    ...options.orderedListItemBlockTypes,
+    ...options.unorderedListItemBlockTypes,
+  ]);
+
+  const simplifyBlocksHelper = (tree: HASTParent) => {
+    let numChildElements = tree.children.length;
+    let activeList: HASTElement | undefined;
+
+    for (let i = 0; i < numChildElements; i++) {
+      const blockOuter = tree.children[i] as HASTElement;
+      const blockContainer = blockOuter.children[0] as HASTElement;
+      const blockContent = blockContainer.children[0] as HASTElement;
+      const blockGroup =
+        blockContainer.children.length === 2
+          ? (blockContainer.children[1] as HASTElement)
+          : null;
+
+      const isListItemBlock = listItemBlockTypes.has(
+        blockContent.properties!["dataContentType"] as string
+      );
+
+      const listItemBlockType = isListItemBlock
+        ? options.orderedListItemBlockTypes.has(
+            blockContent.properties!["dataContentType"] as string
+          )
+          ? "ol"
+          : "ul"
+        : null;
+
+      // Plugin runs recursively to process nested blocks.
+      if (blockGroup !== null) {
+        simplifyBlocksHelper(blockGroup);
+      }
+
+      // Checks that there is an active list, but the block can't be added to it as it's of a different type.
+      if (activeList && activeList.tagName !== listItemBlockType) {
+        // Blocks that were copied into the list are removed and the list is inserted in their place.
+        tree.children.splice(
+          i - activeList.children.length,
+          activeList.children.length,
+          activeList
+        );
+
+        // Updates the current index and number of child elements.
+        const numElementsRemoved = activeList.children.length - 1;
+        i -= numElementsRemoved;
+        numChildElements -= numElementsRemoved;
+
+        activeList = undefined;
+      }
+
+      // Checks if the block represents a list item.
+      if (isListItemBlock) {
+        // Checks if a list isn't already active. We don't have to check if the block and the list are of the same
+        // type as this was already done earlier.
+        if (!activeList) {
+          // Creates a new list element to represent an active list.
+          activeList = fromDom(
+            document.createElement(listItemBlockType!)
+          ) as HASTElement;
+        }
+
+        // Creates a new list item element to represent the block.
+        const listItemElement = fromDom(
+          document.createElement("li")
+        ) as HASTElement;
+
+        // Adds only the content inside the block to the active list.
+        listItemElement.children.push(blockContent.children[0]);
+        // Nested blocks have already been processed in the recursive function call, so the resulting elements are
+        // also added to the active list.
+        if (blockGroup !== null) {
+          listItemElement.children.push(...blockGroup.children);
+        }
+
+        // Adds the list item representing the block to the active list.
+        activeList.children.push(listItemElement);
+      } else if (blockGroup !== null) {
+        // Lifts all children out of the current block, as only list items should allow nesting.
+        tree.children.splice(i + 1, 0, ...blockGroup.children);
+        // Replaces the block with only the content inside it.
+        tree.children[i] = blockContent.children[0];
+
+        // Updates the current index and number of child elements.
+        const numElementsAdded = blockGroup.children.length;
+        i += numElementsAdded;
+        numChildElements += numElementsAdded;
+      } else {
+        // Replaces the block with only the content inside it.
+        tree.children[i] = blockContent.children[0];
+      }
+    }
+
+    // Since the active list is only inserted after encountering a block which can't be added to it, there are cases
+    // where it remains un-inserted after processing all blocks, which are handled here.
+    if (activeList) {
+      tree.children.splice(
+        numChildElements - activeList.children.length,
+        activeList.children.length,
+        activeList
+      );
+    }
+  };
+
+  return simplifyBlocksHelper;
+}

package/src/api/nodeConversions/nodeConversions.ts

@@ -0,0 +1,170 @@
+import { Node, Schema } from "prosemirror-model";
+import {
+  Block,
+  blockProps,
+  PartialBlock,
+} from "../../extensions/Blocks/api/blockTypes";
+import {
+  InlineContent,
+  Style,
+} from "../../extensions/Blocks/api/inlineContentTypes";
+import { getBlockInfoFromPos } from "../../extensions/Blocks/helpers/getBlockInfoFromPos";
+import UniqueID from "../../extensions/UniqueID/UniqueID";
+
+export function blockToNode(block: PartialBlock, schema: Schema) {
+  let id = block.id;
+
+  if (id === undefined) {
+    id = UniqueID.options.generateID();
+  }
+
+  let content: Node[] = [];
+
+  if (typeof block.content === "string") {
+    content.push(schema.text(block.content));
+  } else if (typeof block.content === "object") {
+    for (const styledText of block.content) {
+      const marks = [];
+
+      for (const style of styledText.styles) {
+        marks.push(schema.mark(style.type, style.props));
+      }
+
+      content.push(schema.text(styledText.text, marks));
+    }
+  }
+
+  const contentNode = schema.nodes[block.type].create(block.props, content);
+
+  const children: Node[] = [];
+
+  if (block.children) {
+    for (const child of block.children) {
+      children.push(blockToNode(child, schema));
+    }
+  }
+
+  const groupNode = schema.nodes["blockGroup"].create({}, children);
+
+  return schema.nodes["blockContainer"].create(
+    {
+      id: id,
+      ...block.props,
+    },
+    children.length > 0 ? [contentNode, groupNode] : contentNode
+  );
+}
+
+export function getNodeById(
+  id: string,
+  doc: Node
+): { node: Node; posBeforeNode: number } {
+  let targetNode: Node | undefined = undefined;
+  let posBeforeNode: number | undefined = undefined;
+
+  doc.firstChild!.descendants((node, pos) => {
+    // Skips traversing nodes after node with target ID has been found.
+    if (targetNode) {
+      return false;
+    }
+
+    // Keeps traversing nodes if block with target ID has not been found.
+    if (node.type.name !== "blockContainer" || node.attrs.id !== id) {
+      return true;
+    }
+
+    targetNode = node;
+    posBeforeNode = pos + 1;
+
+    return false;
+  });
+
+  if (targetNode === undefined || posBeforeNode === undefined) {
+    throw Error("Could not find block in the editor with matching ID.");
+  }
+
+  return {
+    node: targetNode,
+    posBeforeNode: posBeforeNode,
+  };
+}
+
+export function nodeToBlock(
+  node: Node,
+  blockCache?: WeakMap<Node, Block>
+): Block {
+  if (node.type.name !== "blockContainer") {
+    throw Error(
+      "Node must be of type blockContainer, but is of type" +
+        node.type.name +
+        "."
+    );
+  }
+
+  const cachedBlock = blockCache?.get(node);
+
+  if (cachedBlock) {
+    return cachedBlock;
+  }
+
+  const blockInfo = getBlockInfoFromPos(node, 0)!;
+
+  let id = blockInfo.id;
+
+  // Only used for blocks converted from other formats.
+  if (id === null) {
+    id = UniqueID.options.generateID();
+  }
+
+  const props: any = {};
+  for (const [attr, value] of Object.entries({
+    ...blockInfo.node.attrs,
+    ...blockInfo.contentNode.attrs,
+  })) {
+    if (!(blockInfo.contentType.name in blockProps)) {
+      throw Error(
+        "Block is of an unrecognized type: " + blockInfo.contentType.name
+      );
+    }
+
+    const validAttrs = blockProps[blockInfo.contentType.name as Block["type"]];
+
+    if (validAttrs.has(attr)) {
+      props[attr] = value;
+    }
+  }
+
+  const content: InlineContent[] = [];
+  blockInfo.contentNode.content.forEach((node) => {
+    const styles: Style[] = [];
+
+    for (const mark of node.marks) {
+      styles.push({
+        type: mark.type.name,
+        props: mark.attrs,
+      } as Style);
+    }
+
+    content.push({
+      text: node.textContent,
+      styles,
+    });
+  });
+
+  const children: Block[] = [];
+  for (let i = 0; i < blockInfo.numChildBlocks; i++) {
+    children.push(nodeToBlock(blockInfo.node.lastChild!.child(i)));
+  }
+
+  const block: Block = {
+    id,
+    type: blockInfo.contentType.name as Block["type"],
+    props,
+    content,
+    children,
+  };
+
+  blockCache?.set(node, block);
+
+  return block;
+}

package/src/editor.module.css

@@ -24,7 +24,8 @@ Tippy popups that are appended to document.body directly
   box-sizing: inherit;
 }
 
-.bnEditor, .dragPreview {
+.bnEditor,
+.dragPreview {
   /* Define a set of colors to be used throughout the app for consistency
   see https://atlassian.design/foundations/color for more info */
   --N800: #172b4d; /* Dark neutral used for tooltips and text on light background */
@@ -38,3 +39,8 @@ Tippy popups that are appended to document.body directly
 
   color: rgb(60, 65, 73);
 }
+
+.dragPreview {
+  position: absolute;
+  top: -1000px;
+}

package/src/extensions/Blocks/PreviousBlockTypePlugin.ts

@@ -24,6 +24,7 @@ const nodeAttributes: Record<string, string> = {
  * Solution: When attributes change on a node, this plugin sets a data-* attribute with the "previous" value. This way we can still use CSS transitions. (See block.module.css)
  */
 export const PreviousBlockTypePlugin = () => {
+  let timeout: any;
   return new Plugin({
     key: PLUGIN_KEY,
     view(_editorView) {
@@ -32,13 +33,18 @@ export const PreviousBlockTypePlugin = () => {
           if (this.key?.getState(view.state).updatedBlocks.size > 0) {
             // use setTimeout 0 to clear the decorations so that at least
             // for one DOM-render the decorations have been applied
-            setTimeout(() => {
+            timeout = setTimeout(() => {
               view.dispatch(
                 view.state.tr.setMeta(PLUGIN_KEY, { clearUpdate: true })
               );
             }, 0);
           }
         },
+        destroy: () => {
+          if (timeout) {
+            clearTimeout(timeout);
+          }
+        },
       };
     },
     state: {

package/src/extensions/Blocks/api/blockTypes.ts

@@ -0,0 +1,85 @@
+/** Define the main block types **/
+
+import { InlineContent } from "./inlineContentTypes";
+
+export type BlockTemplate<
+  // Type of the block.
+  // Examples might include: "paragraph", "heading", or "bulletListItem".
+  Type extends string,
+  // Changeable props which affect the block's behaviour or appearance.
+  // An example might be: { textAlignment: "left" | "right" | "center" } for a paragraph block.
+  Props extends Record<string, string>
+> = {
+  id: string;
+  type: Type;
+  props: Props;
+  content: InlineContent[];
+  children: Block[];
+};
+
+export type GlobalProps = {
+  backgroundColor: string;
+  textColor: string;
+  textAlignment: "left" | "center" | "right" | "justify";
+};
+
+export type NumberedListItemBlock = BlockTemplate<
+  "numberedListItem",
+  GlobalProps
+>;
+
+export type BulletListItemBlock = BlockTemplate<"bulletListItem", GlobalProps>;
+
+export type HeadingBlock = BlockTemplate<
+  "heading",
+  GlobalProps & {
+    level: "1" | "2" | "3";
+  }
+>;
+
+export type ParagraphBlock = BlockTemplate<"paragraph", GlobalProps>;
+
+export type Block =
+  | ParagraphBlock
+  | HeadingBlock
+  | BulletListItemBlock
+  | NumberedListItemBlock;
+
+/** Define "Partial Blocks", these are for updating or creating blocks */
+export type PartialBlockTemplate<B extends Block> = B extends Block
+  ? Partial<Omit<B, "props" | "children" | "content" | "type">> & {
+      type: B["type"];
+      props?: Partial<B["props"]>;
+      content?: string | B["content"];
+      children?: PartialBlock[];
+    }
+  : never;
+
+export type PartialBlock = PartialBlockTemplate<Block>;
+
+export type BlockPropsTemplate<Props> = Props extends Block["props"]
+  ? keyof Props
+  : never;
+
+/**
+ * Expose blockProps. This is currently not very nice, but it's expected this
+ * will change anyway once we allow for custom blocks
+ */
+
+export const globalProps: Array<keyof GlobalProps> = [
+  "backgroundColor",
+  "textColor",
+  "textAlignment",
+];
+
+export const blockProps: Record<Block["type"], Set<string>> = {
+  paragraph: new Set<keyof ParagraphBlock["props"]>([...globalProps]),
+  heading: new Set<keyof HeadingBlock["props"]>([
+    ...globalProps,
+    "level" as const,
+  ]),
+  numberedListItem: new Set<keyof NumberedListItemBlock["props"]>([
+    ...globalProps,
+  ]),
+  bulletListItem: new Set<keyof BulletListItemBlock["props"]>([...globalProps]),
+};

package/src/extensions/Blocks/api/cursorPositionTypes.ts

@@ -0,0 +1,5 @@
+import { Block } from "./blockTypes";
+
+export type TextCursorPosition = {
+  block: Block;
+};

package/src/extensions/Blocks/api/inlineContentTypes.ts

@@ -0,0 +1,44 @@
+export type StyleTemplate<
+  // Type of the style.
+  // Examples might include: "bold", "italic", or "textColor".
+  Type extends string,
+  // Changeable props which affect the style's appearance.
+  // An example might be: { color: string } for a textColor style.
+  Props extends Record<string, string>
+> = {
+  type: Type;
+  props: Props;
+};
+
+export type Bold = StyleTemplate<"bold", {}>;
+
+export type Italic = StyleTemplate<"italic", {}>;
+
+export type Underline = StyleTemplate<"underline", {}>;
+
+export type Strikethrough = StyleTemplate<"strike", {}>;
+
+export type TextColor = StyleTemplate<"textColor", { color: string }>;
+
+export type BackgroundColor = StyleTemplate<
+  "backgroundColor",
+  { color: string }
+>;
+
+export type Link = StyleTemplate<"link", { href: string }>;
+
+export type Style =
+  | Bold
+  | Italic
+  | Underline
+  | Strikethrough
+  | TextColor
+  | BackgroundColor
+  | Link;
+
+export type StyledText = {
+  text: string;
+  styles: Style[];
+};
+
+export type InlineContent = StyledText;

package/src/extensions/Blocks/helpers/getBlockInfoFromPos.ts

@@ -22,7 +22,7 @@ export function getBlockInfoFromPos(
   doc: Node,
   posInBlock: number
 ): BlockInfo | undefined {
-  if (posInBlock <= 0 || posInBlock > doc.nodeSize) {
+  if (posInBlock < 0 || posInBlock > doc.nodeSize) {
     return undefined;
   }
 
@@ -32,11 +32,11 @@ export function getBlockInfoFromPos(
   let node = $pos.node(maxDepth);
   let depth = maxDepth;
 
-  while (depth >= 0) {
-    // If the outermost node is not a block, it means the position does not lie within a block.
-    if (depth === 0) {
+  while (true) {
+    if (depth < 0) {
       return undefined;
     }
+
     if (node.type.name === "blockContainer") {
       break;
     }

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

@@ -1,7 +1,8 @@
 import { mergeAttributes, Node } from "@tiptap/core";
-import { Fragment, Slice } from "prosemirror-model";
+import { Fragment, Node as PMNode, Slice } from "prosemirror-model";
 import { TextSelection } from "prosemirror-state";
-import { BlockUpdate } from "../apiTypes";
+import { blockToNode } from "../../../api/nodeConversions/nodeConversions";
+import { PartialBlock } from "../api/blockTypes";
 import { getBlockInfoFromPos } from "../helpers/getBlockInfoFromPos";
 import { PreviousBlockTypePlugin } from "../PreviousBlockTypePlugin";
 import styles from "./Block.module.css";
@@ -19,13 +20,10 @@ declare module "@tiptap/core" {
       BNDeleteBlock: (posInBlock: number) => ReturnType;
       BNMergeBlocks: (posBetweenBlocks: number) => ReturnType;
       BNSplitBlock: (posInBlock: number, keepType: boolean) => ReturnType;
-      BNUpdateBlock: (
-        posInBlock: number,
-        blockUpdate: BlockUpdate
-      ) => ReturnType;
+      BNUpdateBlock: (posInBlock: number, block: PartialBlock) => ReturnType;
       BNCreateOrUpdateBlock: (
         posInBlock: number,
-        blockUpdate: BlockUpdate
+        block: PartialBlock
       ) => ReturnType;
     };
   }
@@ -197,8 +195,7 @@ export const BlockContainer = Node.create<IBlock>({
           }
 
           // Deletes next block and adds its text content to the nearest previous block.
-          // TODO: Is there any situation where we need the whole block content, not just text? Implementation for this
-          //  is trickier.
+          // TODO: Use slices.
           if (dispatch) {
             state.tr.deleteRange(startPos, startPos + contentNode.nodeSize);
             state.tr.insertText(contentNode.textContent, prevBlockEndPos - 1);
@@ -283,35 +280,88 @@ export const BlockContainer = Node.create<IBlock>({
 
           return true;
         },
-      // Updates the type and attributes of a block at a given position.
+      // Updates a block to the given specification.
       BNUpdateBlock:
-        (posInBlock, blockUpdate) =>
+        (posInBlock, block) =>
         ({ state, dispatch }) => {
           const blockInfo = getBlockInfoFromPos(state.doc, posInBlock);
           if (blockInfo === undefined) {
             return false;
           }
 
-          const { node, startPos, contentNode } = blockInfo;
+          const { startPos, endPos, node, contentNode } = blockInfo;
 
           if (dispatch) {
-            state.tr.setBlockType(
-              startPos + 1,
-              startPos + contentNode.nodeSize + 1,
-              state.schema.node(blockUpdate.type).type,
-              {
-                ...node.attrs,
-                ...blockUpdate.props,
+            // 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.
+                for (const styledText of block.content) {
+                  const marks = [];
+
+                  for (const style of styledText.styles) {
+                    marks.push(state.schema.mark(style.type, style.props));
+                  }
+
+                  content.push(state.schema.text(styledText.text, marks));
+                }
+              }
+
+              // 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, state.schema.nodes[block.type], {
+              ...contentNode.attrs,
+              ...block.props,
+            });
           }
 
           return true;
         },
-      // Changes the block at a given position to a given content type if it's empty, otherwise creates a new block of
-      // that type below it.
+      // Updates a block to the given specification if it's empty, otherwise creates a new block from that specification
+      // below it.
       BNCreateOrUpdateBlock:
-        (posInBlock, blockUpdate) =>
+        (posInBlock, block) =>
         ({ state, chain }) => {
           const blockInfo = getBlockInfoFromPos(state.doc, posInBlock);
           if (blockInfo === undefined) {
@@ -324,7 +374,7 @@ export const BlockContainer = Node.create<IBlock>({
             const oldBlockContentPos = startPos + 1;
 
             return chain()
-              .BNUpdateBlock(posInBlock, blockUpdate)
+              .BNUpdateBlock(posInBlock, block)
               .setTextSelection(oldBlockContentPos)
               .run();
           } else {
@@ -333,7 +383,7 @@ export const BlockContainer = Node.create<IBlock>({
 
             return chain()
               .BNCreateBlock(newBlockInsertionPos)
-              .BNUpdateBlock(newBlockContentPos, blockUpdate)
+              .BNUpdateBlock(newBlockContentPos, block)
               .setTextSelection(newBlockContentPos)
               .run();
           }