@blocknote/core 0.27.2 → 0.29.0

package/types/src/api/nodeConversions/fragmentToBlocks.d.ts

@@ -1,7 +1,6 @@
 import { Fragment } from "@tiptap/pm/model";
-import { BlockNoteSchema } from "../../editor/BlockNoteSchema.js";
 import { BlockNoDefaults, BlockSchema, InlineContentSchema, StyleSchema } from "../../schema/index.js";
 /**
  * Converts all Blocks within a fragment to BlockNote blocks.
  */
-export declare function fragmentToBlocks<B extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema>(fragment: Fragment, schema: BlockNoteSchema<B, I, S>): BlockNoDefaults<B, I, S>[];
+export declare function fragmentToBlocks<B extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema>(fragment: Fragment): BlockNoDefaults<B, I, S>[];

package/types/src/api/nodeConversions/nodeToBlock.d.ts

@@ -1,4 +1,4 @@
-import { Node } from "@tiptap/pm/model";
+import { Node, Schema } from "@tiptap/pm/model";
 import type { BlockSchema, InlineContent, InlineContentSchema, StyleSchema, TableContent } from "../../schema/index.js";
 import type { Block } from "../../blocks/defaultBlocks.js";
 /**
@@ -15,4 +15,4 @@ export declare function nodeToCustomInlineContent<I extends InlineContentSchema,
  *
  * TODO: test changes
  */
-export declare function nodeToBlock<BSchema extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema>(node: Node, blockSchema: BSchema, inlineContentSchema: I, styleSchema: S, blockCache?: WeakMap<Node, Block<BSchema, I, S>>): Block<BSchema, I, S>;
+export declare function nodeToBlock<BSchema extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema>(node: Node, schema: Schema, blockSchema?: BSchema, inlineContentSchema?: I, styleSchema?: S, blockCache?: import("../../index.js").BlockCache<any, any, any>): Block<BSchema, I, S>;

package/types/src/api/nodeUtil.d.ts

@@ -1,4 +1,9 @@
-import { Node } from "prosemirror-model";
+import type { Node } from "prosemirror-model";
+import type { Transaction } from "prosemirror-state";
+import { Block, DefaultBlockSchema, DefaultInlineContentSchema, DefaultStyleSchema } from "../blocks/defaultBlocks.js";
+import type { BlockSchema } from "../schema/index.js";
+import type { InlineContentSchema } from "../schema/inlineContent/types.js";
+import type { StyleSchema } from "../schema/styles/types.js";
 /**
  * Get a TipTap node by id
  */
@@ -6,3 +11,64 @@ export declare function getNodeById(id: string, doc: Node): {
     node: Node;
     posBeforeNode: number;
 } | undefined;
+export declare function isNodeBlock(node: Node): boolean;
+/**
+ * This attributes the changes to a specific source.
+ */
+export type BlockChangeSource = {
+    /**
+     * When an event is triggered by the local user, the source is "local".
+     * This is the default source.
+     */
+    type: "local";
+} | {
+    /**
+     * When an event is triggered by a paste operation, the source is "paste".
+     */
+    type: "paste";
+} | {
+    /**
+     * When an event is triggered by a drop operation, the source is "drop".
+     */
+    type: "drop";
+} | {
+    /**
+     * When an event is triggered by an undo or redo operation, the source is "undo" or "redo".
+     * @note Y.js undo/redo are not differentiated.
+     */
+    type: "undo" | "redo" | "undo-redo";
+} | {
+    /**
+     * When an event is triggered by a remote user, the source is "remote".
+     */
+    type: "yjs-remote";
+};
+export type BlocksChanged<BSchema extends BlockSchema = DefaultBlockSchema, ISchema extends InlineContentSchema = DefaultInlineContentSchema, SSchema extends StyleSchema = DefaultStyleSchema> = Array<{
+    /**
+     * The affected block.
+     */
+    block: Block<BSchema, ISchema, SSchema>;
+    /**
+     * The source of the change.
+     */
+    source: BlockChangeSource;
+} & ({
+    type: "insert" | "delete";
+    /**
+     * Insert and delete changes don't have a previous block.
+     */
+    prevBlock: undefined;
+} | {
+    type: "update";
+    /**
+     * The block before the update.
+     */
+    prevBlock: Block<BSchema, ISchema, SSchema>;
+})>;
+/**
+ * Get the blocks that were changed by a transaction.
+ * @param transaction The transaction to get the changes from.
+ * @param editor The editor to get the changes from.
+ * @returns The blocks that were changed by the transaction.
+ */
+export declare function getBlocksChangedByTransaction<BSchema extends BlockSchema = DefaultBlockSchema, ISchema extends InlineContentSchema = DefaultInlineContentSchema, SSchema extends StyleSchema = DefaultStyleSchema>(transaction: Transaction, appendedTransactions?: Transaction[]): BlocksChanged<BSchema, ISchema, SSchema>;

