@witchcraft/editor 0.0.1

package/src/runtime/pm/features/FileLoader/FileLoader.ts

@@ -0,0 +1,120 @@
+import { mergeAttributes, Node } from "@tiptap/core"
+
+import { insertFile } from "./commands/insertFile.js"
+import { fileLoaderPlugin } from "./plugins/fileLoaderPlugin.js"
+import type { FileLoaderExtensionOptions } from "./types.js"
+import { optionsCheck } from "./utils/optionsCheck.js"
+
+import { isValidId } from "../Blocks/utils/isValidId.js"
+
+/**
+ * Provides a way to asynchronously load files into the editor and a node to display while they are loading.
+ *
+ * An {@link IFileLoaderHandler} interface should be passed to describe what to do with the file at each step. There is a default implementation at {@link FileLoaderHandler} that tries to handler as much as possible. See it for details.
+ *
+ * It also automatically removes fileLoader nodes when the document is loaded. You can disable this with the `cleanupOnLoad` option.
+ *
+ * To force the plugin to cleanup after the first load you can do `tr.setMeta("cleanFileLoaders")`.
+ *
+ * A basic node view that can preview images is provided but not configured.
+ *
+ */
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const FileLoader = Node.create<FileLoaderExtensionOptions>({
+	name: "fileLoader",
+	content: "",
+	marks: "",
+	group: "block",
+	addOptions() {
+		return {
+			cleanupOnLoad: true,
+			onDrop: undefined,
+			onPaste: undefined,
+			// there are checks on init to throw if the user didn't configure a handler
+			handler: undefined as any,
+			embeddedBlockCommandRedirect: undefined,
+			HTMLAttributes: {
+				class: `
+					rounded-sm
+					animate-pulse
+					bg-accent-200
+					text-accent-800
+					dark:bg-accent-700
+					dark:text-accent-300
+					px-2
+				`
+			}
+		}
+	},
+	addAttributes() {
+		return {
+			HTMLAttributes: {
+				default: { }
+			},
+			/** For the optional FileLoaderNodeView. */
+			preview: {
+				default: undefined
+			},
+			fileName: {
+				default: undefined
+			},
+			loading: {
+				default: true
+			},
+			loadingId: {
+				default: undefined
+			}
+		}
+	},
+	parseHTML() {
+		return [
+			{
+				tag: `div[type=${this.name}]`,
+				getAttrs: dom => {
+					const fileName = dom.getAttribute("file-name")
+					const loading = dom.getAttribute("file-loading")
+					const loadingId = dom.getAttribute("file-loading-id")
+					return {
+						fileName,
+						loadingId: isValidId(loadingId, 10) ? loadingId : undefined,
+						loading: loading === "true"
+					}
+				}
+			}
+		]
+	},
+
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	renderHTML({ node, HTMLAttributes }) {
+		return [
+			"div",
+			mergeAttributes(
+				this.options.HTMLAttributes,
+				HTMLAttributes,
+				{
+					"file-loading-id": node.attrs.loadingId,
+					"file-name": node.attrs.fileName,
+					"file-loading": node.attrs.loading,
+					type: this.name
+				}
+			),
+			`Loading "${node.attrs.fileName ?? "Unknown"}" ...`
+		]
+	},
+	addCommands() {
+		optionsCheck(this.editor, this.options)
+		const self = this
+		return {
+			insertFile: insertFile(self.options.handler)
+		}
+	},
+	addProseMirrorPlugins() {
+		const self = this
+		return [
+			fileLoaderPlugin(self.editor, self.options)
+		]
+	}
+})
+
+export type NodeFileLoaderName = "fileLoader"

package/src/runtime/pm/features/FileLoader/FileLoaderHandler/FileLoaderHandler.ts

