@blocknote/core 0.39.0 → 0.39.1-capitol-test

package/types/src/editor/managers/CollaborationManager.d.ts

@@ -0,0 +1,115 @@
+import * as Y from "yjs";
+import { CommentsPlugin } from "../../extensions/Comments/CommentsPlugin.js";
+import { ForkYDocPlugin } from "../../extensions/Collaboration/ForkYDocPlugin.js";
+import { SyncPlugin } from "../../extensions/Collaboration/SyncPlugin.js";
+import { UndoPlugin } from "../../extensions/Collaboration/UndoPlugin.js";
+import { CursorPlugin } from "../../extensions/Collaboration/CursorPlugin.js";
+import type { ThreadStore, User } from "../../comments/index.js";
+import type { BlockNoteEditor } from "../BlockNoteEditor.js";
+import { CustomBlockNoteSchema } from "../../schema/schema.js";
+export interface CollaborationOptions {
+    /**
+     * The Yjs XML fragment that's used for collaboration.
+     */
+    fragment: Y.XmlFragment;
+    /**
+     * The user info for the current user that's shown to other collaborators.
+     */
+    user: {
+        name: string;
+        color: string;
+    };
+    /**
+     * A Yjs provider (used for awareness / cursor information)
+     * Can be null for comments-only mode
+     */
+    provider: any;
+    /**
+     * Optional function to customize how cursors of users are rendered
+     */
+    renderCursor?: (user: any) => HTMLElement;
+    /**
+     * Optional flag to set when the user label should be shown with the default
+     * collaboration cursor. Setting to "always" will always show the label,
+     * while "activity" will only show the label when the user moves the cursor
+     * or types. Defaults to "activity".
+     */
+    showCursorLabels?: "always" | "activity";
+    /**
+     * Comments configuration - can be used with or without collaboration
+     */
+    comments?: {
+        schema?: CustomBlockNoteSchema<any, any, any>;
+        threadStore: ThreadStore;
+    };
+    /**
+     * Function to resolve user IDs to user objects - required for comments
+     */
+    resolveUsers?: (userIds: string[]) => Promise<User[]>;
+}
+/**
+ * CollaborationManager handles all collaboration-related functionality
+ * This manager is completely optional and can be tree-shaken if not used
+ */
+export declare class CollaborationManager {
+    private editor;
+    private options;
+    private _commentsPlugin?;
+    private _forkYDocPlugin?;
+    private _syncPlugin?;
+    private _undoPlugin?;
+    private _cursorPlugin?;
+    constructor(editor: BlockNoteEditor, options: CollaborationOptions);
+    /**
+     * Get the sync plugin instance
+     */
+    get syncPlugin(): SyncPlugin | undefined;
+    /**
+     * Get the undo plugin instance
+     */
+    get undoPlugin(): UndoPlugin | undefined;
+    /**
+     * Get the cursor plugin instance
+     */
+    get cursorPlugin(): CursorPlugin | undefined;
+    /**
+     * Get the fork YDoc plugin instance
+     */
+    get forkYDocPlugin(): ForkYDocPlugin | undefined;
+    initExtensions(): Record<string, unknown>;
+    /**
+     * Update the user info for the current user that's shown to other collaborators
+     */
+    updateUserInfo(user: {
+        name: string;
+        color: string;
+    }): void;
+    /**
+     * Get the collaboration undo command
+     */
+    getUndoCommand(): import("prosemirror-state").Command;
+    /**
+     * Get the collaboration redo command
+     */
+    getRedoCommand(): import("prosemirror-state").Command;
+    /**
+     * Check if initial content should be avoided due to collaboration
+     */
+    shouldAvoidInitialContent(): boolean;
+    /**
+     * Get the collaboration options
+     */
+    getOptions(): CollaborationOptions;
+    /**
+     * Get the comments plugin if available
+     */
+    get comments(): CommentsPlugin | undefined;
+    /**
+     * Check if comments are enabled
+     */
+    get hasComments(): boolean;
+    /**
+     * Get the resolveUsers function
+     */
+    get resolveUsers(): ((userIds: string[]) => Promise<User[]>) | undefined;
+}

