@witchcraft/editor 0.0.1

package/dist/runtime/pm/features/EmbeddedDocument/components/EmbeddedNodeView.vue.d.ts

@@ -0,0 +1,92 @@
+declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    editor: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["editor"]>;
+        required: true;
+    };
+    node: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["node"]>;
+        required: true;
+    };
+    decorations: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["decorations"]>;
+        required: true;
+    };
+    selected: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["selected"]>;
+        required: true;
+    };
+    extension: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["extension"]>;
+        required: true;
+    };
+    getPos: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["getPos"]>;
+        required: true;
+    };
+    updateAttributes: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["updateAttributes"]>;
+        required: true;
+    };
+    deleteNode: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["deleteNode"]>;
+        required: true;
+    };
+    view: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["view"]>;
+        required: true;
+    };
+    innerDecorations: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["innerDecorations"]>;
+        required: true;
+    };
+    HTMLAttributes: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["HTMLAttributes"]>;
+        required: true;
+    };
+}>, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    editor: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["editor"]>;
+        required: true;
+    };
+    node: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["node"]>;
+        required: true;
+    };
+    decorations: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["decorations"]>;
+        required: true;
+    };
+    selected: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["selected"]>;
+        required: true;
+    };
+    extension: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["extension"]>;
+        required: true;
+    };
+    getPos: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["getPos"]>;
+        required: true;
+    };
+    updateAttributes: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["updateAttributes"]>;
+        required: true;
+    };
+    deleteNode: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["deleteNode"]>;
+        required: true;
+    };
+    view: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["view"]>;
+        required: true;
+    };
+    innerDecorations: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["innerDecorations"]>;
+        required: true;
+    };
+    HTMLAttributes: {
+        type: import("vue").PropType<import("@tiptap/core").NodeViewProps["HTMLAttributes"]>;
+        required: true;
+    };
+}>> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+export default _default;

package/dist/runtime/pm/features/EmbeddedDocument/composables/useEmbeddedEditor.d.ts

@@ -0,0 +1,31 @@
+import type { Content, Editor, EditorOptions } from "@tiptap/core";
+import { type ComputedRef, type Ref, type ShallowRef } from "vue";
+import { type DocumentApiInterface, type MaybeEmbedId } from "../../DocumentApi/types.js.js";
+/** Sets up nearly everything for the embedded editor nodeview. */
+export declare function useEmbeddedEditor(embedIdRef: ComputedRef<MaybeEmbedId> | Ref<MaybeEmbedId>, editor: ShallowRef<Editor | undefined>, rootEditor: Editor, 
+/** For forwarding commands the embedded editor can't handle. See {@link Embedded}. */
+getPos: () => number | undefined, { undoTimeouts, selfSymbol, onUndoWarning, onUndoOk, alwaysLoad, injectIsEmbedded, injectIsDeepEmbedded }?: {
+    undoTimeouts?: [number, number];
+    onUndoWarning?: ((ref: Ref<boolean>) => void);
+    onUndoOk?: ((ref: Ref<boolean>) => void);
+    selfSymbol?: symbol;
+    /** By default, documents will not be loaded if they are embedded too deeply or recursively embedded. Passing true will ignore all checks and load them anyways. This also usually requires disabling the injections with the `injectIsEmbedded` and `injectIsDeepEmbedded` options. */
+    alwaysLoad?: boolean;
+    /** By default, the composable injects the `isEmbedded*InjectionKey`s. Passing false will not inject them. */
+    injectIsEmbedded?: boolean;
+    /** By default, the composable injects `isDeepEmbeddedInjectionKey` with true if it is false. Passing false will not inject it. */
+    injectIsDeepEmbedded?: boolean;
+}): {
+    content: Ref<Content | null>;
+    api: DocumentApiInterface;
+    selfSymbol: symbol;
+    isEmbeddedTooDeep: boolean;
+    isEmbeddedBlock?: Ref<boolean>;
+    isRecursivelyEmbedded: ComputedRef<boolean>;
+    showUndoWarning: Ref<boolean>;
+    /** If name is undefined, the embed is a new embed without a document id. */
+    name: ComputedRef<string | undefined>;
+    isLoading: Ref<boolean>;
+    /** The root editor needs to provide it's options so we can pass them to the embedded editor. If we don't, extra extensions (e.g. BaseShortcuts) and options won't be registered on the embedded editor. See the `embeddedEditorOptionsInjectionKey` for why `autofocus` is ommitted. */
+    editorOptions: Partial<Omit<EditorOptions, "autofocus">>;
+};

