@blocknote/core 0.40.0 → 0.41.1

package/src/editor/managers/ExportManager.ts

@@ -0,0 +1,137 @@
+import { createExternalHTMLExporter } from "../../api/exporters/html/externalHTMLExporter.js";
+import { createInternalHTMLSerializer } from "../../api/exporters/html/internalHTMLSerializer.js";
+import { blocksToMarkdown } from "../../api/exporters/markdown/markdownExporter.js";
+import { HTMLToBlocks } from "../../api/parsers/html/parseHTML.js";
+import {
+  markdownToBlocks,
+  markdownToHTML,
+} from "../../api/parsers/markdown/parseMarkdown.js";
+import {
+  Block,
+  DefaultBlockSchema,
+  DefaultInlineContentSchema,
+  DefaultStyleSchema,
+  PartialBlock,
+} from "../../blocks/defaultBlocks.js";
+import {
+  BlockSchema,
+  InlineContentSchema,
+  StyleSchema,
+} from "../../schema/index.js";
+import { BlockNoteEditor } from "../BlockNoteEditor.js";
+
+export class ExportManager<
+  BSchema extends BlockSchema = DefaultBlockSchema,
+  ISchema extends InlineContentSchema = DefaultInlineContentSchema,
+  SSchema extends StyleSchema = DefaultStyleSchema,
+> {
+  constructor(private editor: BlockNoteEditor<BSchema, ISchema, SSchema>) {}
+
+  /**
+   * Exports blocks into a simplified HTML string. To better conform to HTML standards, children of blocks which aren't list
+   * items are un-nested in the output HTML.
+   *
+   * @param blocks An array of blocks that should be serialized into HTML.
+   * @returns The blocks, serialized as an HTML string.
+   */
+  public blocksToHTMLLossy(
+    blocks: PartialBlock<BSchema, ISchema, SSchema>[] = this.editor.document,
+  ): string {
+    const exporter = createExternalHTMLExporter(
+      this.editor.pmSchema,
+      this.editor,
+    );
+    return exporter.exportBlocks(blocks, {});
+  }
+
+  /**
+   * Serializes blocks into an HTML string in the format that would normally be rendered by the editor.
+   *
+   * Use this method if you want to server-side render HTML (for example, a blog post that has been edited in BlockNote)
+   * and serve it to users without loading the editor on the client (i.e.: displaying the blog post)
+   *
+   * @param blocks An array of blocks that should be serialized into HTML.
+   * @returns The blocks, serialized as an HTML string.
+   */
+  public blocksToFullHTML(
+    blocks: PartialBlock<BSchema, ISchema, SSchema>[],
+  ): string {
+    const exporter = createInternalHTMLSerializer(
+      this.editor.pmSchema,
+      this.editor,
+    );
+    return exporter.serializeBlocks(blocks, {});
+  }
+
+  /**
+   * Parses blocks from an HTML string. Tries to create `Block` objects out of any HTML block-level elements, and
+   * `InlineNode` objects from any HTML inline elements, though not all element types are recognized. If BlockNote
+   * doesn't recognize an HTML element's tag, it will parse it as a paragraph or plain text.
+   * @param html The HTML string to parse blocks from.
+   * @returns The blocks parsed from the HTML string.
+   */
+  public tryParseHTMLToBlocks(
+    html: string,
+  ): Block<BSchema, ISchema, SSchema>[] {
+    return HTMLToBlocks(html, this.editor.pmSchema);
+  }
+
+  /**
+   * Serializes blocks into a Markdown string. The output is simplified as Markdown does not support all features of
+   * BlockNote - children of blocks which aren't list items are un-nested and certain styles are removed.
+   * @param blocks An array of blocks that should be serialized into Markdown.
+   * @returns The blocks, serialized as a Markdown string.
+   */
+  public blocksToMarkdownLossy(
+    blocks: PartialBlock<BSchema, ISchema, SSchema>[] = this.editor.document,
+  ): string {
+    return blocksToMarkdown(blocks, this.editor.pmSchema, this.editor, {});
+  }
+
+  /**
+   * Creates a list of blocks from a Markdown string. Tries to create `Block` and `InlineNode` objects based on
+   * Markdown syntax, though not all symbols are recognized. If BlockNote doesn't recognize a symbol, it will parse it
+   * as text.
+   * @param markdown The Markdown string to parse blocks from.
+   * @returns The blocks parsed from the Markdown string.
+   */
+  public tryParseMarkdownToBlocks(
+    markdown: string,
+  ): Block<BSchema, ISchema, SSchema>[] {
+    return markdownToBlocks(markdown, this.editor.pmSchema);
+  }
+
+  /**
+   * Paste HTML into the editor. Defaults to converting HTML to BlockNote HTML.
+   * @param html The HTML to paste.
+   * @param raw Whether to paste the HTML as is, or to convert it to BlockNote HTML.
+   */
+  public pasteHTML(html: string, raw = false) {
+    let htmlToPaste = html;
+    if (!raw) {
+      const blocks = this.tryParseHTMLToBlocks(html);
+      htmlToPaste = this.blocksToFullHTML(blocks);
+    }
+    if (!htmlToPaste) {
+      return;
+    }
+    this.editor.prosemirrorView?.pasteHTML(htmlToPaste);
+  }
+
+  /**
+   * Paste text into the editor. Defaults to interpreting text as markdown.
+   * @param text The text to paste.
+   */
+  public pasteText(text: string) {
+    return this.editor.prosemirrorView?.pasteText(text);
+  }
+
+  /**
+   * Paste markdown into the editor.
+   * @param markdown The markdown to paste.
+   */
+  public pasteMarkdown(markdown: string) {
+    const html = markdownToHTML(markdown);
+    return this.pasteHTML(html);
+  }
+}

