@blocknote/core 0.38.0 → 0.39.0

package/src/schema/inlineContent/types.ts

@@ -1,13 +1,13 @@
 import { Node } from "@tiptap/core";
 import { PropSchema, Props } from "../propTypes.js";
 import { StyleSchema, Styles } from "../styles/types.js";
+import { BlockNoteEditor } from "../../editor/BlockNoteEditor.js";
+import { ViewMutationRecord } from "prosemirror-view";
 
 export type CustomInlineContentConfig = {
   type: string;
   content: "styled" | "none"; // | "plain"
-  draggable?: boolean;
   readonly propSchema: PropSchema;
-  // content: "inline" | "none" | "table";
 };
 // InlineContentConfig contains the "schema" info about an InlineContent type
 // i.e. what props it supports, what content it supports, etc.
@@ -20,7 +20,29 @@ export type InlineContentImplementation<T extends InlineContentConfig> =
   T extends "link" | "text"
     ? undefined
     : {
+        meta?: {
+          draggable?: boolean;
+        };
         node: Node;
+        toExternalHTML?: (
+          inlineContent: any,
+          editor: BlockNoteEditor<any, any, any>,
+        ) =>
+          | {
+              dom: HTMLElement | DocumentFragment;
+              contentDOM?: HTMLElement;
+            }
+          | undefined;
+        render: (
+          inlineContent: any,
+          updateInlineContent: (update: any) => void,
+          editor: BlockNoteEditor<any, any, any>,
+        ) => {
+          dom: HTMLElement | DocumentFragment;
+          contentDOM?: HTMLElement;
+          ignoreMutation?: (mutation: ViewMutationRecord) => boolean;
+          destroy?: () => void;
+        };
       };
 
 export type InlineContentSchemaWithInlineContent<

package/src/schema/propTypes.ts

