@witchcraft/editor 0.1.1 → 0.2.0

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

@@ -1,295 +1,28 @@
-import { type Editor, Extension } from "@tiptap/core"
-import { Plugin, PluginKey } from "@tiptap/pm/state"
-import type { EditorView } from "@tiptap/pm/view"
-import {
-	redo,
-	undo,
-	type UndoPluginState,
-	ySyncPlugin,
-	yUndoPlugin,
-	yUndoPluginKey,
-	yXmlFragmentToProseMirrorRootNode } from "y-prosemirror"
-import * as Y from "yjs"
-
-const ySyncFilterPluginKey = new PluginKey("ySyncFilter")
-// eslint-disable-next-line @typescript-eslint/naming-convention
-type YSyncOpts = Parameters<typeof ySyncPlugin>[1]
-// eslint-disable-next-line @typescript-eslint/naming-convention
-type YUndoOpts = Parameters<typeof yUndoPlugin>[0]
-
-declare module "@tiptap/core" {
-	// eslint-disable-next-line @typescript-eslint/naming-convention
-	interface Commands<ReturnType> {
-		collaboration: {
-			/** Sets the fragment to use for the collaboration extension. */
-			setFragment: (
-				fragment: Y.XmlFragment | undefined,
-				options?: { register?: boolean, unregister?: boolean }
-			) => ReturnType
-			/** Enables or disables collaboration. */
-			enableCollaboration: (enable: boolean) => ReturnType
-			/**
-			 * Undo recent changes
-			 *
-			 * @example editor.commands.undo()
-			 */
-			undo: () => ReturnType
-			/**
-			 * Reapply reverted changes
-			 *
-			 * @example editor.commands.redo()
-			 */
-			redo: () => ReturnType
-		}
-	}
-}
-
-export interface CollaborationStorage {
-	/**
-	 * Whether collaboration is currently disabled.
-	 * Disabling collaboration will prevent any changes from being synced with other users.
-	 */
-	isDisabled: boolean
-}
-
-export interface CollaborationOptions {
-
-	/**
-	 * A raw Y.js fragment, can be used instead of `document` and `field`.
-	 *
-	 * @example new Y.Doc().getXmlFragment('body')
-	 */
-	fragment?: Y.XmlFragment | null
-
-	/**
-	 * Fired when the content from Yjs is initially rendered to Tiptap.
-	 */
-	onFirstRender?: () => void
-
-	/**
-	 * Options for the Yjs sync plugin.
-	 */
-	ySyncOptions?: YSyncOpts
-
-	/**
-	 * Options for the Yjs undo plugin.
-	 */
-	yUndoOptions?: YUndoOpts
-	/** @internal */
-	// eslint-disable-next-line @typescript-eslint/naming-convention
-	_destroySyncPlugin?: () => void
-}
-type CollabInstance = {
-	editor: Editor
-	options: CollaborationOptions
-	storage: CollaborationStorage
-}
-type ExtendedUndoManager = UndoPluginState["undoManager"] & {
-	restore?: () => void
-}
-
-function createUndoPlugin(self: CollabInstance): Plugin { // Quick fix until there is an official implementation (thanks to @hamflx).
-	// See https://github.com/yjs/y-prosemirror/issues/114 and https://github.com/yjs/y-prosemirror/issues/102
-	const yUndoPluginInstance = yUndoPlugin(self.options.yUndoOptions)
-	const originalUndoPluginView = yUndoPluginInstance.spec.view
-
-	yUndoPluginInstance.spec.view = (view: EditorView) => {
-		const { undoManager } = yUndoPluginKey.getState(view.state) as UndoPluginState & { undoManager: ExtendedUndoManager }
-
-		if (undoManager.restore) {
-			undoManager.restore()
-			undoManager.restore = () => {
-				// noop
-			}
-		}
-
-		const viewRet = originalUndoPluginView ? originalUndoPluginView(view) : undefined
-
-		return {
-			destroy: () => {
-				const hasUndoManSelf = undoManager.trackedOrigins.has(undoManager)
-
-				const observers = undoManager._observers
-
-				undoManager.restore = () => {
-					if (hasUndoManSelf) {
-						undoManager.trackedOrigins.add(undoManager)
-					}
-
-					undoManager.doc.on("afterTransaction", undoManager.afterTransactionHandler)
-
-					undoManager._observers = observers
-				}
-
-				if (viewRet?.destroy) {
-					viewRet.destroy()
-				}
-			}
-		}
-	}
-	return yUndoPluginInstance
-}
-function createSyncPlugin(
-	self: CollabInstance
-): { plugin: Plugin, destroy: () => void } {
-	const fragment = self.options.fragment
-	if (!fragment) {
-		throw new Error("Collaboration requires a fragment.")
-	}
-	const plugin = ySyncPlugin(fragment, {
-		...self.options.ySyncOptions,
-		onFirstRender: self.options.onFirstRender
-	})
-
-	let off: (() => void) | undefined
-	function destroy(): void {
-		off?.()
-		// delete self.editor.state[ySyncPluginKey.key]
-	}
-	if (self.editor.options.enableContentCheck) {
-		const onBeforeTransaction = (): false | undefined => {
-			try {
-				yXmlFragmentToProseMirrorRootNode(fragment, self.editor.schema).check()
-			} catch (error) {
-				self.editor.emit("contentError", {
-					error: error as Error,
-					editor: self.editor,
-					disableCollaboration: () => {
-						fragment.doc?.destroy()
-						self.storage.isDisabled = true
-					}
-				})
-				// If the content is invalid, return false to prevent the transaction from being applied
-				return false
-			}
-			return undefined
-		}
-		fragment.doc?.on("beforeTransaction", onBeforeTransaction)
-		off = () => {
-			fragment.doc?.off("beforeTransaction", onBeforeTransaction)
-		}
-	}
-	return { plugin, destroy }
-}
-
-function createSyncFilterPlugin(
-	self: CollabInstance
-): Plugin | undefined {
-	if (!self.editor.options.enableContentCheck) return
-	const fragment = self.options.fragment
-	if (!fragment) {
-		throw new Error("Collaboration requires a fragment.")
-	}
-	return new Plugin({
-		key: ySyncFilterPluginKey,
-		filterTransaction: () => {
-			// When collaboration is disabled, prevent any sync transactions from being applied
-			if (self.storage.isDisabled) {
-				// Destroy the Yjs document to prevent any further sync transactions
-				fragment.doc?.destroy()
-
-				return true
-			}
-
-			return true
-		}
-	})
-}
-
-function createPlugins(self: CollabInstance): Plugin[] {
-	const { plugin: syncPlugin, destroy: destroySyncPlugin } = createSyncPlugin(self)
-	self.options._destroySyncPlugin = destroySyncPlugin
-	const filterPlugin = createSyncFilterPlugin(self)
-	const plugins = [
-		syncPlugin,
-		createUndoPlugin(self)
-	]
-	if (filterPlugin) {
-		plugins.push(filterPlugin)
-	}
-	return plugins
-}
+import BaseCollaboration, { type CollaborationOptions } from "@tiptap/extension-collaboration"
 
 /**
- * This extension allows you to collaborate with others in real-time.
+ * Extension of the base collaboration extension without prosemirror plugins or storage.
+ *
+ * We can't use tiptap's collaboration extension (or any extension that creates the sync plugin) because it expects to be configured with the document's ydoc per editor.
+ *
+ * This doesn't mesh well with how the document api works (see {@link DocumentApi}).
+ *
+ * Instead we let the extension register anything it wants (shortcuts, commands, etc) except the plugins and storage. This way it can just be added to the list of editor extensions normally.
+ *
+ * Then there is a seperate function to actually create the plugins:
+ *
+ * {@link createCollaborationPlugins} creates the plugins **per doc** and can be used from your document api without an editor instance. See {@link useTestDocumentApi} for an example.
  *
- * @see https://tiptap.dev/api/extensions/collaboration
+ * It's also where the `enableContentCheck` option should be set if you need it. It's IGNORED if passed to the extension.
  */
