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

package/src/utils/crdt-user-selections.ts

@@ -0,0 +1,332 @@
+/**
+ * External dependencies
+ */
+import { Y, CRDT_RECORD_MAP_KEY } from '@wordpress/sync';
+
+/**
+ * Internal dependencies
+ */
+import type { YPostRecord } from './crdt';
+import type { YBlock, YBlocks } from './crdt-blocks';
+import { getRootMap } from './crdt-utils';
+import type { WPBlockSelection } from '../types';
+
+/**
+ * The type of selection.
+ */
+export enum SelectionType {
+	None = 'none',
+	Cursor = 'cursor',
+	SelectionInOneBlock = 'selection-in-one-block',
+	SelectionInMultipleBlocks = 'selection-in-multiple-blocks',
+	WholeBlock = 'whole-block',
+}
+
+/**
+ * The position of the cursor.
+ */
+export type CursorPosition = {
+	relativePosition: Y.RelativePosition;
+
+	// Also store the absolute offset index of the cursor from the perspective
+	// of the user who is updating the selection.
+	//
+	// Do not use this value directly, instead use `createAbsolutePositionFromRelativePosition()`
+	// on relativePosition for the most up-to-date positioning.
+	//
+	// This is used because local Y.Text changes (e.g. adding or deleting a character)
+	// can result in the same relative position if it is pinned to an unchanged
+	// character. With both of these values as editor state, a change in perceived
+	// position will always result in a redraw.
+	absoluteOffset: number;
+};
+
+export type SelectionNone = {
+	// The user has not made a selection.
+	type: SelectionType.None;
+};
+
+export type SelectionCursor = {
+	// The user has a cursor position in a block with no text highlighted.
+	type: SelectionType.Cursor;
+	blockId: string;
+	cursorPosition: CursorPosition;
+};
+
+export type SelectionInOneBlock = {
+	// The user has highlighted text in a single block.
+	type: SelectionType.SelectionInOneBlock;
+	blockId: string;
+	cursorStartPosition: CursorPosition;
+	cursorEndPosition: CursorPosition;
+};
+
+export type SelectionInMultipleBlocks = {
+	// The user has highlighted text over multiple blocks.
+	type: SelectionType.SelectionInMultipleBlocks;
+	blockStartId: string;
+	blockEndId: string;
+	cursorStartPosition: CursorPosition;
+	cursorEndPosition: CursorPosition;
+};
+
+export type SelectionWholeBlock = {
+	// The user has a non-text block selected, like an image block.
+	type: SelectionType.WholeBlock;
+	blockId: string;
+};
+
+export type SelectionState =
+	| SelectionNone
+	| SelectionCursor
+	| SelectionInOneBlock
+	| SelectionInMultipleBlocks
+	| SelectionWholeBlock;
+
+/**
+ * Converts WordPress block editor selection to a SelectionState.
+ *
+ * @param selectionStart - The start position of the selection
+ * @param selectionEnd   - The end position of the selection
+ * @param yDoc           - The Yjs document
+ * @return The SelectionState
+ */
+export function getSelectionState(
+	selectionStart: WPBlockSelection,
+	selectionEnd: WPBlockSelection,
+	yDoc: Y.Doc
+): SelectionState {
+	const ymap = getRootMap< YPostRecord >( yDoc, CRDT_RECORD_MAP_KEY );
+	const yBlocks = ymap.get( 'blocks' ) ?? new Y.Array< YBlock >();
+
+	const isSelectionEmpty = Object.keys( selectionStart ).length === 0;
+	const noSelection: SelectionNone = {
+		type: SelectionType.None,
+	};
+
+	if ( isSelectionEmpty ) {
+		// Case 1: No selection
+		return noSelection;
+	}
+
+	// When the page initially loads, selectionStart can contain an empty object `{}`.
+	const isSelectionInOneBlock =
+		selectionStart.clientId === selectionEnd.clientId;
+	const isCursorOnly =
+		isSelectionInOneBlock && selectionStart.offset === selectionEnd.offset;
+	const isSelectionAWholeBlock =
+		isSelectionInOneBlock &&
+		selectionStart.offset === undefined &&
+		selectionEnd.offset === undefined;
+
+	if ( isSelectionAWholeBlock ) {
+		// Case 2: A whole block is selected.
+		return {
+			type: SelectionType.WholeBlock,
+			blockId: selectionStart.clientId,
+		};
+	} else if ( isCursorOnly ) {
+		// Case 3: Cursor only, no text selected
+		const cursorPosition = getCursorPosition( selectionStart, yBlocks );
+
+		if ( ! cursorPosition ) {
+			// If we can't find the cursor position in block text, treat it as a non-selection.
+			return noSelection;
+		}
+
+		return {
+			type: SelectionType.Cursor,
+			blockId: selectionStart.clientId,
+			cursorPosition,
+		};
+	} else if ( isSelectionInOneBlock ) {
+		// Case 4: Selection in a single block
+		const cursorStartPosition = getCursorPosition(
+			selectionStart,
+			yBlocks
+		);
+		const cursorEndPosition = getCursorPosition( selectionEnd, yBlocks );
+
+		if ( ! cursorStartPosition || ! cursorEndPosition ) {
+			// If we can't find the cursor positions in block text, treat it as a non-selection.
+			return noSelection;
+		}
+
+		return {
+			type: SelectionType.SelectionInOneBlock,
+			blockId: selectionStart.clientId,
+			cursorStartPosition,
+			cursorEndPosition,
+		};
+	}
+
+	// Caes 5: Selection in multiple blocks
+	const cursorStartPosition = getCursorPosition( selectionStart, yBlocks );
+	const cursorEndPosition = getCursorPosition( selectionEnd, yBlocks );
+	if ( ! cursorStartPosition || ! cursorEndPosition ) {
+		// If we can't find the cursor positions in block text, treat it as a non-selection.
+		return noSelection;
+	}
+
+	return {
+		type: SelectionType.SelectionInMultipleBlocks,
+		blockStartId: selectionStart.clientId,
+		blockEndId: selectionEnd.clientId,
+		cursorStartPosition,
+		cursorEndPosition,
+	};
+}
+
+/**
+ * Get the cursor position from a selection.
+ *
+ * @param selection - The selection.
+ * @param blocks    - The blocks to search through.
+ * @return The cursor position, or null if not found.
+ */
+function getCursorPosition(
+	selection: WPBlockSelection,
+	blocks: YBlocks
+): CursorPosition | null {
+	const block = findBlockByClientId( selection.clientId, blocks );
+	if ( ! block ) {
+		return null;
+	}
+
+	const attributes = block.get( 'attributes' ) as Y.Map< Y.Text >;
+	const currentYText = attributes.get( selection.attributeKey ) as Y.Text;
+
+	const relativePosition = Y.createRelativePositionFromTypeIndex(
+		currentYText,
+		selection.offset
+	);
+
+	return {
+		relativePosition,
+		absoluteOffset: selection.offset,
+	};
+}
+
+/**
+ * Find a block by its client ID.
+ *
+ * @param blockId - The client ID of the block.
+ * @param blocks  - The blocks to search through.
+ * @return The block if found, null otherwise.
+ */
+function findBlockByClientId(
+	blockId: string,
+	blocks: YBlocks
+): YBlock | null {
+	for ( const block of blocks ) {
+		if ( block.get( 'clientId' ) === blockId ) {
+			return block;
+		}
+
+		const innerBlocks = block.get( 'innerBlocks' );
+
+		if ( innerBlocks && innerBlocks.length > 0 ) {
+			const innerBlock = findBlockByClientId( blockId, innerBlocks );
+
+			if ( innerBlock ) {
+				return innerBlock;
+			}
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Check if two selection states are equal.
+ *
+ * @param selection1 - The first selection state.
+ * @param selection2 - The second selection state.
+ * @return True if the selection states are equal, false otherwise.
+ */
+export function areSelectionsStatesEqual(
+	selection1: SelectionState,
+	selection2: SelectionState
+): boolean {
+	if ( selection1.type !== selection2.type ) {
+		return false;
+	}
+
+	switch ( selection1.type ) {
+		case SelectionType.None:
+			return true;
+
+		case SelectionType.Cursor:
+			return (
+				selection1.blockId ===
+					( selection2 as SelectionCursor ).blockId &&
+				areCursorPositionsEqual(
+					selection1.cursorPosition,
+					( selection2 as SelectionCursor ).cursorPosition
+				)
+			);
+
+		case SelectionType.SelectionInOneBlock:
+			return (
+				selection1.blockId ===
+					( selection2 as SelectionInOneBlock ).blockId &&
+				areCursorPositionsEqual(
+					selection1.cursorStartPosition,
+					( selection2 as SelectionInOneBlock ).cursorStartPosition
+				) &&
+				areCursorPositionsEqual(
+					selection1.cursorEndPosition,
+					( selection2 as SelectionInOneBlock ).cursorEndPosition
+				)
+			);
+
+		case SelectionType.SelectionInMultipleBlocks:
+			return (
+				selection1.blockStartId ===
+					( selection2 as SelectionInMultipleBlocks ).blockStartId &&
+				selection1.blockEndId ===
+					( selection2 as SelectionInMultipleBlocks ).blockEndId &&
+				areCursorPositionsEqual(
+					selection1.cursorStartPosition,
+					( selection2 as SelectionInMultipleBlocks )
+						.cursorStartPosition
+				) &&
+				areCursorPositionsEqual(
+					selection1.cursorEndPosition,
+					( selection2 as SelectionInMultipleBlocks )
+						.cursorEndPosition
+				)
+			);
+		case SelectionType.WholeBlock:
+			return (
+				selection1.blockId ===
+				( selection2 as SelectionWholeBlock ).blockId
+			);
+
+		default:
+			return false;
+	}
+}
+
+/**
+ * Check if two cursor positions are equal.
+ *
+ * @param cursorPosition1 - The first cursor position.
+ * @param cursorPosition2 - The second cursor position.
+ * @return True if the cursor positions are equal, false otherwise.
+ */
+function areCursorPositionsEqual(
+	cursorPosition1: CursorPosition,
+	cursorPosition2: CursorPosition
+): boolean {
+	const isRelativePositionEqual =
+		JSON.stringify( cursorPosition1.relativePosition ) ===
+		JSON.stringify( cursorPosition2.relativePosition );
+
+	// Ensure a change in calculated absolute offset results in a treating the cursor as modified.
+	// This is necessary because Y.Text relative positions can remain the same after text changes.
+	const isAbsoluteOffsetEqual =
+		cursorPosition1.absoluteOffset === cursorPosition2.absoluteOffset;
+
+	return isRelativePositionEqual && isAbsoluteOffsetEqual;
+}

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 );
 	}
 }