package/types/src/editor/managers/EventManager.d.ts

@@ -0,0 +1,58 @@
+import type { BlockNoteEditor } from "../BlockNoteEditor.js";
+import { type BlocksChanged } from "../../api/getBlocksChangedByTransaction.js";
+import { Transaction } from "prosemirror-state";
+import { EventEmitter } from "../../util/EventEmitter.js";
+/**
+ * A function that can be used to unsubscribe from an event.
+ */
+export type Unsubscribe = () => void;
+/**
+ * EventManager is a class which manages the events of the editor
+ */
+export declare class EventManager<Editor extends BlockNoteEditor> extends EventEmitter<{
+    onChange: [
+        editor: Editor,
+        ctx: {
+            getChanges(): BlocksChanged<Editor["schema"]["blockSchema"], Editor["schema"]["inlineContentSchema"], Editor["schema"]["styleSchema"]>;
+        }
+    ];
+    onSelectionChange: [ctx: {
+        editor: Editor;
+        transaction: Transaction;
+    }];
+    onMount: [ctx: {
+        editor: Editor;
+    }];
+    onUnmount: [ctx: {
+        editor: Editor;
+    }];
+}> {
+    private editor;
+    constructor(editor: Editor);
+    /**
+     * Register a callback that will be called when the editor changes.
+     */
+    onChange(callback: (editor: Editor, ctx: {
+        getChanges(): BlocksChanged<Editor["schema"]["blockSchema"], Editor["schema"]["inlineContentSchema"], Editor["schema"]["styleSchema"]>;
+    }) => void): Unsubscribe;
+    /**
+     * Register a callback that will be called when the selection changes.
+     */
+    onSelectionChange(callback: (editor: Editor) => void, 
+    /**
+     * If true, the callback will be triggered when the selection changes due to a yjs sync (i.e.: other user was typing)
+     */
+    includeSelectionChangedByRemote?: boolean): Unsubscribe;
+    /**
+     * Register a callback that will be called when the editor is mounted.
+     */
+    onMount(callback: (ctx: {
+        editor: Editor;
+    }) => void): Unsubscribe;
+    /**
+     * Register a callback that will be called when the editor is unmounted.
+     */
+    onUnmount(callback: (ctx: {
+        editor: Editor;
+    }) => void): Unsubscribe;
+}

package/types/src/editor/managers/ExportManager.d.ts