package/dist/runtime/pm/features/EmbeddedDocument/composables/useEmbeddedEditor.js

@@ -0,0 +1,199 @@
+import { castType } from "@alanscodelog/utils/castType";
+import { computed, inject, onBeforeUnmount, onMounted, provide, ref, watch } from "vue";
+import { getDiffReplacementRange } from "../../../utils/getDiffReplacementRange.js";
+import { documentApiInjectionKey } from "../../DocumentApi/types.js";
+import { convertFullTransactionForPartialState } from "../../DocumentApi/utils/convertFullTransactionForPartialState.js";
+import { getStateEmbedRange } from "../../DocumentApi/utils/getStateEmbedRange.js";
+import { isEmbedId } from "../../DocumentApi/utils/isEmbedId.js";
+import { Embedded } from "../Embedded.js";
+import { embededEditorOptionsInjectionKey, isDeepEmbeddedInjectionKey, isEmbeddedBlockInjectionKey, isEmbeddedInjectionKey, parentEditorIdInjectionKey } from "../types.js";
+function defaultOnUndoWarning(r, state, undoTimeouts = [50, 2e3]) {
+  clearTimeout(state.smallTimeout);
+  clearTimeout(state.timeout);
+  r.value = false;
+  if (state.justWarned) {
+    r.value = true;
+  }
+  state.justWarned = true;
+  state.smallTimeout = setTimeout(() => {
+    state.justWarned = false;
+    r.value = true;
+    clearTimeout(state.timeout);
+    state.timeout = setTimeout(() => {
+      r.value = false;
+    }, undoTimeouts[1]);
+  }, undoTimeouts[0]);
+}
+function defaultOnUndoOk(r, state) {
+  clearTimeout(state.smallTimeout);
+  clearTimeout(state.timeout);
+  r.value = false;
+}
+export function useEmbeddedEditor(embedIdRef, editor, rootEditor, getPos, {
+  undoTimeouts = [50, 2e3],
+  selfSymbol = Symbol(`embedded-editor`),
+  onUndoWarning,
+  onUndoOk,
+  alwaysLoad = false,
+  injectIsEmbedded = true,
+  injectIsDeepEmbedded = true
+} = {}) {
+  const showUndoWarning = ref(false);
+  const content = ref(null);
+  const api = inject(documentApiInjectionKey);
+  if (!api) {
+    throw new Error("No embed api provided.");
+  }
+  const editorOptions = inject(embededEditorOptionsInjectionKey);
+  if (!editorOptions) {
+    throw new Error("No editor options provided.");
+  }
+  editorOptions.extensions = [
+    ...(editorOptions.extensions ?? []).filter((ext) => ext.name !== Embedded.name),
+    Embedded.configure({
+      rootEditor,
+      getPos,
+      getEmbedId: () => embedIdRef.value
+    })
+  ];
+  const isEmbeddedTooDeep = inject(isDeepEmbeddedInjectionKey, false);
+  if (injectIsDeepEmbedded && !isEmbeddedTooDeep) {
+    provide(isDeepEmbeddedInjectionKey, true);
+  }
+  const isEmbeddedBlock = computed(() => !!embedIdRef.value.blockId);
+  if (injectIsEmbedded) {
+    provide(isEmbeddedInjectionKey, true);
+    provide(isEmbeddedBlockInjectionKey, isEmbeddedBlock);
+  }
+  const parentId = inject(parentEditorIdInjectionKey, void 0);
+  const isRecursivelyEmbedded = computed(() => parentId?.value === embedIdRef.value.docId);
+  const isLoading = ref(false);
+  const name = computed(() => isEmbedId(embedIdRef.value) ? api.getEmbedTitle(embedIdRef.value) : void 0);
+  const warningState = {
+    smallTimeout: void 0,
+    timeout: void 0,
+    justWarned: false
+  };
+  function forwardDispatchToFullState(tr) {
+    castType(embedIdRef.value);
+    const stateBefore = api.getFromCache(embedIdRef.value);
+    if (!stateBefore) {
+      throw new Error("Expected stateBefore to exist.");
+    }
+    if (!tr) return;
+    const diff = getDiffReplacementRange(stateBefore.doc, tr.doc);
+    const { start, end } = getStateEmbedRange(tr.doc, embedIdRef.value);
+    if (diff && end !== void 0 && start !== void 0 && (diff.start < start || diff.end > end)) {
+      onUndoWarning ? onUndoWarning(showUndoWarning) : defaultOnUndoWarning(showUndoWarning, warningState, undoTimeouts);
+    } else {
+      onUndoOk ? onUndoOk(showUndoWarning) : defaultOnUndoOk(showUndoWarning, warningState);
+    }
+    tr.setMeta("no-step-convert", true);
+    tr.setMeta("no-schema-convert", true);
+    if (!embedIdRef.value.blockId) {
+      tr.setMeta("no-step-convert", true);
+    }
+    api.updateDocument?.(
+      embedIdRef.value,
+      tr,
+      void 0
+    );
+  }
+  function onTransaction({ transaction }) {
+    castType(embedIdRef.value);
+    if (!transaction.docChanged || transaction.getMeta("ignore")) {
+      return;
+    }
+    if (!embedIdRef.value.blockId) {
+      transaction.setMeta("no-step-convert", true);
+    }
+    api.updateDocument?.(
+      embedIdRef.value,
+      transaction,
+      selfSymbol
+    );
+  }
+  const onUpdateDocument = (incomingEmbedId, tr, _stateBefore, _incomingState, incomingSelfSymbol) => {
+    castType(embedIdRef.value);
+    if (incomingSelfSymbol === selfSymbol || embedIdRef.value.docId !== incomingEmbedId.docId || !tr.docChanged || tr.getMeta("ignore")) {
+      return;
+    }
+    if (content.value) {
+      const convertedTr = convertFullTransactionForPartialState(
+        editor.value.state,
+        tr,
+        embedIdRef.value
+      );
+      if (convertedTr) {
+        if (!convertedTr.before.eq(editor.value.state.doc)) {
+          return;
+        }
+        editor.value.view.dispatch(convertedTr);
+      } else {
+        unloadDocument(embedIdRef.value, { partial: true });
+      }
+    } else {
+      void loadDocument(embedIdRef.value, { partial: true });
+    }
+  };
+  let attached = false;
+  async function loadDocument(embedId, { partial = false } = {}) {
+    if (!isEmbedId(embedId)) return;
+    if (!alwaysLoad && (isRecursivelyEmbedded.value || isEmbeddedTooDeep)) return;
+    if (!partial) {
+      isLoading.value = true;
+      await api.load(embedId);
+    }
+    const res = api.getEmbeddedContent?.(embedId);
+    if (!res) return;
+    if (!partial) {
+      api.addEventListener?.("update", onUpdateDocument);
+    }
+    content.value = res;
+    watch(editor, () => {
+      editor.value.commands.setHistoryRedirect(
+        () => api.getFromCache(embedId),
+        forwardDispatchToFullState
+      );
+      editor.value?.on("transaction", onTransaction);
+      isLoading.value = false;
+      attached = true;
+    }, { once: true });
+  }
+  function unloadDocument(embedId, { partial = false } = {}) {
+    if (!isEmbedId(embedId)) return;
+    if (!alwaysLoad && (isRecursivelyEmbedded.value || isEmbeddedTooDeep)) return;
+    editor.value?.off("transaction", onTransaction);
+    if (!partial && attached) {
+      api.removeEventListener?.("update", onUpdateDocument);
+      api.unload(embedId);
+      attached = false;
+    }
+    editor.value?.commands.setHistoryRedirect(void 0, void 0);
+    content.value = null;
+  }
+  watch(embedIdRef, (newVal, oldVal) => {
+    if (newVal.docId !== oldVal.docId || newVal.blockId !== oldVal.blockId) {
+      unloadDocument(oldVal);
+      void loadDocument(newVal);
+    }
+  });
+  onMounted(async () => {
+    await loadDocument(embedIdRef.value);
+  });
+  onBeforeUnmount(() => {
+    unloadDocument(embedIdRef.value);
+  });
+  return {
+    content,
+    api,
+    selfSymbol,
+    isEmbeddedTooDeep,
+    isEmbeddedBlock,
+    isRecursivelyEmbedded,
+    showUndoWarning,
+    name,
+    isLoading,
+    editorOptions
+  };
+}

