@wordpress/core-data 7.46.0 → 7.48.0

package/src/utils/crdt.ts

@@ -6,7 +6,11 @@ import fastDeepEqual from 'fast-deep-equal/es6/index.js';
 /**
  * WordPress dependencies
  */
-import { __unstableSerializeAndClean } from '@wordpress/blocks';
+import {
+	__unstableSerializeAndClean,
+	parse,
+	type Block as WPBlock,
+} from '@wordpress/blocks';
 import {
 	type CRDTDoc,
 	type ObjectData,
@@ -46,10 +50,16 @@ import {
 	type YMapWrap,
 } from './crdt-utils';
 
+// A function that derives content from blocks. Two callers produce this:
+// `useEntityBlockEditor` reads blocks from its argument (so the optional arg
+// lets it accept whatever caller is invoked with), and the receiver-side
+// injection in this file captures blocks in a closure and ignores the arg.
+type ContentFromBlocksFn = ( args?: { blocks: Block[] } ) => string;
+
 // Changes that can be applied to a post entity record.
 export type PostChanges = Partial< Post > & {
 	blocks?: Block[];
-	content?: Post[ 'content' ] | string;
+	content?: Post[ 'content' ] | string | ContentFromBlocksFn;
 	excerpt?: Post[ 'excerpt' ] | string;
 	selection?: WPSelection;
 	title?: Post[ 'title' ] | string;
@@ -138,15 +148,39 @@ export function applyPostChangesToCRDTDoc(
 
 		const newValue = changes[ key ];
 
-		// Cannot serialize function values, so cannot sync them.
+		// Cannot serialize function values, so cannot sync them. `content` is
+		// often passed as a lazy serializer by `useEntityBlockEditor`; the
+		// receiver re-derives it from the synced blocks (see
+		// getPostChangesFromCRDTDoc), so dropping it here is intentional.
 		if ( 'function' === typeof newValue ) {
 			return;
 		}
 
 		switch ( key ) {
 			case 'blocks': {
+				// Block changes from typing are bundled with a 'selection' update.
+				// Use the resulting cursor position for block merging.
+				const newCursorPosition = parseCursorSelection(
+					changes.selection
+				);
+
 				// Blocks are undefined when they need to be re-parsed from content.
-				if ( ! newValue ) {
+				// When new content is also part of this change (e.g. the Code
+				// Editor dispatching `{ content, blocks: undefined }` on every
+				// keystroke), derive blocks from content so the merge keeps
+				// stable YBlock identities for unchanged blocks.
+
+				const rawContent = getRawValue( changes.content );
+				if ( ! newValue && typeof rawContent === 'string' ) {
+					// We have no blocks but an updated content string.
+					mergeContentWithoutBlocks(
+						ymap,
+						rawContent,
+						newCursorPosition
+					);
+					break;
+				} else if ( ! newValue ) {
+					// We have an update containing empty blocks and content.
 					// Set to undefined instead of deleting the key. This is important
 					// since we iterate over the Y.Map keys in getPostChangesFromCRDTDoc.
 					ymap.set( key, undefined );
@@ -161,12 +195,6 @@ export function applyPostChangesToCRDTDoc(
 					ymap.set( key, currentBlocks );
 				}
 
-				// Block changes from typing are bundled with a 'selection' update.
-				// Pass the resulting cursor position to the mergeCrdtBlocks function.
-				const newCursorPosition = parseCursorSelection(
-					changes.selection
-				);
-
 				// Merge blocks does not need `setValue` because it is operating on a
 				// Yjs type that is already in the Y.Doc.
 				mergeCrdtBlocks( currentBlocks, newValue, newCursorPosition );
@@ -263,6 +291,36 @@ export function applyPostChangesToCRDTDoc(
 	}
 }
 
+/**
+ * Derive blocks from a raw content string and merge them into the post's
+ * blocks Y.Array. Used when a caller dispatches a change with `blocks:
+ * undefined` alongside new content,  most notably the Code Editor's
+ * per-keystroke dispatch.
+ *
+ * @param ymap           The post's root Y.Map.
+ * @param rawContent     The raw HTML content to parse.
+ * @param cursorPosition Cursor position derived from the change's selection,
+ *                       used by mergeCrdtBlocks for rich-text cursor hints.
+ */
+function mergeContentWithoutBlocks(
+	ymap: YMapWrap< YPostRecord >,
+	rawContent: string,
+	cursorPosition: MergeCursorPosition
+): void {
+	let currentBlocks = ymap.get( 'blocks' );
+
+	if ( ! ( currentBlocks instanceof Y.Array ) ) {
+		currentBlocks = new Y.Array< YBlock >();
+		ymap.set( 'blocks', currentBlocks );
+	}
+
+	mergeCrdtBlocks(
+		currentBlocks,
+		parse( rawContent ) as Block[],
+		cursorPosition
+	);
+}
+
 /**
  * Only returns a selection object if it describes a selection within a block, with
  * a cursor inside a RichText field associated with one of that block’s attributes.
@@ -431,6 +489,21 @@ export function getPostChangesFromCRDTDoc(
 		);
 	}
 
+	// When blocks changed but content didn't (the sender internally used a lazy
+	// serializer function), inject a closure that captures the synced blocks
+	// and serializes them on demand. Mirrors what useEntityBlockEditor does
+	// locally. A fresh function on every persistent edit marks the entity
+	// dirty (so the save button reactivates for peers), while serialization
+	// stays lazy (only runs when getEditedPostContent reads it). The closure
+	// captures `capturedBlocks` so the right content is returned even if the
+	// caller later clears `record.blocks` (e.g. the Code Editor re-parsing
+	// from content).
+	if ( changes.blocks && ! changes.content ) {
+		const capturedBlocks = changes.blocks;
+		changes.content = () =>
+			__unstableSerializeAndClean( capturedBlocks as WPBlock[] );
+	}
+
 	// Meta changes must be merged with the edited record since not all meta
 	// properties are synced.
 	if ( 'object' === typeof changes.meta ) {

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

@@ -38,6 +38,15 @@ function createTestDoc() {
 	block2.set( 'clientId', 'block-2' );
 	const block2Attrs = new Y.Map();
 	block2Attrs.set( 'content', new Y.Text( 'Second block' ) );
+	const body = new Y.Array();
+	const row = new Y.Map();
+	const cells = new Y.Array();
+	const cell = new Y.Map();
+	cell.set( 'content', new Y.Text( 'Cell text' ) );
+	cells.push( [ cell ] );
+	row.set( 'cells', cells );
+	body.push( [ row ] );
+	block2Attrs.set( 'body', body );
 	block2.set( 'attributes', block2Attrs );
 	block2.set( 'innerBlocks', new Y.Array() );
 	blocks.push( [ block2 ] );
@@ -210,6 +219,39 @@ describe( 'BlockSelectionHistory', () => {
 			const endPosition = fullSelection.end as YRelativeSelection;
 			expect( endPosition.offset ).toBe( 0 );
 		} );
+
+		test( 'should convert nested rich-text attribute paths to relative positions', () => {
+			const selection = createSelection( {
+				clientId: 'block-2',
+				attributeKey: 'body.0.cells.0.content',
+				offset: 4,
+			} );
+
+			history.updateSelection( selection );
+
+			const selectionHistory = history.getSelectionHistory();
+			expect( selectionHistory.length ).toBe( 1 );
+
+			const fullSelection = selectionHistory[ 0 ];
+			expect( fullSelection.start.type ).toBe(
+				YSelectionType.RelativeSelection
+			);
+			expect( fullSelection.end.type ).toBe(
+				YSelectionType.RelativeSelection
+			);
+
+			const startPosition = fullSelection.start as YRelativeSelection;
+			const endPosition = fullSelection.end as YRelativeSelection;
+
+			expect( startPosition.attributeKey ).toBe(
+				'body.0.cells.0.content'
+			);
+			expect( startPosition.offset ).toBe( 4 );
+			expect( startPosition.relativePosition ).toBeDefined();
+			expect( endPosition.attributeKey ).toBe( 'body.0.cells.0.content' );
+			expect( endPosition.offset ).toBe( 4 );
+			expect( endPosition.relativePosition ).toBeDefined();
+		} );
 	} );
 
 	describe( 'updateSelection with block positions', () => {

package/src/utils/test/crdt-blocks.ts

@@ -196,6 +196,43 @@ describe( 'crdt-blocks', () => {
 			expect( content.toString() ).toBe( 'Updated content' );
 		} );
 
+		it( 'preserves the local clientId when an updated block arrives with a different clientId', () => {
+			// Simulates the Code Editor flow: the sender re-parses raw HTML on
+			// every keystroke, which mints a fresh clientId for every block.
+			// The Y.Doc's clientId should stay stable so remote peers don't
+			// remount the block (and any embed iframe within it).
+			const initialBlocks: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Initial content' },
+					innerBlocks: [],
+					clientId: 'stable-id',
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, initialBlocks, null );
+			expect( yblocks.get( 0 ).get( 'clientId' ) ).toBe( 'stable-id' );
+
+			const reparsedBlocks: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Updated content' },
+					innerBlocks: [],
+					clientId: 'freshly-parsed-id',
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, reparsedBlocks, null );
+
+			expect( yblocks.length ).toBe( 1 );
+			const block = yblocks.get( 0 );
+			expect( block.get( 'clientId' ) ).toBe( 'stable-id' );
+			const content = (
+				block.get( 'attributes' ) as YBlockAttributes
+			 ).get( 'content' ) as Y.Text;
+			expect( content.toString() ).toBe( 'Updated content' );
+		} );
+
 		it( 'deletes blocks that are removed', () => {
 			const initialBlocks: Block[] = [
 				{

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

@@ -396,6 +396,15 @@ function createTestDocWithBlocks() {
 	block2.set( 'clientId', 'block-2' );
 	const block2Attrs = new Y.Map();
 	block2Attrs.set( 'content', new Y.Text( 'Second block content' ) );
+	const body = new Y.Array();
+	const row = new Y.Map();
+	const cells = new Y.Array();
+	const cell = new Y.Map();
+	cell.set( 'content', new Y.Text( 'Cell text' ) );
+	cells.push( [ cell ] );
+	row.set( 'cells', cells );
+	body.push( [ row ] );
+	block2Attrs.set( 'body', body );
 	block2.set( 'attributes', block2Attrs );
 	block2.set( 'innerBlocks', new Y.Array() );
 	blocks.push( [ block2 ] );
@@ -529,6 +538,9 @@ describe( 'getSelectionState', () => {
 			expect(
 				( result as SelectionCursor ).cursorPosition.absoluteOffset
 			).toBe( 5 );
+			expect(
+				( result as SelectionCursor ).cursorPosition.attributeKey
+			).toBe( 'content' );
 		} );
 
 		test( 'returns Cursor at start of block (offset 0)', () => {
@@ -555,6 +567,33 @@ describe( 'getSelectionState', () => {
 			).toBe( 0 );
 		} );
 
+		test( 'returns Cursor for a nested rich-text attribute path', () => {
+			const selectionStart: WPBlockSelection = {
+				clientId: 'block-2',
+				attributeKey: 'body.0.cells.0.content',
+				offset: 4,
+			};
+			const selectionEnd: WPBlockSelection = {
+				clientId: 'block-2',
+				attributeKey: 'body.0.cells.0.content',
+				offset: 4,
+			};
+
+			const result = getSelectionState(
+				selectionStart,
+				selectionEnd,
+				testDoc
+			);
+
+			expect( result.type ).toBe( SelectionType.Cursor );
+			expect(
+				( result as SelectionCursor ).cursorPosition.absoluteOffset
+			).toBe( 4 );
+			expect(
+				( result as SelectionCursor ).cursorPosition.attributeKey
+			).toBe( 'body.0.cells.0.content' );
+		} );
+
 		test( 'returns None when block does not exist', () => {
 			const selectionStart: WPBlockSelection = {
 				clientId: 'non-existent-block',

package/src/utils/test/crdt-utils.ts

@@ -2,6 +2,7 @@
  * External dependencies
  */
 import { describe, expect, it } from '@jest/globals';
+import { Y } from '@wordpress/sync';
 
 /**
  * Internal dependencies
@@ -9,6 +10,7 @@ import { describe, expect, it } from '@jest/globals';
 import {
 	asHtmlStringIndex,
 	asRichTextOffset,
+	getYTextByAttributeKey,
 	htmlIndexToRichTextOffset as typedHtmlIndexToRichTextOffset,
 	richTextOffsetToHtmlIndex as typedRichTextOffsetToHtmlIndex,
 } from '../crdt-utils';
@@ -27,6 +29,56 @@ function richTextOffsetToHtmlIndex( html: string, richTextOffset: number ) {
 	);
 }
 
+function createAttachedAttributes(): Y.Map< unknown > {
+	const ydoc = new Y.Doc();
+	const root = ydoc.getMap( 'test' );
+	const attributes = new Y.Map< unknown >();
+	root.set( 'attributes', attributes );
+	return attributes;
+}
+
+describe( 'getYTextByAttributeKey', () => {
+	it( 'returns a top-level rich-text attribute', () => {
+		const attributes = createAttachedAttributes();
+		const text = new Y.Text( 'Top level' );
+		attributes.set( 'content', text );
+
+		expect( getYTextByAttributeKey( attributes, 'content' ) ).toBe( text );
+	} );
+
+	it( 'returns a nested rich-text attribute by dot path', () => {
+		const attributes = createAttachedAttributes();
+		const body = new Y.Array< Y.Map< unknown > >();
+		const row = new Y.Map< unknown >();
+		const cells = new Y.Array< Y.Map< unknown > >();
+		const cell = new Y.Map< unknown >();
+		const text = new Y.Text( 'Cell text' );
+
+		cell.set( 'content', text );
+		cells.push( [ cell ] );
+		row.set( 'cells', cells );
+		body.push( [ row ] );
+		attributes.set( 'body', body );
+
+		expect(
+			getYTextByAttributeKey( attributes, 'body.0.cells.0.content' )
+		).toBe( text );
+	} );
+
+	it( 'returns null for invalid array path segments', () => {
+		const attributes = createAttachedAttributes();
+		const body = new Y.Array< Y.Map< unknown > >();
+		attributes.set( 'body', body );
+
+		expect(
+			getYTextByAttributeKey( attributes, 'body.01.cells.0.content' )
+		).toBeNull();
+		expect(
+			getYTextByAttributeKey( attributes, 'body.-1.cells.0.content' )
+		).toBeNull();
+	} );
+} );
+
 describe( 'htmlIndexToRichTextOffset', () => {
 	it( 'returns the index unchanged when there are no tags', () => {
 		expect( htmlIndexToRichTextOffset( 'hello world', 5 ) ).toBe( 5 );

package/src/utils/test/crdt.ts

@@ -10,6 +10,9 @@ import { describe, expect, it, jest, beforeEach } from '@jest/globals';
 
 /**
  * Mock getBlockTypes so CRDT merging can identify rich-text attributes.
+ * Also stub __unstableSerializeAndClean so we can assert how it's invoked
+ * (the real implementation returns "" without registered block types, which
+ * isn't useful for asserting closure-capture behavior).
  */
 jest.mock( '@wordpress/blocks', () => {
 	const actual = jest.requireActual( '@wordpress/blocks' ) as Record<
@@ -43,12 +46,19 @@ jest.mock( '@wordpress/blocks', () => {
 				},
 			},
 		],
+		// Mocked so tests can control what the Code Editor sync path "parses"
+		// from raw content without needing real block-type registration.
+		parse: jest.fn( () => [] ),
+		__unstableSerializeAndClean: jest.fn(
+			( blocks: unknown[] ) => `serialized:${ blocks?.length ?? 0 }`
+		),
 	};
 } );
 
 /**
  * WordPress dependencies
  */
+import { parse } from '@wordpress/blocks';
 import { RichTextData } from '@wordpress/rich-text';
 
 /**
@@ -63,7 +73,7 @@ import {
 	type PostChanges,
 	type YPostRecord,
 } from '../crdt';
-import type { YBlock, YBlockRecord, YBlocks } from '../crdt-blocks';
+import type { Block, YBlock, YBlockRecord, YBlocks } from '../crdt-blocks';
 import { updateSelectionHistory } from '../crdt-selection';
 import { createYMap, getRootMap, type YMapWrap } from '../crdt-utils';
 import type { Post } from '../../entity-types';
@@ -126,9 +136,12 @@ describe( 'crdt', () => {
 	beforeEach( () => {
 		doc = new Y.Doc();
 		jest.clearAllMocks();
+		jest.useFakeTimers();
 	} );
 
 	afterEach( () => {
+		jest.runAllTimers();
+		jest.useRealTimers();
 		doc.destroy();
 	} );
 
@@ -286,7 +299,7 @@ describe( 'crdt', () => {
 			expect( blocks ).toBeInstanceOf( Y.Array );
 		} );
 
-		it( 'sets blocks to undefined when blocks value is undefined', () => {
+		it( 'sets blocks to undefined when blocks value is undefined and no content is provided', () => {
 			// First, set some blocks.
 			map.set( 'blocks', new Y.Array< YBlock >() );
 
@@ -301,6 +314,86 @@ describe( 'crdt', () => {
 			expect( map.get( 'blocks' ) ).toBeUndefined();
 		} );
 
+		it( 'parses content into blocks when blocks=undefined is paired with new content', () => {
+			// Pre-populate the Y.Doc with two stable blocks. Simulates the
+			// state after the initial sync: peers share the same blocks Y.Array
+			// with stable clientIds on every YBlock.
+			applyPostChangesToCRDTDoc(
+				doc,
+				{
+					blocks: [
+						{
+							name: 'core/paragraph',
+							attributes: { content: 'Hello' },
+							innerBlocks: [],
+							clientId: 'stable-first',
+						},
+						{
+							name: 'core/paragraph',
+							attributes: { content: 'World' },
+							innerBlocks: [],
+							clientId: 'stable-second',
+						},
+					],
+				} as PostChanges,
+				defaultSyncedProperties
+			);
+
+			// The Code Editor flow: dispatch `{ content, blocks: undefined }`
+			// when the user types. The new HTML edits the second paragraph
+			// only. `parse()` is mocked to return blocks with freshly minted
+			// clientIds — the sync layer must not let those overwrite the
+			// stable clientIds already in the Y.Array.
+			( parse as jest.Mock ).mockReturnValueOnce( [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Hello' },
+					innerBlocks: [],
+					clientId: 'fresh-first',
+				},
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'World!' },
+					innerBlocks: [],
+					clientId: 'fresh-second',
+				},
+			] );
+
+			applyPostChangesToCRDTDoc(
+				doc,
+				{
+					content:
+						'<!-- wp:paragraph --><p>Hello</p><!-- /wp:paragraph -->' +
+						'<!-- wp:paragraph --><p>World!</p><!-- /wp:paragraph -->',
+					blocks: undefined,
+				} as PostChanges,
+				defaultSyncedProperties
+			);
+
+			const yblocks = map.get( 'blocks' );
+			expect( yblocks ).toBeInstanceOf( Y.Array );
+			const blocksArray = yblocks as YBlocks;
+			expect( blocksArray.length ).toBe( 2 );
+
+			// Both clientIds must be preserved: the unchanged first block via
+			// the left-right diff sweep, the edited second block via the
+			// explicit clientId-skip in the update loop.
+			expect( blocksArray.get( 0 ).get( 'clientId' ) ).toBe(
+				'stable-first'
+			);
+			expect( blocksArray.get( 1 ).get( 'clientId' ) ).toBe(
+				'stable-second'
+			);
+
+			// The second block's content reflects the edit.
+			const updatedContent = (
+				blocksArray
+					.get( 1 )
+					.get( 'attributes' ) as unknown as YMapWrap< YBlockRecord >
+			 ).get( 'content' ) as Y.Text;
+			expect( updatedContent.toString() ).toBe( 'World!' );
+		} );
+
 		it( 'syncs content as Y.Text', () => {
 			const changes = {
 				content: 'Hello, world!',
@@ -439,6 +532,23 @@ describe( 'crdt', () => {
 			expect( metaMap?.get( 'custom_field' ) ).toBe( 'value' );
 		} );
 
+		it( 'skips function-valued content in changes', () => {
+			const changes = {
+				content: ( {
+					blocks: blocksForSerialization = [],
+				}: {
+					blocks: Block[];
+				} ) =>
+					blocksForSerialization
+						.map( ( b ) => b.attributes.content )
+						.join( '' ),
+			} as unknown as PostChanges;
+
+			applyPostChangesToCRDTDoc( doc, changes, defaultSyncedProperties );
+
+			expect( map.has( 'content' ) ).toBe( false );
+		} );
+
 		it( 'syncs taxonomy rest_base values included in syncedProperties', () => {
 			const changes = {
 				categories: [ 1, 2, 3 ],
@@ -958,6 +1068,102 @@ describe( 'crdt', () => {
 				expect( changes.selection ).toBeUndefined();
 			} );
 		} );
+
+		it( 'injects a closure-based content function when blocks changed but content did not', () => {
+			addBlockToDoc( map, 'block-1', 'Hello world' );
+
+			const editedRecord = {
+				title: 'CRDT Title',
+				status: 'draft',
+				content: { raw: 'Same content', rendered: 'Same content' },
+				blocks: [],
+			} as unknown as Post;
+
+			const changes = getPostChangesFromCRDTDoc(
+				doc,
+				editedRecord,
+				defaultSyncedProperties
+			);
+
+			// Blocks changed, content didn't, so a lazy content function is injected.
+			expect( changes.blocks ).toBeDefined();
+			expect( typeof changes.content ).toBe( 'function' );
+		} );
+
+		it( 'injected content function captures the synced blocks and ignores its caller-supplied argument', () => {
+			addBlockToDoc( map, 'block-1', 'Hello world' );
+
+			const editedRecord = {
+				title: 'CRDT Title',
+				status: 'draft',
+				content: { raw: 'Same content', rendered: 'Same content' },
+				blocks: [],
+			} as unknown as Post;
+
+			const changes = getPostChangesFromCRDTDoc(
+				doc,
+				editedRecord,
+				defaultSyncedProperties
+			);
+
+			// The injected function takes no parameters and serializes the
+			// captured (synced) blocks. This is what makes getEditedPostContent
+			// keep working after the Code Editor clears `record.blocks` to force
+			// a re-parse: the closure already has the right blocks on hand.
+			//
+			// The mocked __unstableSerializeAndClean returns "serialized:<n>"
+			// where n is the length of the blocks it was called with. The
+			// captured blocks have one entry, so both calls below should yield
+			// "serialized:1" (proving the closure ignores its argument and
+			// uses the captured blocks instead).
+			const contentFn = changes.content as ( args?: {
+				blocks: Block[];
+			} ) => string;
+			expect( contentFn() ).toBe( 'serialized:1' );
+			expect( contentFn( { blocks: [] } ) ).toBe( 'serialized:1' );
+		} );
+
+		it( 'does not inject a content function when content also changed in the doc', () => {
+			addBlockToDoc( map, 'block-1', 'Hello world' );
+			map.set( 'content', new Y.Text( 'New content' ) );
+
+			const editedRecord = {
+				title: 'CRDT Title',
+				status: 'draft',
+				content: { raw: 'Old content', rendered: 'Old content' },
+				blocks: [],
+			} as unknown as Post;
+
+			const changes = getPostChangesFromCRDTDoc(
+				doc,
+				editedRecord,
+				defaultSyncedProperties
+			);
+
+			// Content changed directly, so it should be a string, not a function.
+			expect( changes.blocks ).toBeDefined();
+			expect( typeof changes.content ).toBe( 'string' );
+			expect( changes.content ).toBe( 'New content' );
+		} );
+
+		it( 'does not inject a content function when blocks did not change', () => {
+			map.set( 'content', new Y.Text( 'Same content' ) );
+
+			const editedRecord = {
+				title: 'CRDT Title',
+				status: 'draft',
+				content: { raw: 'Same content', rendered: 'Same content' },
+			} as unknown as Post;
+
+			const changes = getPostChangesFromCRDTDoc(
+				doc,
+				editedRecord,
+				defaultSyncedProperties
+			);
+
+			expect( changes.blocks ).toBeUndefined();
+			expect( changes.content ).toBeUndefined();
+		} );
 	} );
 } );