@wordpress/core-data 7.40.2-next.v.202602241322.0 → 7.40.2

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

@@ -12,7 +12,7 @@ import { store as blockEditorStore } from '@wordpress/block-editor';
 import { CRDT_RECORD_MAP_KEY } from '../sync';
 import type { YPostRecord } from './crdt';
 import type { YBlock, YBlocks } from './crdt-blocks';
-import { getRootMap } from './crdt-utils';
+import { getRootMap, richTextOffsetToHtmlIndex } from './crdt-utils';
 import type {
 	AbsoluteBlockIndexPath,
 	WPBlockSelection,
@@ -36,6 +36,16 @@ export enum SelectionType {
 	WholeBlock = 'whole-block',
 }
 
+/**
+ * The direction of a text selection, indicating where the caret sits.
+ */
+export enum SelectionDirection {
+	/** The caret is at the end of the selection (default / left-to-right). */
+	Forward = 'f',
+	/** The caret is at the start of the selection (right-to-left). */
+	Backward = 'b',
+}
+
 /**
  * Converts WordPress block editor selection to a SelectionState.
  *
@@ -44,16 +54,20 @@ export enum SelectionType {
  * differ between the block-editor store and the Yjs document (e.g. in "Show
  * Template" mode).
  *
- * @param selectionStart - The start position of the selection
- * @param selectionEnd   - The end position of the selection
- * @param yDoc           - The Yjs document
+ * @param selectionStart             - The start position of the selection
+ * @param selectionEnd               - The end position of the selection
+ * @param yDoc                       - The Yjs document
+ * @param options                    - Optional parameters
+ * @param options.selectionDirection - The direction of the selection (forward or backward)
  * @return The SelectionState
  */
 export function getSelectionState(
 	selectionStart: WPBlockSelection,
 	selectionEnd: WPBlockSelection,
-	yDoc: Y.Doc
+	yDoc: Y.Doc,
+	options?: { selectionDirection?: SelectionDirection }
 ): SelectionState {
+	const { selectionDirection } = options ?? {};
 	const ymap = getRootMap< YPostRecord >( yDoc, CRDT_RECORD_MAP_KEY );
 	const yBlocks = ymap.get( 'blocks' );
 
@@ -122,6 +136,7 @@ export function getSelectionState(
 			type: SelectionType.SelectionInOneBlock,
 			cursorStartPosition,
 			cursorEndPosition,
+			selectionDirection,
 		};
 	}
 
@@ -137,6 +152,7 @@ export function getSelectionState(
 		type: SelectionType.SelectionInMultipleBlocks,
 		cursorStartPosition,
 		cursorEndPosition,
+		selectionDirection,
 	};
 }
 
