@blocknote/core 0.4.3 → 0.4.4

package/types/src/BlockNoteEditor.d.ts

@@ -1,4 +1,4 @@
-import { Block, PartialBlock } from "./extensions/Blocks/api/blockTypes";
+import { Block, BlockIdentifier, PartialBlock } from "./extensions/Blocks/api/blockTypes";
 import { UiFactories } from "./BlockNoteExtensions";
 import { BaseSlashMenuItem } from "./extensions/SlashMenu";
 import { Editor as TiptapEditor } from "@tiptap/core/dist/packages/core/src/Editor";
@@ -10,8 +10,9 @@ export type BlockNoteEditorOptions = {
     slashCommands: BaseSlashMenuItem[];
     parentElement: HTMLElement;
     editorDOMAttributes: Record<string, string>;
-    onUpdate: (editor: BlockNoteEditor) => void;
-    onCreate: (editor: BlockNoteEditor) => void;
+    onEditorCreate: (editor: BlockNoteEditor) => void;
+    onEditorContentChange: (editor: BlockNoteEditor) => void;
+    onTextCursorPositionChange: (editor: BlockNoteEditor) => void;
     _tiptapOptions: any;
 };
 export declare class BlockNoteEditor {
@@ -22,75 +23,92 @@ export declare class BlockNoteEditor {
     get domElement(): HTMLDivElement;
     constructor(options?: Partial<BlockNoteEditorOptions>);
     /**
-     * Gets a list of all top-level blocks that are in the editor.
+     * Gets a snapshot of all top-level (non-nested) blocks in the editor.
+     * @returns A snapshot of all top-level (non-nested) blocks in the editor.
      */
     get topLevelBlocks(): Block[];
     /**
-     * Traverses all blocks in the editor, including all nested blocks, and executes a callback for each. The traversal is
-     * depth-first, which is the same order as blocks appear in the editor by y-coordinate.
-     * @param callback The callback to execute for each block.
+     * Gets a snapshot of an existing block from the editor.
+     * @param blockIdentifier The identifier of an existing block that should be retrieved.
+     * @returns The block that matches the identifier, or `undefined` if no matching block was found.
+     */
+    getBlock(blockIdentifier: BlockIdentifier): Block | undefined;
+    /**
+     * Traverses all blocks in the editor depth-first, and executes a callback for each.
+     * @param callback The callback to execute for each block. Returning `false` stops the traversal.
      * @param reverse Whether the blocks should be traversed in reverse order.
      */
-    allBlocks(callback: (block: Block) => void, reverse?: boolean): void;
+    forEachBlock(callback: (block: Block) => void, reverse?: boolean): void;
     /**
-     * Gets information regarding the position of the text cursor in the editor.
+     * Gets a snapshot of the current text cursor position.
+     * @returns A snapshot of the current text cursor position.
      */
     getTextCursorPosition(): TextCursorPosition;
-    setTextCursorPosition(block: Block, placement?: "start" | "end"): void;
     /**
-     * Inserts multiple blocks before, after, or nested inside an existing block in the editor.
-     * @param blocksToInsert An array of blocks to insert.
-     * @param blockToInsertAt An existing block, marking where the new blocks should be inserted at.
-     * @param placement Determines whether the blocks should be inserted just before, just after, or nested inside the
-     * existing block.
+     * 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.
+     */
+    setTextCursorPosition(targetBlock: BlockIdentifier, placement?: "start" | "end"): void;
+    /**
+     * Inserts new blocks into the editor. If a block's `id` is undefined, BlockNote generates one automatically. Throws an
+     * error if the reference block could not be found.
+     * @param blocksToInsert An array of partial blocks that should be inserted.
+     * @param referenceBlock An identifier for an existing block, at which the new blocks should be inserted.
+     * @param placement Whether the blocks should be inserted just before, just after, or nested inside the
+     * `referenceBlock`. Inserts the blocks at the start of the existing block's children if "nested" is used.
      */
-    insertBlocks(blocksToInsert: PartialBlock[], blockToInsertAt: Block, placement?: "before" | "after" | "nested"): void;
+    insertBlocks(blocksToInsert: PartialBlock[], referenceBlock: BlockIdentifier, placement?: "before" | "after" | "nested"): void;
     /**
-     * Updates a block in the editor to the given specification.
+     * Updates an existing block in the editor. Since updatedBlock is a PartialBlock object, some fields might not be
+     * defined. These undefined fields are kept as-is from the existing block. Throws an error if the block to update could
+     * not be found.
      * @param blockToUpdate The block that should be updated.
-     * @param updatedBlock The specification that the block should be updated to.
+     * @param update A partial block which defines how the existing block should be changed.
      */
-    updateBlock(blockToUpdate: Block, updatedBlock: PartialBlock): void;
+    updateBlock(blockToUpdate: Block, update: PartialBlock): void;
     /**
-     * Removes multiple blocks from the editor. Throws an error if any of the blocks could not be found.
-     * @param blocksToRemove An array of blocks that should be removed.
+     * 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: Block[]): void;
     /**
-     * Replaces multiple blocks in the editor with several other blocks. If the provided blocks to remove are not adjacent
-     * to each other, the new blocks are inserted at the position of the first block in the array. Throws an error if any
-     * of the blocks could not be found.
+     * 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
+     * `blocksToRemove`. Throws an error if any of the blocks to remove could not be found.
      * @param blocksToRemove An array of blocks that should be replaced.
-     * @param blocksToInsert An array of blocks to replace the old ones with.
+     * @param blocksToInsert An array of partial blocks to replace the old ones with.
      */
     replaceBlocks(blocksToRemove: Block[], blocksToInsert: PartialBlock[]): void;
     /**
-     * Executes a callback function whenever the editor's content changes.
-     * @param callback The callback function to execute.
-     */
-    onContentChange(callback: () => void): void;
-    /**
-     * Serializes a list of blocks into an HTML string. The output is not the same as what's rendered by the editor, and
-     * is simplified in order to better conform to HTML standards. Block structuring elements are removed, children of
-     * blocks which aren't list items are lifted out of them, and list items blocks are wrapped in `ul`/`ol` tags.
-     * @param blocks The list of blocks to serialize into HTML.
+     * Serializes blocks into an 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.
      */
     blocksToHTML(blocks: Block[]): Promise<string>;
     /**
-     * Creates a list of blocks from an HTML string.
-     * @param htmlString The HTML string to create a list of blocks from.
+     * 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.
      */
-    HTMLToBlocks(htmlString: string): Promise<Block[]>;
+    HTMLToBlocks(html: string): Promise<Block[]>;
     /**
-     * Serializes a list of blocks into a Markdown string. The output is simplified as Markdown does not support all
-     * features of BlockNote. Block structuring elements are removed, children of blocks which aren't list items are
-     * lifted out of them, and certain styles are removed.
-     * @param blocks The list of blocks to serialize into Markdown.
+     * 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.
      */
     blocksToMarkdown(blocks: Block[]): Promise<string>;
     /**
-     * Creates a list of blocks from a Markdown string.
-     * @param markdownString The Markdown string to create a list of blocks from.
+     * 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.
      */
-    markdownToBlocks(markdownString: string): Promise<Block[]>;
+    markdownToBlocks(markdown: string): Promise<Block[]>;
 }

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

@@ -1,6 +1,6 @@
 import { Schema } from "prosemirror-model";
 import { Block } from "../../extensions/Blocks/api/blockTypes";
 export declare function blocksToHTML(blocks: Block[], schema: Schema): Promise<string>;
-export declare function HTMLToBlocks(htmlString: string, schema: Schema): Promise<Block[]>;
+export declare function HTMLToBlocks(html: string, schema: Schema): Promise<Block[]>;
 export declare function blocksToMarkdown(blocks: Block[], schema: Schema): Promise<string>;
-export declare function markdownToBlocks(markdownString: string, schema: Schema): Promise<Block[]>;
+export declare function markdownToBlocks(markdown: string, schema: Schema): Promise<Block[]>;