@@ -34,17 +34,23 @@ export type Props<PSchema extends PropSchema> = {
   // for required props, get type from type of "default" value,
   // and if values are specified, get type from values
   [PName in keyof PSchema]: (
-    PSchema[PName] extends { default: boolean } | { type: "boolean" }
-      ? PSchema[PName]["values"] extends readonly boolean[]
-        ? PSchema[PName]["values"][number]
+    NonNullable<PSchema[PName]> extends
+      | { default: boolean }
+      | { type: "boolean" }
+      ? NonNullable<PSchema[PName]>["values"] extends readonly boolean[]
+        ? NonNullable<PSchema[PName]>["values"][number]
         : boolean
-      : PSchema[PName] extends { default: number } | { type: "number" }
-        ? PSchema[PName]["values"] extends readonly number[]
-          ? PSchema[PName]["values"][number]
+      : NonNullable<PSchema[PName]> extends
+            | { default: number }
+            | { type: "number" }
+        ? NonNullable<PSchema[PName]>["values"] extends readonly number[]
+          ? NonNullable<PSchema[PName]>["values"][number]
           : number
-        : PSchema[PName] extends { default: string } | { type: "string" }
-          ? PSchema[PName]["values"] extends readonly string[]
-            ? PSchema[PName]["values"][number]
+        : NonNullable<PSchema[PName]> extends
+              | { default: string }
+              | { type: "string" }
+          ? NonNullable<PSchema[PName]>["values"] extends readonly string[]
+            ? NonNullable<PSchema[PName]>["values"][number]
             : string
           : never
   ) extends infer T

package/src/schema/schema.ts

@@ -0,0 +1,209 @@
+import { BlockNoteEditor } from "../editor/BlockNoteEditor.js";
+import { createDependencyGraph, toposortReverse } from "../util/topo-sort.js";
+import {
+  BlockNoDefaults,
+  BlockSchema,
+  BlockSpecs,
+  InlineContentConfig,
+  InlineContentSchema,
+  InlineContentSpec,
+  InlineContentSpecs,
+  LooseBlockSpec,
+  PartialBlockNoDefaults,
+  StyleSchema,
+  StyleSpecs,
+  addNodeAndExtensionsToSpec,
+  getInlineContentSchemaFromSpecs,
+  getStyleSchemaFromSpecs,
+} from "./index.js";
+
+function removeUndefined<T extends Record<string, any> | undefined>(obj: T): T {
+  if (!obj) {
+    return obj;
+  }
+  return Object.fromEntries(
+    Object.entries(obj).filter(([, value]) => value !== undefined),
+  ) as T;
+}
+
+export class CustomBlockNoteSchema<
+  BSchema extends BlockSchema,
+  ISchema extends InlineContentSchema,
+  SSchema extends StyleSchema,
+> {
+  // Helper so that you can use typeof schema.BlockNoteEditor
+  public readonly BlockNoteEditor: BlockNoteEditor<BSchema, ISchema, SSchema> =
+    "only for types" as any;
+
+  public readonly Block: BlockNoDefaults<BSchema, ISchema, SSchema> =
+    "only for types" as any;
+
+  public readonly PartialBlock: PartialBlockNoDefaults<
+    BSchema,
+    ISchema,
+    SSchema
+  > = "only for types" as any;
+
+  public inlineContentSpecs: InlineContentSpecs;
+  public styleSpecs: StyleSpecs;
+  public blockSpecs: {
+    [K in keyof BSchema]: K extends string
+      ? LooseBlockSpec<K, BSchema[K]["propSchema"], BSchema[K]["content"]>
+      : never;
+  };
+
+  public blockSchema: BSchema;
+  public inlineContentSchema: ISchema;
+  public styleSchema: SSchema;
+
+  constructor(
+    private opts: {
+      blockSpecs: BlockSpecs;
+      inlineContentSpecs: InlineContentSpecs;
+      styleSpecs: StyleSpecs;
+    },
+  ) {
+    const {
+      blockSpecs,
+      inlineContentSpecs,
+      styleSpecs,
+      blockSchema,
+      inlineContentSchema,
+      styleSchema,
+    } = this.init();
+    this.blockSpecs = blockSpecs;
+    this.styleSpecs = styleSpecs;
+    this.styleSchema = styleSchema;
+    this.inlineContentSpecs = inlineContentSpecs;
+    this.blockSchema = blockSchema;
+    this.inlineContentSchema = inlineContentSchema;
+  }
+
+  private init() {
+    const dag = createDependencyGraph();
+    const defaultSet = new Set<string>();
+    dag.set("default", defaultSet);
+
+    for (const [key, specDef] of Object.entries(this.opts.blockSpecs)) {
+      if (specDef.implementation.runsBefore) {
+        dag.set(key, new Set(specDef.implementation.runsBefore));
+      } else {
+        defaultSet.add(key);
+      }
+    }
+    const sortedSpecs = toposortReverse(dag);
+    const defaultIndex = sortedSpecs.findIndex((set) => set.has("default"));
+
+    /**
+     * The priority of a block is described relative to the "default" block (an arbitrary block which can be used as the reference)
+     *
+     * Since blocks are topologically sorted, we can see what their relative position is to the "default" block
+     * Each layer away from the default block is 10 priority points (arbitrarily chosen)
+     * The default block is fixed at 101 (1 point higher than any tiptap extension, giving priority to custom blocks than any defaults)
+     *
+     * This is a bit of a hack, but it's a simple way to ensure that custom blocks are always rendered with higher priority than default blocks
+     * and that custom blocks are rendered in the order they are defined in the schema
+     */
+    const getPriority = (key: string) => {
+      const index = sortedSpecs.findIndex((set) => set.has(key));
+      // the default index should map to 101
+      // one before the default index is 91
+      // one after is 111
+      return 91 + (index + defaultIndex) * 10;
+    };
+
+    const blockSpecs = Object.fromEntries(
+      Object.entries(this.opts.blockSpecs).map(([key, blockSpec]) => {
+        return [
+          key,
+          addNodeAndExtensionsToSpec(
+            blockSpec.config,
+            blockSpec.implementation,
+            blockSpec.extensions,
+            getPriority(key),
+          ),
+        ];
+      }),
+    ) as {
+      [K in keyof BSchema]: K extends string
+        ? LooseBlockSpec<K, BSchema[K]["propSchema"], BSchema[K]["content"]>
+        : never;
+    };
+
+    return {
+      blockSpecs,
+      blockSchema: Object.fromEntries(
+        Object.entries(blockSpecs).map(([key, blockDef]) => {
+          return [key, blockDef.config];
+        }),
+      ) as any,
+      inlineContentSpecs: removeUndefined(this.opts.inlineContentSpecs),
+      styleSpecs: removeUndefined(this.opts.styleSpecs),
+      inlineContentSchema: getInlineContentSchemaFromSpecs(
+        this.opts.inlineContentSpecs,
+      ) as any,
+      styleSchema: getStyleSchemaFromSpecs(this.opts.styleSpecs) as any,
+    };
+  }
+
+  /**
+   * Adds additional block specs to the current schema in a builder pattern.
+   * This method allows extending the schema after it has been created.
+   *
+   * @param additionalBlockSpecs - Additional block specs to add to the schema
+   * @returns The current schema instance for chaining
+   */
+  public extend<
+    AdditionalBlockSpecs extends BlockSpecs = Record<string, never>,
+    AdditionalInlineContentSpecs extends Record<
+      string,
+      InlineContentSpec<InlineContentConfig>
+    > = Record<string, never>,
+    AdditionalStyleSpecs extends StyleSpecs = Record<string, never>,
+  >(opts: {
+    blockSpecs?: AdditionalBlockSpecs;
+    inlineContentSpecs?: AdditionalInlineContentSpecs;
+    styleSpecs?: AdditionalStyleSpecs;
+  }): CustomBlockNoteSchema<
+    AdditionalBlockSpecs extends undefined | Record<string, never>
+      ? BSchema
+      : BSchema & {
+          [K in keyof AdditionalBlockSpecs]: K extends string
+            ? AdditionalBlockSpecs[K]["config"]
+            : never;
+        },
+    AdditionalInlineContentSpecs extends undefined | Record<string, never>
+      ? ISchema
+      : ISchema & {
+          [K in keyof AdditionalInlineContentSpecs]: AdditionalInlineContentSpecs[K]["config"];
+        },
+    AdditionalStyleSpecs extends undefined | Record<string, never>
+      ? SSchema
+      : SSchema & {
+          [K in keyof AdditionalStyleSpecs]: AdditionalStyleSpecs[K]["config"];
+        }
+  > {
+    // Merge the new specs with existing ones
+    Object.assign(this.opts.blockSpecs, opts.blockSpecs);
+    Object.assign(this.opts.inlineContentSpecs, opts.inlineContentSpecs);
+    Object.assign(this.opts.styleSpecs, opts.styleSpecs);
+
+    // Reinitialize the block specs with the merged specs
+    const {
+      blockSpecs,
+      inlineContentSpecs,
+      styleSpecs,
+      blockSchema,
+      inlineContentSchema,
+      styleSchema,
+    } = this.init();
+    this.blockSpecs = blockSpecs;
+    this.styleSpecs = styleSpecs;
+    this.styleSchema = styleSchema;
+    this.inlineContentSpecs = inlineContentSpecs;
+    this.blockSchema = blockSchema;
+    this.inlineContentSchema = inlineContentSchema;
+
+    return this as any;
+  }
+}

package/src/schema/styles/createSpec.ts

@@ -1,7 +1,6 @@
 import { Mark } from "@tiptap/core";
 
-import { ParseRule } from "@tiptap/pm/model";
-import { UnreachableCaseError } from "../../util/typescript.js";
+import { ParseRule, TagParseRule } from "@tiptap/pm/model";
 import {
   addStyleAttributes,
   createInternalStyleSpec,
@@ -10,21 +9,26 @@ import {
 import { StyleConfig, StyleSpec } from "./types.js";
 
 export type CustomStyleImplementation<T extends StyleConfig> = {
-  render: T["propSchema"] extends "boolean"
-    ? () => {
-        dom: HTMLElement;
-        contentDOM?: HTMLElement;
-      }
-    : (value: string) => {
-        dom: HTMLElement;
-        contentDOM?: HTMLElement;
-      };
+  render: (value: T["propSchema"] extends "boolean" ? undefined : string) => {
+    dom: HTMLElement;
+    contentDOM?: HTMLElement;
+  };
+  toExternalHTML?: (
+    value: T["propSchema"] extends "boolean" ? undefined : string,
+  ) => {
+    dom: HTMLElement;
+    contentDOM?: HTMLElement;
+  };
+  parse?: (
+    element: HTMLElement,
+  ) => (T["propSchema"] extends "boolean" ? true : string) | undefined;
 };
 
-// TODO: support serialization
-
-export function getStyleParseRules(config: StyleConfig): ParseRule[] {
-  return [
+export function getStyleParseRules<T extends StyleConfig>(
+  config: T,
+  customParseFunction?: CustomStyleImplementation<T>["parse"],
+): ParseRule[] {
+  const rules: TagParseRule[] = [
     {
       tag: `[data-style-type="${config.type}"]`,
       contentElement: (element) => {
@@ -38,9 +42,29 @@ export function getStyleParseRules(config: StyleConfig): ParseRule[] {
       },
     },
   ];
+
+  if (customParseFunction) {
+    rules.push({
+      tag: "*",
+      getAttrs(node: string | HTMLElement) {
+        if (typeof node === "string") {
+          return false;
+        }
+
+        const stringValue = customParseFunction?.(node);
+
+        if (stringValue === undefined) {
+          return false;
+        }
+
+        return { stringValue };
+      },
+    });
+  }
+  return rules;
 }
 
-export function createStyleSpec<T extends StyleConfig>(
+export function createStyleSpec<const T extends StyleConfig>(
   styleConfig: T,
   styleImplementation: CustomStyleImplementation<T>,
 ): StyleSpec<T> {
@@ -52,25 +76,14 @@ export function createStyleSpec<T extends StyleConfig>(
     },
 
     parseHTML() {
-      return getStyleParseRules(styleConfig);
+      return getStyleParseRules(styleConfig, styleImplementation.parse);
     },
 
     renderHTML({ mark }) {
-      let renderResult: {
-        dom: HTMLElement;
-        contentDOM?: HTMLElement;
-      };
+      const renderResult = (
+        styleImplementation.toExternalHTML || styleImplementation.render
+      )(mark.attrs.stringValue);
 
-      if (styleConfig.propSchema === "boolean") {
-        // @ts-ignore not sure why this is complaining
-        renderResult = styleImplementation.render();
-      } else if (styleConfig.propSchema === "string") {
-        renderResult = styleImplementation.render(mark.attrs.stringValue);
-      } else {
-        throw new UnreachableCaseError(styleConfig.propSchema);
-      }
-
-      // const renderResult = styleImplementation.render();
       return addStyleAttributes(
         renderResult,
         styleConfig.type,
@@ -78,9 +91,44 @@ export function createStyleSpec<T extends StyleConfig>(
         styleConfig.propSchema,
       );
     },
+
+    addMarkView() {
+      return ({ mark }) => {
+        const renderResult = styleImplementation.render(mark.attrs.stringValue);
+
+        return addStyleAttributes(
+          renderResult,
+          styleConfig.type,
+          mark.attrs.stringValue,
+          styleConfig.propSchema,
+        );
+      };
+    },
   });
 
   return createInternalStyleSpec(styleConfig, {
     mark,
+    render: (value) => {
+      const renderResult = styleImplementation.render(value as any);
+
+      return addStyleAttributes(
+        renderResult,
+        styleConfig.type,
+        value,
+        styleConfig.propSchema,
+      );
+    },
+    toExternalHTML: (value) => {
+      const renderResult = (
+        styleImplementation.toExternalHTML || styleImplementation.render
+      )(value as any);
+
+      return addStyleAttributes(
+        renderResult,
+        styleConfig.type,
+        value,
+        styleConfig.propSchema,
+      );
+    },
   });
 }

package/src/schema/styles/internal.ts

@@ -1,4 +1,5 @@
 import { Attributes, Mark } from "@tiptap/core";
+import { DOMSerializer } from "@tiptap/pm/model";
 import {
   StyleConfig,
   StyleImplementation,
@@ -55,7 +56,7 @@ export function addStyleAttributes<
     element.dom.setAttribute("data-value", styleValue as string);
   }
 
-  if (element.contentDOM !== undefined) {
+  if (element.contentDOM) {
     element.contentDOM.setAttribute("data-editable", "");
   }
 
@@ -66,7 +67,7 @@ export function addStyleAttributes<
 // config and implementation that conform to the type of Config
 export function createInternalStyleSpec<T extends StyleConfig>(
   config: T,
-  implementation: StyleImplementation,
+  implementation: StyleImplementation<T>,
 ) {
   return {
     config,
@@ -85,6 +86,64 @@ export function createStyleSpecFromTipTapMark<
     },
     {
       mark,
+      render(value, editor) {
+        const toDOM = editor.pmSchema.marks[mark.name].spec.toDOM;
+
+        if (toDOM === undefined) {
+          throw new Error(
+            "This block has no default HTML serialization as its corresponding TipTap node doesn't implement `renderHTML`.",
+          );
+        }
+
+        const markInstance = editor.pmSchema.mark(mark.name, {
+          stringValue: value,
+        });
+
+        const renderSpec = DOMSerializer.renderSpec(
+          document,
+          toDOM(markInstance, true),
+        );
+
+        if (typeof renderSpec !== "object" || !("dom" in renderSpec)) {
+          throw new Error(
+            "Cannot use this block's default HTML serialization as its corresponding TipTap mark's `renderHTML` function does not return an object with the `dom` property.",
+          );
+        }
+
+        return renderSpec as {
+          dom: HTMLElement;
+          contentDOM?: HTMLElement;
+        };
+      },
+      toExternalHTML(value, editor) {
+        const toDOM = editor.pmSchema.marks[mark.name].spec.toDOM;
+
+        if (toDOM === undefined) {
+          throw new Error(
+            "This block has no default HTML serialization as its corresponding TipTap node doesn't implement `renderHTML`.",
+          );
+        }
+
+        const markInstance = editor.pmSchema.mark(mark.name, {
+          stringValue: value,
+        });
+
+        const renderSpec = DOMSerializer.renderSpec(
+          document,
+          toDOM(markInstance, true),
+        );
+
+        if (typeof renderSpec !== "object" || !("dom" in renderSpec)) {
+          throw new Error(
+            "Cannot use this block's default HTML serialization as its corresponding TipTap mark's `renderHTML` function does not return an object with the `dom` property.",
+          );
+        }
+
+        return renderSpec as {
+          dom: HTMLElement;
+          contentDOM?: HTMLElement;
+        };
+      },
     },
   );
 }

package/src/schema/styles/types.ts

@@ -1,4 +1,5 @@
 import { Mark } from "@tiptap/core";
+import { BlockNoteEditor } from "../../editor/BlockNoteEditor.js";
 
 export type StylePropSchema = "boolean" | "string"; // TODO: use PropSchema as name? Use objects as type similar to blocks?
 
@@ -7,20 +8,33 @@ export type StylePropSchema = "boolean" | "string"; // TODO: use PropSchema as n
 export type StyleConfig = {
   type: string;
   readonly propSchema: StylePropSchema;
-  // content: "inline" | "none" | "table";
 };
 
 // StyleImplementation contains the "implementation" info about a Style element.
 // Currently, the implementation is always a TipTap Mark
-export type StyleImplementation = {
+export type StyleImplementation<T extends StyleConfig> = {
   mark: Mark;
+  render: (
+    value: T["propSchema"] extends "boolean" ? undefined : string,
+    editor: BlockNoteEditor<any, any, any>,
+  ) => {
+    dom: HTMLElement;
+    contentDOM?: HTMLElement;
+  };
+  toExternalHTML?: (
+    value: T["propSchema"] extends "boolean" ? undefined : string,
+    editor: BlockNoteEditor<any, any, any>,
+  ) => {
+    dom: HTMLElement;
+    contentDOM?: HTMLElement;
+  };
 };
 
 // Container for both the config and implementation of a Style,
 // and the type of `implementation` is based on that of the config
 export type StyleSpec<T extends StyleConfig> = {
   config: T;
-  implementation: StyleImplementation;
+  implementation: StyleImplementation<T>;
 };
 
 // A Schema contains all the types (Configs) supported in an editor

package/src/util/topo-sort.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect, it } from "vitest";
+import { toposort as batchingToposort, toposortReverse } from "./topo-sort.js";
+
+describe("toposort", () => {
+  it("toposorts an empty graph", () => {
+    expect(batchingToposort(new Map())).toEqual([]);
+  });
+
+  it("toposorts a simple DAG", () => {
+    expect(
+      batchingToposort(
+        new Map([
+          ["a", ["b"]],
+          ["b", ["c"]],
+          ["c", []],
+        ]),
+      ),
+    ).toEqual([new Set(["a"]), new Set(["b"]), new Set(["c"])]);
+  });
+
+  it("toposorts a richer DAG", () => {
+    expect(
+      batchingToposort(
+        new Map([
+          ["a", ["c"]],
+          ["b", ["c"]],
+          ["c", []],
+        ]),
+      ),
+    ).toEqual([new Set(["a", "b"]), new Set(["c"])]);
+  });
+
+  it("toposorts a complex DAG", () => {
+    expect(
+      batchingToposort(
+        new Map([
+          ["a", ["c", "f"]],
+          ["b", ["d", "e"]],
+          ["c", ["f"]],
+          ["d", ["f", "g"]],
+          ["e", ["h"]],
+          ["f", ["i"]],
+          ["g", ["j"]],
+          ["h", ["j"]],
+          ["i", []],
+          ["j", []],
+        ]),
+      ),
+    ).toEqual([
+      new Set(["a", "b"]),
+      new Set(["c", "d", "e"]),
+      new Set(["f", "g", "h"]),
+      new Set(["i", "j"]),
+    ]);
+  });
+
+  it("errors on a small cyclic graph", () => {
+    const dg = new Map([
+      ["a", ["b"]],
+      ["b", ["a"]],
+      ["c", []],
+    ]);
+    const sortCyclicGraph = () => {
+      batchingToposort(dg);
+    };
+    expect(sortCyclicGraph).toThrowError(Error);
+  });
+
+  it("errors on a larger cyclic graph", () => {
+    const dg = new Map([
+      ["a", ["b", "c"]],
+      ["b", ["c"]],
+      ["c", ["d", "e"]],
+      ["d", ["b"]],
+      ["e", []],
+    ]);
+    const sortCyclicGraph = () => {
+      batchingToposort(dg);
+    };
+    expect(sortCyclicGraph).toThrowError(Error);
+  });
+
+  it("can sort a graph with missing dependencies", () => {
+    const dg = new Map([
+      ["a", ["non-existent-node"]],
+      ["b", ["c"]],
+      ["c", []],
+    ]);
+    const result = batchingToposort(dg);
+    expect(result).toEqual([
+      new Set(["a", "b"]),
+      new Set(["non-existent-node", "c"]),
+    ]);
+  });
+});
+
+describe("toposortReverse", () => {
+  it("can sort stuff", () => {
+    const graph = new Map([
+      ["floss", ["brushTeeth"]],
+      ["drinkCoffee", ["wakeUp"]],
+      ["wakeUp", []],
+      ["brushTeeth", ["drinkCoffee", "eatBreakfast"]],
+      ["eatBreakfast", ["wakeUp"]],
+    ]);
+    const result = toposortReverse(graph);
+    expect(result).toMatchInlineSnapshot(`
+      [
+        Set {
+          "wakeUp",
+        },
+        Set {
+          "drinkCoffee",
+          "eatBreakfast",
+        },
+        Set {
+          "brushTeeth",
+        },
+        Set {
+          "floss",
+        },
+      ]
+    `);
+  });
+});