@@ -0,0 +1,100 @@
+import type { MakeOptional } from "@alanscodelog/utils/types"
+import { unreachable } from "@alanscodelog/utils/unreachable"
+import type { Editor } from "@tiptap/core"
+import { nanoid } from "nanoid"
+
+import { findUpwards } from "../../../utils/findUpwards.js"
+import type { IFileLoaderHandler } from "../types.js"
+import { cleanupFileLoaderNode } from "../utils/cleanupFileLoaderNode.js"
+
+/**
+ * A partial implementation of {@link IFileLoaderHandler}.
+ *
+ * Using the defaults of this class, you only need to specify the handler's `loadFile` and `replaceLoadingNode` properties.
+ *
+ * It assumes the use of the {@link Item} extension since it uses the node to wrap the fileLoader node.
+ *
+ * To identify each fileLoader node and fetch it again once the file is loaded, it uses a 10 character nanoid.
+ */
+export class FileLoaderHandler<
+	TFile extends File,
+	T = { file: TFile, result: string | ArrayBuffer | null },
+	TKey = string
+>implements IFileLoaderHandler<TFile, T, TKey> {
+	loadFile: IFileLoaderHandler<TFile, T, TKey>["loadFile"]
+
+	onLoadError: IFileLoaderHandler<TFile, T, TKey>["onLoadError"]
+
+	insertPosition: IFileLoaderHandler<TFile, T, TKey>["insertPosition"]
+
+	insertLoadingNode: IFileLoaderHandler<TFile, T, TKey>["insertLoadingNode"]
+
+	replaceLoadingNode: IFileLoaderHandler<TFile, T, TKey>["replaceLoadingNode"]
+
+	filterFile: IFileLoaderHandler<TFile, T, TKey>["filterFile"]
+
+	constructor(
+		opts: MakeOptional<IFileLoaderHandler<TFile, T, TKey>, "onLoadError" | "insertPosition" | "insertLoadingNode">
+	) {
+		this.loadFile = opts.loadFile
+		this.replaceLoadingNode = opts.replaceLoadingNode
+
+		if (opts.onLoadError) this.onLoadError = opts.onLoadError
+		else this.onLoadError = this.defaultOnLoadError
+		if (opts.insertPosition) this.insertPosition = opts.insertPosition
+		else this.insertPosition = this.defaultInsertPosition
+		if (opts.insertLoadingNode) this.insertLoadingNode = opts.insertLoadingNode
+		else this.insertLoadingNode = this.defaultInsertLoadingNode
+		if (opts.filterFile) this.filterFile = opts.filterFile
+		else this.filterFile = this.defaultFilterFile
+	}
+
+	defaultFilterFile(file: File): TFile | undefined {
+		return file as TFile
+	}
+
+	defaultInsertPosition(_file: TFile, editor: Editor, pos?: number): number | undefined {
+		const position = pos ?? editor.state.selection.anchor
+		const $insertionNode = findUpwards(editor.state.doc, position, $node => {
+			if ($node.node().type.name === "item") {
+				return true
+			}
+			return false
+		}).$pos
+		return $insertionNode ? $insertionNode.end() + 1 : undefined
+	}
+
+	defaultOnLoadError(_file: TFile, editor: Editor, pos: number | undefined): void {
+		if (pos === undefined) unreachable()
+		editor.commands.command(({ tr }) => {
+			cleanupFileLoaderNode(
+				tr,
+				pos,
+				editor.schema.nodes.fileLoader,
+				[
+					editor.state.schema.nodes.item,
+					editor.state.schema.nodes.list
+				],
+				editor.schema.nodes.paragraph
+			)
+			return true
+		})
+	}
+
+	defaultInsertLoadingNode(file: TFile, editor: Editor, insertPos: number): TKey {
+		const attrs = {
+			loadingId: nanoid(10),
+			fileName: file.name,
+			loading: true
+		}
+		editor.commands.command(({ tr }) => {
+			const pm = editor.schema.nodes
+			tr.insert(insertPos, pm.item.create(
+				{},
+				pm.fileLoader.create(attrs)
+			))
+			return true
+		})
+		return attrs.loadingId as TKey
+	}
+}

package/src/runtime/pm/features/FileLoader/FileLoaderHandler/TestFileLoaderHandler.ts

