@wordpress/core-data 7.37.1-next.v.0 → 7.38.0

package/src/utils/crdt-blocks.ts

@@ -7,16 +7,15 @@ import fastDeepEqual from 'fast-deep-equal/es6/index.js';
 /**
  * WordPress dependencies
  */
-import { RichTextData } from '@wordpress/rich-text';
-import { Y } from '@wordpress/sync';
-
 // @ts-expect-error No exported types.
 import { getBlockTypes } from '@wordpress/blocks';
+import { RichTextData } from '@wordpress/rich-text';
+import { Y, Delta } from '@wordpress/sync';
 
 /**
  * Internal dependencies
  */
-import type { WPBlockSelection } from '../types';
+import { createYMap, type YMapRecord, type YMapWrap } from './crdt-utils';
 
 interface BlockAttributes {
 	[ key: string ]: unknown;
@@ -27,34 +26,33 @@ interface BlockType {
 	attributes?: Record< string, { type?: string } >;
 }
 
+// A block as represented in Gutenberg's data store.
 export interface Block {
 	attributes: BlockAttributes;
 	clientId?: string;
 	innerBlocks: Block[];
-	originalContent?: string; // unserializable
-	validationIssues?: string[]; // unserializable
+	isValid?: boolean;
 	name: string;
+	originalContent?: string;
+	validationIssues?: string[]; // unserializable
 }
 
-export type YBlock = Y.Map<
-	/* name, clientId, and originalContent are strings. */
-	| string
-	/* validationIssues? is an array of strings. */
-	| string[]
-	/* attributes is a Y.Map< unknown >. */
-	| YBlockAttributes
-	/* innerBlocks is a Y.Array< YBlock >. */
-	| YBlocks
->;
+// A block as represented in the CRDT document (Y.Map).
+interface YBlockRecord extends YMapRecord {
+	attributes: YBlockAttributes;
+	clientId: string;
+	innerBlocks: YBlocks;
+	isValid?: boolean;
+	originalContent?: string;
+	name: string;
+}
 
+export type YBlock = YMapWrap< YBlockRecord >;
 export type YBlocks = Y.Array< YBlock >;
-export type YBlockAttributes = Y.Map< Y.Text | unknown >;
 
-// The Y.Map type is not easy to work with. The generic type it accepts represents
-// the possible values of the map, which are varied in our case. This type is
-// accurate, but will require aggressive type narrowing when the map values are
-// accessed -- or type casting with `as`.
-// export type YBlock = Y.Map< Block[ keyof Block ] >;
+// Block attribute schema cannot be known at compile time, so we use Y.Map.
+// Attribute values will be typed as the union of `Y.Text` and `unknown`.
+export type YBlockAttributes = Y.Map< Y.Text | unknown >;
 
 const serializableBlocksCache = new WeakMap< WeakKey, Block[] >();
 
@@ -70,13 +68,10 @@ function makeBlockAttributesSerializable(
 	return newAttributes;
 }
 
-function makeBlocksSerializable( blocks: Block[] | YBlocks ): Block[] {
-	return blocks.map( ( block: Block | YBlock ) => {
-		const blockAsJson = block instanceof Y.Map ? block.toJSON() : block;
-		const { name, innerBlocks, attributes, ...rest } = blockAsJson;
+function makeBlocksSerializable( blocks: Block[] ): Block[] {
+	return blocks.map( ( block: Block ) => {
+		const { name, innerBlocks, attributes, ...rest } = block;
 		delete rest.validationIssues;
-		delete rest.originalContent;
-		// delete rest.isValid
 		return {
 			...rest,
 			name,
@@ -104,10 +99,10 @@ function areBlocksEqual( gblock: Block, yblock: YBlock ): boolean {
 		Object.assign( {}, yblockAsJson, overwrites )
 	);
 	const inners = gblock.innerBlocks || [];
-	const yinners = yblock.get( 'innerBlocks' ) as YBlocks;
+	const yinners = yblock.get( 'innerBlocks' );
 	return (
 		res &&
-		inners.length === yinners.length &&
+		inners.length === yinners?.length &&
 		inners.every( ( block: Block, i: number ) =>
 			areBlocksEqual( block, yinners.get( i ) )
 		)
@@ -149,35 +144,40 @@ function createNewYAttributeValue(
 }
 
 function createNewYBlock( block: Block ): YBlock {
-	return new Y.Map(
-		Object.entries( block ).map( ( [ key, value ] ) => {
-			switch ( key ) {
-				case 'attributes': {
-					return [ key, createNewYAttributeMap( block.name, value ) ];
-				}
+	return createYMap< YBlockRecord >(
+		Object.fromEntries(
+			Object.entries( block ).map( ( [ key, value ] ) => {
+				switch ( key ) {
+					case 'attributes': {
+						return [
+							key,
+							createNewYAttributeMap( block.name, value ),
+						];
+					}
 
-				case 'innerBlocks': {
-					const innerBlocks = new Y.Array();
+					case 'innerBlocks': {
+						const innerBlocks = new Y.Array();
+
+						// If not an array, set to empty Y.Array.
+						if ( ! Array.isArray( value ) ) {
+							return [ key, innerBlocks ];
+						}
+
+						innerBlocks.insert(
+							0,
+							value.map( ( innerBlock: Block ) =>
+								createNewYBlock( innerBlock )
+							)
+						);
 
-					// If not an array, set to empty Y.Array.
-					if ( ! Array.isArray( value ) ) {
 						return [ key, innerBlocks ];
 					}
 
-					innerBlocks.insert(
-						0,
-						value.map( ( innerBlock: Block ) =>
-							createNewYBlock( innerBlock )
-						)
-					);
-
-					return [ key, innerBlocks ];
+					default:
+						return [ key, value ];
 				}
-
-				default:
-					return [ key, value ];
-			}
-		} )
+			} )
+		)
 	);
 }
 
@@ -186,13 +186,13 @@ function createNewYBlock( block: Block ): YBlock {
  * This function is called to sync local block changes to a shared Y.Doc.
  *
  * @param yblocks        The blocks in the local Y.Doc.
- * @param incomingBlocks Gutenberg blocks being synced, either from a peer or from the local editor.
- * @param lastSelection  The last cursor position, used for hinting the diff algorithm.
+ * @param incomingBlocks Gutenberg blocks being synced.
+ * @param cursorPosition The position of the cursor after the change occurs.
  */
 export function mergeCrdtBlocks(
 	yblocks: YBlocks,
 	incomingBlocks: Block[],
-	lastSelection: WPBlockSelection | null
+	cursorPosition: number | null
 ): void {
 	// Ensure we are working with serializable block data.
 	if ( ! serializableBlocksCache.has( incomingBlocks ) ) {
@@ -269,9 +269,7 @@ export function mergeCrdtBlocks(
 		Object.entries( block ).forEach( ( [ key, value ] ) => {
 			switch ( key ) {
 				case 'attributes': {
-					const currentAttributes = yblock.get(
-						key
-					) as YBlockAttributes;
+					const currentAttributes = yblock.get( key );
 
 					// If attributes are not set on the yblock, use the new values.
 					if ( ! currentAttributes ) {
@@ -293,6 +291,8 @@ export function mergeCrdtBlocks(
 								return;
 							}
 
+							const currentAttribute =
+								currentAttributes.get( attributeName );
 							const isRichText = isRichTextAttribute(
 								block.name,
 								attributeName
@@ -302,18 +302,14 @@ export function mergeCrdtBlocks(
 								isRichText &&
 								'string' === typeof attributeValue &&
 								currentAttributes.has( attributeName ) &&
-								currentAttributes.get(
-									attributeName
-								) instanceof Y.Text
+								currentAttribute instanceof Y.Text
 							) {
 								// Rich text values are stored as persistent Y.Text instances.
 								// Update the value with a delta in place.
 								mergeRichTextUpdate(
-									currentAttributes.get(
-										attributeName
-									) as Y.Text,
+									currentAttribute,
 									attributeValue,
-									lastSelection
+									cursorPosition
 								);
 							} else {
 								currentAttributes.set(
@@ -342,8 +338,18 @@ export function mergeCrdtBlocks(
 
 				case 'innerBlocks': {
 					// Recursively merge innerBlocks
-					const yInnerBlocks = yblock.get( key ) as Y.Array< YBlock >;
-					mergeCrdtBlocks( yInnerBlocks, value ?? [], lastSelection );
+					let yInnerBlocks = yblock.get( key );
+
+					if ( ! ( yInnerBlocks instanceof Y.Array ) ) {
+						yInnerBlocks = new Y.Array< YBlock >();
+						yblock.set( key, yInnerBlocks );
+					}
+
+					mergeCrdtBlocks(
+						yInnerBlocks,
+						value ?? [],
+						cursorPosition
+					);
 					break;
 				}
 
@@ -375,7 +381,11 @@ export function mergeCrdtBlocks(
 	for ( let j = 0; j < yblocks.length; j++ ) {
 		const yblock: YBlock = yblocks.get( j );
 
-		let clientId: string = yblock.get( 'clientId' ) as string;
+		let clientId = yblock.get( 'clientId' );
+
+		if ( ! clientId ) {
+			continue;
+		}
 
 		if ( knownClientIds.has( clientId ) ) {
 			clientId = uuidv4();
@@ -452,22 +462,21 @@ function isRichTextAttribute(
 	);
 }
 
+let localDoc: Y.Doc;
+
 /**
  * Given a Y.Text object and an updated string value, diff the new value and
  * apply the delta to the Y.Text.
  *
- * @param blockYText    The Y.Text to update.
- * @param updatedValue  The updated value.
- * @param lastSelection The last cursor position before this update, used to hint the diff algorithm.
+ * @param blockYText     The Y.Text to update.
+ * @param updatedValue   The updated value.
+ * @param cursorPosition The position of the cursor after the change occurs.
  */
 function mergeRichTextUpdate(
 	blockYText: Y.Text,
 	updatedValue: string,
-	// eslint-disable-next-line @typescript-eslint/no-unused-vars
-	lastSelection: WPBlockSelection | null
+	cursorPosition: number | null
 ): void {
-	// TODO
-	// ====
 	// Gutenberg does not use Yjs shared types natively, so we can only subscribe
 	// to changes from store and apply them to Yjs types that we create and
 	// manage. Crucially, for rich-text attributes, we do not receive granular
@@ -475,31 +484,24 @@ function mergeRichTextUpdate(
 	// only a single character changed.
 	//
 	// The code below allows us to compute a delta between the current and new
-	// value, then apply it to the Y.Text. However, it relies on a library
-	// (quill-delta) with a licensing issue that we are working to resolve.
-	//
-	// For now, we simply replace the full text content on each change.
-	//
-	// if ( ! localDoc ) {
-	// 	// Y.Text must be attached to a Y.Doc to be able to do operations on it.
-	// 	// Create a temporary Y.Text attached to a local Y.Doc for delta computation.
-	// 	localDoc = new Y.Doc();
-	// }
-
-	// const localYText = localDoc.getText( 'temporary-text' );
-	// localYText.delete( 0, localYText.length );
-	// localYText.insert( 0, updatedValue );
+	// value, then apply it to the Y.Text.
 
-	// const currentValueAsDelta = new Delta( blockYText.toDelta() );
-	// const updatedValueAsDelta = new Delta( localYText.toDelta() );
+	if ( ! localDoc ) {
+		// Y.Text must be attached to a Y.Doc to be able to do operations on it.
+		// Create a temporary Y.Text attached to a local Y.Doc for delta computation.
+		localDoc = new Y.Doc();
+	}
 
-	// const deltaDiff = currentValueAsDelta.diff(
-	// 	updatedValueAsDelta,
-	// 	lastSelection?.offset
-	// );
+	const localYText = localDoc.getText( 'temporary-text' );
+	localYText.delete( 0, localYText.length );
+	localYText.insert( 0, updatedValue );
 
-	// blockYText.applyDelta( deltaDiff.ops );
+	const currentValueAsDelta = new Delta( blockYText.toDelta() );
+	const updatedValueAsDelta = new Delta( localYText.toDelta() );
+	const deltaDiff = currentValueAsDelta.diffWithCursor(
+		updatedValueAsDelta,
+		cursorPosition
+	);
 
-	blockYText.delete( 0, blockYText.toString().length );
-	blockYText.insert( 0, updatedValue );
+	blockYText.applyDelta( deltaDiff.ops );
 }

package/src/utils/crdt-utils.ts

@@ -0,0 +1,77 @@
+/**
+ * WordPress dependencies
+ */
+import { Y } from '@wordpress/sync';
+
+/**
+ * A YMapRecord represents the shape of the data stored in a Y.Map.
+ */
+export type YMapRecord = Record< string, unknown >;
+
+/**
+ * A wrapper around Y.Map to provide type safety. The generic type accepted by
+ * Y.Map represents the union of possible values of the map, which are varied in
+ * many cases. This type is accurate, but its non-specificity requires aggressive
+ * type narrowing or type casting / destruction with `as`.
+ *
+ * This type provides type enhancements so that the correct value type can be
+ * inferred based on the provided key. It is just a type wrap / overlay, and
+ * does not change the runtime behavior of Y.Map.
+ *
+ * This interface cannot extend Y.Map directly due to the limitations of
+ * TypeScript's structural typing. One negative consequence of this is that
+ * `instanceof` checks against Y.Map continue to work at runtime but will blur
+ * the type at compile time. To navigate this, use the `isYMap` function below.
+ */
+export interface YMapWrap< T extends YMapRecord > extends Y.AbstractType< T > {
+	delete: < K extends keyof T >( key: K ) => void;
+	forEach: (
+		callback: (
+			value: T[ keyof T ],
+			key: keyof T,
+			map: YMapWrap< T >
+		) => void
+	) => void;
+	has: < K extends keyof T >( key: K ) => boolean;
+	get: < K extends keyof T >( key: K ) => T[ K ] | undefined;
+	set: < K extends keyof T >( key: K, value: T[ K ] ) => void;
+	toJSON: () => T;
+	// add types for other Y.Map methods as needed
+}
+
+/**
+ * Get or create a root-level Map for the given Y.Doc. Use this instead of
+ * doc.getMap() for additional type safety.
+ *
+ * @param doc Y.Doc
+ * @param key Map key
+ */
+export function getRootMap< T extends YMapRecord >(
+	doc: Y.Doc,
+	key: string
+): YMapWrap< T > {
+	return doc.getMap< T >( key ) as unknown as YMapWrap< T >;
+}
+
+/**
+ * Create a new Y.Map (provided with YMapWrap type), optionally initialized with
+ * data. Use this instead of `new Y.Map()` for additional type safety.
+ *
+ * @param partial Partial data to initialize the map with.
+ */
+export function createYMap< T extends YMapRecord >(
+	partial: Partial< T > = {}
+): YMapWrap< T > {
+	return new Y.Map( Object.entries( partial ) ) as unknown as YMapWrap< T >;
+}
+
+/**
+ * Type guard to check if a value is a Y.Map without losing type information.
+ *
+ * @param value Value to check.
+ */
+export function isYMap< T extends YMapRecord >(
+	value: YMapWrap< T > | undefined
+): value is YMapWrap< T > {
+	return value instanceof Y.Map;
+}

package/src/utils/crdt.ts

@@ -26,8 +26,16 @@ import {
 	CRDT_RECORD_MAP_KEY,
 	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
 } from '../sync';
-import type { WPBlockSelection, WPSelection } from '../types';
-
+import type { WPSelection } from '../types';
+import {
+	createYMap,
+	getRootMap,
+	isYMap,
+	type YMapRecord,
+	type YMapWrap,
+} from './crdt-utils';
+
+// Changes that can be applied to a post entity record.
 export type PostChanges = Partial< Post > & {
 	blocks?: Block[];
 	excerpt?: Post[ 'excerpt' ] | string;
@@ -35,8 +43,24 @@ export type PostChanges = Partial< Post > & {
 	title?: Post[ 'title' ] | string;
 };
 
-// Hold a reference to the last known selection to help compute Y.Text deltas.
-let lastSelection: WPBlockSelection | null = null;
+// A post record as represented in the CRDT document (Y.Map).
+export interface YPostRecord extends YMapRecord {
+	author: number;
+	blocks: YBlocks;
+	comment_status: string;
+	date: string | null;
+	excerpt: string;
+	featured_media: number;
+	format: string;
+	meta: YMapWrap< YMapRecord >;
+	ping_status: string;
+	slug: string;
+	status: string;
+	sticky: boolean;
+	tags: number[];
+	template: string;
+	title: string;
+}
 
 // Properties that are allowed to be synced for a post.
 const allowedPostProperties = new Set< string >( [
@@ -47,8 +71,8 @@ const allowedPostProperties = new Set< string >( [
 	'excerpt',
 	'featured_media',
 	'format',
-	'ping_status',
 	'meta',
+	'ping_status',
 	'slug',
 	'status',
 	'sticky',
@@ -74,7 +98,7 @@ export function defaultApplyChangesToCRDTDoc(
 	ydoc: CRDTDoc,
 	changes: ObjectData
 ): void {
-	const ymap = ydoc.getMap( CRDT_RECORD_MAP_KEY );
+	const ymap = getRootMap( ydoc, CRDT_RECORD_MAP_KEY );
 
 	Object.entries( changes ).forEach( ( [ key, newValue ] ) => {
 		// Cannot serialize function values, so cannot sync them.
@@ -82,17 +106,12 @@ export function defaultApplyChangesToCRDTDoc(
 			return;
 		}
 
-		// Set the value in the root document.
-		function setValue< T = unknown >( updatedValue: T ): void {
-			ymap.set( key, updatedValue );
-		}
-
 		switch ( key ) {
 			// Add support for additional data types here.
 
 			default: {
 				const currentValue = ymap.get( key );
-				mergeValue( currentValue, newValue, setValue );
+				updateMapValue( ymap, key, currentValue, newValue );
 			}
 		}
 	} );
@@ -112,60 +131,60 @@ export function applyPostChangesToCRDTDoc(
 	changes: PostChanges,
 	_postType: Type // eslint-disable-line @typescript-eslint/no-unused-vars
 ): void {
-	const ymap = ydoc.getMap( CRDT_RECORD_MAP_KEY );
+	const ymap = getRootMap< YPostRecord >( ydoc, CRDT_RECORD_MAP_KEY );
 
-	Object.entries( changes ).forEach( ( [ key, newValue ] ) => {
+	Object.keys( changes ).forEach( ( key ) => {
 		if ( ! allowedPostProperties.has( key ) ) {
 			return;
 		}
 
+		const newValue = changes[ key ];
+
 		// Cannot serialize function values, so cannot sync them.
 		if ( 'function' === typeof newValue ) {
 			return;
 		}
 
-		// Set the value in the root document.
-		function setValue< T = unknown >( updatedValue: T ): void {
-			ymap.set( key, updatedValue );
-		}
-
 		switch ( key ) {
 			case 'blocks': {
-				let currentBlocks = ymap.get( 'blocks' ) as YBlocks;
+				let currentBlocks = ymap.get( key );
 
 				// Initialize.
 				if ( ! ( currentBlocks instanceof Y.Array ) ) {
 					currentBlocks = new Y.Array< YBlock >();
-					setValue( currentBlocks );
+					ymap.set( key, currentBlocks );
 				}
 
 				// Block[] from local changes.
 				const newBlocks = ( newValue as PostChanges[ 'blocks' ] ) ?? [];
 
+				// Block changes from typing are bundled with a 'selection' update.
+				// Pass the resulting cursor position to the mergeCrdtBlocks function.
+				const cursorPosition =
+					changes.selection?.selectionStart?.offset ?? null;
+
 				// Merge blocks does not need `setValue` because it is operating on a
 				// Yjs type that is already in the Y.Doc.
-				mergeCrdtBlocks( currentBlocks, newBlocks, lastSelection );
+				mergeCrdtBlocks( currentBlocks, newBlocks, cursorPosition );
 				break;
 			}
 
 			case 'excerpt': {
-				const currentValue = ymap.get( 'excerpt' ) as
-					| string
-					| undefined;
+				const currentValue = ymap.get( 'excerpt' );
 				const rawNewValue = getRawValue( newValue );
 
-				mergeValue( currentValue, rawNewValue, setValue );
+				updateMapValue( ymap, key, currentValue, rawNewValue );
 				break;
 			}
 
 			// "Meta" is overloaded term; here, it refers to post meta.
 			case 'meta': {
-				let metaMap = ymap.get( 'meta' ) as Y.Map< unknown >;
+				let metaMap = ymap.get( 'meta' );
 
 				// Initialize.
-				if ( ! ( metaMap instanceof Y.Map ) ) {
-					metaMap = new Y.Map();
-					setValue( metaMap );
+				if ( ! isYMap( metaMap ) ) {
+					metaMap = createYMap< YMapRecord >();
+					ymap.set( 'meta', metaMap );
 				}
 
 				// Iterate over each meta property in the new value and merge it if it
@@ -176,12 +195,11 @@ export function applyPostChangesToCRDTDoc(
 							return;
 						}
 
-						mergeValue(
+						updateMapValue(
+							metaMap,
+							metaKey,
 							metaMap.get( metaKey ), // current value in CRDT
-							metaValue, // new value from changes
-							( updatedMetaValue: unknown ): void => {
-								metaMap.set( metaKey, updatedMetaValue );
-							}
+							metaValue // new value from changes
 						);
 					}
 				);
@@ -195,13 +213,13 @@ export function applyPostChangesToCRDTDoc(
 					break;
 				}
 
-				const currentValue = ymap.get( 'slug' ) as string;
-				mergeValue( currentValue, newValue, setValue );
+				const currentValue = ymap.get( key );
+				updateMapValue( ymap, key, currentValue, newValue );
 				break;
 			}
 
 			case 'title': {
-				const currentValue = ymap.get( 'title' ) as string | undefined;
+				const currentValue = ymap.get( key );
 
 				// Copy logic from prePersistPostType to ensure that the "Auto
 				// Draft" template title is not synced.
@@ -210,27 +228,22 @@ export function applyPostChangesToCRDTDoc(
 					rawNewValue = '';
 				}
 
-				mergeValue( currentValue, rawNewValue, setValue );
+				updateMapValue( ymap, key, currentValue, rawNewValue );
 				break;
 			}
 
-			// Add support for additional data types here.
+			// Add support for additional properties here.
 
 			default: {
 				const currentValue = ymap.get( key );
-				mergeValue( currentValue, newValue, setValue );
+				updateMapValue( ymap, key, currentValue, newValue );
 			}
 		}
 	} );
-
-	// Update the lastSelection for use in computing Y.Text deltas.
-	if ( 'selection' in changes ) {
-		lastSelection = changes.selection?.selectionStart ?? null;
-	}
 }
 
 export function defaultGetChangesFromCRDTDoc( crdtDoc: CRDTDoc ): ObjectData {
-	return crdtDoc.getMap( CRDT_RECORD_MAP_KEY ).toJSON();
+	return getRootMap( crdtDoc, CRDT_RECORD_MAP_KEY ).toJSON();
 }
 
 /**
@@ -248,7 +261,7 @@ export function getPostChangesFromCRDTDoc(
 	editedRecord: Post,
 	_postType: Type // eslint-disable-line @typescript-eslint/no-unused-vars
 ): PostChanges {
-	const ymap = ydoc.getMap( CRDT_RECORD_MAP_KEY );
+	const ymap = getRootMap< YPostRecord >( ydoc, CRDT_RECORD_MAP_KEY );
 
 	let allowedMetaChanges: Post[ 'meta' ] = {};
 
@@ -394,19 +407,25 @@ function getRawValue( value?: unknown ): string | undefined {
 	return undefined;
 }
 
-function haveValuesChanged< ValueType = any >(
-	currentValue: ValueType,
-	newValue: ValueType
+function haveValuesChanged< ValueType >(
+	currentValue: ValueType | undefined,
+	newValue: ValueType | undefined
 ): boolean {
 	return ! fastDeepEqual( currentValue, newValue );
 }
 
-function mergeValue< ValueType = any >(
-	currentValue: ValueType,
-	newValue: ValueType,
-	setValue: ( value: ValueType ) => void
+function updateMapValue< T extends YMapRecord, K extends keyof T >(
+	map: YMapWrap< T >,
+	key: K,
+	currentValue: T[ K ] | undefined,
+	newValue: T[ K ] | undefined
 ): void {
-	if ( haveValuesChanged< ValueType >( currentValue, newValue ) ) {
-		setValue( newValue );
+	if ( undefined === newValue ) {
+		map.delete( key );
+		return;
+	}
+
+	if ( haveValuesChanged< T[ K ] >( currentValue, newValue ) ) {
+		map.set( key, newValue );
 	}
 }