package/dist/runtime/pm/features/EmbeddedDocument/types.d.ts

@@ -0,0 +1,49 @@
+import type { Dispatch, Editor, EditorOptions } from "@tiptap/core";
+import type { ComputedRef, InjectionKey, Ref } from "vue";
+import type { MaybeEmbedId } from "../DocumentApi/types.js.js";
+export interface EmbeddedDocumentNodeOptions extends WithOnTriggerByEmbeddedBlockOptions {
+    rootEditor: Editor;
+    /** Provided by the embedded node view. */
+    getPos: () => number | undefined;
+    getEmbedId: () => MaybeEmbedId;
+}
+/** Tells the editor and embedded doc view whether it's deeply embedded (more than one level) or not. */
+export declare const isDeepEmbeddedInjectionKey: InjectionKey<boolean>;
+/** Tells the editor and embedded doc view whether it's embedded or not. */
+export declare const isEmbeddedInjectionKey: InjectionKey<boolean>;
+export declare const isEmbeddedBlockInjectionKey: InjectionKey<ComputedRef<boolean> | Ref<boolean>>;
+/** Injects the editor component to use for embedded editors. */
+export declare const embeddedEditorComponentInjectionKey: InjectionKey<new (...args: any) => {
+    editor?: Editor;
+}>;
+/** Injects the parent editor id so the embedded editor can know who is embedding it (to track recursive/disallowed embeds). */
+export declare const parentEditorIdInjectionKey: InjectionKey<Ref<string | undefined>>;
+/**
+    * Injects the editor options so the embedded editor can use the same ones as it's parent.
+    *
+    * Note that autofocus is always disabled for embedded editors, hence it's omission.
+    */
+export declare const embededEditorOptionsInjectionKey: InjectionKey<Partial<Omit<EditorOptions, "autofocus">>>;
+export type WithOnTriggerByEmbeddedBlockOptions = {
+    /**
+     * When the editor is embedded and it's embedding a single block, certain commands are nullified and just return true and do nothing because they would break the embedding (e.g. enter, split, indent, etc).
+     *
+     * All such commands forward to the `embeddedCommandRedirect` command if it's available (otherwise a warning is logged). The `Embedded` extension takes care of registering this redirect and can redirect some of the commands to the root editor, but not all of them.
+     *
+     * You can use this function to handle the redirection yourself. You will get passed both editor instances (root and embedded) to facilitate communication. If you can handle the command, you should return a boolean as with a regular command. Otherwise you can return undefined to let the default handler take care of it.
+     *
+     * Note that if the change moves the node, the component will get remounted and the embedded editor will no longer exist (to, for example, focus it).
+     *
+     * The included EmbeddedNodeView takes care of auto-focusing when the selection matches it's position. So as a workaround for focus at least, you can use `tr.setNodeSelection(nodePos + offset)`. Note the use of `offset`. The node's position will have probably changed depending on the command so you will need to know how much to offset it or have some way to find it's position again. While the embedId is provided, it's not guaranteed there is only one node embedding that id, there might be multiple. A better way is to first find the parent embedding item id before executing your command, note the `blockId`, then use it to find the node again.
+     *
+     * See {@link redirectFromEmbedded} for creating redirectable commands.
+     */
+    embeddedBlockCommandRedirect?: (commandName: string, args: any, context: {
+        editor: Editor;
+        rootEditor: Editor;
+        nodePos: number | undefined;
+        embedId: MaybeEmbedId;
+        dispatch: Dispatch;
+    }) => boolean | undefined;
+};
+export type OnTriggerByEmbeddedBlock = WithOnTriggerByEmbeddedBlockOptions["embeddedBlockCommandRedirect"];

