@blocknote/core 0.38.0 → 0.39.0

package/src/schema/blocks/types.ts

@@ -1,7 +1,10 @@
 /** Define the main block types **/
-import type { Extension, Node } from "@tiptap/core";
-
+// import { Extension, Node } from "@tiptap/core";
+import type { Node, NodeViewRendererProps } from "@tiptap/core";
+import type { Fragment, Schema } from "prosemirror-model";
+import type { ViewMutationRecord } from "prosemirror-view";
 import type { BlockNoteEditor } from "../../editor/BlockNoteEditor.js";
+import type { BlockNoteExtension } from "../../editor/BlockNoteExtension.js";
 import type {
   InlineContent,
   InlineContentSchema,
@@ -21,92 +24,128 @@ export type BlockNoteDOMAttributes = Partial<{
   [DOMElement in BlockNoteDOMElement]: Record<string, string>;
 }>;
 
-export type FileBlockConfig = {
-  type: string;
-  readonly propSchema: PropSchema & {
-    caption: {
-      default: "";
-    };
-    name: {
-      default: "";
-    };
+export interface BlockConfigMeta {
+  /**
+   * Defines which keyboard shortcut should be used to insert a hard break into the block's inline content.
+   * @default "shift+enter"
+   */
+  hardBreakShortcut?: "shift+enter" | "enter" | "none";
+
+  /**
+   * Whether the block is selectable
+   */
+  selectable?: boolean;
+
+  /**
+   * The accept mime types for the file block
+   */
+  fileBlockAccept?: string[];
 
-    // URL is optional, as we also want to accept files with no URL, but for example ids
-    // (ids can be used for files that are resolved on the backend)
-    url?: {
-      default: "";
-    };
+  /**
+   * Whether the block is a {@link https://prosemirror.net/docs/ref/#model.NodeSpec.code} block
+   */
+  code?: boolean;
 
-    // Whether to show the file preview or the name only.
-    // This is useful for some file blocks, but not all
-    // (e.g.: not relevant for default "file" block which doesn;'t show previews)
-    showPreview?: {
-      default: boolean;
-    };
-    // File preview width in px.
-    previewWidth?: {
-      default: undefined;
-      type: "number";
-    };
-  };
-  content: "none";
-  isSelectable?: boolean;
-  isFileBlock: true;
-  fileBlockAccept?: string[];
-};
+  /**
+   * Whether the block is a {@link https://prosemirror.net/docs/ref/#model.NodeSpec.defining} block
+   */
+  defining?: boolean;
 
-// BlockConfig contains the "schema" info about a Block type
-// i.e. what props it supports, what content it supports, etc.
-export type BlockConfig =
-  | {
-      type: string;
-      readonly propSchema: PropSchema;
-      content: "inline" | "none" | "table";
-      isSelectable?: boolean;
-      isFileBlock?: false;
-      hardBreakShortcut?: "shift+enter" | "enter" | "none";
-    }
-  | FileBlockConfig;
-
-// Block implementation contains the "implementation" info about a Block
-// such as the functions / Nodes required to render and / or serialize it
-export type TiptapBlockImplementation<
-  T extends BlockConfig,
-  B extends BlockSchema,
-  I extends InlineContentSchema,
-  S extends StyleSchema,
-> = {
-  requiredExtensions?: Array<Extension | Node>;
-  node: Node;
-  toInternalHTML: (
-    block: BlockFromConfigNoChildren<T, I, S> & {
-      children: BlockNoDefaults<B, I, S>[];
-    },
-    editor: BlockNoteEditor<B, I, S>,
-  ) => {
-    dom: HTMLElement;
-    contentDOM?: HTMLElement;
-  };
-  toExternalHTML: (
-    block: BlockFromConfigNoChildren<T, I, S> & {
-      children: BlockNoDefaults<B, I, S>[];
-    },
-    editor: BlockNoteEditor<B, I, S>,
-  ) => {
-    dom: HTMLElement;
-    contentDOM?: HTMLElement;
-  };
-};
+  /**
+   * Whether the block is a {@link https://prosemirror.net/docs/ref/#model.NodeSpec.isolating} block
+   */
+  isolating?: boolean;
+}
+
+/**
+ * BlockConfig contains the "schema" info about a Block type
+ * i.e. what props it supports, what content it supports, etc.
+ */
+export interface BlockConfig<
+  T extends string = string,
+  PS extends PropSchema = PropSchema,
+  C extends "inline" | "none" | "table" = "inline" | "none" | "table",
+> {
+  /**
+   * The type of the block (unique identifier within a schema)
+   */
+  type: T;
+  /**
+   * The properties that the block supports
+   * @todo will be zod schema in the future
+   */
+  readonly propSchema: PS;
+  /**
+   * The content that the block supports
+   */
+  content: C;
+  // TODO: how do you represent things that have nested content?
+  // e.g. tables, alerts (with title & content)
+}
+
+// restrict content to "inline" and "none" only
+export type CustomBlockConfig<
+  T extends string = string,
+  PS extends PropSchema = PropSchema,
+  C extends "inline" | "none" = "inline" | "none",
+> = BlockConfig<T, PS, C>;
 
 // A Spec contains both the Config and Implementation
 export type BlockSpec<
-  T extends BlockConfig,
-  B extends BlockSchema,
-  I extends InlineContentSchema,
-  S extends StyleSchema,
+  T extends string = string,
+  PS extends PropSchema = PropSchema,
+  C extends "inline" | "none" | "table" = "inline" | "none" | "table",
 > = {
-  config: T;
-  implementation: TiptapBlockImplementation<NoInfer<T>, B, I, S>;
+  config: BlockConfig<T, PS, C>;
+  implementation: BlockImplementation<T, PS, C>;
+  extensions?: BlockNoteExtension<any>[];
+};
+
+/**
+ * This allows de-coupling the types that we display to users versus the types we expose internally.
+ *
+ * This prevents issues with type-inference across parameters that Typescript cannot handle.
+ * Specifically, the blocks shape cannot be properly inferred to a specific type like we expose to the user.
+ */
+export type LooseBlockSpec<
+  T extends string = string,
+  PS extends PropSchema = PropSchema,
+  C extends "inline" | "none" | "table" = "inline" | "none" | "table",
+> = {
+  config: BlockConfig<T, PS, C>;
+  implementation: Omit<
+    BlockImplementation<T, PS, C>,
+    "render" | "toExternalHTML"
+  > & {
+    // purposefully stub the types for render and toExternalHTML since they reference the block
+    render: (
+      /**
+       * The custom block to render
+       */
+      block: any,
+      /**
+       * The BlockNote editor instance
+       */
+      editor: BlockNoteEditor<any>,
+    ) => {
+      dom: HTMLElement | DocumentFragment;
+      contentDOM?: HTMLElement;
+      ignoreMutation?: (mutation: ViewMutationRecord) => boolean;
+      destroy?: () => void;
+    };
+    toExternalHTML?: (
+      block: any,
+      editor: BlockNoteEditor<any>,
+    ) =>
+      | {
+          dom: HTMLElement | DocumentFragment;
+          contentDOM?: HTMLElement;
+        }
+      | undefined;
+
+    node: Node;
+  };
+  extensions?: BlockNoteExtension<any>[];
 };
 
 // Utility type. For a given object block schema, ensures that the key of each
@@ -125,25 +164,66 @@ type NamesMatch<Blocks extends Record<string, BlockConfig>> = Blocks extends {
 // The keys are the "type" of a block
 export type BlockSchema = NamesMatch<Record<string, BlockConfig>>;
 
-export type BlockSpecs = Record<
-  string,
-  BlockSpec<any, any, InlineContentSchema, StyleSchema>
->;
+export type BlockSpecs = {
+  [k in string]: {
+    config: BlockSpec<k>["config"];
+    implementation: Omit<
+      BlockSpec<k>["implementation"],
+      "render" | "toExternalHTML"
+    > & {
+      // purposefully stub the types for render and toExternalHTML since they reference the block
+      render: (
+        /**
+         * The custom block to render
+         */
+        block: any,
+        /**
+         * The BlockNote editor instance
+         */
+        editor: BlockNoteEditor<any>,
+      ) => {
+        dom: HTMLElement | DocumentFragment;
+        contentDOM?: HTMLElement;
+        ignoreMutation?: (mutation: ViewMutationRecord) => boolean;
+        destroy?: () => void;
+      };
+      toExternalHTML?: (
+        block: any,
+        editor: BlockNoteEditor<any>,
+      ) =>
+        | {
+            dom: HTMLElement | DocumentFragment;
+            contentDOM?: HTMLElement;
+          }
+        | undefined;
+    };
+    extensions?: BlockNoteExtension<any>[];
+  };
+};
 
 export type BlockImplementations = Record<
   string,
-  TiptapBlockImplementation<any, any, any, any>
+  BlockImplementation<any, any>
 >;
 
-export type BlockSchemaFromSpecs<T extends BlockSpecs> = {
-  [K in keyof T]: T[K]["config"];
+export type BlockSchemaFromSpecs<BS extends BlockSpecs> = {
+  [K in keyof BS]: BS[K]["config"];
 };
 
-export type BlockSchemaWithBlock<
-  BType extends string,
-  C extends BlockConfig,
-> = {
-  [k in BType]: C;
+export type BlockSpecsFromSchema<BS extends BlockSchema> = {
+  [K in keyof BS]: {
+    config: BlockConfig<BS[K]["type"], BS[K]["propSchema"], BS[K]["content"]>;
+    implementation: BlockImplementation<
+      BS[K]["type"],
+      BS[K]["propSchema"],
+      BS[K]["content"]
+    >;
+    extensions?: BlockNoteExtension<any>[];
+  };
+};
+
+export type BlockSchemaWithBlock<T extends string, C extends BlockConfig> = {
+  [k in T]: C;
 };
 
 export type TableCellProps = {
@@ -275,7 +355,9 @@ type PartialBlockFromConfigNoChildren<
     ? PartialInlineContent<I, S>
     : B["content"] extends "table"
       ? PartialTableContent<I, S>
-      : undefined;
+      : B["content"] extends "none"
+        ? undefined
+        : never;
 };
 
 type PartialBlocksWithoutChildren<
@@ -321,3 +403,91 @@ export type PartialBlockFromConfig<
 };
 
 export type BlockIdentifier = { id: string } | string;
+
+export type BlockImplementation<
+  TName extends string = string,
+  TProps extends PropSchema = PropSchema,
+  TContent extends "inline" | "none" | "table" = "inline" | "none" | "table",
+> = {
+  /**
+   * Metadata
+   */
+  meta?: BlockConfigMeta;
+  /**
+   * A function that converts the block into a DOM element
+   */
+  render: (
+    this:
+      | Record<string, never>
+      | ({
+          blockContentDOMAttributes: Record<string, string>;
+        } & (
+          | {
+              renderType: "nodeView";
+              props: NodeViewRendererProps;
+            }
+          | {
+              renderType: "dom";
+              props: undefined;
+            }
+        )),
+    /**
+     * The custom block to render
+     */
+    block: BlockFromConfig<BlockConfig<TName, TProps, TContent>, any, any>,
+    /**
+     * The BlockNote editor instance
+     */
+    editor: BlockNoteEditor<
+      Record<TName, BlockConfig<TName, TProps, TContent>>
+    >,
+  ) => {
+    dom: HTMLElement | DocumentFragment;
+    contentDOM?: HTMLElement;
+    ignoreMutation?: (mutation: ViewMutationRecord) => boolean;
+    destroy?: () => void;
+  };
+
+  /**
+   * Exports block to external HTML. If not defined, the output will be the same
+   * as `render(...).dom`.
+   */
+  toExternalHTML?: (
+    this: Partial<{
+      blockContentDOMAttributes: Record<string, string>;
+    }>,
+    block: BlockFromConfig<BlockConfig<TName, TProps, TContent>, any, any>,
+    editor: BlockNoteEditor<
+      Record<TName, BlockConfig<TName, TProps, TContent>>
+    >,
+  ) =>
+    | {
+        dom: HTMLElement | DocumentFragment;
+        contentDOM?: HTMLElement;
+      }
+    | undefined;
+
+  /**
+   * Parses an external HTML element into a block of this type when it returns the block props object, otherwise undefined
+   */
+  parse?: (el: HTMLElement) => Partial<Props<TProps>> | undefined;
+
+  /**
+   * The blocks that this block should run before.
+   * This is used to determine the order in which blocks are parsed
+   */
+  runsBefore?: string[];
+
+  /**
+   * Advanced parsing function that controls how content within the block is parsed.
+   * This is not recommended to use, and is only useful for advanced use cases.
+   */
+  parseContent?: (options: { el: HTMLElement; schema: Schema }) => Fragment;
+};
+
+// restrict content to "inline" and "none" only
+export type CustomBlockImplementation<
+  T extends string = string,
+  PS extends PropSchema = PropSchema,
+  C extends "inline" | "none" = "inline" | "none",
+> = BlockImplementation<T, PS, C>;

package/src/schema/index.ts

@@ -8,3 +8,4 @@ export * from "./propTypes.js";
 export * from "./styles/createSpec.js";
 export * from "./styles/internal.js";
 export * from "./styles/types.js";
+export * from "./schema.js";

package/src/schema/inlineContent/createSpec.ts

@@ -19,19 +19,30 @@ import {
   PartialCustomInlineContentFromConfig,
 } from "./types.js";
 
-// TODO: support serialization
-
 export type CustomInlineContentImplementation<
   T extends CustomInlineContentConfig,
-  // B extends BlockSchema,
-  // I extends InlineContentSchema,
   S extends StyleSchema,
 > = {
+  meta?: {
+    draggable?: boolean;
+  };
+
+  /**
+   * Parses an external HTML element into a inline content of this type when it returns the block props object, otherwise undefined
+   */
+  parse?: (el: HTMLElement) => Partial<Props<T["propSchema"]>> | undefined;
+
+  /**
+   * Renders an inline content to DOM elements
+   */
   render: (
     /**
      * The custom inline content to render
      */
     inlineContent: InlineContentFromConfig<T, S>,
+    /**
+     * A callback that allows overriding the inline content element
+     */
     updateInlineContent: (
       update: PartialCustomInlineContentFromConfig<T, S>,
     ) => void,
@@ -46,14 +57,37 @@ export type CustomInlineContentImplementation<
   ) => {
     dom: HTMLElement;
     contentDOM?: HTMLElement;
-    // destroy?: () => void;
+    destroy?: () => void;
   };
+
+  /**
+   * Renders an inline content to external HTML elements for use outside the editor
+   * If not provided, falls back to the render method
+   */
+  toExternalHTML?: (
+    /**
+     * The custom inline content to render
+     */
+    inlineContent: InlineContentFromConfig<T, 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<any, any, S>,
+  ) =>
+    | {
+        dom: HTMLElement | DocumentFragment;
+        contentDOM?: HTMLElement;
+      }
+    | undefined;
 };
 
-export function getInlineContentParseRules(
-  config: CustomInlineContentConfig,
-): TagParseRule[] {
-  return [
+export function getInlineContentParseRules<C extends CustomInlineContentConfig>(
+  config: C,
+  customParseFunction?: CustomInlineContentImplementation<C, any>["parse"],
+) {
+  const rules: TagParseRule[] = [
     {
       tag: `[data-inline-content-type="${config.type}"]`,
       contentElement: (element) => {
@@ -67,6 +101,26 @@ export function getInlineContentParseRules(
       },
     },
   ];
+
+  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;
+      },
+    });
+  }
+  return rules;
 }
 
 export function createInlineContentSpec<
@@ -80,11 +134,10 @@ export function createInlineContentSpec<
     name: inlineContentConfig.type,
     inline: true,
     group: "inline",
+    draggable: inlineContentImplementation.meta?.draggable,
     selectable: inlineContentConfig.content === "styled",
     atom: inlineContentConfig.content === "none",
-    content: (inlineContentConfig.content === "styled"
-      ? "inline*"
-      : "") as T["content"] extends "styled" ? "inline*" : "",
+    content: inlineContentConfig.content === "styled" ? "inline*" : "",
 
     addAttributes() {
       return propsToAttributes(inlineContentConfig.propSchema);
@@ -95,13 +148,17 @@ export function createInlineContentSpec<
     },
 
     parseHTML() {
-      return getInlineContentParseRules(inlineContentConfig);
+      return getInlineContentParseRules(
+        inlineContentConfig,
+        inlineContentImplementation.parse,
+      );
     },
 
     renderHTML({ node }) {
       const editor = this.options.editor;
 
-      const output = inlineContentImplementation.render(
+      const output = inlineContentImplementation.render.call(
+        { renderType: "dom", props: undefined },
         nodeToCustomInlineContent(
           node,
           editor.schema.inlineContentSchema,
@@ -122,24 +179,28 @@ export function createInlineContentSpec<
     },
 
     addNodeView() {
-      return ({ node, getPos }) => {
+      return (props) => {
+        const { node, getPos } = props;
         const editor = this.options.editor as BlockNoteEditor<any, any, S>;
 
-        const output = inlineContentImplementation.render(
+        const output = inlineContentImplementation.render.call(
+          { renderType: "nodeView", props },
           nodeToCustomInlineContent(
             node,
             editor.schema.inlineContentSchema,
             editor.schema.styleSchema,
           ) as any as InlineContentFromConfig<T, S>, // TODO: fix cast
           (update) => {
-            if (typeof getPos === "boolean") {
+            const content = inlineContentToNodes([update], editor.pmSchema);
+
+            const pos = getPos();
+
+            if (!pos) {
               return;
             }
 
-            const content = inlineContentToNodes([update], editor.pmSchema);
-
             editor.transact((tr) =>
-              tr.replaceWith(getPos(), getPos() + node.nodeSize, content),
+              tr.replaceWith(pos, pos + node.nodeSize, content),
             );
           },
           editor,
@@ -158,5 +219,22 @@ export function createInlineContentSpec<
   return createInlineContentSpecFromTipTapNode(
     node,
     inlineContentConfig.propSchema,
-  ) as InlineContentSpec<T>; // TODO: fix cast
+    {
+      toExternalHTML: inlineContentImplementation.toExternalHTML,
+      render(inlineContent, updateInlineContent, editor) {
+        const output = inlineContentImplementation.render(
+          inlineContent,
+          updateInlineContent,
+          editor,
+        );
+
+        return addInlineContentAttributes(
+          output,
+          inlineContentConfig.type,
+          inlineContent.props,
+          inlineContentConfig.propSchema,
+        );
+      },
+    },
+  ) as InlineContentSpec<T>;
 }

package/src/schema/inlineContent/internal.ts

@@ -4,7 +4,6 @@ import { camelToDataKebab } from "../../util/string.js";
 import { PropSchema, Props } from "../propTypes.js";
 import {
   CustomInlineContentConfig,
-  InlineContentConfig,
   InlineContentImplementation,
   InlineContentSchemaFromSpecs,
   InlineContentSpec,
@@ -43,7 +42,7 @@ export function addInlineContentAttributes<
     })
     .forEach(([prop, value]) => element.dom.setAttribute(prop, value));
 
-  if (element.contentDOM !== undefined) {
+  if (element.contentDOM) {
     element.contentDOM.setAttribute("data-editable", "");
   }
 
@@ -73,20 +72,29 @@ export function addInlineContentKeyboardShortcuts<
 
 // This helper function helps to instantiate a InlineContentSpec with a
 // config and implementation that conform to the type of Config
-export function createInternalInlineContentSpec<T extends InlineContentConfig>(
+export function createInternalInlineContentSpec<
+  const T extends CustomInlineContentConfig,
+>(
   config: T,
-  implementation: InlineContentImplementation<T>,
-) {
+  implementation: InlineContentImplementation<NoInfer<T>>,
+): InlineContentSpec<T> {
   return {
     config,
     implementation,
-  } satisfies InlineContentSpec<T>;
+  } as const;
 }
 
 export function createInlineContentSpecFromTipTapNode<
   T extends Node,
   P extends PropSchema,
->(node: T, propSchema: P) {
+>(
+  node: T,
+  propSchema: P,
+  implementation: Omit<
+    InlineContentImplementation<CustomInlineContentConfig>,
+    "node"
+  >,
+) {
   return createInternalInlineContentSpec(
     {
       type: node.name as T["name"],
@@ -94,6 +102,7 @@ export function createInlineContentSpecFromTipTapNode<
       content: node.config.content === "inline*" ? "styled" : "none",
     },
     {
+      ...implementation,
       node,
     },
   );