@blocknote/core 0.9.5 → 0.10.0

package/src/pm-nodes/BlockGroup.ts

@@ -0,0 +1,54 @@
+import { Node } from "@tiptap/core";
+import { BlockNoteDOMAttributes } from "../schema";
+import { mergeCSSClasses } from "../util/browser";
+
+export const BlockGroup = Node.create<{
+  domAttributes?: BlockNoteDOMAttributes;
+}>({
+  name: "blockGroup",
+  group: "blockGroup",
+  content: "blockContainer+",
+
+  parseHTML() {
+    return [
+      {
+        tag: "div",
+        getAttrs: (element) => {
+          if (typeof element === "string") {
+            return false;
+          }
+
+          if (element.getAttribute("data-node-type") === "blockGroup") {
+            // Null means the element matches, but we don't want to add any attributes to the node.
+            return null;
+          }
+
+          return false;
+        },
+      },
+    ];
+  },
+
+  renderHTML({ HTMLAttributes }) {
+    const blockGroupHTMLAttributes = {
+      ...(this.options.domAttributes?.blockGroup || {}),
+      ...HTMLAttributes,
+    };
+    const blockGroup = document.createElement("div");
+    blockGroup.className = mergeCSSClasses(
+      "bn-block-group",
+      blockGroupHTMLAttributes.class
+    );
+    blockGroup.setAttribute("data-node-type", "blockGroup");
+    for (const [attribute, value] of Object.entries(blockGroupHTMLAttributes)) {
+      if (attribute !== "class") {
+        blockGroup.setAttribute(attribute, value);
+      }
+    }
+
+    return {
+      dom: blockGroup,
+      contentDOM: blockGroup,
+    };
+  },
+});

package/src/pm-nodes/Doc.ts

@@ -0,0 +1,7 @@
+import {Node} from "@tiptap/core";
+
+export const Doc = Node.create({
+    name: "doc",
+    topNode: true,
+    content: "blockGroup",
+});

package/src/pm-nodes/README.md

@@ -0,0 +1,42 @@
+### @blocknote/core/src/pm-nodes
+
+Defines the prosemirror nodes and base node structure. See below:
+
+
+# Node structure
+
+We use a Prosemirror document structure where every element is a `block` with 1 `content` element and one optional group of children (`blockgroup`).
+
+- A `block` can only appear in a `blockgroup` (which is also the type of the root node)
+- Every `block` element can have attributes (e.g.: is it a heading or a list item)
+- Every `block` element can contain a `blockgroup` as second child. In this case the `blockgroup` is considered nested (indented in the UX)
+
+This architecture is different from the "default" Prosemirror / Tiptap implementation which would use more semantic HTML node types (`p`, `li`, etc.). We have designed this block structure instead to more easily:
+
+- support indentation of any node (without complex wrapping logic)
+- supporting animations (nodes stay the same type, only attrs are changed)
+
+## Example
+
+```xml
+<blockgroup>
+    <block>
+        <content>Parent element 1</content>
+        <blockgroup>
+            <block>
+                <content>Nested / child / indented item</content>
+            </block>
+        </blockgroup>
+    </block>
+    <block>
+        <content>Parent element 2</content>
+        <blockgroup>
+            <block>...</block>
+            <block>...</block>
+        </blockgroup>
+    </block>
+    <block>
+        <content>Element 3 without children</content>
+    </block>
+</blockgroup>
+```

package/src/pm-nodes/index.ts

@@ -0,0 +1,3 @@
+export { BlockContainer } from "./BlockContainer";
+export { BlockGroup } from "./BlockGroup";
+export { Doc } from "./Doc";

package/src/schema/README.md

@@ -0,0 +1,3 @@
+### @blocknote/core/src/schema
+
+The BlockNote Schema consists of Blocks, InlineContent and Styles.

package/src/schema/blocks/createSpec.ts