package/dist/runtime/pm/features/EmbeddedDocument/types.js

@@ -0,0 +1,6 @@
+export const isDeepEmbeddedInjectionKey = Symbol("isEmbeddedInjectionKey");
+export const isEmbeddedInjectionKey = Symbol("isEmbeddedInjectionKey");
+export const isEmbeddedBlockInjectionKey = Symbol("isEmbeddedBlockInjectionKey");
+export const embeddedEditorComponentInjectionKey = Symbol("embeddedEditorComponentInjectionKey");
+export const parentEditorIdInjectionKey = Symbol("parentEditorIdInjectionKey");
+export const embededEditorOptionsInjectionKey = Symbol("embededEditorOptionsInjectionKey");

package/dist/runtime/pm/features/EmbeddedDocument/utils/isEmbeddedBlock.d.ts

@@ -0,0 +1,9 @@
+import type { EditorView } from "@tiptap/pm/view";
+/**
+    * Returns whether the current view is a block embed embedded in another view.
+    *
+    * This is done by checking if the immediate parent has the class `editor-is-embedded-block` which the editor component adds when it receives the {@link isEmbeddedBlockInjectionKey} injection key.
+    *
+    * We cannot do this via state since a document can be both embedded and not embedded at the same time.
+    */
+export declare function isEmbeddedBlock(view: EditorView): boolean;