@@ -0,0 +1,61 @@
+import { delay } from "@alanscodelog/utils/delay"
+import mime from "mime/lite"
+
+import { FileLoaderHandler } from "./FileLoaderHandler.js"
+
+import { findLoadingNodePos } from "../utils/findLoadingNodePos.js"
+import { readAsDataUrl } from "../utils/readAsDataUrl.js"
+
+export const testFileLoaderDelay = 2000
+/** Instance of {@link FileLoaderHandler} for testing. */
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const TestFileLoaderHandler = new FileLoaderHandler({
+	filterFile: file => {
+		const mimeExtension = mime.getExtension(file.type)
+		if (!mimeExtension) return undefined
+		const normalizedMimeType = mime.getType(mimeExtension)
+		;(file as any).parsedMime = normalizedMimeType
+
+		if (!normalizedMimeType?.startsWith("image")) return undefined
+		return file as File & { parsedMime: string }
+	},
+	replaceLoadingNode(editor, pos, res) {
+		const pm = editor.schema.nodes
+		const parsedMime = res.file.parsedMime
+		const returnVal = editor.commands.command(({ tr }) => {
+			if (parsedMime.startsWith("image")) {
+				tr.replaceWith(pos, pos + 1, pm.image.create({
+					src: res.result
+				}))
+				return true
+			}
+			tr.delete(pos, pos + 1)
+			// todo show warning
+			return false
+		})
+		return returnVal
+	},
+	loadFile: async (file, insertId, editor) => {
+		const result = await readAsDataUrl(file)
+		const replacePos = findLoadingNodePos(editor.state, insertId)
+
+		// preview the "upload"
+		if (replacePos !== undefined) {
+			editor.commands.command(({ tr }) => {
+				tr.setNodeAttribute(replacePos, "preview", result)
+				return true
+			})
+		}
+
+		if (file.parsedMime.startsWith("image")) {
+			// simulating a upload, using Math.random() to simulate different speeds
+			await delay(testFileLoaderDelay * Math.random())
+			return {
+				file,
+				result
+			}
+		}
+		return undefined
+	}
+})

package/src/runtime/pm/features/FileLoader/commands/insertFile.ts

@@ -0,0 +1,87 @@
+import type { Command } from "@tiptap/core"
+
+import { redirectFromEmbedded } from "../../EmbeddedDocument/utils/redirectFromEmbedded.js"
+import type { IFileLoaderHandler } from "../types.js"
+import { findLoadingNodePos } from "../utils/findLoadingNodePos.js"
+
+declare module "@tiptap/core" {
+
+	// eslint-disable-next-line @typescript-eslint/naming-convention
+	interface Commands<ReturnType> {
+		fileLoader: {
+			/**
+			 * Insert a file into the editor using the FileLoader extension. The configured {@link IFileLoaderHandler} determines where exactly it's inserted (in an item node after by default).
+			 *
+			 * You can technically test if this will work with `can` but it's not 100% accurate. We only check if at least one file passes the file filter, not everything else.
+			 *
+			 * @redirectable
+			 */
+			// this exists in part because I cannot get e2e tests with drop events to work
+			// see the FileLoader tests
+			// we also need inserFiles to be redirectable
+			insertFile(files: File[], pos?: number): ReturnType
+		}
+	}
+}
+export const insertFile = (
+	handler: IFileLoaderHandler<any, any>,
+	debug: boolean = false
+) => (
+	files: File[],
+	pos?: number
+): Command => ({ tr, editor, view, commands, dispatch }): boolean => {
+	const redirect = redirectFromEmbedded(view, "insertFile", { args: [files, pos], view, commands })
+	if (redirect.redirected) { return redirect.result as any }
+	// since the handler can call it's own new transactions
+	// if we don't prevent this one, we'll get a mismatched transaction error
+	if (dispatch) tr.setMeta("fileLoaderIgnore", true)
+
+	if (!dispatch) {
+		return files.some(file => handler.filterFile?.(file) ?? true)
+	}
+	// insert them in reverse so they show up in the correct order
+	void Promise.allSettled(files.reverse().map(async file => {
+		// eslint-disable-next-line no-console
+		if (debug) console.log(`insertFile for ${file.name}`, file)
+		const f = handler.filterFile ? handler.filterFile(file) : file
+		if (!f) return
+
+		// eslint-disable-next-line no-console
+		if (debug) console.log(`filterFile for ${file.name}`, f)
+
+		const insertPosition = handler.insertPosition(f, editor, pos)
+
+		// eslint-disable-next-line no-console
+		if (debug) console.log(`insertPosition for ${file.name}`, insertPosition)
+		if (insertPosition === undefined) return
+
+		const insertLoadingNode = handler.insertLoadingNode
+		const insertId = insertLoadingNode(f, editor, insertPosition, pos)
+
+		// eslint-disable-next-line no-console
+		if (debug) console.log(`insertId for ${file.name}`, insertId)
+		if (!insertId) return
+
+		const res = await handler.loadFile?.(f, insertId, editor)
+
+		// eslint-disable-next-line no-console
+		if (debug) console.log(`result for ${file.name}`, res)
+		if (!res) {
+			return handler.onLoadError(f, editor, undefined, new Error("fileLoader returned nothing."), insertId)
+		}
+
+		const replacePos = findLoadingNodePos(editor.state, insertId)
+
+		// eslint-disable-next-line no-console
+		if (debug) console.log(`replacePos for ${file.name}`, replacePos)
+		if (replacePos === undefined) {
+			return handler.onLoadError(f, editor, replacePos, new Error("Could not find node to replace."), insertId)
+		}
+
+		const replaceRes = handler.replaceLoadingNode(editor, replacePos, res as any, insertId)
+
+		// eslint-disable-next-line no-console
+		if (debug) console.log(`called replaceLoadingNode for ${file.name}, replaced node:`, replaceRes)
+	})).then(() => {})
+	return true
+}