package/types/src/api/parsers/html/parseHTML.d.ts

@@ -1,4 +1,4 @@
 import { Schema } from "prosemirror-model";
 import { BlockSchema, InlineContentSchema, StyleSchema } from "../../../schema/index.js";
 import { Block } from "../../../blocks/defaultBlocks.js";
-export declare function HTMLToBlocks<BSchema extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema>(html: string, blockSchema: BSchema, icSchema: I, styleSchema: S, pmSchema: Schema): Promise<Block<BSchema, I, S>[]>;
+export declare function HTMLToBlocks<BSchema extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema>(html: string, pmSchema: Schema): Promise<Block<BSchema, I, S>[]>;

package/types/src/api/parsers/markdown/parseMarkdown.d.ts

@@ -2,4 +2,4 @@ import { Schema } from "prosemirror-model";
 import { Block } from "../../../blocks/defaultBlocks.js";
 import { BlockSchema, InlineContentSchema, StyleSchema } from "../../../schema/index.js";
 export declare function markdownToHTML(markdown: string): Promise<string>;
-export declare function markdownToBlocks<BSchema extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema>(markdown: string, blockSchema: BSchema, icSchema: I, styleSchema: S, pmSchema: Schema): Promise<Block<BSchema, I, S>[]>;
+export declare function markdownToBlocks<BSchema extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema>(markdown: string, pmSchema: Schema): Promise<Block<BSchema, I, S>[]>;

package/types/src/api/pmUtil.d.ts

@@ -0,0 +1,12 @@
+import type { Node, Schema } from "prosemirror-model";
+import type { Transaction } from "prosemirror-state";
+import type { BlockSchema } from "../schema/blocks/types.js";
+import type { InlineContentSchema } from "../schema/inlineContent/types.js";
+import type { StyleSchema } from "../schema/styles/types.js";
+import { BlockNoteSchema } from "../editor/BlockNoteSchema.js";
+export declare function getPmSchema(trOrNode: Transaction | Node): Schema<any, any>;
+export declare function getBlockNoteSchema<BSchema extends BlockSchema, I extends InlineContentSchema, S extends StyleSchema>(schema: Schema): BlockNoteSchema<BSchema, I, S>;
+export declare function getBlockSchema<BSchema extends BlockSchema>(schema: Schema): BSchema;
+export declare function getInlineContentSchema<I extends InlineContentSchema>(schema: Schema): I;
+export declare function getStyleSchema<S extends StyleSchema>(schema: Schema): S;
+export declare function getBlockCache(schema: Schema): import("../index.js").BlockCache<any, any, any>;

package/types/src/api/positionMapping.d.ts

@@ -0,0 +1,25 @@
+import type { BlockNoteEditor } from "../editor/BlockNoteEditor.js";
+/**
+ * This is used to keep track of positions of elements in the editor.
+ * It is needed because y-prosemirror's sync plugin can disrupt normal prosemirror position mapping.
+ *
+ * It is specifically made to be able to be used whether the editor is being used in a collaboratively, or single user, providing the same API.
+ *
+ * @param editor The editor to track the position of.
+ * @param position The position to track.
+ * @param side The side of the position to track. "left" is the default. "right" would move with the change if the change is in the right direction.
+ * @returns A function that returns the position of the element.
+ */
+export declare function trackPosition(
+/**
+ * The editor to track the position of.
+ */
+editor: BlockNoteEditor<any, any, any>, 
+/**
+ * The position to track.
+ */
+position: number, 
+/**
+ * This is the side of the position to track. "left" is the default. "right" would move with the change if the change is in the right direction.
+ */
+side?: "left" | "right"): () => number;

package/types/src/editor/BlockNoteEditor.d.ts

@@ -16,16 +16,18 @@ import { Selection } from "./selectionTypes.js";
 import { BlockNoteSchema } from "./BlockNoteSchema.js";
 import { BlockNoteTipTapEditor } from "./BlockNoteTipTapEditor.js";
 import { Dictionary } from "../i18n/dictionary.js";