package/dist/runtime/pm/features/EmbeddedDocument/utils/isEmbeddedBlock.js

@@ -0,0 +1,3 @@
+export function isEmbeddedBlock(view) {
+  return view.dom.parentElement?.classList.contains("editor-is-embedded-block") ?? false;
+}

package/dist/runtime/pm/features/EmbeddedDocument/utils/redirectFromEmbedded.d.ts

@@ -0,0 +1,28 @@
+import type { SingleCommands } from "@tiptap/core";
+import type { EditorView } from "@tiptap/pm/view";
+/**
+ * Commands that can split a block or modify it's position (indent/unindent) should not be called when the editor is in embedded block mode.
+ *
+ * This takes care of redirecting the command if possible (see {@link WithOnTriggerByEmbeddedBlockOptions.onTriggerByEmbeddedBlock}), otherwise it logs a warning.
+ *
+ * If the command should not be called at all and offers no redirect, don't pass the redirect parameter and it will log a different warning.
+ *
+ * You can use it in a command like this:
+ *
+ * ```ts
+ * commandName: (arg:any) => ({ commands, view, dispatch  }) => {
+ *		const redirect = isEmbeddedBlock(view, "commandName", { args:[arg], view, commands, dispatch }))
+ * 	if (redirect.redirected) { return redirect.result }
+ * }
+ *  ```
+ */
+export declare function redirectFromEmbedded(view: EditorView, name: string, redirect?: {
+    args: any[];
+    view: EditorView;
+    commands: SingleCommands;
+}): {
+    redirected: true;
+    result: any;
+} | {
+    redirected: false;
+};

package/dist/runtime/pm/features/EmbeddedDocument/utils/redirectFromEmbedded.js

@@ -0,0 +1,17 @@
+import { isEmbeddedBlock } from "./isEmbeddedBlock.js";
+export function redirectFromEmbedded(view, name, redirect) {
+  if (isEmbeddedBlock(view)) {
+    if (redirect && "embeddedCommandRedirect" in redirect.commands) {
+      const result = redirect.commands.embeddedCommandRedirect(
+        name,
+        redirect.args
+      );
+      return { redirected: true, result };
+    }
+    console.warn(
+      redirect ? `Command ${name} called from an embedded editor. This command supports command redirection, but no "embeddedCommandRedirect" command found. Command ignored (returning true to prevent further action).` : `Command ${name} should not be called from an embedded editor. Command ignored (returning true to prevent further action).`
+    );
+    return { redirected: true, result: true };
+  }
+  return { redirected: false };
+}

