@witchcraft/editor 0.1.0 → 0.2.0

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

@@ -33,16 +33,33 @@ export type DocumentApiInterface<
 	getFromCache: (docId: DocId, options?: { errorIfNotFound?: boolean }) => EditorState | undefined
 	/** Load should be called the first time, before attempting to load the state. */
 	getFullState: (docId: DocId) => EditorState
-	/** Like {@link DocumentApi.preEditorInit}, but after initializing and loading the document (and before the transaction listeners are added). */
+	/**
+	 * For replacing {@link DocumentApi.preEditorInit} which runs after initializing and loading the document but before the transaction listeners are added.
+	 *
+	 * Can be used to add the Collaboration extension for example (see useTestDocumentApi for an example).
+	 *
+	 * The default implementation just sets the content:
+	 *
+	 * ```ts
+	 * preEditorInit: (_docId, options, state) => {
+	 *		options.content = state.doc.toJSON()
+	 *		return options
+	 *	}
+	 * ```
+	 *
+	 */
 	postEditorInit: (docId: string, editor: Editor) => void
+	connectedEditors: Record<string, Editor[]>
+	connectEditor: (docId: string, editor: Editor) => void
+	disconnectEditor: (docId: string, editor: Editor) => void
 	/**
-	 * Sets options before initializing the editor. By default just does `options.content = state.doc.toJSON()`, but can be useful when managing the document state in some other way (e.g. collab.
+	 * Sets options before initializing the editor. By default just does `options.content = state.doc.toJSON()`, but can be useful for using **per editor component** plugins.
 	 *
-	 * Also useful for creating per-doc instances for certain extensions, such as Collaboration.
+	 * This is normally a bit tricky to do since the editor component initializes the editor before the document is loaded and is re-used (the wrapper Editor *component*, not the editor) when the document changes.
 	 *
-	 * This is a bit tricky to do normally since the editor component initializes the editor before the document is loaded and is re-used (the wrapper Editor *component*, not the editor) when the document changes.
+	 * So this hook can be used to add these additional per-editor instances of extensions. Be sure to clone the properties you are modifying. They are only shallow cloned before being passed to the function.
 	 *
-	 * So this hook can be used to add these additional per-doc instances of extensions. Be sure to clone the properties you are modifying. They are only shallow cloned before being passed to the function.
+	 * If you need **per doc** plugins use `load` instead. See {@link useTestDocumentApi} for an example.
 	 *
 	 * ```ts
 	 * preEditorInit(docId, options: Partial<EditorOptions>, state: EditorState) {
@@ -51,58 +68,19 @@ export type DocumentApiInterface<
 	 * 	const ydoc = cache.value[docId].ydoc
 	 * 	// it's suggested you add the collab extension only here
 	 *		// otherwise you would have to initially configure it with a dummy document
-	 * 	const collabExt = Collaboration.configure({
-	 * 		document: ydoc
-	 * 	}) as any
 	 * 	options.extensions = [
 	 * 		...(options.extensions ?? []),
-	 * 		collabExt
+	 *			// per editor extensions
 	 * 	]
 	 * 	return options
 	 * },
-	 * load: async (
-	 * 	docId: string,
-	 * 	schema: Schema,
-	 * 	plugins: Plugin[],
-	 * ) => {
-	 * 	if (cache.value[docId]?.state) {
-	 * 		return { state: toRaw(cache.value[docId].state) }
-	 * 	}
-	 * 	const doc = getFromYourDb(docId)
-	 * 	const decoded = toUint8Array(doc.contentBinary)
-	 * 	const yDoc = new Y.Doc()
-	 * 	Y.applyUpdate(yDoc, decoded)
-	 *
-	 * 	const yjs = initProseMirrorDoc(yDoc.getXmlFragment("prosemirror"), schema)
-	 * 	const state = EditorState.create({
-	 * 		doc: yjs.doc,
-	 * 		schema,
-	 * 		plugins:[
-	 * 			...plugins,
-	 * 			// the document api's yjs instance
-	 * 			ySyncPlugin(yDoc.getXmlFragment("prosemirror"), {mapping:yjs.mapping}),
-	 * 		]
-	 * 	})
-	 * 	// return the state and any additional data we want refCounter.load to be called with.
-	 * 	return { state, doc, yDoc }
-	 * },
-	 * updateFilter(tr:Transaction) {
-	 * 	const meta = tr.getMeta(ySyncPluginKey)
-	 * 	if (meta) return false
-	 * 	return true
-	 * },
 	 * ```
-	 * See {@link DocumentApi.updateFilter} for why yjs (and other syncronization mechanisms) might need to ignore transactions.
 	 */
 	preEditorInit: (docId: string, options: Partial<EditorOptions>, state: EditorState) => Partial<EditorOptions>
 	/**
-	 * Return false to ignore the transaction.
-	 *
-	 * This is useful when using a secondary syncronization mechanism, such as yjs.
-	 *
-	 * If you load all editors of a file with yjs's plugin and point to the same ydoc, yjs's plugin will sync them. But that means that when the DocumentApi tries to sync the transactions they will have already been applied and the document update will fail.
+	 * Return false to prevent applying the transaction to the state in the cache.
 	 *
-	 * So we have to ignore all of yjs's transactions, but NOT transactions from partially embedded docs => full state, as these do not pass through yjs.
+	 * This used to be needed to ignore yjs transactions, but that's no longer the case. Even with multiple editors loaded to use the same ydoc, everything should work. Leaving the option in case it's needed for some other rare use case.
 	 */
 	updateFilter?: (tr: Transaction) => boolean | undefined
 	updateDocument: (
@@ -110,10 +88,10 @@ export type DocumentApiInterface<
 		tr: Transaction,
 		selfSymbol?: symbol
 	) => void
