@blocknote/core 0.42.3 → 0.44.0

package/src/editor/BlockNoteExtension.test.ts

@@ -0,0 +1,103 @@
+import { expect, it } from "vitest";
+import { createExtension, ExtensionOptions } from "./BlockNoteExtension.js";
+import { BlockNoteEditor } from "./BlockNoteEditor.js";
+
+const editor = BlockNoteEditor.create();
+/**
+ * @vitest-environment jsdom
+ */
+it("creates an extension factory", () => {
+  const extension = createExtension(() => {
+    return {
+      key: "test",
+      prosemirrorPlugins: [],
+    } as const;
+  });
+
+  const extInstance = extension()({ editor });
+  expect(extInstance.key).toBe("test");
+  expect(extInstance.prosemirrorPlugins).toEqual([]);
+});
+
+it("creates an extension factory with options", () => {
+  const extension = createExtension((opts: ExtensionOptions<{ x: number }>) => {
+    expect(opts.options.x).toBe(1);
+    return {
+      key: "test",
+      prosemirrorPlugins: [],
+    } as const;
+  });
+
+  const extInstance = extension({ x: 1 })({ editor });
+  expect(extInstance.key).toBe("test");
+  expect(extInstance.prosemirrorPlugins).toEqual([]);
+});
+
+it("creates an extension factory with undefined options", () => {
+  const extension = createExtension(
+    (opts: ExtensionOptions<{ x: number } | undefined>) => {
+      expect(opts.options).toBe(undefined);
+      return {
+        key: "test",
+        prosemirrorPlugins: [],
+      } as const;
+    },
+  );
+
+  const extInstance = extension()({ editor });
+  expect(extInstance.key).toBe("test");
+  expect(extInstance.prosemirrorPlugins).toEqual([]);
+});
+
+it("creates an extension factory from an object", () => {
+  const extension = createExtension({
+    key: "test",
+    prosemirrorPlugins: [],
+  } as const);
+
+  const extInstance = extension({ editor });
+  expect(extInstance.key).toBe("test");
+  expect(extInstance.prosemirrorPlugins).toEqual([]);
+});
+
+it("allows arbitrary properties on a no-options extension", () => {
+  const extension = createExtension(() => {
+    return {
+      key: "test",
+      prosemirrorPlugins: [],
+      arbitraryProperty: "arbitraryValue",
+      arbitraryMethod: () => {
+        return "arbitraryValue";
+      },
+    } as const;
+  });
+
+  const extInstance = extension()({ editor });
+  expect(extInstance.arbitraryProperty).toBe("arbitraryValue");
+  expect(extInstance.arbitraryMethod()).toBe("arbitraryValue");
+  // @ts-expect-error - this method takes no arguments
+  extInstance.arbitraryMethod(90);
+  // @ts-expect-error - this property is not defined
+  extInstance.nonExistentProperty = "newArbitraryValue";
+});
+
+it("allows arbitrary properties on an extension with options", () => {
+  const extension = createExtension((opts: ExtensionOptions<{ x: number }>) => {
+    expect(opts.options.x).toBe(1);
+    return {
+      key: "test",
+      prosemirrorPlugins: [],
+      arbitraryProperty: "arbitraryValue",
+      arbitraryMethod: () => {
+        return "arbitraryValue";
+      },
+    } as const;
+  });
+
+  const extInstance = extension({ x: 1 })({ editor });
+  expect(extInstance.arbitraryProperty).toBe("arbitraryValue");
+  // @ts-expect-error - this method takes no arguments
+  extInstance.arbitraryMethod(90);
+  // @ts-expect-error - this property is not defined
+  extInstance.nonExistentProperty = "newArbitraryValue";
+});

package/src/editor/BlockNoteExtension.ts