package/dist/runtime/pm/features/FileLoader/FileLoader.d.ts

@@ -0,0 +1,16 @@
+import { Node } from "@tiptap/core";
+import type { FileLoaderExtensionOptions } from "./types.js.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.
+ *
+ */
+export declare const FileLoader: Node<FileLoaderExtensionOptions, any>;
+export type NodeFileLoaderName = "fileLoader";

package/dist/runtime/pm/features/FileLoader/FileLoader.js

@@ -0,0 +1,99 @@
+import { mergeAttributes, Node } from "@tiptap/core";
+import { insertFile } from "./commands/insertFile.js";
+import { fileLoaderPlugin } from "./plugins/fileLoaderPlugin.js";
+import { optionsCheck } from "./utils/optionsCheck.js";
+import { isValidId } from "../Blocks/utils/isValidId.js";
+export const FileLoader = Node.create({
+  name: "fileLoader",
+  content: "",
+  marks: "",
+  group: "block",
+  addOptions() {
+    return {
+      cleanupOnLoad: true,
+      onDrop: void 0,
+      onPaste: void 0,
+      // there are checks on init to throw if the user didn't configure a handler
+      handler: void 0,
+      embeddedBlockCommandRedirect: void 0,
+      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: void 0
+      },
+      fileName: {
+        default: void 0
+      },
+      loading: {
+        default: true
+      },
+      loadingId: {
+        default: void 0
+      }
+    };
+  },
+  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 : void 0,
+            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)
+    ];
+  }
+});

package/dist/runtime/pm/features/FileLoader/FileLoaderHandler/FileLoaderHandler.d.ts

@@ -0,0 +1,28 @@
+import type { MakeOptional } from "@alanscodelog/utils/types";
+import type { Editor } from "@tiptap/core";
+import type { IFileLoaderHandler } from "../types.js.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 declare 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">);
+    defaultFilterFile(file: File): TFile | undefined;
+    defaultInsertPosition(_file: TFile, editor: Editor, pos?: number): number | undefined;
+    defaultOnLoadError(_file: TFile, editor: Editor, pos: number | undefined): void;
+    defaultInsertLoadingNode(file: TFile, editor: Editor, insertPos: number): TKey;
+}

package/dist/runtime/pm/features/FileLoader/FileLoaderHandler/FileLoaderHandler.js

@@ -0,0 +1,69 @@
+import { unreachable } from "@alanscodelog/utils/unreachable";
+import { nanoid } from "nanoid";
+import { findUpwards } from "../../../utils/findUpwards.js";
+import { cleanupFileLoaderNode } from "../utils/cleanupFileLoaderNode.js";
+export class FileLoaderHandler {
+  loadFile;
+  onLoadError;
+  insertPosition;
+  insertLoadingNode;
+  replaceLoadingNode;
+  filterFile;
+  constructor(opts) {
+    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) {
+    return file;
+  }
+  defaultInsertPosition(_file, editor, pos) {
+    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 : void 0;
+  }
+  defaultOnLoadError(_file, editor, pos) {
+    if (pos === void 0) 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, editor, insertPos) {
+    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;
+  }
+}

package/dist/runtime/pm/features/FileLoader/FileLoaderHandler/TestFileLoaderHandler.d.ts

@@ -0,0 +1,11 @@
+import { FileLoaderHandler } from "./FileLoaderHandler.js.js";
+export declare const testFileLoaderDelay = 2000;
+/** Instance of {@link FileLoaderHandler} for testing. */
+export declare const TestFileLoaderHandler: FileLoaderHandler<File & {
+    parsedMime: string;
+}, {
+    file: File & {
+        parsedMime: string;
+    };
+    result: string | ArrayBuffer | null;
+}, string>;