@verdant-web/tiptap 0.1.5 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verdant-web/tiptap",
-  "version": "0.1.5",
+  "version": "1.0.0",
   "access": "public",
   "type": "module",
   "main": "dist/esm/index.js",
@@ -26,8 +26,8 @@
     "@tiptap/pm": "^2.11.5",
     "@tiptap/react": "^2.11.5",
     "react": "^19.0.0",
-    "@verdant-web/react": "40.2.4",
-    "@verdant-web/store": "4.1.6"
+    "@verdant-web/react": "41.0.0",
+    "@verdant-web/store": "4.2.0"
   },
   "peerDependenciesMeta": {
     "@verdant-web/react": {
@@ -41,11 +41,11 @@
     }
   },
   "dependencies": {
-    "@verdant-web/common": "2.7.3"
+    "@verdant-web/common": "2.8.0"
   },
   "devDependencies": {
     "typescript": "5.7.3",
-    "vitest": "3.0.6",
+    "vitest": "3.0.8",
     "@tiptap/core": "^2.11.5",
     "@tiptap/pm": "^2.11.5",
     "@tiptap/react": "^2.11.5",
@@ -54,15 +54,15 @@
     "@types/react": "19.0.10",
     "vitest-browser-react": "0.1.1",
     "@vitest/browser": "3.0.6",
-    "playwright": "1.50.1",
+    "playwright": "1.51.0",
     "vite": "6.1.1",
     "@vitejs/plugin-react": "4.3.4",
     "react-dom": "19.0.0",
     "@types/react-dom": "19.0.4",
+    "@verdant-web/react": "41.0.0",
+    "@verdant-web/store": "4.2.0",
     "@verdant-web/cli": "4.8.2",
-    "@verdant-web/store": "4.1.6",
-    "@verdant-web/server": "3.3.8",
-    "@verdant-web/react": "40.2.4"
+    "@verdant-web/server": "3.3.9"
   },
   "scripts": {
     "test": "vitest",

package/src/__browserTests__/react.test.tsx

@@ -193,3 +193,155 @@ it('should support nullable tiptap schema fields with a specified default doc',
 		text: null,
 	});
 });
+
+it('should support Verdant undo and redo', async () => {
+	const testPost = await client.posts.put({});
+
+	// reset history
+	await client.entities.flushAllBatches();
+	client.undoHistory.clear();
+
+	const TipTapTest = () => {
+		const editor = useSyncedEditor(testPost, 'requiredBody', {
+			editorOptions: {
+				extensions: [
+					StarterKit.configure({
+						// using Verdant history.
+						history: false,
+					}),
+				],
+			},
+			// NOTE: this config is not required in regular usage, I'm tweaking batching
+			// to be sure it captures the entire testing change in one batch for undo to
+			// make the test predictable.
+			extensionOptions: {
+				batchConfig: {
+					// capture up to 100 changes in the batch.
+					max: 100,
+					timeout: null,
+					batchName: 'tiptap',
+					undoable: true,
+				},
+			},
+		});
+
+		return (
+			<div>
+				<div>Text editor:</div>
+				<EditorContent
+					style={{
+						width: 500,
+						height: 300,
+					}}
+					editor={editor}
+					id="#editor"
+					data-testid="editor"
+				/>
+			</div>
+		);
+	};
+
+	const screen = await renderWithProvider(<TipTapTest />);
+	await expect.element(screen.getByTestId('editor')).toBeVisible();
+
+	const editor = screen.getByTestId('editor').getByRole('textbox');
+	await expect.element(editor).toHaveTextContent('');
+
+	// send keystrokes to the editor
+	await userEvent.type(editor, 'Hello, world!');
+	await expect.element(editor).toHaveTextContent('Hello, world!');
+
+	await client.entities.flushAllBatches();
+
+	expect(client.undoHistory.undoLength).toBe(1);
+	await client.undoHistory.undo();
+
+	expect(testPost.get('requiredBody').getSnapshot()).toEqual({
+		type: 'doc',
+		attrs: {},
+		from: null,
+		to: null,
+		content: [],
+		marks: [],
+		text: null,
+	});
+});
+
+it('should support TipTap undo and redo', async () => {
+	const testPost = await client.posts.put({});
+
+	// reset history
+	await client.entities.flushAllBatches();
+	client.undoHistory.clear();
+
+	const TipTapTest = () => {
+		const editor = useSyncedEditor(testPost, 'requiredBody', {
+			editorOptions: {
+				extensions: [StarterKit],
+			},
+			extensionOptions: {
+				batchConfig: {
+					undoable: false,
+				},
+			},
+		});
+
+		return (
+			<div>
+				<div>Text editor:</div>
+				<EditorContent
+					style={{
+						width: 500,
+						height: 300,
+					}}
+					editor={editor}
+					id="#editor"
+					data-testid="editor"
+				/>
+				<button data-testid="undo" onClick={() => editor!.commands.undo()}>
+					Undo
+				</button>
+			</div>
+		);
+	};
+
+	const screen = await renderWithProvider(<TipTapTest />);
+	await expect.element(screen.getByTestId('editor')).toBeVisible();
+
+	const editor = screen.getByTestId('editor').getByRole('textbox');
+	await expect.element(editor).toHaveTextContent('');
+
+	// send keystrokes to the editor
+	await userEvent.type(editor, 'Hello, world!');
+	await expect.element(editor).toHaveTextContent('Hello, world!');
+
+	await client.entities.flushAllBatches();
+
+	// Verdant did not capture the change in undo history.
+	expect(client.undoHistory.undoLength).toBe(0);
+
+	await userEvent.click(screen.getByTestId('undo'));
+	await expect.element(editor).toHaveTextContent('');
+
+	// notably, TipTap history doesn't seem to remove the paragraph node,
+	// but to the user this behaves as expected.
+	expect(testPost.get('requiredBody').getSnapshot()).toEqual({
+		type: 'doc',
+		attrs: {},
+		from: null,
+		to: null,
+		content: [
+			{
+				attrs: {},
+				content: [],
+				from: null,
+				marks: [],
+				text: null,
+				to: null,
+				type: 'paragraph',
+			},
+		],
+		marks: [],
+		text: null,
+	});
+});