package/src/runtime/pm/features/FileLoader/components/FileLoaderNodeView.vue

@@ -0,0 +1,38 @@
+<template>
+<!-- @vue-expect-error contenteditable exists -->
+<node-view-wrapper
+	:class="twMerge(`
+		group/file-loader
+		rounded-sm
+		animate-pulse
+		bg-accent-200
+		text-accent-800
+		dark:bg-accent-700
+		dark:text-accent-300
+		px-2
+		flex
+		flex-col
+		items-center
+		gap-2
+	`
+	)"
+	contenteditable="false"
+>
+	<div class="self-start">
+		{{ `Loading "${node.attrs.fileName ?? `Unknown`}" ...` }}
+	</div>
+	<img
+		v-if="node.attrs.preview"
+		class="!max-h-[200px] !max-w-[200px] mb-2"
+		:src="node.attrs.preview"
+		alt="Loading Image"
+	>
+</node-view-wrapper>
+</template>
+
+<script setup lang="ts">
+import { nodeViewProps, NodeViewWrapper } from "@tiptap/vue-3"
+import { twMerge } from "tailwind-merge"
+
+/* const props =  */defineProps(nodeViewProps)
+</script>

package/src/runtime/pm/features/FileLoader/plugins/fileLoaderPlugin.ts

@@ -0,0 +1,70 @@
+import type { Editor } from "@tiptap/core"
+import { Plugin, PluginKey, type Transaction } from "@tiptap/pm/state"
+
+import type { FileLoaderExtensionOptions } from "../types.js"
+import { cleanupFileLoaderNodes } from "../utils/cleanupFileLoaderNodes.js"
+
+export const fileLoaderPluginKey = new PluginKey("fileLoader")
+
+export function fileLoaderPlugin(
+	editor: Editor,
+	options: Pick<FileLoaderExtensionOptions, "cleanupOnLoad">
+): Plugin<any> {
+	let cleaned = false
+	return new Plugin({
+		key: fileLoaderPluginKey,
+		/** See {@link DocumentApi} */
+		stateInit: (tr: Transaction) => {
+			if (!options.cleanupOnLoad) return
+			cleaned = true
+			return cleanupFileLoaderNodes(
+				tr,
+				editor.schema,
+				editor.state.schema.nodes.fileLoader,
+				[
+					editor.state.schema.nodes.item,
+					editor.state.schema.nodes.list
+				],
+				editor.state.schema.nodes.paragraph
+			)
+		},
+		// in case the documentApi isn't being used to load documents
+		appendTransaction: (_, _oldState, newState) => {
+			if (!newState.tr.getMeta("cleanFileLoaders") && (!options.cleanupOnLoad || cleaned)) return
+			cleaned = true
+			return cleanupFileLoaderNodes(
+				newState.tr,
+				editor.schema,
+				editor.state.schema.nodes.fileLoader,
+				[
+					editor.state.schema.nodes.item,
+					editor.state.schema.nodes.list
+				],
+				editor.state.schema.nodes.paragraph
+			)
+		},
+		filterTransaction: tr => {
+			if (tr.getMeta("fileLoaderIgnore")) return false
+			return true
+		},
+		props: {
+			handleDOMEvents: {
+				drop: (view, event) => {
+					event.preventDefault()
+					const pos = view.posAtCoords({ left: event.clientX, top: event.clientY })
+					if (!pos) return
+					const position = pos.inside > 0 ? pos.inside : pos.pos - 1
+					const files = Array.from(event.dataTransfer?.files ?? [])
+					void editor.commands.insertFile(files, position)
+				},
+				paste: (_view, event) => {
+					const files = Array.from(event.clipboardData?.files ?? [])
+					const htmlContent = event.clipboardData?.getData("text/html")
+					// let the editor handle it
+					if (htmlContent) return
+					void editor.commands.insertFile(files)
+				}
+			}
+		}
+	})
+}

package/src/runtime/pm/features/FileLoader/types.ts

@@ -0,0 +1,91 @@
+import type { Editor } from "@tiptap/core"
+
+import type { HTMLAttributesOptions } from "../../../types/index.js"
+import type { WithOnTriggerByEmbeddedBlockOptions } from "../EmbeddedDocument/types.js"
+
+export interface FileLoaderExtensionOptions extends HTMLAttributesOptions, WithOnTriggerByEmbeddedBlockOptions {
+	/**
+	 * By default, the plugin removes fileLoader nodes using {@link cleanupFileLoaderNodes} when the document is loaded. This can happen if the user interrupts a file load/upload/save and the document is saved with a fileLoader node.
+	 *
+	 * We can't keep a reference to the file they wanted to load without external work, so the nodes are removed.
+	 */
+	cleanupOnLoad?: boolean
+	/** See {@link IFileLoaderHandler} */
+	handler: IFileLoaderHandler<File, any>
+}
+
+/**
+ * Helps handle the loading of files. Provides a way to adjust the insert position and takes care of keeping track of loading vs loaded nodes.
+ *
+ * See {@link FileLoaderHandler} for a partial implementation you can customize to create the interface.
+ *
+ * The insert handlers are called with the files in reverse order so that you can more easily insert them one after the other without position mapping.
+ */
+
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export type IFileLoaderHandler<
+	TFile extends File,
+	T = { file: TFile, result: string | ArrayBuffer | null },
+	TKey = string
+> = {
+	/**
+	 * Should load/save/upload the file and return the information neccesary to create the loaded node.
+	 *
+	 * The `insertId` and `editor` are provided in case you're uploading the file or doing some other heavy operation and want to update the fileLoader node as soon as you can load the image.
+	 *
+	 * A `FileLoaderNodeView` is provided (but no pre-configured) for these purposes. If you set the node's `preview` property it will use it as the src for an image.
+	 */
+	loadFile: (file: TFile, insertId: TKey, editor: Editor) => Promise<T | undefined>
+	/**
+	 * This can be used to remove the loading node on errors.
+	 *
+	 * The default {@link FileLoaderHandler.onLoadError} uses {@link cleanupFileLoaderNodes} to remove the parent item node if possible, otherwise it turns the fileLoader node into a paragraph.
+	 */
+	onLoadError: (
+		file: TFile,
+		editor: Editor,
+		pos: number | undefined,
+		error: Error,
+		loadingKey: TKey,
+	) => void
+
+	/**
+	 *
+	 * Where to insert the fileLoader node.
+	 *
+	 * The default @{@link FileLoaderHandler.insertPosition} returns the position after the closest parent item node. The idea being one inserts a new item node there with a loading file node inside.
+	 *
+	 * You can override this by returning a different position. If no position is returned, no node is inserted.
+	 */
+	insertPosition: (file: TFile, editor: Editor, pos?: number) => number | undefined
+	/**
+	 * Given a file, should insert a fileLoader node with the `loadingId` set to a unique key that the extension can then use to find the node again. It should return this key if it inserted the node.
+	 *
+	 * Using the file name is not a good idea as it's not guaranteed to be unique if the user inserts the same item twice.
+	 *
+	 * The default {@link FileLoaderHandler.insertLoadingNode} inserts a new item node with a fileLoader node inside after in the closest viable position after the insertPos. It uses a nanoid for the loading id.
+	 */
+	insertLoadingNode: (file: TFile, editor: Editor, insertPos: number, originalPos?: number) => TKey | undefined
+	/**
+	 * After loading the file, if it's successful, this is passed the result and the position of the fileLoader node.
+	 *
+	 * Note that this position points at the node with those attributes, and not it's parent in the case of having inserted a wrapping node.
+	 *
+	 *
+	 */
+	replaceLoadingNode: (
+		editor: Editor,
+		pos: number,
+		res: T,
+		loadingKey: TKey,
+	) => void
+	/**
+	 * Return the file (or whatever type you'd like) to allow the extension to handle it.
+	 *
+	 * If the function doesn't return anything, the file will be ignored.
+	 * No fileLoader node will be created. The event will still be preventDefaulted.
+	 *
+	 * This can be used to filter out mime types you can't handle with a library like `mime`. Mime type filtering is not handled by the extension since it can be complicated.
+	 */
+	filterFile: (file: File) => TFile | undefined
+}

package/src/runtime/pm/features/FileLoader/utils/cleanupFileLoaderNode.ts

@@ -0,0 +1,39 @@
+import type { NodeType, ResolvedPos } from "@tiptap/pm/model"
+import type { Transaction } from "@tiptap/pm/state"
+
+import { findUpwards } from "../../../utils/findUpwards.js"
+
+/** Like {@link cleanupFileLoaderNodes} but for single nodes when you already know the position. Returns true if it deleted a node. */
+
+export function cleanupFileLoaderNode(
+	tr: Transaction,
+	pos: number,
+	fileLoaderType: NodeType,
+	wrappingTypes: NodeType[],
+	replaceType: NodeType
+): boolean {
+	const node = tr.doc.nodeAt(pos)
+	if (!node) return false
+	if (node.type === fileLoaderType) {
+		let $parent: ResolvedPos | undefined
+		findUpwards(tr.doc, pos, $pos => {
+			if (wrappingTypes.includes($pos.parent.type)) {
+				if ($pos.parent.childCount === 1) {
+					$parent = $pos
+				} else {
+					return true
+				}
+			} else if ($parent) {
+				return true
+			}
+			return false
+		})
+		if ($parent) {
+			tr.delete($parent.start() - 1, $parent.end() + 1)
+		} else {
+			tr.replaceWith(pos, pos + node.nodeSize, replaceType.create())
+		}
+		return true
+	}
+	return false
+}

package/src/runtime/pm/features/FileLoader/utils/cleanupFileLoaderNodes.ts

@@ -0,0 +1,42 @@
+import { unreachable } from "@alanscodelog/utils/unreachable"
+import { getNodeType } from "@tiptap/core"
+import type { NodeType, Schema } from "@tiptap/pm/model"
+import type { Transaction } from "@tiptap/pm/state"
+
+import { cleanupFileLoaderNode } from "./cleanupFileLoaderNode.js"
+
+/**
+ * Removes all `fileLoader` nodes from the document.
+ *
+ * Searches up parent wrappers of the given `wrappingTypes`. If any exist and have no other children, they are removed.
+ */
+export function cleanupFileLoaderNodes(
+	tr: Transaction,
+	schema: Schema,
+	fileLoaderTypeOrName: string | NodeType,
+	wrappingTypesOrNames: (string | NodeType)[],
+	replaceTypeOrName: string | NodeType,
+	callback: typeof cleanupFileLoaderNode = cleanupFileLoaderNode
+): Transaction {
+	const fileLoaderType = getNodeType(fileLoaderTypeOrName, schema)
+	const wrappingTypes = wrappingTypesOrNames.map(_ => getNodeType(_, schema))
+	const replaceType = getNodeType(replaceTypeOrName, schema)
+	const positions: number[] = []
+	tr.doc.descendants((node, pos) => {
+		if (node.type === fileLoaderType) {
+			positions.push(pos)
+		}
+	})
+	// reversed so that we don't need to map positions
+	// and also so we delete the deepest nodes first
+	// giving a chance for parents to be completely deleted
+	for (const pos of positions.reverse()) {
+		const mappedPos = tr.mapping.map(pos)
+		// todo remove
+		if (mappedPos !== pos) unreachable()
+		callback(tr, mappedPos, fileLoaderType, wrappingTypes, replaceType)
+	}
+	tr.setMeta("preventClearDocument", true)
+	tr.setMeta("addToHistory", false)
+	return tr
+}

package/src/runtime/pm/features/FileLoader/utils/findLoadingNodePos.ts

@@ -0,0 +1,16 @@
+import type { EditorState } from "@tiptap/pm/state"
+
+export function findLoadingNodePos(
+	state: EditorState,
+	loadingId: string
+): number | undefined {
+	let replacePos
+	state.doc.nodesBetween(0, state.doc.content.size - 1, (node, position) => {
+		if (node.attrs.loadingId === loadingId) {
+			replacePos = position
+			return false
+		}
+		return true
+	})
+	return replacePos
+}

package/src/runtime/pm/features/FileLoader/utils/optionsCheck.ts

@@ -0,0 +1,16 @@
+import type { Editor } from "@tiptap/core"
+
+import type { FileLoaderExtensionOptions } from "../types.js"
+
+
+export function optionsCheck(editor: Editor, options: FileLoaderExtensionOptions): void {
+	if (!options.handler) {
+		throw new Error("The FileLoader needs to be configered with a handler (see FileLoaderHandler).")
+	}
+	if ((!options.handler.insertLoadingNode
+		|| !options.handler.onLoadError
+		|| !options.handler?.insertPosition)
+	&& editor.state.schema.nodes.item === undefined) {
+		throw new Error("Could not find item node in schema. Add the block extensions or specify a custom `handler.insertLoadingNode` function for the FileLoader.")
+	}
+}