@wordpress/core-data 7.32.0 → 7.32.1-next.ff1cebbba.0

package/src/utils/crdt.ts

@@ -0,0 +1,310 @@
+/**
+ * External dependencies
+ */
+import fastDeepEqual from 'fast-deep-equal/es6';
+
+/**
+ * WordPress dependencies
+ */
+import { type CRDTDoc, type ObjectData, Y } from '@wordpress/sync';
+
+/**
+ * Internal dependencies
+ */
+import {
+	mergeCrdtBlocks,
+	type Block,
+	type YBlock,
+	type YBlocks,
+} from './crdt-blocks';
+import { type Post } from '../entity-types/post';
+import { type Type } from '../entity-types';
+import { CRDT_RECORD_MAP_KEY } from '../sync';
+import type { WPBlockSelection, WPSelection } from '../types';
+
+export type PostChanges = Partial< Post > & {
+	blocks?: Block[];
+	excerpt?: Post[ 'excerpt' ] | string;
+	selection?: WPSelection;
+	title?: Post[ 'title' ] | string;
+};
+
+// Hold a reference to the last known selection to help compute Y.Text deltas.
+let lastSelection: WPBlockSelection | null = null;
+
+// Properties that are allowed to be synced for a post.
+const allowedPostProperties = new Set< string >( [
+	'author',
+	'blocks',
+	'comment_status',
+	'date',
+	'excerpt',
+	'featured_media',
+	'format',
+	'ping_status',
+	'slug',
+	'status',
+	'sticky',
+	'tags',
+	'template',
+	'title',
+] );
+
+/**
+ * Given a set of local changes to a generic entity record, apply those changes
+ * to the local Y.Doc.
+ *
+ * @param {CRDTDoc}               ydoc
+ * @param {Partial< ObjectData >} changes
+ * @return {void}
+ */
+export function defaultApplyChangesToCRDTDoc(
+	ydoc: CRDTDoc,
+	changes: ObjectData
+): void {
+	const ymap = ydoc.getMap( CRDT_RECORD_MAP_KEY );
+
+	Object.entries( changes ).forEach( ( [ key, newValue ] ) => {
+		// 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 ) {
+			// Add support for additional data types here.
+
+			default: {
+				const currentValue = ymap.get( key );
+				mergeValue( currentValue, newValue, setValue );
+			}
+		}
+	} );
+}
+
+/**
+ * Given a set of local changes to a post record, apply those changes to the
+ * local Y.Doc.
+ *
+ * @param {CRDTDoc}     ydoc
+ * @param {PostChanges} changes
+ * @param {Type}        postType
+ * @return {void}
+ */
+export function applyPostChangesToCRDTDoc(
+	ydoc: CRDTDoc,
+	changes: PostChanges,
+	postType: Type // eslint-disable-line @typescript-eslint/no-unused-vars
+): void {
+	const ymap = ydoc.getMap( CRDT_RECORD_MAP_KEY );
+
+	Object.entries( changes ).forEach( ( [ key, newValue ] ) => {
+		if ( ! allowedPostProperties.has( key ) ) {
+			return;
+		}
+
+		// 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;
+
+				// Initialize.
+				if ( ! ( currentBlocks instanceof Y.Array ) ) {
+					currentBlocks = new Y.Array< YBlock >();
+					setValue( currentBlocks );
+				}
+
+				// Block[] from local changes.
+				const newBlocks = ( newValue as PostChanges[ 'blocks' ] ) ?? [];
+
+				// 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 );
+				break;
+			}
+
+			case 'excerpt': {
+				const currentValue = ymap.get( 'excerpt' ) as
+					| string
+					| undefined;
+				const rawNewValue = getRawValue( newValue );
+
+				mergeValue( currentValue, rawNewValue, setValue );
+				break;
+			}
+
+			case 'slug': {
+				// Do not sync an empty slug. This indicates that the post is using
+				// the default auto-generated slug.
+				if ( ! newValue ) {
+					break;
+				}
+
+				const currentValue = ymap.get( 'slug' ) as string;
+				mergeValue( currentValue, newValue, setValue );
+				break;
+			}
+
+			case 'title': {
+				const currentValue = ymap.get( 'title' ) as string | undefined;
+
+				// Copy logic from prePersistPostType to ensure that the "Auto
+				// Draft" template title is not synced.
+				let rawNewValue = getRawValue( newValue );
+				if ( ! currentValue && 'Auto Draft' === rawNewValue ) {
+					rawNewValue = '';
+				}
+
+				mergeValue( currentValue, rawNewValue, setValue );
+				break;
+			}
+
+			// Add support for additional data types here.
+
+			default: {
+				const currentValue = ymap.get( key );
+				mergeValue( currentValue, newValue, setValue );
+			}
+		}
+	} );
+
+	// 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();
+}
+
+/**
+ * Given a local Y.Doc that *may* contain changes from remote peers, compare
+ * against the local record and determine if there are changes (edits) we want
+ * to dispatch.
+ *
+ * @param {CRDTDoc} ydoc
+ * @param {Post}    editedRecord
+ * @param {Type}    postType
+ * @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
+): PostChanges {
+	const ymap = ydoc.getMap( CRDT_RECORD_MAP_KEY );
+
+	return Object.fromEntries(
+		Object.entries( ymap.toJSON() ).filter( ( [ key, newValue ] ) => {
+			if ( ! allowedPostProperties.has( key ) ) {
+				return false;
+			}
+
+			const currentValue = editedRecord[ key ];
+
+			switch ( key ) {
+				case 'blocks': {
+					// The consumers of blocks have memoization that renders optimization
+					// here unnecessary.
+					return true;
+				}
+
+				case 'date': {
+					// Do not sync an empty date if our current value is 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 );
+
+					if ( ! newValue && currentDateIsFloating ) {
+						return false;
+					}
+
+					return haveValuesChanged( currentValue, newValue );
+				}
+
+				case 'status': {
+					// Do not sync an invalid status.
+					if ( 'auto-draft' === newValue ) {
+						return false;
+					}
+
+					return haveValuesChanged( currentValue, newValue );
+				}
+
+				case 'excerpt':
+				case 'title': {
+					return haveValuesChanged(
+						getRawValue( currentValue ),
+						newValue
+					);
+				}
+
+				// Add support for additional data types here.
+
+				default: {
+					return haveValuesChanged( currentValue, newValue );
+				}
+			}
+		} )
+	);
+}
+
+/**
+ * Extract the raw string value from a property that may be a string or an object
+ * with a `raw` property (`RenderedText`).
+ *
+ * @param {unknown} value The value to extract from.
+ * @return {string|undefined} The raw string value, or undefined if it could not be determined.
+ */
+function getRawValue( value?: unknown ): string | undefined {
+	// Value may be a string property or a nested object with a `raw` property.
+	if ( 'string' === typeof value ) {
+		return value;
+	}
+
+	if (
+		value &&
+		'object' === typeof value &&
+		'raw' in value &&
+		'string' === typeof value.raw
+	) {
+		return value.raw;
+	}
+
+	return undefined;
+}
+
+function haveValuesChanged< ValueType = any >(
+	currentValue: ValueType,
+	newValue: ValueType
+): boolean {
+	return ! fastDeepEqual( currentValue, newValue );
+}
+
+function mergeValue< ValueType = any >(
+	currentValue: ValueType,
+	newValue: ValueType,
+	setValue: ( value: ValueType ) => void
+): void {
+	if ( haveValuesChanged< ValueType >( currentValue, newValue ) ) {
+		setValue( newValue );
+	}
+}

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