-import { Plugin, Transaction } from "@tiptap/pm/state";
+import { type Command, type Plugin, type Transaction } from "@tiptap/pm/state";
 import { EditorView } from "prosemirror-view";
+import { BlocksChanged } from "../api/nodeUtil.js";
+import { CodeBlockOptions } from "../blocks/CodeBlockContent/CodeBlockContent.js";
 import type { ThreadStore, User } from "../comments/index.js";
 import "../style.css";
 import { EventEmitter } from "../util/EventEmitter.js";
-import { CodeBlockOptions } from "../blocks/CodeBlockContent/CodeBlockContent.js";
 export type BlockNoteExtensionFactory = (editor: BlockNoteEditor<any, any, any>) => BlockNoteExtension;
 export type BlockNoteExtension = AnyExtension | {
     plugin: Plugin;
 };
+export type BlockCache<BSchema extends BlockSchema = any, ISchema extends InlineContentSchema = any, SSchema extends StyleSchema = any> = WeakMap<Node, Block<BSchema, ISchema, SSchema>>;
 export type BlockNoteEditorOptions<BSchema extends BlockSchema, ISchema extends InlineContentSchema, SSchema extends StyleSchema> = {
     /**
      * Whether changes to blocks (like indentation, creating lists, changing headings) should be animated or not. Defaults to `true`.
@@ -267,7 +269,7 @@ export declare class BlockNoteEditor<BSchema extends BlockSchema = DefaultBlockS
      * This is especially useful when we want to keep track of the same block across multiple operations,
      * with this cache, blocks stay the same object reference (referential equality with ===).
      */
-    blockCache: WeakMap<Node, Block<any, any, any>>;
+    blockCache: BlockCache;
     /**
      * The dictionary contains translations for the editor.
      */
@@ -315,7 +317,61 @@ export declare class BlockNoteEditor<BSchema extends BlockSchema = DefaultBlockS
     };
     static create<BSchema extends BlockSchema = DefaultBlockSchema, ISchema extends InlineContentSchema = DefaultInlineContentSchema, SSchema extends StyleSchema = DefaultStyleSchema>(options?: Partial<BlockNoteEditorOptions<BSchema, ISchema, SSchema>>): BlockNoteEditor<BSchema, ISchema, SSchema>;
     protected constructor(options: Partial<BlockNoteEditorOptions<any, any, any>>);
-    dispatch: (tr: Transaction) => void;
+    /**
+     * Stores the currently active transaction, which is the accumulated transaction from all {@link dispatch} calls during a {@link transact} calls
+     */
+    private activeTransaction;
+    /**
+     * 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!"));
+     * });
+     * ```
+     */
+    exec(command: Command): boolean;
+    /**
+     * 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
+     * }
+     * ```
+     */
+    canExec(command: Command): boolean;
+    /**
+     * 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!");
+     *   });
+     * });
+     * ```
+     */
+    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;
     /**
      * Mount the editor to a parent DOM element. Call mount(undefined) to clean up
      *
@@ -326,10 +382,6 @@ export declare class BlockNoteEditor<BSchema extends BlockSchema = DefaultBlockS
      * Get the underlying prosemirror view
      */
     get prosemirrorView(): EditorView | undefined;
-    /**
-     * Get the underlying prosemirror state
-     */
-    get prosemirrorState(): import("prosemirror-state").EditorState;
     get domElement(): HTMLDivElement | undefined;
     isFocused(): boolean;
     focus(): void;
@@ -415,6 +467,11 @@ export declare class BlockNoteEditor<BSchema extends BlockSchema = DefaultBlockS
      * Gets a snapshot of the current selection.
      */
     getSelection(): Selection<BSchema, ISchema, SSchema> | undefined;
+    /**
+     * 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.
+     */
     setSelection(startBlock: BlockIdentifier, endBlock: BlockIdentifier): void;
     /**
      * Checks if the editor is currently editable, or if it's locked.
@@ -447,7 +504,7 @@ export declare class BlockNoteEditor<BSchema extends BlockSchema = DefaultBlockS
      * Removes existing blocks from the editor. Throws an error if any of the blocks could not be found.
      * @param blocksToRemove An array of identifiers for existing blocks that should be removed.
      */