@@ -0,0 +1,220 @@
+import { ParseRule } from "@tiptap/pm/model";
+import type { BlockNoteEditor } from "../../editor/BlockNoteEditor";
+import { InlineContentSchema } from "../inlineContent/types";
+import { StyleSchema } from "../styles/types";
+import {
+  createInternalBlockSpec,
+  createStronglyTypedTiptapNode,
+  getBlockFromPos,
+  propsToAttributes,
+  wrapInBlockStructure,
+} from "./internal";
+import {
+  BlockConfig,
+  BlockFromConfig,
+  BlockSchemaWithBlock,
+  PartialBlockFromConfig,
+} from "./types";
+
+// restrict content to "inline" and "none" only
+export type CustomBlockConfig = BlockConfig & {
+  content: "inline" | "none";
+};
+
+export type CustomBlockImplementation<
+  T extends CustomBlockConfig,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+> = {
+  render: (
+    /**
+     * The custom block to render
+     */
+    block: BlockFromConfig<T, I, S>,
+    /**
+     * The BlockNote editor instance
+     * This is typed generically. If you want an editor with your custom schema, you need to
+     * cast it manually, e.g.: `const e = editor as BlockNoteEditor<typeof mySchema>;`
+     */
+    editor: BlockNoteEditor<BlockSchemaWithBlock<T["type"], T>, I, S>
+    // (note) if we want to fix the manual cast, we need to prevent circular references and separate block definition and render implementations
+    // or allow manually passing <BSchema>, but that's not possible without passing the other generics because Typescript doesn't support partial inferred generics
+  ) => {
+    dom: HTMLElement;
+    contentDOM?: HTMLElement;
+    destroy?: () => void;
+  };
+  // Exports block to external HTML. If not defined, the output will be the same
+  // as `render(...).dom`. Used to create clipboard data when pasting outside
+  // BlockNote.
+  // TODO: Maybe can return undefined to ignore when serializing?
+  toExternalHTML?: (
+    block: BlockFromConfig<T, I, S>,
+    editor: BlockNoteEditor<BlockSchemaWithBlock<T["type"], T>, I, S>
+  ) => {
+    dom: HTMLElement;
+    contentDOM?: HTMLElement;
+  };
+
+  parse?: (
+    el: HTMLElement
+  ) => PartialBlockFromConfig<T, I, S>["props"] | undefined;
+};
+
+// Function that uses the 'parse' function of a blockConfig to create a
+// TipTap node's `parseHTML` property. This is only used for parsing content
+// from the clipboard.
+export function getParseRules(
+  config: BlockConfig,
+  customParseFunction: CustomBlockImplementation<any, any, any>["parse"]
+) {
+  const rules: ParseRule[] = [
+    {
+      tag: "[data-content-type=" + config.type + "]",
+      contentElement: "[data-editable]",
+    },
+  ];
+
+  if (customParseFunction) {
+    rules.push({
+      tag: "*",
+      getAttrs(node: string | HTMLElement) {
+        if (typeof node === "string") {
+          return false;
+        }
+
+        const props = customParseFunction?.(node);
+
+        if (props === undefined) {
+          return false;
+        }
+
+        return props;
+      },
+    });
+  }
+  //     getContent(node, schema) {
+  //       const block = blockConfig.parse?.(node as HTMLElement);
+  //
+  //       if (block !== undefined && block.content !== undefined) {
+  //         return Fragment.from(
+  //           typeof block.content === "string"
+  //             ? schema.text(block.content)
+  //             : inlineContentToNodes(block.content, schema)
+  //         );
+  //       }
+  //
+  //       return Fragment.empty;
+  //     },
+  //   });
+  // }
+
+  return rules;
+}
+
+// A function to create custom block for API consumers
+// we want to hide the tiptap node from API consumers and provide a simpler API surface instead
+export function createBlockSpec<
+  T extends CustomBlockConfig,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+>(blockConfig: T, blockImplementation: CustomBlockImplementation<T, I, S>) {
+  const node = createStronglyTypedTiptapNode({
+    name: blockConfig.type as T["type"],
+    content: (blockConfig.content === "inline"
+      ? "inline*"
+      : "") as T["content"] extends "inline" ? "inline*" : "",
+    group: "blockContent",
+    selectable: true,
+
+    addAttributes() {
+      return propsToAttributes(blockConfig.propSchema);
+    },
+
+    parseHTML() {
+      return getParseRules(blockConfig, blockImplementation.parse);
+    },
+
+    renderHTML() {
+      // renderHTML is not really used, as we always use a nodeView, and we use toExternalHTML / toInternalHTML for serialization
+      // There's an edge case when this gets called nevertheless; before the nodeviews have been mounted
+      // this is why we implement it with a temporary placeholder
+      const div = document.createElement("div");
+      div.setAttribute("data-tmp-placeholder", "true");
+      return {
+        dom: div,
+      };
+    },
+
+    addNodeView() {
+      return ({ getPos }) => {
+        // Gets the BlockNote editor instance
+        const editor = this.options.editor;
+        // Gets the block
+        const block = getBlockFromPos(
+          getPos,
+          editor,
+          this.editor,
+          blockConfig.type
+        );
+        // Gets the custom HTML attributes for `blockContent` nodes
+        const blockContentDOMAttributes =
+          this.options.domAttributes?.blockContent || {};
+
+        const output = blockImplementation.render(block as any, editor);
+
+        return wrapInBlockStructure(
+          output,
+          block.type,
+          block.props,
+          blockConfig.propSchema,
+          blockContentDOMAttributes
+        );
+      };
+    },
+  });
+
+  if (node.name !== blockConfig.type) {
+    throw new Error(
+      "Node name does not match block type. This is a bug in BlockNote."
+    );
+  }
+
+  return createInternalBlockSpec(blockConfig, {
+    node,
+    toInternalHTML: (block, editor) => {
+      const blockContentDOMAttributes =
+        node.options.domAttributes?.blockContent || {};
+
+      const output = blockImplementation.render(block as any, editor as any);
+
+      return wrapInBlockStructure(
+        output,
+        block.type,
+        block.props,
+        blockConfig.propSchema,
+        blockContentDOMAttributes
+      );
+    },
+    toExternalHTML: (block, editor) => {
+      const blockContentDOMAttributes =
+        node.options.domAttributes?.blockContent || {};
+
+      let output = blockImplementation.toExternalHTML?.(
+        block as any,
+        editor as any
+      );
+      if (output === undefined) {
+        output = blockImplementation.render(block as any, editor as any);
+      }
+
+      return wrapInBlockStructure(
+        output,
+        block.type,
+        block.props,
+        blockConfig.propSchema,
+        blockContentDOMAttributes
+      );
+    },
+  });
+}

