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

package/src/test/store.js

@@ -113,6 +113,122 @@ describe( 'getEntityRecord', () => {
 	} );
 } );
 
+describe( 'getEntityRecords', () => {
+	const POSTS = [
+		createTestPost( 1 ),
+		createTestPost( 2 ),
+		createTestPost( 3 ),
+	];
+
+	let registry;
+
+	beforeEach( () => {
+		registry = createTestRegistry();
+		triggerFetch.mockReset();
+	} );
+
+	it( 'preserves collection when getEntityRecord resolves after getEntityRecords', async () => {
+		let resolveSlowFetch;
+		const slowFetchPromise = new Promise( ( resolve ) => {
+			resolveSlowFetch = resolve;
+		} );
+
+		triggerFetch.mockImplementation( ( { path } ) => {
+			// Single post fetch (e.g. /wp/v2/posts/1): return slow promise.
+			if ( /\/wp\/v2\/posts\/\d+/.test( path ) ) {
+				return slowFetchPromise;
+			}
+			// Collection fetch: return immediately.
+			return Promise.resolve( {
+				json: () => Promise.resolve( POSTS ),
+				headers: {
+					get: ( header ) => {
+						if ( header === 'X-WP-Total' ) {
+							return String( POSTS.length );
+						}
+						if ( header === 'X-WP-TotalPages' ) {
+							return '1';
+						}
+						return null;
+					},
+				},
+			} );
+		} );
+
+		const resolveSelectStore = registry.resolveSelect( coreDataStore );
+
+		// Start getEntityRecord first (slow), then getEntityRecords (fast).
+		const singlePromise = resolveSelectStore.getEntityRecord(
+			'postType',
+			'post',
+			1,
+			{ context: 'edit' }
+		);
+		await resolveSelectStore.getEntityRecords( 'postType', 'post', {
+			context: 'edit',
+		} );
+
+		// Now resolve the slow single-record fetch.
+		resolveSlowFetch( {
+			json: () => Promise.resolve( POSTS[ 0 ] ),
+			headers: { get: () => null },
+		} );
+		await singlePromise;
+
+		// Wait for all pending thunks to settle.
+		await new Promise( ( resolve ) => setTimeout( resolve, 0 ) );
+
+		const allPosts = registry
+			.select( coreDataStore )
+			.getEntityRecords( 'postType', 'post', { context: 'edit' } );
+		expect( allPosts.map( ( p ) => p.id ) ).toEqual( [ 1, 2, 3 ] );
+	} );
+
+	it( 'preserves collection when getEntityRecord is called after getEntityRecords', async () => {
+		triggerFetch.mockImplementation( ( { path } ) => {
+			// Collection fetch.
+			if ( ! /\/wp\/v2\/posts\/\d+/.test( path ) ) {
+				return Promise.resolve( {
+					json: () => Promise.resolve( POSTS ),
+					headers: {
+						get: ( header ) => {
+							if ( header === 'X-WP-Total' ) {
+								return String( POSTS.length );
+							}
+							if ( header === 'X-WP-TotalPages' ) {
+								return '1';
+							}
+							return null;
+						},
+					},
+				} );
+			}
+			// Single post fetch.
+			return Promise.resolve( {
+				json: () => Promise.resolve( POSTS[ 0 ] ),
+				headers: { get: () => null },
+			} );
+		} );
+
+		const resolveSelectStore = registry.resolveSelect( coreDataStore );
+
+		// First resolve the collection.
+		await resolveSelectStore.getEntityRecords( 'postType', 'post', {
+			context: 'edit',
+		} );
+
+		// Then resolve a single record.
+		await resolveSelectStore.getEntityRecord( 'postType', 'post', 1, {
+			context: 'edit',
+		} );
+
+		const allPosts = registry
+			.select( coreDataStore )
+			.getEntityRecords( 'postType', 'post', { context: 'edit' } );
+		expect( allPosts.map( ( p ) => p.id ) ).toEqual( [ 1, 2, 3 ] );
+	} );
+} );
+
 describe( 'clearEntityRecordEdits', () => {
 	let registry;
 

package/src/types.ts

@@ -1,12 +1,21 @@
 /**
  * WordPress dependencies
  */
-import type { Y } from '@wordpress/sync';
+import type { ConnectionStatusDisconnected, Y } from '@wordpress/sync';
 
 /**
  * Internal dependencies
  */
-import type { SelectionType } from './utils/crdt-user-selections';
+import type {
+	SelectionType,
+	SelectionDirection,
+} from './utils/crdt-user-selections';
+
+export type { ConnectionStatus } from '@wordpress/sync';
+
+export type ConnectionError = NonNullable<
+	ConnectionStatusDisconnected[ 'error' ]
+>;
 
 export interface AnyFunction {
 	( ...args: any[] ): any;
@@ -86,6 +95,8 @@ export type SelectionInOneBlock = {
 	type: SelectionType.SelectionInOneBlock;
 	cursorStartPosition: CursorPosition;
 	cursorEndPosition: CursorPosition;
+	// The direction of the selection, indicating where the caret sits.
+	selectionDirection?: SelectionDirection;
 };
 
 export type SelectionInMultipleBlocks = {
@@ -95,6 +106,8 @@ export type SelectionInMultipleBlocks = {
 	type: SelectionType.SelectionInMultipleBlocks;
 	cursorStartPosition: CursorPosition;
 	cursorEndPosition: CursorPosition;
+	// The direction of the selection, indicating where the caret sits.
+	selectionDirection?: SelectionDirection;
 };
 
 export type SelectionWholeBlock = {
@@ -111,3 +124,8 @@ export type SelectionState =
 	| SelectionInOneBlock
 	| SelectionInMultipleBlocks
 	| SelectionWholeBlock;
+
+export interface ResolvedSelection {
+	richTextOffset: number | null;
+	localClientId: string | null;
+}

package/src/utils/block-selection-history.ts

@@ -9,7 +9,10 @@ import { Y } from '@wordpress/sync';
 /**
  * Internal dependencies
  */
-import { findBlockByClientIdInDoc } from './crdt-utils';
+import {
+	findBlockByClientIdInDoc,
+	richTextOffsetToHtmlIndex,
+} from './crdt-utils';
 import type { WPBlockSelection, WPSelection } from '../types';
 
 // Default size for selection history (not including current selection)
@@ -163,7 +166,7 @@ function convertWPBlockSelectionToSelection(
 	const offset = selection.offset ?? 0;
 	const relativePosition = Y.createRelativePositionFromTypeIndex(
 		changedYText,
-		offset
+		richTextOffsetToHtmlIndex( changedYText.toString(), offset )
 	);
 
 	return {

package/src/utils/crdt-blocks.ts

@@ -16,15 +16,22 @@ import { Y } from '@wordpress/sync';
  * Internal dependencies
  */
 import { createYMap, type YMapRecord, type YMapWrap } from './crdt-utils';
+import { getCachedRichTextData } from './crdt-text';
 import { Delta } from '../sync';
 
 interface BlockAttributes {
 	[ key: string ]: unknown;
 }
 
+interface BlockAttributeType {
+	role?: string;
+	type?: string;
+	query?: Record< string, BlockAttributeType >;
+}
+
 interface BlockType {
+	attributes?: Record< string, BlockAttributeType >;
 	name: string;
-	attributes?: Record< string, { type?: string } >;
 }
 
 // A block as represented in Gutenberg's data store.
@@ -57,14 +64,49 @@ export type YBlockAttributes = Y.Map< Y.Text | unknown >;
 
 const serializableBlocksCache = new WeakMap< WeakKey, Block[] >();
 
+/**
+ * Recursively walk an attribute value and convert any RichTextData instances
+ * to their string (HTML) representation. This is necessary for array-type and
+ * object-type attributes, which can contain nested RichTextData.
+ *
+ * @param value The attribute value to serialize.
+ * @return The value with all RichTextData instances replaced by strings.
+ */
+function serializeAttributeValue( value: unknown ): unknown {
+	if ( value instanceof RichTextData ) {
+		return value.valueOf();
+	}
+
+	// e.g. core/table `body`: [ { cells: [ { content: RichTextData } ] } ]
+	if ( Array.isArray( value ) ) {
+		return value.map( serializeAttributeValue );
+	}
+
+	// e.g. a single row inside core/table `body`: { cells: [ ... ] }
+	if ( value && typeof value === 'object' ) {
+		const result: Record< string, unknown > = {};
+
+		for ( const [ k, v ] of Object.entries( value ) ) {
+			result[ k ] = serializeAttributeValue( v );
+		}
+		return result;
+	}
+
+	return value;
+}
+
 function makeBlockAttributesSerializable(
+	blockName: string,
 	attributes: BlockAttributes
 ): BlockAttributes {
 	const newAttributes = { ...attributes };
 	for ( const [ key, value ] of Object.entries( attributes ) ) {
-		if ( value instanceof RichTextData ) {
-			newAttributes[ key ] = value.valueOf();
+		if ( isLocalAttribute( blockName, key ) ) {
+			delete newAttributes[ key ];
+			continue;
 		}
+
+		newAttributes[ key ] = serializeAttributeValue( value );
 	}
 	return newAttributes;
 }
@@ -76,12 +118,91 @@ function makeBlocksSerializable( blocks: Block[] ): Block[] {
 		return {
 			...rest,
 			name,
-			attributes: makeBlockAttributesSerializable( attributes ),
+			attributes: makeBlockAttributesSerializable( name, attributes ),
 			innerBlocks: makeBlocksSerializable( innerBlocks ),
 		};
 	} );
 }
 
+/**
+ * Recursively walk an attribute value and convert any strings that correspond
+ * to rich-text schema nodes into RichTextData instances. This is the inverse
+ * of serializeAttributeValue and handles nested structures like table cells.
+ *
+ * @param schema The attribute type definition for this value.
+ * @param value  The attribute value from CRDT (toJSON).
+ * @return The value with rich-text strings replaced by RichTextData.
+ */
+function deserializeAttributeValue(
+	schema: BlockAttributeType | undefined,
+	value: unknown
+): unknown {
+	if ( schema?.type === 'rich-text' && typeof value === 'string' ) {
+		return getCachedRichTextData( value );
+	}
+
+	// e.g. core/table `body`: [ { cells: [ { content: RichTextData } ] } ]
+	if ( Array.isArray( value ) ) {
+		return value.map( ( item ) =>
+			deserializeAttributeValue( schema, item )
+		);
+	}
+
+	// e.g. a single row inside core/table `body`: { cells: [ ... ] }
+	if ( value && typeof value === 'object' ) {
+		const result: Record< string, unknown > = {};
+
+		for ( const [ key, innerValue ] of Object.entries(
+			value as Record< string, unknown >
+		) ) {
+			result[ key ] = deserializeAttributeValue(
+				schema?.query?.[ key ],
+				innerValue
+			);
+		}
+
+		return result;
+	}
+
+	return value;
+}
+
+/**
+ * Convert blocks from their CRDT-serialized form back to the runtime form
+ * expected by the block editor. Rich-text attributes are stored as Y.Text in
+ * the CRDT document, which serializes to plain strings via toJSON(). This
+ * function restores them to RichTextData instances so that block edit
+ * components that rely on RichTextData methods (e.g. `.text`) work correctly.
+ *
+ * @param blocks Blocks as extracted from the CRDT document via toJSON().
+ * @return Blocks with rich-text attributes restored to RichTextData.
+ */
+export function deserializeBlockAttributes( blocks: Block[] ): Block[] {
+	return blocks.map( ( block: Block ) => {
+		const { name, innerBlocks, attributes, ...rest } = block;
+
+		const newAttributes = { ...attributes };
+
+		for ( const [ key, value ] of Object.entries( attributes ) ) {
+			const schema = getBlockAttributeType( name, key );
+
+			if ( schema ) {
+				newAttributes[ key ] = deserializeAttributeValue(
+					schema,
+					value
+				);
+			}
+		}
+
+		return {
+			...rest,
+			name,
+			attributes: newAttributes,
+			innerBlocks: deserializeBlockAttributes( innerBlocks ?? [] ),
+		};
+	} );
+}
+
 /**
  * @param {any}   gblock
  * @param {Y.Map} yblock
@@ -202,12 +323,7 @@ export function mergeCrdtBlocks(
 			makeBlocksSerializable( incomingBlocks )
 		);
 	}
-	const allBlocks = serializableBlocksCache.get( incomingBlocks ) ?? [];
-
-	// Ensure we skip blocks that we don't want to sync at the moment
-	const blocksToSync = allBlocks.filter( ( block ) =>
-		shouldBlockBeSynced( block )
-	);
+	const blocksToSync = serializableBlocksCache.get( incomingBlocks ) ?? [];
 
 	// This is a rudimentary diff implementation similar to the y-prosemirror diffing
 	// approach.
@@ -382,32 +498,6 @@ export function mergeCrdtBlocks(
 	}
 }
 
-/**
- * Determine if a block should be synced.
- *
- * Ex: A gallery block should not be synced until the images have been
- * uploaded to WordPress, and their url is available. Before that,
- * it's not possible to access the blobs on a client as those are
- * local.
- *
- * @param block The block to check.
- * @return True if the block should be synced, false otherwise.
- */
-function shouldBlockBeSynced( block: Block ): boolean {
-	// Verify that the gallery block is ready to be synced.
-	// This means that, all images have had their blobs converted to full URLs.
-	// Checking for only the blobs ensures that blocks that have just been inserted work as well.
-	if ( 'core/gallery' === block.name ) {
-		return ! block.innerBlocks.some(
-			( innerBlock ) =>
-				innerBlock.attributes && innerBlock.attributes.blob
-		);
-	}
-
-	// Allow all other blocks to be synced.
-	return true;
-}
-
 /**
  * Update a single attribute on a Yjs block attributes map (currentAttributes).
  *
@@ -448,38 +538,35 @@ function updateYBlockAttribute(
 	}
 }
 
-// Cached types for block attributes.
-let cachedBlockAttributeTypes: Map< string, Map< string, string > >;
+// Cached block attribute types, populated once from getBlockTypes().
+let cachedBlockAttributeTypes: Map< string, Map< string, BlockAttributeType > >;
 
 /**
- * Get the defined attribute type for a block attribute.
+ * Get the attribute type definition for a block attribute.
  *
  * @param blockName     The name of the block, e.g. 'core/paragraph'.
  * @param attributeName The name of the attribute, e.g. 'content'.
- * @return The type of the attribute, e.g. 'rich-text' or 'string'.
+ * @return The type definition of the attribute.
  */
 function getBlockAttributeType(
 	blockName: string,
 	attributeName: string
-): string | undefined {
+): BlockAttributeType | undefined {
 	if ( ! cachedBlockAttributeTypes ) {
 		// Parse the attributes for all blocks once.
-		cachedBlockAttributeTypes = new Map< string, Map< string, string > >();
+		cachedBlockAttributeTypes = new Map();
 
 		for ( const blockType of getBlockTypes() as BlockType[] ) {
-			const blockAttributeTypeMap = new Map< string, string >();
-
-			for ( const [ name, definition ] of Object.entries(
-				blockType.attributes ?? {}
-			) ) {
-				if ( definition.type ) {
-					blockAttributeTypeMap.set( name, definition.type );
-				}
-			}
-
 			cachedBlockAttributeTypes.set(
 				blockType.name,
-				blockAttributeTypeMap
+				new Map< string, BlockAttributeType >(
+					Object.entries( blockType.attributes ?? {} ).map(
+						( [ name, definition ] ) => {
+							const { role, type, query } = definition;
+							return [ name, { role, type, query } ];
+						}
+					)
+				)
 			);
 		}
 	}
@@ -503,11 +590,13 @@ function isExpectedAttributeType(
 	const expectedAttributeType = getBlockAttributeType(
 		blockName,
 		attributeName
-	);
+	)?.type;
 
 	if ( expectedAttributeType === 'rich-text' ) {
 		return attributeValue instanceof Y.Text;
-	} else if ( expectedAttributeType === 'string' ) {
+	}
+
+	if ( expectedAttributeType === 'string' ) {
 		return typeof attributeValue === 'string';
 	}
 
@@ -515,6 +604,18 @@ function isExpectedAttributeType(
 	return true;
 }
 
+/**
+ * Given a block name and attribute key, return true if the attribute is local
+ * and should not be synced.
+ *
+ * @param blockName     The name of the block, e.g. 'core/image'.
+ * @param attributeName The name of the attribute to check, e.g. 'blob'.
+ * @return True if the attribute is local, false otherwise.
+ */
+function isLocalAttribute( blockName: string, attributeName: string ): boolean {
+	return 'local' === getBlockAttributeType( blockName, attributeName )?.role;
+}
+
 /**
  * Given a block name and attribute key, return true if the attribute is rich-text typed.
  *
@@ -526,7 +627,9 @@ function isRichTextAttribute(
 	blockName: string,
 	attributeName: string
 ): boolean {
-	return 'rich-text' === getBlockAttributeType( blockName, attributeName );
+	return (
+		'rich-text' === getBlockAttributeType( blockName, attributeName )?.type
+	);
 }
 
 let localDoc: Y.Doc;

package/src/utils/crdt-selection.ts

@@ -18,7 +18,10 @@ import {
 	type YFullSelection,
 	type YSelection,
 } from './block-selection-history';
-import { findBlockByClientIdInDoc } from './crdt-utils';
+import {
+	findBlockByClientIdInDoc,
+	htmlIndexToRichTextOffset,
+} from './crdt-utils';
 import type { WPBlockSelection, WPSelection } from '../types';
 
 // WeakMap to store BlockSelectionHistory instances per Y.Doc
@@ -74,7 +77,10 @@ function convertYSelectionToBlockSelection(
 			return {
 				clientId,
 				attributeKey,
-				offset: absolutePosition.index,
+				offset: htmlIndexToRichTextOffset(
+					absolutePosition.type.toString(),
+					absolutePosition.index
+				),
 			};
 		}
 	} else if ( ySelection.type === YSelectionType.BlockSelection ) {

package/src/utils/crdt-text.ts

@@ -0,0 +1,43 @@
+/**
+ * WordPress dependencies
+ */
+import { RichTextData } from '@wordpress/rich-text';
+
+const RICH_TEXT_CACHE_MAX_SIZE = 500;
+
+/**
+ * Returns a function that converts HTML strings to RichTextData instances,
+ * using a FIFO cache bounded by `maxSize` to avoid re-parsing identical
+ * strings. Repeated calls with the same string return the cached instance
+ * without re-running the HTML parser and DOM traversal.
+ *
+ * @param maxSize Maximum number of entries to hold in the cache.
+ * @return A cached version of RichTextData.fromHTMLString.
+ */
+export function createRichTextDataCache(
+	maxSize: number
+): ( value: string ) => RichTextData {
+	const cache = new Map< string, RichTextData >();
+
+	return function ( value: string ): RichTextData {
+		const cached = cache.get( value );
+
+		if ( cached ) {
+			return cached;
+		}
+
+		const result = RichTextData.fromHTMLString( value );
+
+		if ( cache.size >= maxSize ) {
+			// Evict the oldest entry (Map preserves insertion order).
+			cache.delete( cache.keys().next().value! );
+		}
+
+		cache.set( value, result );
+		return result;
+	};
+}
+
+export const getCachedRichTextData = createRichTextDataCache(
+	RICH_TEXT_CACHE_MAX_SIZE
+);

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(