-	addEventListener (type: "saving" | "saved", cb: OnSaveDocumentCallback): void
-	addEventListener (type: "update", cb: OnUpdateDocumentCallback): void
-	removeEventListener (type: "saving" | "saved", cb: OnSaveDocumentCallback): void
-	removeEventListener (type: "update", cb: OnUpdateDocumentCallback): void
+	addEventListener(type: "saving" | "saved", cb: OnSaveDocumentCallback): void
+	addEventListener(type: "update", cb: OnUpdateDocumentCallback): void
+	removeEventListener(type: "saving" | "saved", cb: OnSaveDocumentCallback): void
+	removeEventListener(type: "update", cb: OnUpdateDocumentCallback): void
 
 	/** For the embedded document picker, should return suggestions for the search string. */
 	getSuggestions: (searchString: string) => Promise<{ title: string, docId: string }[]>
@@ -123,7 +101,7 @@ export type DocumentApiInterface<
 	 * Tells the document api how to load an unloaded document and any additional data. Whatever this function returns will be passed to the refCounter.load option in the default DocumentApi implementation.
 	 *
 	 * ```ts
-	 *	 load: async ( docId: string, schema: Schema, plugins: Plugin[],) => {
+	 *	 load: async ( docId: string, schema: Schema, plugins: Plugin[], getConnectedEditors: () => Editor[]) => {
 	 * 	const dbDoc = getFromYourDb(docId)
 	 *
 	 * 	const state = EditorState.create({

package/dist/runtime/demo/App.d.vue.ts

@@ -1,3 +0,0 @@
-declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
-declare const _default: typeof __VLS_export;
-export default _default;

package/dist/runtime/demo/App.vue

@@ -1,100 +0,0 @@
-<template>
-<WRoot class="items-center py-4">
-	<style>
-		{{ codeBlocksThemeCss.join("\n") }}
-	</style>
-	<DemoControls
-		:code-blocks-theme-list="codeBlocksThemeList"
-		v-model:code-blocks-theme="codeBlocksTheme"
-		@blur="blur"
-	/>
-	<Editor
-		class="max-w-[700px] flex-1 max-h-[700px] flex"
-		v-bind="{
-  codeBlocksThemeIsDark,
-  cssVariables: {
-    pmCodeBlockBgColor: codeBlocksThemeBgColor
-  },
-  docId,
-  documentApi,
-  linkOptions,
-  editorOptions,
-  menus
-}"
-	/>
-	<div class="py-[50px]"/>
-</WRoot>
-</template>
-
-<script setup>
-import WRoot from "@witchcraft/ui/components/LibRoot";
-import { nextTick, reactive, ref, shallowRef } from "vue";
-import Editor from "../components/Editor.vue";
-import DemoControls from "../components/EditorDemoControls.vue";
-import { useHighlightJsTheme } from "../pm/features/CodeBlock/composables/useHighlightJsTheme.js";
-import { defaultCommandBarMenuItems } from "../pm/features/CommandsMenus/commandBarMenuItems";
-import CommandBar from "../pm/features/CommandsMenus/components/CommandBar.vue";
-import { useTestDocumentApi } from "../pm/features/DocumentApi/composables/useTestDocumentApi.js";
-import BubbleMenuLink from "../pm/features/Link/components/BubbleMenuLink.vue";
-import { testExtensions } from "../pm/testSchema.js";
-import { testDocuments } from "../testDocuments";
-const {
-  theme: codeBlocksTheme,
-  knownThemes: codeBlocksThemeList,
-  themeCss: codeBlocksThemeCss,
-  isDark: codeBlocksThemeIsDark,
-  backgroundColor: codeBlocksThemeBgColor
-} = useHighlightJsTheme();
-function blur() {
-  const was = codeBlocksTheme.value;
-  codeBlocksTheme.value = "";
-  nextTick(() => {
-    codeBlocksTheme.value = was;
-  });
-}
-const editorOptions = {
-  extensions: testExtensions
-};
-const linkOptions = {
-  openInternal: (href) => {
-    window.alert(`This would open an internal link to ${href}.`);
-    console.log(`Would open internal link to ${href}.`);
-  }
-};
-const fakeSuggestions = reactive(["some", "suggestions"]);
-const menus = shallowRef({
-  linkMenu: {
-    component: BubbleMenuLink,
-    props: (editor) => ({
-      editor,
-      linkSuggestions: fakeSuggestions,
-      getInternalLinkHref(href) {
-        return `internal://${href.replace(/[^\w-]/g, "")}`;
-      }
-    })
-  },
-  commandBar: {
-    component: CommandBar,
-    props: (editor) => ({
-      editor,
-      commands: defaultCommandBarMenuItems.commands
-    }),
-    popupOptions: {
-      pinToItemDistance: (state) => {
-        const { $from, $to } = state.selection;
-        const fromNode = $from.node(-1);
-        const toNode = $to.node(-1);
-        if (fromNode.type !== toNode.type) {
-          return 0;
-        }
-        return fromNode.type.name.startsWith("table") ? 120 : 0;
-      }
-    }
-  }
-});
-const { documentApi } = useTestDocumentApi(
-  editorOptions,
-  testDocuments
-);
-const docId = ref("root");
-</script>