@@ -1,42 +1,57 @@
-import { Plugin } from "prosemirror-state";
-import { EventEmitter } from "../util/EventEmitter.js";
-
-import { AnyExtension } from "@tiptap/core";
-import {
-  BlockSchema,
-  InlineContentSchema,
-  PartialBlockNoDefaults,
-  StyleSchema,
-} from "../schema/index.js";
-import { BlockNoteEditor } from "./BlockNoteEditor.js";
-
-export abstract class BlockNoteExtension<
-  TEvent extends Record<string, any> = any,
-> extends EventEmitter<TEvent> {
-  public static key(): string {
-    throw new Error("You must implement the key method in your extension");
-  }
+import { Store, StoreOptions } from "@tanstack/store";
+import { type AnyExtension } from "@tiptap/core";
+import type { Plugin as ProsemirrorPlugin } from "prosemirror-state";
+import type { PartialBlockNoDefaults } from "../schema/index.js";
+import type { BlockNoteEditor } from "./BlockNoteEditor.js";
+import { originalFactorySymbol } from "./managers/ExtensionManager/symbol.js";
 
-  protected addProsemirrorPlugin(plugin: Plugin) {
-    this.plugins.push(plugin);
-  }
+/**
+ * This function is called when the extension is destroyed.
+ */
+type OnDestroy = () => void;
 
-  public readonly plugins: Plugin[] = [];
-  public get priority(): number | undefined {
-    return undefined;
-  }
+/**
+ * Describes a BlockNote extension.
+ */
+export interface Extension<State = any, Key extends string = string> {
+  /**
+   * The unique identifier for the extension.
+   */
+  readonly key: Key;
 
-  // eslint-disable-next-line
-  constructor(..._args: any[]) {
-    super();
-    // Allow subclasses to have constructors with parameters
-    // without this, we can't easily implement BlockNoteEditor.extension(MyExtension) pattern
-  }
+  /**
+   * Triggered when the extension is mounted to the editor.
+   */
+  readonly mount?: (ctx: {
+    /**
+     * The DOM element that the editor is mounted to.
+     */
+    dom: HTMLElement;
+    /**
+     * The root document of the {@link document} that the editor is mounted to.
+     */
+    root: Document | ShadowRoot;
+    /**
+     * An {@link AbortSignal} that will be aborted when the extension is destroyed.
+     */
+    signal: AbortSignal;
+  }) => void | OnDestroy;
+
+  /**
+   * The store for the extension.
+   */
+  readonly store?: Store<State>;
+
+  /**
+   * Declares what {@link Extension}s that this extension depends on.
+   */
+  readonly runsBefore?: ReadonlyArray<string>;
 
   /**
-   * Input rules for the block
+   * Input rules for a block: An input rule is what is used to replace text in a block when a regular expression match is found.
+   * As an example, typing `#` in a paragraph block will trigger an input rule to replace the text with a heading block.
    */
-  public inputRules?: InputRule[];
+  readonly inputRules?: ReadonlyArray<InputRule>;
 
   /**
    * A mapping of a keyboard shortcut to a function that will be called when the shortcut is pressed
@@ -60,17 +75,27 @@ export abstract class BlockNoteExtension<
    * }
    * ```
    */
-  public keyboardShortcuts?: Record<
+  readonly keyboardShortcuts?: Record<
     string,
-    (ctx: {
-      editor: BlockNoteEditor<BlockSchema, InlineContentSchema, StyleSchema>;
-    }) => boolean
+    (ctx: { editor: BlockNoteEditor<any, any, any> }) => boolean
   >;
 
-  public tiptapExtensions?: AnyExtension[];
+  /**
+   * Add additional prosemirror plugins to the editor.
+   */
+  readonly prosemirrorPlugins?: ReadonlyArray<ProsemirrorPlugin>;
+
+  /**
+   * Add additional tiptap extensions to the editor.
+   */
+  readonly tiptapExtensions?: ReadonlyArray<AnyExtension>;
 }
 
-export type InputRule = {
+/**
+ * An input rule is what is used to replace text in a block when a regular expression match is found.
+ * As an example, typing `#` in a paragraph block will trigger an input rule to replace the text with a heading block.
+ */
+type InputRule = {
   /**
    * The regex to match when to trigger the input rule
    */
@@ -97,22 +122,115 @@ export type InputRule = {
 };
 
 /**
- * This creates an instance of a BlockNoteExtension that can be used to add to a schema.
- * It is a bit of a hack, but it works.
+ * These are the arguments that are passed to an {@link ExtensionFactoryInstance}.
+ */
+export interface ExtensionOptions<
+  Options extends Record<string, any> | undefined =
+    | Record<string, any>
+    | undefined,
+> {
+  options: Options;
+  editor: BlockNoteEditor<any, any, any>;
+}
+
+// a type that maps the extension key to the return type of the extension factory
+export type ExtensionMap<T extends ReadonlyArray<ExtensionFactoryInstance>> = {
+  [K in T[number] extends ExtensionFactoryInstance<infer Ext>
+    ? Ext["key"]
+    : never]: T[number] extends ExtensionFactoryInstance<infer Ext>
+    ? Ext
+    : never;
+};
+
+/**
+ * This is a type that represents the function which will actually create the extension.
+ * It requires the editor instance to be passed in, but will already have the options applied automatically.
+ *
+ * @note Only the BlockNoteEditor should instantiate this function, not the user. Look at {@link createExtension} for user-facing functions.
  */
-export function createBlockNoteExtension(
-  options: Partial<
-    Pick<
-      BlockNoteExtension,
-      "inputRules" | "keyboardShortcuts" | "plugins" | "tiptapExtensions"
-    >
-  > & { key: string },
-) {
-  const x = Object.create(BlockNoteExtension.prototype);
-  x.key = options.key;
-  x.inputRules = options.inputRules;
-  x.keyboardShortcuts = options.keyboardShortcuts;
-  x.plugins = options.plugins ?? [];
-  x.tiptapExtensions = options.tiptapExtensions;
-  return x as BlockNoteExtension;
+export type ExtensionFactoryInstance<
+  Ext extends Extension<any, any> = Extension<any, any>,
+> = (ctx: Omit<ExtensionOptions<any>, "options">) => Ext;
+
+/**
+ * This is the return type of the {@link createExtension} function.
+ * It is a function that can be invoked with the extension's options to create a new extension factory.
+ */
+export type ExtensionFactory<
+  State = any,
+  Key extends string = string,
+  Factory extends (ctx: any) => Extension<State, Key> = (
+    ctx: ExtensionOptions<any>,
+  ) => Extension<State, Key>,
+> =
+  Parameters<Factory>[0] extends ExtensionOptions<infer Options>
+    ? undefined extends Options
+      ? (
+          options?: Exclude<Options, undefined>,
+        ) => ExtensionFactoryInstance<ReturnType<Factory>>
+      : (options: Options) => ExtensionFactoryInstance<ReturnType<Factory>>
+    : () => ExtensionFactoryInstance<ReturnType<Factory>>;
+
+/**
+ * Constructs a BlockNote {@link ExtensionFactory} from a factory function or object
+ */
+// This overload is for `createExtension({ key: "test", ... })`
+export function createExtension<
+  const State = any,
+  const Key extends string = string,
+  const Ext extends Extension<State, Key> = Extension<State, Key>,
+>(factory: Ext): ExtensionFactoryInstance<Ext>;
+// This overload is for `createExtension(({editor, options}) => ({ key: "test", ... }))`
+export function createExtension<
+  const State = any,
+  const Options extends Record<string, any> | undefined = any,
+  const Key extends string = string,
+  const Factory extends (ctx: any) => Extension<State, Key> = (
+    ctx: ExtensionOptions<Options>,
+  ) => Extension<State, Key>,
+>(factory: Factory): ExtensionFactory<State, Key, Factory>;
+// This overload is for both of the above overloads as it is the implementation of the function
+export function createExtension<
+  const State = any,
+  const Options extends Record<string, any> | undefined = any,
+  const Key extends string = string,
+  const Factory extends
+    | Extension<State, Key>
+    | ((ctx: any) => Extension<State, Key>) = (
+    ctx: ExtensionOptions<Options>,
+  ) => Extension<State, Key>,
+>(
+  factory: Factory,
+): Factory extends Extension<State, Key>
+  ? ExtensionFactoryInstance<Factory>
+  : Factory extends (ctx: any) => Extension<State, Key>
+    ? ExtensionFactory<State, Key, Factory>
+    : never {
+  if (typeof factory === "object" && "key" in factory) {
+    return function factoryFn() {
+      (factory as any)[originalFactorySymbol] = factoryFn;
+      return factory;
+    } as any;
+  }
+
+  if (typeof factory !== "function") {
+    throw new Error("factory must be a function");
+  }
+
+  return function factoryFn(options: Options) {
+    return (ctx: { editor: BlockNoteEditor<any, any, any> }) => {
+      const extension = factory({ editor: ctx.editor, options });
+      // We stick a symbol onto the extension to allow us to retrieve the original factory for comparison later.
+      // This enables us to do things like: `editor.getExtension(YSync).prosemirrorPlugins`
+      (extension as any)[originalFactorySymbol] = factoryFn;
+      return extension;
+    };
+  } as any;
+}
+
+export function createStore<T = any>(
+  initialState: T,
+  options?: StoreOptions<T>,
+): Store<T> {
+  return new Store(initialState, options);
 }

package/src/editor/managers/EventManager.ts

@@ -5,6 +5,11 @@ import {
 } from "../../api/getBlocksChangedByTransaction.js";
 import { Transaction } from "prosemirror-state";
 import { EventEmitter } from "../../util/EventEmitter.js";
+import {
+  BlockSchema,
+  InlineContentSchema,
+  StyleSchema,
+} from "../../schema/index.js";
 
 /**
  * A function that can be used to unsubscribe from an event.
@@ -14,37 +19,33 @@ export type Unsubscribe = () => void;
 /**
  * EventManager is a class which manages the events of the editor
  */
-export class EventManager<Editor extends BlockNoteEditor> extends EventEmitter<{
+export class EventManager<
+  BSchema extends BlockSchema,
+  I extends InlineContentSchema,
+  S extends StyleSchema,
+> extends EventEmitter<{
   onChange: [
-    editor: Editor,
     ctx: {
-      getChanges(): BlocksChanged<
-        Editor["schema"]["blockSchema"],
-        Editor["schema"]["inlineContentSchema"],
-        Editor["schema"]["styleSchema"]
-      >;
+      editor: BlockNoteEditor<BSchema, I, S>;
+      transaction: Transaction;
+      appendedTransactions: Transaction[];
     },
   ];
-  onSelectionChange: [ctx: { editor: Editor; transaction: Transaction }];
-  onMount: [ctx: { editor: Editor }];
-  onUnmount: [ctx: { editor: Editor }];
+  onSelectionChange: [
+    ctx: { editor: BlockNoteEditor<BSchema, I, S>; transaction: Transaction },
+  ];
+  onMount: [ctx: { editor: BlockNoteEditor<BSchema, I, S> }];
+  onUnmount: [ctx: { editor: BlockNoteEditor<BSchema, I, S> }];
 }> {
-  constructor(private editor: Editor) {
+  constructor(private editor: BlockNoteEditor<BSchema, I, S>) {
     super();
     // We register tiptap events only once the editor is finished initializing
     // otherwise we would be trying to register events on a tiptap editor which does not exist yet
-    editor.onCreate(() => {
+    editor.on("create", () => {
       editor._tiptapEditor.on(
         "update",
         ({ transaction, appendedTransactions }) => {
-          this.emit("onChange", editor, {
-            getChanges() {
-              return getBlocksChangedByTransaction(
-                transaction,
-                appendedTransactions,
-              );
-            },
-          });
+          this.emit("onChange", { editor, transaction, appendedTransactions });
         },
       );
       editor._tiptapEditor.on("selectionUpdate", ({ transaction }) => {
@@ -64,20 +65,41 @@ export class EventManager<Editor extends BlockNoteEditor> extends EventEmitter<{
    */
   public onChange(
     callback: (
-      editor: Editor,
+      editor: BlockNoteEditor<BSchema, I, S>,
       ctx: {
-        getChanges(): BlocksChanged<
-          Editor["schema"]["blockSchema"],
-          Editor["schema"]["inlineContentSchema"],
-          Editor["schema"]["styleSchema"]
-        >;
+        getChanges(): BlocksChanged<BSchema, I, S>;
       },
     ) => void,
+    /**
+     * If true, the callback will be triggered when the changes are caused by a remote user
+     * @default true
+     */
+    includeUpdatesFromRemote = true,
   ): Unsubscribe {
-    this.on("onChange", callback);
+    const cb = ({
+      transaction,
+      appendedTransactions,
+    }: {
+      transaction: Transaction;
+      appendedTransactions: Transaction[];
+    }) => {
+      if (!includeUpdatesFromRemote && isRemoteTransaction(transaction)) {
+        // don't trigger the callback if the changes are caused by a remote user
+        return;
+      }
+      callback(this.editor, {
+        getChanges() {
+          return getBlocksChangedByTransaction(
+            transaction,
+            appendedTransactions,
+          );
+        },
+      });
+    };
+    this.on("onChange", cb);
 
     return () => {
-      this.off("onChange", callback);
+      this.off("onChange", cb);
     };
   }
 
@@ -85,7 +107,7 @@ export class EventManager<Editor extends BlockNoteEditor> extends EventEmitter<{
    * Register a callback that will be called when the selection changes.
    */
   public onSelectionChange(
-    callback: (editor: Editor) => void,
+    callback: (editor: BlockNoteEditor<BSchema, I, S>) => void,
     /**
      * If true, the callback will be triggered when the selection changes due to a yjs sync (i.e.: other user was typing)
      */
@@ -93,11 +115,10 @@ export class EventManager<Editor extends BlockNoteEditor> extends EventEmitter<{
   ): Unsubscribe {
     const cb = (e: { transaction: Transaction }) => {
       if (
-        e.transaction.getMeta("$y-sync") &&
-        !includeSelectionChangedByRemote
+        !includeSelectionChangedByRemote &&
+        isRemoteTransaction(e.transaction)
       ) {
-        // selection changed because of a yjs sync (i.e.: other user was typing)
-        // we don't want to trigger the callback in this case
+        // don't trigger the callback if the selection changed because of a remote user
         return;
       }
       callback(this.editor);
@@ -113,7 +134,9 @@ export class EventManager<Editor extends BlockNoteEditor> extends EventEmitter<{
   /**
    * Register a callback that will be called when the editor is mounted.
    */
-  public onMount(callback: (ctx: { editor: Editor }) => void): Unsubscribe {
+  public onMount(
+    callback: (ctx: { editor: BlockNoteEditor<BSchema, I, S> }) => void,
+  ): Unsubscribe {
     this.on("onMount", callback);
 
     return () => {
@@ -124,7 +147,9 @@ export class EventManager<Editor extends BlockNoteEditor> extends EventEmitter<{
   /**
    * Register a callback that will be called when the editor is unmounted.
    */
-  public onUnmount(callback: (ctx: { editor: Editor }) => void): Unsubscribe {
+  public onUnmount(
+    callback: (ctx: { editor: BlockNoteEditor<BSchema, I, S> }) => void,
+  ): Unsubscribe {
     this.on("onUnmount", callback);
 
     return () => {
@@ -132,3 +157,7 @@ export class EventManager<Editor extends BlockNoteEditor> extends EventEmitter<{
     };
   }
 }
+
+function isRemoteTransaction(transaction: Transaction): boolean {
+  return !!transaction.getMeta("y-sync$");
+}