package/src/fields.ts

@@ -39,17 +39,11 @@ export function createTipTapFieldSchema(options: {
 			'createTiptapFieldSchema requires a default value. Specify "null" to make the field nullable.',
 		);
 	}
+
 	const baseField = schema.fields.object({
 		fields: {},
-		default: () => {
-			if (options.default === null) {
-				return null;
-			}
-			return structuredClone(options.default);
-		},
-		nullable: options.default === null,
 	});
-	return schema.fields.replaceObjectFields(baseField, {
+	const nestedContent = schema.fields.replaceObjectFields(baseField, {
 		type: schema.fields.string(),
 		from: schema.fields.number({ nullable: true }),
 		to: schema.fields.number({ nullable: true }),
@@ -64,4 +58,31 @@ export function createTipTapFieldSchema(options: {
 			items: baseField,
 		}),
 	});
+
+	const rootField = schema.fields.object({
+		fields: {
+			type: schema.fields.string(),
+			from: schema.fields.number({ nullable: true }),
+			to: schema.fields.number({ nullable: true }),
+			attrs: schema.fields.map({
+				values: schema.fields.any(),
+			}),
+			content: schema.fields.array({
+				items: nestedContent,
+			}),
+			text: schema.fields.string({ nullable: true }),
+			marks: schema.fields.array({
+				items: nestedContent,
+			}),
+		},
+		default: () => {
+			if (options.default === null) {
+				return null;
+			}
+			return structuredClone(options.default);
+		},
+		nullable: options.default === null,
+	});
+
+	return rootField as any;
 }

package/src/plugins.ts

@@ -1,6 +1,12 @@
-import { Extension } from '@tiptap/core';
+import { Extension, JSONContent } from '@tiptap/core';
 import { Plugin, PluginKey } from '@tiptap/pm/state';
-import { id } from '@verdant-web/store';
+import { assignOid, cloneDeep, maybeGetOid } from '@verdant-web/common';
+import {
+	AnyEntity,
+	getEntityClient,
+	id,
+	ObjectEntity,
+} from '@verdant-web/store';
 
 const NodeIdPlugin = new Plugin({
 	key: new PluginKey('node-ids'),
@@ -11,13 +17,21 @@ const NodeIdPlugin = new Plugin({
 		// force replacement of any duplicates, too
 		const usedIds = new Set<string>();
 		newState.doc.descendants((node, pos) => {
-			if (!node.isText && (!node.attrs.id || usedIds.has(node.attrs.id))) {
+			if (
+				!node.isText &&
+				(!node.attrs.id || usedIds.has(node.attrs.id)) &&
+				node !== newState.doc
+			) {
 				const nodeId = id();
-				tr.setNodeMarkup(pos, null, {
-					...node.attrs,
-					id: nodeId,
-				});
-				usedIds.add(nodeId);
+				try {
+					tr.setNodeMarkup(pos, null, {
+						...node.attrs,
+						id: nodeId,
+					});
+					usedIds.add(nodeId);
+				} catch (err) {
+					console.error('Error assigning node ID', err);
+				}
 			} else if (node.attrs?.id) {
 				usedIds.add(node.attrs.id);
 			}
@@ -25,50 +39,283 @@ const NodeIdPlugin = new Plugin({
 		return tr;
 	},
 });
+export const NodeIdExtension = Extension.create({
+	name: 'nodeId',
+	addProseMirrorPlugins() {
+		return [NodeIdPlugin];
+	},
+	addOptions() {
+		return {
+			types: [],
+		};
+	},
+	addGlobalAttributes() {
+		return [
+			{
+				types: this.options.types,
+				attributes: {
+					id: {
+						default: null,
+						keepOnSplit: false,
+						parseHTML: (element) => element.getAttribute('data-id'),
+						renderHTML: (attributes) => {
+							if (!attributes.id) return {};
+							return {
+								'data-id': attributes.id,
+							};
+						},
+					},
+				},
+			},
+		];
+	},
+});
 
-const defaultAllNodes = [
-	'blockquote',
-	'bulletList',
-	'codeBlock',
-	'heading',
-	'listItem',
-	'orderedList',
-	'paragraph',
-	'image',
-	'mention',
-	'table',
-	'taskList',
-	'taskItem',
-	'youtube',
-];
-export const NodeIdExtension = (
-	options: {
-		nodeTypes?: string[];
-	} = {},
-) =>
-	Extension.create({
-		name: 'nodeId',
-		addProseMirrorPlugins() {
-			return [NodeIdPlugin];
-		},
-		addGlobalAttributes() {
-			return [
-				{
-					types: options.nodeTypes || defaultAllNodes,
-					attributes: {
-						id: {
-							default: null,
-							keepOnSplit: false,
-							parseHTML: (element) => element.getAttribute('data-id'),
-							renderHTML: (attributes) => {
-								if (!attributes.id) return {};
-								return {
-									'data-id': attributes.id,
-								};
-							},
+export const verdantIdAttribute = 'data-verdant-oid';
+export interface VerdantExtensionOptions {
+	parent: AnyEntity<any, any, any>;
+	fieldName: string | number;
+	nullDocumentDefault?: any;
+	batchConfig?: {
+		undoable?: boolean;
+		batchName?: string;
+		max?: number | null;
+		timeout?: number | null;
+	};
+}
+export const VerdantExtension = Extension.create<
+	VerdantExtensionOptions,
+	{ updating: boolean; unsubscribe: (() => void) | null }
+>({
+	name: 'verdant',
+	addOptions() {
+		return {
+			parent: null as any,
+			fieldName: '',
+			nullDocumentDefault: null,
+			batchConfig: {
+				undoable: true,
+				batchName: 'tiptap',
+				max: null,
+				timeout: 600,
+			},
+		};
+	},
+	addStorage() {
+		return {
+			updating: false,
+			unsubscribe: null,
+		};
+	},
+	addGlobalAttributes() {
+		const nodeTypes = this.extensions
+			.filter((ext) => ext.type === 'node')
+			.filter((ext) => ext.config.group !== 'inline')
+			.map((ext) => ext.name)
+			.filter((s) => s !== null);
+		return [
+			{
+				types: nodeTypes,
+				attributes: {
+					[verdantIdAttribute]: {
+						default: null,
+						keepOnSplit: false,
+						parseHTML: (element) => element.getAttribute(verdantIdAttribute),
+						renderHTML: (attributes) => {
+							if (!attributes[verdantIdAttribute]) return {};
+							return {
+								[verdantIdAttribute]: attributes[verdantIdAttribute],
+							};
 						},
 					},
 				},
-			];
-		},
+			},
+		];
+	},
+	onBeforeCreate() {
+		const { parent, fieldName, nullDocumentDefault } = this.options;
+		// validate options
+		if (!parent) {
+			throw new Error('VerdantOidExtension requires a parent entity');
+		}
+		if (!fieldName) {
+			throw new Error('VerdantOidExtension requires a field name');
+		}
+		const fieldSchema = parent.getFieldSchema(fieldName);
+		if (!fieldSchema) {
+			throw new Error(
+				`VerdantOidExtension error: ${fieldName} is not a valid field of the parent entity`,
+			);
+		}
+		if (fieldSchema.type !== 'object') {
+			throw new Error(
+				`VerdantOidExtension requires an object field for the document, ${fieldName} is a ${fieldSchema.type}`,
+			);
+		}
+		if (fieldSchema.nullable && !fieldSchema.default && !nullDocumentDefault) {
+			throw new Error(
+				'VerdantOidExtension requires a nullDocumentDefault for a nullable document field',
+			);
+		}
+
+		// subscribe to field changes
+		let unsubscribe: (() => void) | null = null;
+		const updateFromField = (field: ObjectEntity<any, any> | null) => {
+			if (this.editor && !this.editor.isDestroyed) {
+				this.storage.updating = true;
+				const { from, to } = this.editor.state.selection;
+				this.editor.commands.setContent(
+					ensureDocShape(
+						getFieldSnapshot(field, nullDocumentDefault, fieldName),
+					),
+					false,
+				);
+				this.editor.commands.setTextSelection({ from, to });
+				this.storage.updating = false;
+			}
+		};
+		const subscribeToDocumentChanges = () => {
+			const field = parent.get(fieldName) as ObjectEntity<any, any> | null;
+			if (field) {
+				unsubscribe = field.subscribe('changeDeep', (target, info) => {
+					if (!info.isLocal || target === field) {
+						updateFromField(field);
+					}
+				});
+				updateFromField(field);
+			}
+		};
+		this.storage.unsubscribe = parent.subscribe('change', (info) => {
+			unsubscribe?.();
+			subscribeToDocumentChanges();
+		});
+		subscribeToDocumentChanges();
+	},
+	onUpdate() {
+		// this flag is set synchronously while applying changes from the entity
+		// to the editor. if it's true, we don't want to apply changes from the editor
+		// back to the entity again, making an infinite cycle.
+		if (this.storage.updating) {
+			return;
+		}
+
+		const newData = this.editor.getJSON();
+		const value = this.options.parent.get(
+			this.options.fieldName,
+		) as ObjectEntity<any, any> | null;
+		if (!value) {
+			this.options.parent.set(this.options.fieldName as any, newData);
+		} else {
+			// re-assign oids to data objects so they can be diffed more effectively
+			// against existing data
+			consumeOidsAndAssignToSnapshots(newData);
+			// printAllOids(newData);
+			const client = getEntityClient(value);
+			client.batch(this.options.batchConfig).run(() => {
+				value.update(newData, {
+					merge: false,
+					dangerouslyDisableMerge: true,
+					replaceSubObjects: false,
+				});
+			});
+		}
+	},
+	onDestroy() {
+		this.storage.unsubscribe?.();
+	},
+});
+
+export type ValidEntityKey<Ent extends AnyEntity<any, any, any>> =
+	Ent extends never
+		? string
+		: Ent extends AnyEntity<any, any, infer Shape>
+			? keyof Shape
+			: never;
+
+export type EntitySnapshot<
+	Ent extends AnyEntity<any, any, any>,
+	Key extends ValidEntityKey<Ent>,
+> =
+	Ent extends AnyEntity<any, any, infer Snap>
+		? Key extends keyof Snap
+			? Snap[Key]
+			: any
+		: never;
+
+export function createVerdantExtension<
+	TEnt extends AnyEntity<any, any, any>,
+	Key extends ValidEntityKey<TEnt>,
+>(
+	parent: TEnt,
+	fieldName: Key,
+	options?: Omit<
+		VerdantExtensionOptions,
+		'parent' | 'fieldName' | 'nullDocumentDefault'
+	> & {
+		nullDocumentDefault?: EntitySnapshot<TEnt, Key>;
+	},
+) {
+	return VerdantExtension.configure({
+		parent,
+		fieldName: fieldName as string | number,
+		...options,
 	});
+}
+
+function consumeOidsAndAssignToSnapshots(doc: JSONContent) {
+	if (doc.attrs?.[verdantIdAttribute] !== undefined) {
+		assignOid(doc, doc.attrs[verdantIdAttribute]);
+		delete doc.attrs[verdantIdAttribute];
+	}
+	if (doc.content) {
+		doc.content.forEach(consumeOidsAndAssignToSnapshots);
+	}
+}
+
+// since the schema doesn't enforce this shape but it's
+// needed for the editor to work, we'll ensure it here
+function ensureDocShape(json: any) {
+	for (const node of json.content ?? []) {
+		// remove undefined nodes
+		node.content = node.content.filter((n: any) => !!n).map(ensureDocShape);
+	}
+	return json;
+}
+
+function getFieldSnapshot(
+	field: ObjectEntity<any, any> | undefined | null,
+	nullDocumentDefault: any,
+	fieldName: string | symbol | number,
+) {
+	const content = field
+		? cloneDeep(field.getSnapshot())
+		: (nullDocumentDefault ?? null);
+	if (content === null) {
+		throw new Error(`The provided field "${String(fieldName)}" is null and a default document was not provided.
+		Please provide a default document or ensure the field is not null when calling useSyncedEditor, or make your
+		field schema non-null and specify a default document there.`);
+	}
+	addOidAttrs(content);
+	return content;
+}
+
+function addOidAttrs(doc: JSONContent) {
+	const oid = maybeGetOid(doc);
+	if (oid) {
+		doc.attrs = doc.attrs ?? {};
+		doc.attrs[verdantIdAttribute] = oid;
+	}
+	if (doc.content) {
+		doc.content.forEach(addOidAttrs);
+	}
+}
+
+function printAllOids(obj: any) {
+	if (obj && typeof obj === 'object') {
+		const oid = maybeGetOid(obj);
+		if (oid) console.log(oid, obj);
+		for (const key in obj) {
+			printAllOids(obj[key]);
+		}
+	}
+}