package/src/editor/managers/ExtensionManager.ts

@@ -0,0 +1,130 @@
+import { FilePanelProsemirrorPlugin } from "../../extensions/FilePanel/FilePanelPlugin.js";
+import { FormattingToolbarProsemirrorPlugin } from "../../extensions/FormattingToolbar/FormattingToolbarPlugin.js";
+import { LinkToolbarProsemirrorPlugin } from "../../extensions/LinkToolbar/LinkToolbarPlugin.js";
+import { ShowSelectionPlugin } from "../../extensions/ShowSelection/ShowSelectionPlugin.js";
+import { SideMenuProsemirrorPlugin } from "../../extensions/SideMenu/SideMenuPlugin.js";
+import { SuggestionMenuProseMirrorPlugin } from "../../extensions/SuggestionMenu/SuggestionPlugin.js";
+import { TableHandlesProsemirrorPlugin } from "../../extensions/TableHandles/TableHandlesPlugin.js";
+import { BlockNoteExtension } from "../BlockNoteExtension.js";
+import { BlockNoteEditor } from "../BlockNoteEditor.js";
+
+export class ExtensionManager {
+  constructor(private editor: BlockNoteEditor) {}
+
+  /**
+   * Shorthand to get a typed extension from the editor, by
+   * just passing in the extension class.
+   *
+   * @param ext - The extension class to get
+   * @param key - optional, the key of the extension in the extensions object (defaults to the extension name)
+   * @returns The extension instance
+   */
+  public extension<T extends BlockNoteExtension>(
+    ext: { new (...args: any[]): T } & typeof BlockNoteExtension,
+    key = ext.key(),
+  ): T {
+    const extension = this.editor.extensions[key] as T;
+    if (!extension) {
+      throw new Error(`Extension ${key} not found`);
+    }
+    return extension;
+  }
+
+  /**
+   * Get all extensions
+   */
+  public getExtensions() {
+    return this.editor.extensions;
+  }
+
+  /**
+   * Get a specific extension by key
+   */
+  public getExtension(key: string) {
+    return this.editor.extensions[key];
+  }
+
+  /**
+   * Check if an extension exists
+   */
+  public hasExtension(key: string): boolean {
+    return key in this.editor.extensions;
+  }
+
+  // Plugin getters - these provide access to the core BlockNote plugins
+
+  /**
+   * Get the formatting toolbar plugin
+   */
+  public get formattingToolbar(): FormattingToolbarProsemirrorPlugin {
+    return this.editor.extensions[
+      "formattingToolbar"
+    ] as FormattingToolbarProsemirrorPlugin;
+  }
+
+  /**
+   * Get the link toolbar plugin
+   */
+  public get linkToolbar(): LinkToolbarProsemirrorPlugin<any, any, any> {
+    return this.editor.extensions[
+      "linkToolbar"
+    ] as LinkToolbarProsemirrorPlugin<any, any, any>;
+  }
+
+  /**
+   * Get the side menu plugin
+   */
+  public get sideMenu(): SideMenuProsemirrorPlugin<any, any, any> {
+    return this.editor.extensions["sideMenu"] as SideMenuProsemirrorPlugin<
+      any,
+      any,
+      any
+    >;
+  }
+
+  /**
+   * Get the suggestion menus plugin
+   */
+  public get suggestionMenus(): SuggestionMenuProseMirrorPlugin<any, any, any> {
+    return this.editor.extensions[
+      "suggestionMenus"
+    ] as SuggestionMenuProseMirrorPlugin<any, any, any>;
+  }
+
+  /**
+   * Get the file panel plugin (if available)
+   */
+  public get filePanel(): FilePanelProsemirrorPlugin<any, any> | undefined {
+    return this.editor.extensions["filePanel"] as
+      | FilePanelProsemirrorPlugin<any, any>
+      | undefined;
+  }
+
+  /**
+   * Get the table handles plugin (if available)
+   */
+  public get tableHandles():
+    | TableHandlesProsemirrorPlugin<any, any>
+    | undefined {
+    return this.editor.extensions["tableHandles"] as
+      | TableHandlesProsemirrorPlugin<any, any>
+      | undefined;
+  }
+
+  /**
+   * Get the show selection plugin
+   */
+  public get showSelectionPlugin(): ShowSelectionPlugin {
+    return this.editor.extensions["showSelection"] as ShowSelectionPlugin;
+  }
+
+  /**
+   * Check if collaboration is enabled (Yjs or Liveblocks)
+   */
+  public get isCollaborationEnabled(): boolean {
+    return (
+      this.hasExtension("ySyncPlugin") ||
+      this.hasExtension("liveblocksExtension")
+    );
+  }
+}