-// eslint-disable-next-line @typescript-eslint/naming-convention
-export const Collaboration = Extension.create<CollaborationOptions, CollaborationStorage>({
-	name: "collaboration",
-
-	priority: 1000,
-
-	addOptions() {
-		return {
-			document: null,
-			field: "default",
-			fragment: new Y.Doc().getXmlFragment("prosemirror")
-		}
-	},
 
+// eslint-disable-next-line @typescript-eslint/naming-convention
+export const Collaboration = BaseCollaboration.extend<Omit<CollaborationOptions, "document" | "field" | "fragment">, Record<string, never>>({
 	addStorage() {
-		return {
-			isDisabled: false
-		}
-	},
-
-	onCreate() {
-		if (this.editor.extensionManager.extensions.find(extension => extension.name === "history")) {
-			// eslint-disable-next-line no-console
-			console.warn(
-				"[tiptap warn]: \"@tiptap/extension-collaboration\" comes with its own history support and is not compatible with \"@tiptap/extension-history\"."
-			)
-		}
+		return {}
 	},
-
-	addCommands() {
-		// const self = this
-		return {
-			enableCollaboration: (enable: boolean) => () => {
-				this.storage.isDisabled = !enable
-				return true
-			},
-			undo: () => ({ tr, state, dispatch }) => {
-				tr.setMeta("preventDispatch", true)
-
-				const undoManager = yUndoPluginKey.getState(state)!.undoManager as ExtendedUndoManager
-
-				if (undoManager.undoStack.length === 0) {
-					return false
-				}
-
-				if (!dispatch) {
-					return true
-				}
-
-				return undo(state)
-			},
-			redo: () => ({ tr, state, dispatch }) => {
-				tr.setMeta("preventDispatch", true)
-
-				const undoManager = yUndoPluginKey.getState(state)!.undoManager as ExtendedUndoManager
-
-				if (undoManager.redoStack.length === 0) {
-					return false
-				}
-
-				if (!dispatch) {
-					return true
-				}
-
-				return redo(state)
-			}
-
-		}
-	},
-	onDestroy() {
-		this.options._destroySyncPlugin?.()
-	},
-
-	addProseMirrorPlugins(): Plugin[] {
-		const self = this
-		return createPlugins(self)
+	addProseMirrorPlugins() {
+		return []
 	}
 })
+

package/src/runtime/pm/features/Collaboration/createCollaborationPlugins.ts

@@ -0,0 +1,129 @@
+import type { CollaborationOptions } from "@tiptap/extension-collaboration"
+import { Plugin, PluginKey } from "@tiptap/pm/state"
+import type { EditorView } from "@tiptap/pm/view"
+import {
+	ySyncPlugin,
+	yUndoPlugin,
+	yUndoPluginKey,
+	yXmlFragmentToProsemirrorJSON
+} from "@tiptap/y-tiptap"
+import type { Doc } from "yjs"
+
+/**
+ * Copied from tiptap's collaboration extension with a few minor changes to make it work with our document api.
+ *
+ * Changes:
+ *
+ * - A local object is created for the plugin instance to simulate the extension's storage.
+ * - When it needs the editor (for the `contentError` event), every editor currently using the doc is iterated over and sent the event.
+ * - The normally editor level `enableContentCheck` option should be set here, it has no effect if passed to the extension.
+ *
+ * See {@link Collaboration} for more info and {@link useTestDocumentApi} for an example of how to use it.
+ */
+export function createCollaborationPlugins(
+	options: CollaborationOptions & { enableContentCheck: boolean },
+	schema: any,
+	getConnectedEditors?: () => any
+): Plugin[] {
+	const storage = {
+		isDisabled: false
+	}
+	const fragment = options.fragment
+		? options.fragment
+		: (options.document as Doc).getXmlFragment(options.field)
+
+	// Quick fix until there is an official implementation (thanks to @hamflx).
+	// See https://github.com/yjs/y-prosemirror/issues/114 and https://github.com/yjs/y-prosemirror/issues/102
+	const yUndoPluginInstance = yUndoPlugin(options.yUndoOptions)
+	const originalUndoPluginView = yUndoPluginInstance.spec.view
+
+	yUndoPluginInstance.spec.view = (view: EditorView) => {
+		const { undoManager } = yUndoPluginKey.getState(view.state)
+
+		if (undoManager.restore) {
+			undoManager.restore()
+			undoManager.restore = () => {
+				// noop
+			}
+		}
+
+		const viewRet = originalUndoPluginView ? originalUndoPluginView(view) : undefined
+
+		return {
+			destroy: () => {
+				const hasUndoManSelf = undoManager.trackedOrigins.has(undoManager)
+
+				const observers = undoManager._observers
+
+				undoManager.restore = () => {
+					if (hasUndoManSelf) {
+						undoManager.trackedOrigins.add(undoManager)
+					}
+
+					undoManager.doc.on("afterTransaction", undoManager.afterTransactionHandler)
+
+					undoManager._observers = observers
+				}
+
+				if (viewRet?.destroy) {
+					viewRet.destroy()
+				}
+			}
+		}
+	}
+
+	const ySyncPluginOptions: Parameters<typeof ySyncPlugin>[1] = {
+		...options.ySyncOptions,
+		onFirstRender: options.onFirstRender
+	}
+
+	const ySyncPluginInstance = ySyncPlugin(fragment, ySyncPluginOptions)
+
+	if (options.enableContentCheck) {
+		fragment.doc?.on("beforeTransaction", () => {
+			try {
+				const jsonContent = yXmlFragmentToProsemirrorJSON(fragment)
+
+				if (jsonContent.content.length === 0) {
+					return
+				}
+
+				schema.nodeFromJSON(jsonContent).check()
+			} catch (error) {
+				for (const editor of (getConnectedEditors?.() ?? [])) {
+					editor.emit("contentError", {
+						error: error as Error,
+						editor: editor,
+						disableCollaboration: () => {
+							fragment.doc?.destroy()
+							storage.isDisabled = true
+						}
+					})
+				}
+				// If the content is invalid, return false to prevent the transaction from being applied
+				return false
+			}
+		})
+	}
+
+	return [
+		ySyncPluginInstance,
+		yUndoPluginInstance,
+		options.enableContentCheck
+		&& new Plugin({
+			key: new PluginKey("filterInvalidContent"),
+			filterTransaction: () => {
+				// When collaboration is disabled, prevent any sync transactions from being applied
+				if (storage.isDisabled !== false) {
+					// Destroy the Yjs document to prevent any further sync transactions
+					fragment.doc?.destroy()
+
+					return true
+				}
+				// TODO should we be returning false when the transaction is a collaboration transaction?
+
+				return true
+			}
+		})
+	].filter(Boolean)
+}

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

@@ -1,9 +1,9 @@
 import { debounce, type DebounceQueue } from "@alanscodelog/utils/debounce"
 import { unreachable } from "@alanscodelog/utils/unreachable"
 import type { Content, EditorOptions } from "@tiptap/core"
+import { Editor } from "@tiptap/core"
 import type { Schema } from "@tiptap/pm/model"
 import type { EditorState, Plugin, Transaction } from "@tiptap/pm/state"
-import { Editor } from "@tiptap/vue-3"
 import { isProxy } from "vue"
 
 import type { DocId, DocumentApiInterface, EmbedId, OnSaveDocumentCallback, OnUpdateDocumentCallback } from "./types.js"
@@ -30,7 +30,17 @@ import { getEmbedNodeFromDoc } from "./utils/getEmbedNodeFromDoc.js"
  *
  * If there are extensions that use onCreate to set state or have plugins that need to change the state on init with appendTransaction, they will not work since there is no view to initialize the plugins. To get around this, plugins can specify a stateInit function that will be called with a transaction from the initial loaded state which it can then modify while having access to `this` and the extension options.
  *
- * The api creates a default instance of the editor to copy plugins from, this can be replaced by passing your own editor instance.
+ * ### Internals / How does it work?
+ *
+ * It can be a bit confusing how this works. It's quite different from how tiptap works.
+ *
+ * First, the api creates a **single** instance of the editor with the editor options **initially** provided (it can be replaced by passing your own editor instance).
+ *
+ * On load **per document**, the state of the doc is initialized. The plugins are copied from the single editor instance so that we can properly initialize the state. The plugin's `stateInit` is called, see above.
+ *
+ * When an editor **component** is mounted, useEditorContent will call the document api's `preEditorInit` to get a configuration for that component. This configuration can be edited in `preEditorInit` and is **per editor component**. It is disconnected from the **per document** configuration.
+ *
+ * There is no **per document** editor instance. This makes it tricky to work with extensions like Collaboration that expect this setup. They require some weird workarounds unfortunately.
  *
  * See {@link useTestDocumentApi} for an example of how to set things up.
  */
@@ -43,7 +53,7 @@ export class DocumentApi<
 		saving: OnSaveDocumentCallback[]
 	} = { update: [], saved: [], saving: [] }
 
-	private readonly _load: (docId: string, schema: Schema, plugins: Plugin[]) => Promise<{ state: EditorState, data?: T }>
+	private readonly _load: (docId: string, schema: Schema, plugins: Plugin[], getConnectedEditors: () => Editor[]) => Promise<{ state: EditorState, data?: T }>
 
 	private readonly _save?: (docId: string) => Promise<void>
 
@@ -84,6 +94,8 @@ export class DocumentApi<
 
 	editor: Editor
 
+	connectedEditors: Record<string, Editor[]> = {}
+
 	constructor({
 		editorOptions,
 		getTitle,
@@ -104,7 +116,7 @@ export class DocumentApi<
 		getTitle?: (docId: string, blockId?: string) => string
 		getSuggestions: DocumentApiInterface["getSuggestions"]
 		/** Load should create the editor state and return it. It can also optionally return extra data which will be passed to the refCounter's load function. */
-		load: (docId: string, schema: Schema, plugins: Plugin[]) => Promise<{ state: EditorState, data?: T }>
+		load: (docId: string, schema: Schema, plugins: Plugin[], getConnectedEditors: () => Editor[]) => Promise<{ state: EditorState, data?: T }>
 		save?: DocumentApi["_save"]
 		saveDebounce?: number
 		cache: DocumentApi["_cache"]
@@ -236,7 +248,8 @@ export class DocumentApi<
 		const loaded = await this._load(
 			docId,
 			schema,
-			[...this.editor.extensionManager.plugins]
+			[...this.editor.extensionManager.plugins],
+			() => this.connectedEditors[docId] ?? []
 		)
 		let state = loaded.state
 		const tr = state.tr
@@ -282,4 +295,21 @@ export class DocumentApi<
 			return getEmbedJson(nodeWanted) ?? json
 		}
 	}
+
+	connectEditor(docId: string, editor: Editor) {
+		if (!this.connectedEditors[docId]) {
+			this.connectedEditors[docId] = []
+		}
+		this.connectedEditors[docId].push(editor)
+	}
+
+	disconnectEditor(docId: string, editor: Editor) {
+		if (!this.connectedEditors[docId]) {
+			return
+		}
+		const index = this.connectedEditors[docId].indexOf(editor)
+		if (index !== -1) {
+			this.connectedEditors[docId].splice(index, 1)
+		}
+	}
 }

package/src/runtime/pm/features/DocumentApi/composables/useEditorContent.ts

@@ -58,6 +58,7 @@ export function useEditorContent(
 
 				recreate(options => documentApi.preEditorInit?.(id.value!, { ...options }, state))
 				await nextTick(async () => {
+					documentApi.connectEditor(id.value!, editor.value!)
 					editor.value!.on("transaction", onTransaction)
 					documentApi!.addEventListener("update", onUpdateDocument)
 					documentApi.postEditorInit(id.value!, editor.value!)
@@ -69,6 +70,7 @@ export function useEditorContent(
 	function unload(oldId: string): void {
 		if (oldId !== undefined && documentApi) {
 			documentApi.unload({ docId: oldId })
+			documentApi.disconnectEditor(id.value!, editor.value!)
 			if (attached) {
 				documentApi.removeEventListener("update", onUpdateDocument)
 				editor.value?.off("transaction", onTransaction)

package/src/runtime/pm/features/DocumentApi/composables/useTestDocumentApi.ts

@@ -1,24 +1,34 @@
 import { delay } from "@alanscodelog/utils/delay"
 import { keys } from "@alanscodelog/utils/keys"
 import { unreachable } from "@alanscodelog/utils/unreachable"
-import type { EditorOptions } from "@tiptap/core"
+import type { Editor, EditorOptions } from "@tiptap/core"
 import { createDocument, generateJSON } from "@tiptap/core"
 import type { Schema } from "@tiptap/pm/model"
 import type { Plugin } from "@tiptap/pm/state"
 import { EditorState } from "@tiptap/pm/state"
+import { prosemirrorToYDoc } from "@tiptap/y-tiptap"
 import { type Ref, ref, toRaw } from "vue"
+import type * as Y from "yjs"
 
 import { testExtensions } from "../../../testSchema.js"
+import { Collaboration } from "../../Collaboration/Collaboration.js"
+import { createCollaborationPlugins } from "../../Collaboration/createCollaborationPlugins.js"
 import { DocumentApi } from "../DocumentApi.js"
 import type { DocumentApiInterface } from "../types.js"
 
-type Cache = Record<string, { state?: EditorState, count: number }>
+type Cache = Record<string, { state?: EditorState, count: number, yDoc?: Y.Doc }>
 
 /** Creates a simple instance of the DocumentApi for testing purposes. */
 export function useTestDocumentApi(
 	editorOptions: Partial<EditorOptions>,
 	embeds: Record<string, { content: any, title?: string }>,
-	{ loadDelay = 0 }: { loadDelay?: number } = { }
+	{
+		useCollab = false,
+		loadDelay = 0
+	}: {
+		useCollab?: boolean
+		loadDelay?: number
+	} = {}
 ): {
 	cache: Ref<Cache>
 	documentApi: DocumentApiInterface
@@ -51,11 +61,29 @@ export function useTestDocumentApi(
 				cache.value[docId].state = state
 			}
 		},
+		preEditorInit(docId, options: Partial<EditorOptions>) {
+			if (!cache.value[docId]) unreachable()
+			const yDoc = cache.value[docId].yDoc
+			if (useCollab && !yDoc) unreachable()
+			if (!cache.value[docId].state) unreachable()
+
+			const perDoc = ["history"]
+
+			options.content = cache.value[docId].state.doc.toJSON()
+			options.extensions = [
+				...(options.extensions ?? []).filter(ext => !perDoc.includes(ext.name)),
+				...(useCollab
+					? [Collaboration]
+					: [])
+			]
+			return options
+		},
 		load: async (
 			docId: string,
 			schema: Schema,
-			plugins: Plugin[]
-		): Promise<{ state: EditorState }> => {
+			plugins: Plugin[],
+			getConnectedEditors: () => Editor[]
+		): Promise<{ state: EditorState, data?: { yDoc?: Y.Doc } }> => {
 			if (loadDelay) {
 				await delay(loadDelay)
 			}
@@ -64,19 +92,39 @@ export function useTestDocumentApi(
 				throw new Error(`No embed found for docId ${docId} in: ${JSON.stringify(embeds, null, "\t")}`)
 			}
 
+			if (cache.value[docId]?.state) {
+				return { state: toRaw(cache.value[docId].state) as any, data: { yDoc: cache.value[docId].yDoc } }
+			}
+
 			const json = generateJSON(embeds[docId].content as any, testExtensions)
 			const doc = createDocument(json, schema)
+			const yDoc = useCollab ? prosemirrorToYDoc(doc, "prosemirror") : undefined
+
 			const state = EditorState.create({
 				doc,
 				schema,
-				plugins
+				plugins: [
+					...plugins,
+					...(useCollab
+						? createCollaborationPlugins(
+								{
+									document: yDoc,
+									field: "prosemirror",
+									enableContentCheck: true
+								},
+								schema,
+								getConnectedEditors
+							)
+						: [])
+				]
 			})
-			return { state /** , data: {...any additional data} */ }
+
+			return { state, data: { yDoc } } as any
 		},
 		refCounter: {
 			load(docId: string, loaded) {
 				// loaded.data can be accessed here if we need it
-				cache.value[docId] ??= { ...loaded, count: 0 }
+				cache.value[docId] ??= { ...loaded, yDoc: loaded.data!.yDoc, count: 0 }
 				cache.value[docId].count++
 			},
 			unload: (docId: string) => {