package/src/schema/blocks/internal.ts

@@ -0,0 +1,253 @@
+import {
+  Attribute,
+  Attributes,
+  Editor,
+  Extension,
+  Node,
+  NodeConfig,
+} from "@tiptap/core";
+import { defaultBlockToHTML } from "../../blocks/defaultBlockHelpers";
+import { inheritedProps } from "../../blocks/defaultProps";
+import type { BlockNoteEditor } from "../../editor/BlockNoteEditor";
+import { mergeCSSClasses } from "../../util/browser";
+import { camelToDataKebab } from "../../util/string";
+import { InlineContentSchema } from "../inlineContent/types";
+import { PropSchema, Props } from "../propTypes";
+import { StyleSchema } from "../styles/types";
+import {
+  BlockConfig,
+  BlockSchemaFromSpecs,
+  BlockSchemaWithBlock,
+  BlockSpec,
+  BlockSpecs,
+  SpecificBlock,
+  TiptapBlockImplementation,
+} from "./types";
+
+// Function that uses the 'propSchema' of a blockConfig to create a TipTap
+// node's `addAttributes` property.
+// TODO: extract function
+export function propsToAttributes(propSchema: PropSchema): Attributes {
+  const tiptapAttributes: Record<string, Attribute> = {};
+
+  Object.entries(propSchema)
+    .filter(([name, _spec]) => !inheritedProps.includes(name))
+    .forEach(([name, spec]) => {
+      tiptapAttributes[name] = {
+        default: spec.default,
+        keepOnSplit: true,
+        // Props are displayed in kebab-case as HTML attributes. If a prop's
+        // value is the same as its default, we don't display an HTML
+        // attribute for it.
+        parseHTML: (element) => {
+          const value = element.getAttribute(camelToDataKebab(name));
+
+          if (value === null) {
+            return null;
+          }
+
+          if (typeof spec.default === "boolean") {
+            if (value === "true") {
+              return true;
+            }
+
+            if (value === "false") {
+              return false;
+            }
+
+            return null;
+          }
+
+          if (typeof spec.default === "number") {
+            const asNumber = parseFloat(value);
+            const isNumeric =
+              !Number.isNaN(asNumber) && Number.isFinite(asNumber);
+
+            if (isNumeric) {
+              return asNumber;
+            }
+
+            return null;
+          }
+
+          return value;
+        },
+        renderHTML: (attributes) =>
+          attributes[name] !== spec.default
+            ? {
+                [camelToDataKebab(name)]: attributes[name],
+              }
+            : {},
+      };
+    });
+
+  return tiptapAttributes;
+}
+
+// Used to figure out which block should be rendered. This block is then used to
+// create the node view.
+export function getBlockFromPos<
+  BType extends string,
+  Config extends BlockConfig,
+  BSchema extends BlockSchemaWithBlock<BType, Config>,
+  I extends InlineContentSchema,
+  S extends StyleSchema
+>(
+  getPos: (() => number) | boolean,
+  editor: BlockNoteEditor<BSchema, I, S>,
+  tipTapEditor: Editor,
+  type: BType
+) {
+  // Gets position of the node
+  if (typeof getPos === "boolean") {
+    throw new Error(
+      "Cannot find node position as getPos is a boolean, not a function."
+    );
+  }
+  const pos = getPos();
+  // Gets parent blockContainer node
+  const blockContainer = tipTapEditor.state.doc.resolve(pos!).node();
+  // Gets block identifier
+  const blockIdentifier = blockContainer.attrs.id;
+  // Gets the block
+  const block = editor.getBlock(blockIdentifier)! as SpecificBlock<
+    BSchema,
+    BType,
+    I,
+    S
+  >;
+  if (block.type !== type) {
+    throw new Error("Block type does not match");
+  }
+
+  return block;
+}
+
+// Function that wraps the `dom` element returned from 'blockConfig.render' in a
+// `blockContent` div, which contains the block type and props as HTML
+// attributes. If `blockConfig.render` also returns a `contentDOM`, it also adds
+// an `inlineContent` class to it.
+export function wrapInBlockStructure<
+  BType extends string,
+  PSchema extends PropSchema
+>(
+  element: {
+    dom: HTMLElement;
+    contentDOM?: HTMLElement;
+    destroy?: () => void;
+  },
+  blockType: BType,
+  blockProps: Props<PSchema>,
+  propSchema: PSchema,
+  domAttributes?: Record<string, string>
+): {
+  dom: HTMLElement;
+  contentDOM?: HTMLElement;
+  destroy?: () => void;
+} {
+  // Creates `blockContent` element
+  const blockContent = document.createElement("div");
+
+  // Adds custom HTML attributes
+  if (domAttributes !== undefined) {
+    for (const [attr, value] of Object.entries(domAttributes)) {
+      if (attr !== "class") {
+        blockContent.setAttribute(attr, value);
+      }
+    }
+  }
+  // Sets blockContent class
+  blockContent.className = mergeCSSClasses(
+    "bn-block-content",
+    domAttributes?.class || ""
+  );
+  // Sets content type attribute
+  blockContent.setAttribute("data-content-type", blockType);
+  // Adds props as HTML attributes in kebab-case with "data-" prefix. Skips props
+  // which are already added as HTML attributes to the parent `blockContent`
+  // element (inheritedProps) and props set to their default values.
+  for (const [prop, value] of Object.entries(blockProps)) {
+    if (!inheritedProps.includes(prop) && value !== propSchema[prop].default) {
+      blockContent.setAttribute(camelToDataKebab(prop), value);
+    }
+  }
+
+  blockContent.appendChild(element.dom);
+
+  if (element.contentDOM !== undefined) {
+    element.contentDOM.className = mergeCSSClasses(
+      "bn-inline-content",
+      element.contentDOM.className
+    );
+    element.contentDOM.setAttribute("data-editable", "");
+  }
+
+  return {
+    ...element,
+    dom: blockContent,
+  };
+}
+
+// Helper type to keep track of the `name` and `content` properties after calling Node.create.
+type StronglyTypedTipTapNode<
+  Name extends string,
+  Content extends "inline*" | "tableRow+" | ""
+> = Node & { name: Name; config: { content: Content } };
+
+export function createStronglyTypedTiptapNode<
+  Name extends string,
+  Content extends "inline*" | "tableRow+" | ""
+>(config: NodeConfig & { name: Name; content: Content }) {
+  return Node.create(config) as StronglyTypedTipTapNode<Name, Content>; // force re-typing (should be safe as it's type-checked from the config)
+}
+
+// This helper function helps to instantiate a blockspec with a
+// config and implementation that conform to the type of Config
+export function createInternalBlockSpec<T extends BlockConfig>(
+  config: T,
+  implementation: TiptapBlockImplementation<
+    T,
+    any,
+    InlineContentSchema,
+    StyleSchema
+  >
+) {
+  return {
+    config,
+    implementation,
+  } satisfies BlockSpec<T, any, InlineContentSchema, StyleSchema>;
+}
+
+export function createBlockSpecFromStronglyTypedTiptapNode<
+  T extends Node,
+  P extends PropSchema
+>(node: T, propSchema: P, requiredExtensions?: Array<Extension | Node>) {
+  return createInternalBlockSpec(
+    {
+      type: node.name as T["name"],
+      content: (node.config.content === "inline*"
+        ? "inline"
+        : node.config.content === "tableRow+"
+        ? "table"
+        : "none") as T["config"]["content"] extends "inline*"
+        ? "inline"
+        : T["config"]["content"] extends "tableRow+"
+        ? "table"
+        : "none",
+      propSchema,
+    },
+    {
+      node,
+      requiredExtensions,
+      toInternalHTML: defaultBlockToHTML,
+      toExternalHTML: defaultBlockToHTML,
+      // parse: () => undefined, // parse rules are in node already
+    }
+  );
+}
+
+export function getBlockSchemaFromSpecs<T extends BlockSpecs>(specs: T) {
+  return Object.fromEntries(
+    Object.entries(specs).map(([key, value]) => [key, value.config])
+  ) as BlockSchemaFromSpecs<T>;
+}