@@ -171,7 +187,7 @@ function getCursorPosition(
 
 	const relativePosition = Y.createRelativePositionFromTypeIndex(
 		currentYText,
-		selection.offset
+		richTextOffsetToHtmlIndex( currentYText.toString(), selection.offset )
 	);
 
 	return {
@@ -315,7 +331,9 @@ export function areSelectionsStatesEqual(
 				areCursorPositionsEqual(
 					selection1.cursorEndPosition,
 					( selection2 as SelectionInOneBlock ).cursorEndPosition
-				)
+				) &&
+				selection1.selectionDirection ===
+					( selection2 as SelectionInOneBlock ).selectionDirection
 			);
 
 		case SelectionType.SelectionInMultipleBlocks:
@@ -329,7 +347,10 @@ export function areSelectionsStatesEqual(
 					selection1.cursorEndPosition,
 					( selection2 as SelectionInMultipleBlocks )
 						.cursorEndPosition
-				)
+				) &&
+				selection1.selectionDirection ===
+					( selection2 as SelectionInMultipleBlocks )
+						.selectionDirection
 			);
 		case SelectionType.WholeBlock:
 			return Y.compareRelativePositions(

package/src/utils/crdt-utils.ts

@@ -2,6 +2,7 @@
  * WordPress dependencies
  */
 import { Y } from '@wordpress/sync';
+import { create, insert, toHTMLString } from '@wordpress/rich-text';
 
 /**
  * Internal dependencies
@@ -104,6 +105,104 @@ export function findBlockByClientIdInDoc(
 	return findBlockByClientIdInBlocks( blockId, blocks );
 }
 
+// Marker for insertion.
+const MARKER_START = 0xe000;
+
+/**
+ * Pick a marker character that does not appear in `text`. Returns the marker
+ * or `null` if all candidates are present (extremely unlikely in practice).
+ *
+ * @param text The string to check for existing marker characters.
+ */
+function pickMarker( text: string ): string | null {
+	const tryCount = 0x10;
+
+	// Scan the unicode private use area for the first code point not present
+	// in the text.
+	for ( let code = MARKER_START; code < MARKER_START + tryCount; code++ ) {
+		const candidate = String.fromCharCode( code );
+
+		if ( ! text.includes( candidate ) ) {
+			return candidate;
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Convert an HTML character index (counting tag characters) to a rich-text
+ * offset (counting only text characters). Used on read paths where Y.Text
+ * resolves to an HTML index but the block editor expects a text offset.
+ *
+ * @param html      The full HTML string from Y.Text.
+ * @param htmlIndex The HTML character index.
+ * @return The corresponding rich-text offset.
+ */
+export function htmlIndexToRichTextOffset(
+	html: string,
+	htmlIndex: number
+): number {
+	if ( ! html.includes( '<' ) && ! html.includes( '&' ) ) {
+		return htmlIndex;
+	}
+
+	const marker = pickMarker( html );
+	if ( ! marker ) {
+		return htmlIndex;
+	}
+
+	// Insert marker and let create() do the parsing.
+	const withMarker =
+		html.slice( 0, htmlIndex ) + marker + html.slice( htmlIndex );
+	const value = create( { html: withMarker } );
+	const markerPos = value.text.indexOf( marker );
+
+	return markerPos === -1 ? htmlIndex : markerPos;
+}
+
+/**
+ * Convert a rich-text offset (counting only text characters) to an HTML
+ * character index (counting tag characters). Used on write paths where the
+ * block editor provides a text offset but Y.Text expects an HTML index.
+ *
+ * @param html           The full HTML string from Y.Text.
+ * @param richTextOffset The rich-text text offset.
+ * @return The corresponding HTML character index.
+ */
+export function richTextOffsetToHtmlIndex(
+	html: string,
+	richTextOffset: number
+): number {
+	if ( ! html.includes( '<' ) && ! html.includes( '&' ) ) {
+		return richTextOffset;
+	}
+
+	const marker = pickMarker( html );
+	if ( ! marker ) {
+		return richTextOffset;
+	}
+
+	const value = create( { html } );
+	const markerValue = create( { text: marker } );
+	// The marker must inherit the formatting at the insertion point so that
+	// toHTMLString does not split surrounding tags (e.g. <strong>) around it.
+	if ( value.formats[ richTextOffset ] ) {
+		markerValue.formats[ 0 ] = value.formats[ richTextOffset ];
+	}
+
+	const withMarker = insert(
+		value,
+		markerValue,
+		richTextOffset,
+		richTextOffset
+	);
+
+	const htmlWithMarker = toHTMLString( { value: withMarker } );
+	const markerIndex = htmlWithMarker.indexOf( marker );
+	return markerIndex === -1 ? richTextOffset : markerIndex;
+}
+
 function findBlockByClientIdInBlocks(
 	blockId: string,
 	blocks: YBlocks

package/src/utils/crdt.ts

@@ -11,6 +11,8 @@ import { __unstableSerializeAndClean } from '@wordpress/blocks';
 import {
 	type CRDTDoc,
 	type ObjectData,
+	type ObjectID,
+	type ObjectType,
 	type SyncConfig,
 	Y,
 } from '@wordpress/sync';
@@ -20,6 +22,7 @@ import {
  */
 import { BaseAwareness } from '../awareness/base-awareness';
 import {
+	deserializeBlockAttributes,
 	mergeCrdtBlocks,
 	mergeRichTextUpdate,
 	type Block,
@@ -27,14 +30,13 @@ import {
 	type YBlocks,
 } from './crdt-blocks';
 import { type Post } from '../entity-types/post';
-import { type Type } from '../entity-types';
-import {
-	CRDT_DOC_META_PERSISTENCE_KEY,
-	CRDT_RECORD_MAP_KEY,
-	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
-} from '../sync';
+import { CRDT_DOC_META_PERSISTENCE_KEY, CRDT_RECORD_MAP_KEY } from '../sync';
 import type { WPSelection } from '../types';
-import { updateSelectionHistory } from './crdt-selection';
+import {
+	getSelectionHistory,
+	getShiftedSelection,
+	updateSelectionHistory,
+} from './crdt-selection';
 import {
 	createYMap,
 	getRootMap,
@@ -74,30 +76,11 @@ export interface YPostRecord extends YMapRecord {
 	title: Y.Text;
 }
 
-// Properties that are allowed to be synced for a post.
-const allowedPostProperties = new Set< string >( [
-	'author',
-	'blocks',
-	'content',
-	'categories',
-	'comment_status',
-	'date',
-	'excerpt',
-	'featured_media',
-	'format',
-	'meta',
-	'ping_status',
-	'slug',
-	'status',
-	'sticky',
-	'tags',
-	'template',
-	'title',
-] );
+export const POST_META_KEY_FOR_CRDT_DOC_PERSISTENCE = '_crdt_document';
 
 // Post meta keys that should *not* be synced.
 const disallowedPostMetaKeys = new Set< string >( [
-	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
+	POST_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
 ] );
 
 /**
@@ -137,18 +120,18 @@ function defaultApplyChangesToCRDTDoc(
  *
  * @param {CRDTDoc}     ydoc
  * @param {PostChanges} changes
- * @param {Type}        _postType
+ * @param {Set<string>} syncedProperties
  * @return {void}
  */
 export function applyPostChangesToCRDTDoc(
 	ydoc: CRDTDoc,
 	changes: PostChanges,
-	_postType: Type // eslint-disable-line @typescript-eslint/no-unused-vars
+	syncedProperties: Set< string >
 ): void {
 	const ymap = getRootMap< YPostRecord >( ydoc, CRDT_RECORD_MAP_KEY );
 
 	Object.keys( changes ).forEach( ( key ) => {
-		if ( ! allowedPostProperties.has( key ) ) {
+		if ( ! syncedProperties.has( key ) ) {
 			return;
 		}
 
@@ -287,15 +270,15 @@ function defaultGetChangesFromCRDTDoc( crdtDoc: CRDTDoc ): ObjectData {
  * against the local record and determine if there are changes (edits) we want
  * to dispatch.
  *
- * @param {CRDTDoc} ydoc
- * @param {Post}    editedRecord
- * @param {Type}    _postType
+ * @param {CRDTDoc}     ydoc
+ * @param {Post}        editedRecord
+ * @param {Set<string>} syncedProperties
  * @return {Partial<PostChanges>} The changes that should be applied to the local record.
  */
 export function getPostChangesFromCRDTDoc(
 	ydoc: CRDTDoc,
 	editedRecord: Post,
-	_postType: Type // eslint-disable-line @typescript-eslint/no-unused-vars
+	syncedProperties: Set< string >
 ): PostChanges {
 	const ymap = getRootMap< YPostRecord >( ydoc, CRDT_RECORD_MAP_KEY );
 
@@ -303,7 +286,7 @@ export function getPostChangesFromCRDTDoc(
 
 	const changes = Object.fromEntries(
 		Object.entries( ymap.toJSON() ).filter( ( [ key, newValue ] ) => {
-			if ( ! allowedPostProperties.has( key ) ) {
+			if ( ! syncedProperties.has( key ) ) {
 				return false;
 			}
 
@@ -340,8 +323,6 @@ export function getPostChangesFromCRDTDoc(
 						);
 					}
 
-					// The consumers of blocks have memoization that renders optimization
-					// here unnecessary.
 					return true;
 				}
 
@@ -349,11 +330,8 @@ export function getPostChangesFromCRDTDoc(
 					// Do not overwrite a "floating" date. Borrowing logic from the
 					// isEditedPostDateFloating selector.
 					const currentDateIsFloating =
-						[ 'draft', 'auto-draft', 'pending' ].includes(
-							ymap.get( 'status' ) as string
-						) &&
-						( null === currentValue ||
-							editedRecord.modified === currentValue );
+						null === currentValue ||
+						editedRecord.modified === currentValue;
 
 					if ( currentDateIsFloating ) {
 						return false;
@@ -363,17 +341,29 @@ export function getPostChangesFromCRDTDoc(
 				}
 
 				case 'meta': {
+					const currentMeta =
+						( currentValue as PostChanges[ 'meta' ] ) ?? {};
+
 					allowedMetaChanges = Object.fromEntries(
 						Object.entries( newValue ?? {} ).filter(
-							( [ metaKey ] ) =>
-								! disallowedPostMetaKeys.has( metaKey )
+							( [ metaKey ] ) => {
+								if ( disallowedPostMetaKeys.has( metaKey ) ) {
+									return false;
+								}
+
+								// Ignore meta keys that are no longer registered
+								// for this post (absent from the REST response).
+								// Without this, orphaned CRDT meta would mark
+								// the post permanently dirty.
+								return metaKey in currentMeta;
+							}
 						)
 					);
 
 					// Merge the allowed meta changes with the current meta values since
 					// not all meta properties are synced.
 					const mergedValue = {
-						...( currentValue as PostChanges[ 'meta' ] ),
+						...currentMeta,
 						...allowedMetaChanges,
 					};
 
@@ -407,6 +397,15 @@ export function getPostChangesFromCRDTDoc(
 		} )
 	);
 
+	// Blocks extracted from the CRDT document have rich-text attributes as
+	// plain strings (from Y.Text.toJSON()). Convert them back to RichTextData
+	// so block edit components receive the same types as locally-created blocks.
+	if ( changes.blocks ) {
+		changes.blocks = deserializeBlockAttributes(
+			changes.blocks as Block[]
+		);
+	}
+
 	// Meta changes must be merged with the edited record since not all meta
 	// properties are synced.
 	if ( 'object' === typeof changes.meta ) {
@@ -416,6 +415,20 @@ export function getPostChangesFromCRDTDoc(
 		};
 	}
 
+	// When remote content changes are detected, recalculate the local user's
+	// selection using Y.RelativePosition to account for text shifts. The ydoc
+	// has already been updated with remote content at this point, so converting
+	// relative positions to absolute gives corrected offsets. Including the
+	// selection in PostChanges ensures it dispatches atomically with content.
+	const selectionHistory = getSelectionHistory( ydoc );
+	const shiftedSelection = getShiftedSelection( ydoc, selectionHistory );
+	if ( shiftedSelection ) {
+		changes.selection = {
+			...shiftedSelection,
+			initialPosition: 0,
+		};
+	}
+
 	return changes;
 }
 
@@ -429,6 +442,19 @@ export const defaultSyncConfig: SyncConfig = {
 	getChangesFromCRDTDoc: defaultGetChangesFromCRDTDoc,
 };
 
+/**
+ * This default collection sync config can be used to sync entity collections
+ * (e.g., block comments) where we are not interested in merging changes at the
+ * individual record level, but instead want to replace the entire collection
+ * when changes are detected.
+ */
+export const defaultCollectionSyncConfig: SyncConfig = {
+	applyChangesToCRDTDoc: () => {},
+	getChangesFromCRDTDoc: () => ( {} ),
+	shouldSync: ( _: ObjectType, objectId: ObjectID | null ) =>
+		null === objectId,
+};
+
 /**
  * Extract the raw string value from a property that may be a string or an object
  * with a `raw` property (`RenderedText`).