@@ -0,0 +1,64 @@
+import { Block, DefaultBlockSchema, DefaultInlineContentSchema, DefaultStyleSchema, PartialBlock } from "../../blocks/defaultBlocks.js";
+import { BlockSchema, InlineContentSchema, StyleSchema } from "../../schema/index.js";
+import { BlockNoteEditor } from "../BlockNoteEditor.js";
+export declare class ExportManager<BSchema extends BlockSchema = DefaultBlockSchema, ISchema extends InlineContentSchema = DefaultInlineContentSchema, SSchema extends StyleSchema = DefaultStyleSchema> {
+    private editor;
+    constructor(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.
+     */
+    blocksToHTMLLossy(blocks?: PartialBlock<BSchema, ISchema, SSchema>[]): string;
+    /**
+     * 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.
+     */
+    blocksToFullHTML(blocks: PartialBlock<BSchema, ISchema, SSchema>[]): string;
+    /**
+     * 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.
+     */
+    tryParseHTMLToBlocks(html: string): Block<BSchema, ISchema, SSchema>[];
+    /**
+     * 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.
+     */
+    blocksToMarkdownLossy(blocks?: PartialBlock<BSchema, ISchema, SSchema>[]): string;
+    /**
+     * 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.
+     */
+    tryParseMarkdownToBlocks(markdown: string): Block<BSchema, ISchema, SSchema>[];
+    /**
+     * 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.
+     */
+    pasteHTML(html: string, raw?: boolean): void;
+    /**
+     * Paste text into the editor. Defaults to interpreting text as markdown.
+     * @param text The text to paste.
+     */
+    pasteText(text: string): boolean;
+    /**
+     * Paste markdown into the editor.
+     * @param markdown The markdown to paste.
+     */
+    pasteMarkdown(markdown: string): void;
+}

package/types/src/editor/managers/ExtensionManager.d.ts

@@ -0,0 +1,68 @@
+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 declare class ExtensionManager {
+    private editor;
+    constructor(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
+     */
+    extension<T extends BlockNoteExtension>(ext: {
+        new (...args: any[]): T;
+    } & typeof BlockNoteExtension, key?: string): T;
+    /**
+     * Get all extensions
+     */
+    getExtensions(): Record<string, import("../BlockNoteEditor.js").SupportedExtension>;
+    /**
+     * Get a specific extension by key
+     */
+    getExtension(key: string): import("../BlockNoteEditor.js").SupportedExtension;
+    /**
+     * Check if an extension exists
+     */
+    hasExtension(key: string): boolean;
+    /**
+     * Get the formatting toolbar plugin
+     */
+    get formattingToolbar(): FormattingToolbarProsemirrorPlugin;
+    /**
+     * Get the link toolbar plugin
+     */
+    get linkToolbar(): LinkToolbarProsemirrorPlugin<any, any, any>;
+    /**
+     * Get the side menu plugin
+     */
+    get sideMenu(): SideMenuProsemirrorPlugin<any, any, any>;
+    /**
+     * Get the suggestion menus plugin
+     */
+    get suggestionMenus(): SuggestionMenuProseMirrorPlugin<any, any, any>;
+    /**
+     * Get the file panel plugin (if available)
+     */
+    get filePanel(): FilePanelProsemirrorPlugin<any, any> | undefined;
+    /**
+     * Get the table handles plugin (if available)
+     */
+    get tableHandles(): TableHandlesProsemirrorPlugin<any, any> | undefined;
+    /**
+     * Get the show selection plugin
+     */
+    get showSelectionPlugin(): ShowSelectionPlugin;
+    /**
+     * Check if collaboration is enabled (Yjs or Liveblocks)
+     */
+    get isCollaborationEnabled(): boolean;
+}

package/types/src/editor/managers/SelectionManager.d.ts

@@ -0,0 +1,54 @@
+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 declare class SelectionManager<BSchema extends BlockSchema = DefaultBlockSchema, ISchema extends InlineContentSchema = DefaultInlineContentSchema, SSchema extends StyleSchema = DefaultStyleSchema> {
+    private editor;
+    constructor(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.
+     */
+    getSelection(): Selection<BSchema, ISchema, SSchema> | undefined;
+    /**
+     * 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.
+     */
+    getSelectionCutBlocks(): {
+        blocks: import("../../index.js").Block<Record<string, import("../../index.js").BlockConfig<string, import("../../index.js").PropSchema, "inline" | "none" | "table">>, InlineContentSchema, StyleSchema>[];
+        blockCutAtStart: string | undefined;
+        blockCutAtEnd: string | undefined;
+        _meta: {
+            startPos: number;
+            endPos: number;
+        };
+    };
+    /**
+     * 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;
+    /**
+     * Gets a snapshot of the current text cursor position.
+     * @returns A snapshot of the current text cursor position.
+     */
+    getTextCursorPosition(): TextCursorPosition<BSchema, ISchema, SSchema>;
+    /**
+     * 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;
+    /**
+     * Gets the bounding box of the current selection.
+     */
+    getSelectionBoundingBox(): DOMRect | undefined;
+}

package/types/src/editor/managers/StateManager.d.ts

@@ -0,0 +1,115 @@
+import { redo, undo } from "@tiptap/pm/history";
+import { Command, Transaction } from "prosemirror-state";
+import { BlockNoteEditor } from "../BlockNoteEditor.js";
+export declare class StateManager {
+    private editor;
+    private options?;
+    constructor(editor: BlockNoteEditor, 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;
+    } | undefined);
+    /**
+     * Stores the currently active transaction, which is the accumulated transaction from all {@link dispatch} calls during a {@link transact} calls
+     */
+    private activeTransaction;
+    /**
+     * 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
+     * }
+     */
+    can(cb: () => boolean): boolean;
+    private isInCan;
+    /**
+     * 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;
+    /**
+     * 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
+     */
+    get prosemirrorState(): import("prosemirror-state").EditorState;
+    /**
+     * Get the underlying prosemirror view
+     * @see https://prosemirror.net/docs/ref/#view.EditorView
+     */
+    get prosemirrorView(): import("prosemirror-view").EditorView;
+    isFocused(): boolean;
+    focus(): void;
+    /**
+     * Checks if the editor is currently editable, or if it's locked.
+     * @returns True if the editor is editable, false otherwise.
+     */
+    get isEditable(): boolean;
+    /**
+     * 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.
+     */
+    set isEditable(editable: boolean);
+    /**
+     * Undo the last action.
+     */
+    undo(): boolean;
+    /**
+     * Redo the last action.
+     */
+    redo(): boolean;
+}

package/types/src/editor/managers/StyleManager.d.ts

@@ -0,0 +1,48 @@
+import { BlockSchema, InlineContentSchema, PartialInlineContent, StyleSchema, Styles } from "../../schema/index.js";
+import { DefaultBlockSchema, DefaultInlineContentSchema, DefaultStyleSchema } from "../../blocks/defaultBlocks.js";
+import { BlockNoteEditor } from "../BlockNoteEditor.js";
+export declare class StyleManager<BSchema extends BlockSchema = DefaultBlockSchema, ISchema extends InlineContentSchema = DefaultInlineContentSchema, SSchema extends StyleSchema = DefaultStyleSchema> {
+    private editor;
+    constructor(editor: BlockNoteEditor<BSchema, ISchema, SSchema>);
+    /**
+     * Insert a piece of content at the current cursor position.
+     *
+     * @param content can be a string, or array of partial inline content elements
+     */
+    insertInlineContent(content: PartialInlineContent<ISchema, SSchema>, { updateSelection }?: {
+        updateSelection?: boolean;
+    }): void;
+    /**
+     * Gets the active text styles at the text cursor position or at the end of the current selection if it's active.
+     */
+    getActiveStyles(): Styles<SSchema>;
+    /**
+     * Adds styles to the currently selected content.
+     * @param styles The styles to add.
+     */
+    addStyles(styles: Styles<SSchema>): void;
+    /**
+     * Removes styles from the currently selected content.
+     * @param styles The styles to remove.
+     */
+    removeStyles(styles: Styles<SSchema>): void;
+    /**
+     * Toggles styles on the currently selected content.
+     * @param styles The styles to toggle.
+     */
+    toggleStyles(styles: Styles<SSchema>): void;
+    /**
+     * Gets the currently selected text.
+     */
+    getSelectedText(): string;
+    /**
+     * Gets the URL of the last link in the current selection, or `undefined` if there are no links in the selection.
+     */
+    getSelectedLinkUrl(): string | undefined;
+    /**
+     * Creates a new link to replace the selected content.
+     * @param url The link URL.
+     * @param text The text to display the link with.
+     */
+    createLink(url: string, text?: string): void;
+}

package/types/src/editor/managers/index.d.ts

@@ -0,0 +1,8 @@
+export { BlockManager } from "./BlockManager.js";
+export { CollaborationManager, type CollaborationOptions, } from "./CollaborationManager.js";
+export { EventManager } from "./EventManager.js";
+export { ExportManager } from "./ExportManager.js";
+export { ExtensionManager } from "./ExtensionManager.js";
+export { SelectionManager } from "./SelectionManager.js";
+export { StateManager } from "./StateManager.js";
+export { StyleManager } from "./StyleManager.js";