package/src/editor/managers/SelectionManager.ts

@@ -0,0 +1,114 @@
+import {
+  getSelection,
+  getSelectionCutBlocks,
+  setSelection,
+} from "../../api/blockManipulation/selections/selection.js";
+import {
+  getTextCursorPosition,
+  setTextCursorPosition,
+} from "../../api/blockManipulation/selections/textCursorPosition.js";
+import { isNodeSelection, posToDOMRect } from "@tiptap/core";
+import {
+  BlockIdentifier,
+  BlockSchema,
+  InlineContentSchema,
+  StyleSchema,
+} from "../../schema/index.js";
+import {
+  DefaultBlockSchema,
+  DefaultInlineContentSchema,
+  DefaultStyleSchema,
+} from "../../blocks/defaultBlocks.js";
+import { Selection } from "../selectionTypes.js";
+import { TextCursorPosition } from "../cursorPositionTypes.js";
+import { BlockNoteEditor } from "../BlockNoteEditor.js";
+
+export class SelectionManager<
+  BSchema extends BlockSchema = DefaultBlockSchema,
+  ISchema extends InlineContentSchema = DefaultInlineContentSchema,
+  SSchema extends StyleSchema = DefaultStyleSchema,
+> {
+  constructor(private editor: BlockNoteEditor<BSchema, ISchema, SSchema>) {}
+
+  /**
+   * Gets a snapshot of the current selection. This contains all blocks (included nested blocks)
+   * that the selection spans across.
+   *
+   * If the selection starts / ends halfway through a block, the returned data will contain the entire block.
+   */
+  public getSelection(): Selection<BSchema, ISchema, SSchema> | undefined {
+    return this.editor.transact((tr) => getSelection(tr));
+  }
+
+  /**
+   * Gets a snapshot of the current selection. This contains all blocks (included nested blocks)
+   * that the selection spans across.
+   *
+   * If the selection starts / ends halfway through a block, the returned block will be
+   * only the part of the block that is included in the selection.
+   */
+  public getSelectionCutBlocks() {
+    return this.editor.transact((tr) => getSelectionCutBlocks(tr));
+  }
+
+  /**
+   * Sets the selection to a range of blocks.
+   * @param startBlock The identifier of the block that should be the start of the selection.
+   * @param endBlock The identifier of the block that should be the end of the selection.
+   */
+  public setSelection(startBlock: BlockIdentifier, endBlock: BlockIdentifier) {
+    return this.editor.transact((tr) => setSelection(tr, startBlock, endBlock));
+  }
+
+  /**
+   * Gets a snapshot of the current text cursor position.
+   * @returns A snapshot of the current text cursor position.
+   */
+  public getTextCursorPosition(): TextCursorPosition<
+    BSchema,
+    ISchema,
+    SSchema
+  > {
+    return this.editor.transact((tr) => getTextCursorPosition(tr));
+  }
+
+  /**
+   * Sets the text cursor position to the start or end of an existing block. Throws an error if the target block could
+   * not be found.
+   * @param targetBlock The identifier of an existing block that the text cursor should be moved to.
+   * @param placement Whether the text cursor should be placed at the start or end of the block.
+   */
+  public setTextCursorPosition(
+    targetBlock: BlockIdentifier,
+    placement: "start" | "end" = "start",
+  ) {
+    return this.editor.transact((tr) =>
+      setTextCursorPosition(tr, targetBlock, placement),
+    );
+  }
+
+  /**
+   * Gets the bounding box of the current selection.
+   */
+  public getSelectionBoundingBox() {
+    if (!this.editor.prosemirrorView) {
+      return undefined;
+    }
+
+    const { selection } = this.editor.prosemirrorState;
+
+    // support for CellSelections
+    const { ranges } = selection;
+    const from = Math.min(...ranges.map((range) => range.$from.pos));
+    const to = Math.max(...ranges.map((range) => range.$to.pos));
+
+    if (isNodeSelection(selection)) {
+      const node = this.editor.prosemirrorView.nodeDOM(from) as HTMLElement;
+      if (node) {
+        return node.getBoundingClientRect();
+      }
+    }
+
+    return posToDOMRect(this.editor.prosemirrorView, from, to);
+  }
+}