package/dist/runtime/demo/App.vue.d.ts

@@ -1,3 +0,0 @@
-declare const __VLS_export: import("vue").DefineComponent<{}, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<{}> & Readonly<{}>, {}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
-declare const _default: typeof __VLS_export;
-export default _default;

package/src/runtime/demo/App.vue

@@ -1,113 +0,0 @@
-<template>
-<WRoot class="items-center py-4">
-	<style>
-		{{ codeBlocksThemeCss.join("\n") }}
-	</style>
-	<DemoControls
-		:code-blocks-theme-list="codeBlocksThemeList"
-		v-model:code-blocks-theme="codeBlocksTheme"
-		@blur="blur"
-	/>
-	<Editor
-		class="max-w-[700px] flex-1 max-h-[700px] flex"
-		v-bind="{
-			codeBlocksThemeIsDark,
-			cssVariables: {
-				pmCodeBlockBgColor: codeBlocksThemeBgColor
-			},
-			docId,
-			documentApi,
-			linkOptions,
-			editorOptions,
-			menus
-		}"
-	/>
-	<div class="py-[50px]"/>
-</WRoot>
-</template>
-
-<script setup lang="ts">
-import type { EditorOptions } from "@tiptap/core"
-import WRoot from "@witchcraft/ui/components/LibRoot"
-import { nextTick, reactive, ref, shallowRef } from "vue"
-
-import Editor from "../components/Editor.vue"
-import DemoControls from "../components/EditorDemoControls.vue"
-import { useHighlightJsTheme } from "../pm/features/CodeBlock/composables/useHighlightJsTheme.js"
-import { defaultCommandBarMenuItems } from "../pm/features/CommandsMenus/commandBarMenuItems"
-import CommandBar from "../pm/features/CommandsMenus/components/CommandBar.vue"
-import { useTestDocumentApi } from "../pm/features/DocumentApi/composables/useTestDocumentApi.js"
-import BubbleMenuLink from "../pm/features/Link/components/BubbleMenuLink.vue"
-import type { EditorLinkOptions } from "../pm/features/Link/types.js"
-import type { MenuRenderInfo } from "../pm/features/Menus/types"
-import { testExtensions } from "../pm/testSchema.js"
-import { testDocuments } from "../testDocuments"
-
-const {
-	theme: codeBlocksTheme,
-	knownThemes: codeBlocksThemeList,
-	themeCss: codeBlocksThemeCss,
-	isDark: codeBlocksThemeIsDark,
-	backgroundColor: codeBlocksThemeBgColor
-} = useHighlightJsTheme()
-
-function blur(): void {
-	const was = codeBlocksTheme.value
-	codeBlocksTheme.value = ""
-	nextTick(() => {
-		codeBlocksTheme.value = was
-	})
-}
-
-const editorOptions: Partial<EditorOptions> = {
-	extensions: testExtensions as any
-}
-
-const linkOptions: EditorLinkOptions = {
-	openInternal: href => {
-		window.alert(`This would open an internal link to ${href}.`)
-
-		// eslint-disable-next-line no-console
-		console.log(`Would open internal link to ${href}.`)
-	}
-}
-const fakeSuggestions = reactive<string[]>(["some", "suggestions"])
-
-const menus = shallowRef<Record<string, MenuRenderInfo>>({
-	linkMenu: {
-		component: BubbleMenuLink,
-		props: editor => ({
-			editor,
-			linkSuggestions: fakeSuggestions,
-			getInternalLinkHref(href: string) {
-				return `internal://${href.replace(/[^\w-]/g, "")}`
-			}
-		})
-	},
-	commandBar: {
-		component: CommandBar,
-		props: editor => ({
-			editor,
-			commands: defaultCommandBarMenuItems.commands
-		}),
-		popupOptions: {
-			pinToItemDistance: state => {
-				const { $from, $to } = state.selection
-				const fromNode = $from.node(-1)
-				const toNode = $to.node(-1)
-				// tables don't support selections outside of each cell, so no need to check we're in the same table or anything
-				if (fromNode.type !== toNode.type) {
-					return 0
-				}
-				return (fromNode.type.name.startsWith("table")) ? 120 : 0
-			}
-		}
-	}
-})
-
-const { documentApi } = useTestDocumentApi(
-	editorOptions as any,
-	testDocuments
-)
-const docId = ref("root")
-</script>