@@ -0,0 +1,375 @@
+/**
+ * WordPress dependencies
+ */
+import { Y } from '@wordpress/sync';
+
+/**
+ * External dependencies
+ */
+import { describe, expect, it, jest, beforeEach } from '@jest/globals';
+
+/**
+ * Internal dependencies
+ */
+import {
+	mergeCrdtBlocks,
+	type Block,
+	type YBlock,
+	type YBlocks,
+	type YBlockAttributes,
+} from '../crdt-blocks';
+
+describe( 'crdt-blocks', () => {
+	let doc: Y.Doc;
+	let yblocks: Y.Array< YBlock >;
+
+	beforeEach( () => {
+		doc = new Y.Doc();
+		yblocks = doc.getArray< YBlock >();
+		jest.clearAllMocks();
+	} );
+
+	afterEach( () => {
+		doc.destroy();
+	} );
+
+	describe( 'mergeCrdtBlocks', () => {
+		it( 'inserts new blocks into empty Y.Array', () => {
+			const incomingBlocks: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Hello World' },
+					innerBlocks: [],
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, incomingBlocks, null );
+
+			expect( yblocks.length ).toBe( 1 );
+			const block = yblocks.get( 0 );
+			expect( block.get( 'name' ) ).toBe( 'core/paragraph' );
+			const content = (
+				block.get( 'attributes' ) as YBlockAttributes
+			 ).get( 'content' ) as Y.Text;
+			expect( content.toString() ).toBe( 'Hello World' );
+		} );
+
+		it( 'updates existing blocks when content changes', () => {
+			const initialBlocks: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Initial content' },
+					innerBlocks: [],
+					clientId: 'block-1',
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, initialBlocks, null );
+
+			const updatedBlocks: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Updated content' },
+					innerBlocks: [],
+					clientId: 'block-1',
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, updatedBlocks, null );
+
+			expect( yblocks.length ).toBe( 1 );
+			const block = yblocks.get( 0 );
+			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[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Block 1' },
+					innerBlocks: [],
+					clientId: 'block-1',
+				},
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Block 2' },
+					innerBlocks: [],
+					clientId: 'block-2',
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, initialBlocks, null );
+			expect( yblocks.length ).toBe( 2 );
+
+			const updatedBlocks: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Block 1' },
+					innerBlocks: [],
+					clientId: 'block-1',
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, updatedBlocks, null );
+
+			expect( yblocks.length ).toBe( 1 );
+			const block = yblocks.get( 0 );
+			const content = (
+				block.get( 'attributes' ) as YBlockAttributes
+			 ).get( 'content' ) as Y.Text;
+			expect( content.toString() ).toBe( 'Block 1' );
+		} );
+
+		it( 'handles innerBlocks recursively', () => {
+			const blocksWithInner: Block[] = [
+				{
+					name: 'core/group',
+					attributes: {},
+					innerBlocks: [
+						{
+							name: 'core/paragraph',
+							attributes: { content: 'Inner paragraph' },
+							innerBlocks: [],
+						},
+					],
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, blocksWithInner, null );
+
+			expect( yblocks.length ).toBe( 1 );
+			const block = yblocks.get( 0 );
+			const innerBlocks = block.get( 'innerBlocks' ) as YBlocks;
+			expect( innerBlocks.length ).toBe( 1 );
+			const innerBlock = innerBlocks.get( 0 );
+			expect( innerBlock.get( 'name' ) ).toBe( 'core/paragraph' );
+		} );
+
+		it( 'skips gallery blocks with unuploaded images (blob attributes)', () => {
+			const galleryWithBlobs: Block[] = [
+				{
+					name: 'core/gallery',
+					attributes: {},
+					innerBlocks: [
+						{
+							name: 'core/image',
+							attributes: {
+								url: 'http://example.com/image.jpg',
+								blob: 'blob:...',
+							},
+							innerBlocks: [],
+						},
+					],
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, galleryWithBlobs, null );
+
+			// Gallery block should not be synced because it has blob attributes
+			expect( yblocks.length ).toBe( 0 );
+		} );
+
+		it( 'syncs gallery blocks without blob attributes', () => {
+			const galleryWithoutBlobs: Block[] = [
+				{
+					name: 'core/gallery',
+					attributes: {},
+					innerBlocks: [
+						{
+							name: 'core/image',
+							attributes: {
+								url: 'http://example.com/image.jpg',
+							},
+							innerBlocks: [],
+						},
+					],
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, galleryWithoutBlobs, null );
+
+			expect( yblocks.length ).toBe( 1 );
+			const block = yblocks.get( 0 );
+			expect( block.get( 'name' ) ).toBe( 'core/gallery' );
+		} );
+
+		it( 'handles block reordering', () => {
+			const initialBlocks: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'First' },
+					innerBlocks: [],
+					clientId: 'block-1',
+				},
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Second' },
+					innerBlocks: [],
+					clientId: 'block-2',
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, initialBlocks, null );
+
+			// Reorder blocks
+			const reorderedBlocks: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Second' },
+					innerBlocks: [],
+					clientId: 'block-2',
+				},
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'First' },
+					innerBlocks: [],
+					clientId: 'block-1',
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, reorderedBlocks, null );
+
+			expect( yblocks.length ).toBe( 2 );
+			const block0 = yblocks.get( 0 );
+			const content0 = (
+				block0.get( 'attributes' ) as YBlockAttributes
+			 ).get( 'content' ) as Y.Text;
+			expect( content0.toString() ).toBe( 'Second' );
+
+			const block1 = yblocks.get( 1 );
+			const content1 = (
+				block1.get( 'attributes' ) as YBlockAttributes
+			 ).get( 'content' ) as Y.Text;
+			expect( content1.toString() ).toBe( 'First' );
+		} );
+
+		it( 'creates Y.Text for rich-text attributes', () => {
+			const blocks: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Rich text content' },
+					innerBlocks: [],
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, blocks, null );
+
+			const block = yblocks.get( 0 );
+			const contentAttr = (
+				block.get( 'attributes' ) as YBlockAttributes
+			 ).get( 'content' ) as Y.Text;
+			expect( contentAttr.toString() ).toBe( 'Rich text content' );
+		} );
+
+		it( 'removes duplicate clientIds', () => {
+			const blocksWithDuplicateIds: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'First' },
+					innerBlocks: [],
+					clientId: 'duplicate-id',
+				},
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Second' },
+					innerBlocks: [],
+					clientId: 'duplicate-id',
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, blocksWithDuplicateIds, null );
+
+			const block0 = yblocks.get( 0 );
+			const clientId1 = block0.get( 'clientId' );
+			const block1 = yblocks.get( 1 );
+			const clientId2 = block1.get( 'clientId' );
+
+			expect( clientId1 ).not.toBe( clientId2 );
+		} );
+
+		it( 'handles attribute deletion', () => {
+			const initialBlocks: Block[] = [
+				{
+					name: 'core/heading',
+					attributes: {
+						content: 'Heading',
+						level: 2,
+					},
+					innerBlocks: [],
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, initialBlocks, null );
+
+			const updatedBlocks: Block[] = [
+				{
+					name: 'core/heading',
+					attributes: {
+						content: 'Heading',
+					},
+					innerBlocks: [],
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, updatedBlocks, null );
+
+			const block = yblocks.get( 0 );
+			const attributes = block.get( 'attributes' ) as YBlockAttributes;
+			expect( attributes.has( 'level' ) ).toBe( false );
+			expect( attributes.has( 'content' ) ).toBe( true );
+		} );
+
+		it( 'preserves blocks that match from both left and right', () => {
+			const initialBlocks: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'First' },
+					innerBlocks: [],
+				},
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Middle' },
+					innerBlocks: [],
+				},
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Last' },
+					innerBlocks: [],
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, initialBlocks, null );
+
+			// Update only the middle block
+			const updatedBlocks: Block[] = [
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'First' },
+					innerBlocks: [],
+				},
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Updated Middle' },
+					innerBlocks: [],
+				},
+				{
+					name: 'core/paragraph',
+					attributes: { content: 'Last' },
+					innerBlocks: [],
+				},
+			];
+
+			mergeCrdtBlocks( yblocks, updatedBlocks, null );
+
+			expect( yblocks.length ).toBe( 3 );
+			const block = yblocks.get( 1 );
+			const content = (
+				block.get( 'attributes' ) as YBlockAttributes
+			 ).get( 'content' ) as Y.Text;
+			expect( content.toString() ).toBe( 'Updated Middle' );
+		} );
+	} );
+} );