-    removeBlocks(blocksToRemove: BlockIdentifier[]): Block<BSchema, ISchema, SSchema>[];
+    removeBlocks(blocksToRemove: BlockIdentifier[]): Block<Record<string, import("../index.js").BlockConfig>, InlineContentSchema, StyleSchema>[];
     /**
      * Replaces existing blocks in the editor with new blocks. If the blocks that should be removed are not adjacent or
      * are at different nesting levels, `blocksToInsert` will be inserted at the position of the first block in
@@ -580,7 +637,12 @@ export declare class BlockNoteEditor<BSchema extends BlockSchema = DefaultBlockS
      * @param callback The callback to execute.
      * @returns A function to remove the callback.
      */
-    onChange(callback: (editor: BlockNoteEditor<BSchema, ISchema, SSchema>) => void): (() => void) | undefined;
+    onChange(callback: (editor: BlockNoteEditor<BSchema, ISchema, SSchema>, context: {
+        /**
+         * Returns the blocks that were inserted, updated, or deleted by the change that occurred.
+         */
+        getChanges(): BlocksChanged<BSchema, ISchema, SSchema>;
+    }) => void): (() => void) | undefined;
     /**
      * A callback function that runs whenever the text cursor position or selection changes.
      *

package/types/src/editor/BlockNoteTipTapEditor.d.ts

@@ -1,4 +1,4 @@
-import { EditorOptions } from "@tiptap/core";
+import { Editor, EditorOptions } from "@tiptap/core";
 import { Editor as TiptapEditor } from "@tiptap/core";
 import { EditorState, Transaction } from "@tiptap/pm/state";
 import { PartialBlock } from "../blocks/defaultBlocks.js";
@@ -16,7 +16,7 @@ export declare class BlockNoteTipTapEditor extends TiptapEditor {
     static create: (options: BlockNoteTipTapEditorOptions, styleSchema: StyleSchema) => BlockNoteTipTapEditor;
     protected constructor(options: BlockNoteTipTapEditorOptions, styleSchema: StyleSchema);
     get state(): EditorState;
-    dispatch(tr: Transaction): void;
+    dispatch(transaction: Transaction): void;
     /**
      * Replace the default `createView` method with a custom one - which we call on mount
      */
@@ -28,3 +28,16 @@ export declare class BlockNoteTipTapEditor extends TiptapEditor {
      */
     mount: (blockNoteEditor: BlockNoteEditor<any, any, any>, element?: HTMLElement | null, contentComponent?: any) => void;
 }
+declare module "@tiptap/core" {
+    interface EditorEvents {
+        /**
+         * This is a custom event that will be emitted in Tiptap V3.
+         * We use it to provide the appendedTransactions, until Tiptap V3 is released.
+         */
+        "v3-update": {
+            editor: Editor;
+            transaction: Transaction;
+            appendedTransactions: Transaction[];
+        };
+    }
+}

package/types/src/extensions/TableHandles/TableHandlesPlugin.d.ts

@@ -102,7 +102,7 @@ export declare class TableHandlesProsemirrorPlugin<I extends InlineContentSchema
     } | {
         orientation: "column";
         side: "left" | "right";
-    }) => boolean;
+    }) => void;
     /**
      * Removes a row or column from the table using prosemirror-table commands
      */

package/types/src/index.d.ts

@@ -3,7 +3,6 @@ export * from "./api/exporters/html/externalHTMLExporter.js";
 export * from "./api/exporters/html/internalHTMLSerializer.js";
 export * from "./api/getBlockInfoFromPos.js";
 export * from "./api/nodeUtil.js";
-export * from "./api/testUtil/index.js";
 export * from "./blocks/AudioBlockContent/AudioBlockContent.js";
 export * from "./blocks/CodeBlockContent/CodeBlockContent.js";
 export * from "./blocks/FileBlockContent/FileBlockContent.js";
@@ -54,9 +53,9 @@ export * from "./util/string.js";
 export * from "./util/typescript.js";
 export type { CodeBlockOptions } from "./blocks/CodeBlockContent/CodeBlockContent.js";
 export { UnreachableCaseError, assertEmpty } from "./util/typescript.js";
+export { selectedFragmentToHTML } from "./api/clipboard/toClipboard/copyExtension.js";
 export * from "./api/nodeConversions/blockToNode.js";
 export * from "./api/nodeConversions/nodeToBlock.js";
-export * from "./api/testUtil/partialBlockTestUtil.js";
 export * from "./extensions/UniqueID/UniqueID.js";
 export * from "./api/exporters/markdown/markdownExporter.js";
 export * from "./api/parsers/html/parseHTML.js";