package/src/editor/managers/StateManager.ts

@@ -0,0 +1,238 @@
+import { redo, undo } from "@tiptap/pm/history";
+import { Command, Transaction } from "prosemirror-state";
+import { BlockNoteEditor } from "../BlockNoteEditor.js";
+
+export class StateManager {
+  constructor(
+    private editor: BlockNoteEditor,
+    private options?: {
+      /**
+       * Swap the default undo command with a custom command.
+       */
+      undo?: typeof undo;
+      /**
+       * Swap the default redo command with a custom command.
+       */
+      redo?: typeof redo;
+    },
+  ) {}
+
+  /**
+   * Stores the currently active transaction, which is the accumulated transaction from all {@link dispatch} calls during a {@link transact} calls
+   */
+  private activeTransaction: Transaction | null = null;
+
+  /**
+   * For any command that can be executed, you can check if it can be executed by calling `editor.can(command)`.
+   * @example
+   * ```ts
+   * if (editor.can(editor.undo)) {
+   *   // show button
+   * } else {
+   *   // hide button
+   * }
+   */
+  public can(cb: () => boolean) {
+    try {
+      this.isInCan = true;
+      return cb();
+    } finally {
+      this.isInCan = false;
+    }
+  }
+
+  // Flag to indicate if we're in a `can` call
+  private isInCan = false;
+
+  /**
+   * Execute a prosemirror command. This is mostly for backwards compatibility with older code.
+   *
+   * @note You should prefer the {@link transact} method when possible, as it will automatically handle the dispatching of the transaction and work across blocknote transactions.
+   *
+   * @example
+   * ```ts
+   * editor.exec((state, dispatch, view) => {
+   *   dispatch(state.tr.insertText("Hello, world!"));
+   * });
+   * ```
+   */
+  public exec(command: Command) {
+    if (this.activeTransaction) {
+      throw new Error(
+        "`exec` should not be called within a `transact` call, move the `exec` call outside of the `transact` call",
+      );
+    }
+    if (this.isInCan) {
+      return this.canExec(command);
+    }
+    const state = this.prosemirrorState;
+    const view = this.prosemirrorView;
+    const dispatch = (tr: Transaction) => this.prosemirrorView.dispatch(tr);
+
+    return command(state, dispatch, view);
+  }
+
+  /**
+   * Check if a command can be executed. A command should return `false` if it is not valid in the current state.
+   *
+   * @example
+   * ```ts
+   * if (editor.canExec(command)) {
+   *   // show button
+   * } else {
+   *   // hide button
+   * }
+   * ```
+   */
+  public canExec(command: Command): boolean {
+    if (this.activeTransaction) {
+      throw new Error(
+        "`canExec` should not be called within a `transact` call, move the `canExec` call outside of the `transact` call",
+      );
+    }
+    const state = this.prosemirrorState;
+    const view = this.prosemirrorView;
+
+    return command(state, undefined, view);
+  }
+
+  /**
+   * Execute a function within a "blocknote transaction".
+   * All changes to the editor within the transaction will be grouped together, so that
+   * we can dispatch them as a single operation (thus creating only a single undo step)
+   *
+   * @note There is no need to dispatch the transaction, as it will be automatically dispatched when the callback is complete.
+   *
+   * @example
+   * ```ts
+   * // All changes to the editor will be grouped together
+   * editor.transact((tr) => {
+   *   tr.insertText("Hello, world!");
+   * // These two operations will be grouped together in a single undo step
+   *   editor.transact((tr) => {
+   *     tr.insertText("Hello, world!");
+   *   });
+   * });
+   * ```
+   */
+  public transact<T>(
+    callback: (
+      /**
+       * The current active transaction, this will automatically be dispatched to the editor when the callback is complete
+       * If another `transact` call is made within the callback, it will be passed the same transaction as the parent call.
+       */
+      tr: Transaction,
+    ) => T,
+  ): T {
+    if (this.activeTransaction) {
+      // Already in a transaction, so we can just callback immediately
+      return callback(this.activeTransaction);
+    }
+
+    try {
+      // Enter transaction mode, by setting a starting transaction
+      this.activeTransaction = this.editor._tiptapEditor.state.tr;
+
+      // Capture all dispatch'd transactions
+      const result = callback(this.activeTransaction);
+
+      // Any transactions captured by the `dispatch` call will be stored in `this.activeTransaction`
+      const activeTr = this.activeTransaction;
+
+      this.activeTransaction = null;
+      if (
+        activeTr &&
+        // Only dispatch if the transaction was actually modified in some way
+        (activeTr.docChanged ||
+          activeTr.selectionSet ||
+          activeTr.scrolledIntoView ||
+          activeTr.storedMarksSet ||
+          !activeTr.isGeneric)
+      ) {
+        // Dispatch the transaction if it was modified
+        this.prosemirrorView.dispatch(activeTr);
+      }
+
+      return result;
+    } finally {
+      // We wrap this in a finally block to ensure we don't disable future transactions just because of an error in the callback
+      this.activeTransaction = null;
+    }
+  }
+  /**
+   * Get the underlying prosemirror state
+   * @note Prefer using `editor.transact` to read the current editor state, as that will ensure the state is up to date
+   * @see https://prosemirror.net/docs/ref/#state.EditorState
+   */
+  public get prosemirrorState() {
+    if (this.activeTransaction) {
+      throw new Error(
+        "`prosemirrorState` should not be called within a `transact` call, move the `prosemirrorState` call outside of the `transact` call or use `editor.transact` to read the current editor state",
+      );
+    }
+    return this.editor._tiptapEditor.state;
+  }
+
+  /**
+   * Get the underlying prosemirror view
+   * @see https://prosemirror.net/docs/ref/#view.EditorView
+   */
+  public get prosemirrorView() {
+    return this.editor._tiptapEditor.view;
+  }
+
+  public isFocused() {
+    return this.prosemirrorView?.hasFocus() || false;
+  }
+
+  public focus() {
+    this.prosemirrorView?.focus();
+  }
+
+  /**
+   * Checks if the editor is currently editable, or if it's locked.
+   * @returns True if the editor is editable, false otherwise.
+   */
+  public get isEditable(): boolean {
+    if (!this.editor._tiptapEditor) {
+      if (!this.editor.headless) {
+        throw new Error("no editor, but also not headless?");
+      }
+      return false;
+    }
+    return this.editor._tiptapEditor.isEditable === undefined
+      ? true
+      : this.editor._tiptapEditor.isEditable;
+  }
+
+  /**
+   * Makes the editor editable or locks it, depending on the argument passed.
+   * @param editable True to make the editor editable, or false to lock it.
+   */
+  public set isEditable(editable: boolean) {
+    if (!this.editor._tiptapEditor) {
+      if (!this.editor.headless) {
+        throw new Error("no editor, but also not headless?");
+      }
+      // not relevant on headless
+      return;
+    }
+    if (this.editor._tiptapEditor.options.editable !== editable) {
+      this.editor._tiptapEditor.setEditable(editable);
+    }
+  }
+
+  /**
+   * Undo the last action.
+   */
+  public undo() {
+    return this.exec(this.options?.undo ?? undo);
+  }
+
+  /**
+   * Redo the last action.
+   */
+  public redo() {
+    return this.exec(this.options?.redo ?? redo);
+  }
+}