@wordpress/core-data 7.45.0 → 7.45.1-next.v.202605131032.0

package/src/test/rtc-rich-text-offset-space.test.js

@@ -0,0 +1,204 @@
+/**
+ * External dependencies
+ */
+import { act, render, waitFor } from '@testing-library/react';
+import {
+	afterEach,
+	beforeEach,
+	describe,
+	expect,
+	it,
+	jest,
+} from '@jest/globals';
+
+/**
+ * WordPress dependencies
+ */
+import {
+	getBlockTypes,
+	registerBlockType,
+	unregisterBlockType,
+} from '@wordpress/blocks';
+import { RichText } from '@wordpress/block-editor';
+import { createRegistry, RegistryProvider } from '@wordpress/data';
+import { Y } from '@wordpress/sync';
+
+/**
+ * Mock sync manager accessor.
+ */
+jest.mock( '../sync', () => ( {
+	...jest.requireActual( '../sync' ),
+	getSyncManager: jest.fn(),
+	LOCAL_EDITOR_ORIGIN: 'local-editor',
+} ) );
+
+/**
+ * Internal dependencies
+ */
+import { store as coreDataStore } from '../index';
+import { CRDT_RECORD_MAP_KEY, getSyncManager } from '../sync';
+import useEntityBlockEditor from '../hooks/use-entity-block-editor';
+import { applyPostChangesToCRDTDoc } from '../utils/crdt';
+import { getRootMap } from '../utils/crdt-utils';
+
+const mockGetSyncManager = jest.mocked( getSyncManager );
+
+const postTypeConfig = {
+	kind: 'postType',
+	name: 'post',
+	baseURL: '/wp/v2/posts',
+	transientEdits: { blocks: true, selection: true },
+	mergedEdits: { meta: true },
+	rawAttributes: [ 'title', 'excerpt', 'content' ],
+	syncConfig: {},
+};
+
+const postTypeEntity = {
+	slug: 'post',
+	rest_base: 'posts',
+	labels: {
+		item_updated: 'Updated Post',
+		item_published: 'Post published',
+		item_reverted_to_draft: 'Post reverted to draft.',
+	},
+};
+
+const OLD_HTML = '<em>italic</em><em>italic</em>';
+const NEW_HTML = '<em>italic</em>beta';
+const TEXT_OFFSET = 10;
+const SYNCED_PROPERTIES = new Set( [ 'blocks' ] );
+
+function createRegistryWithStores() {
+	const registry = createRegistry();
+
+	registry.register( coreDataStore );
+	registry.dispatch( coreDataStore ).addEntities( [ postTypeConfig ] );
+	registry
+		.dispatch( coreDataStore )
+		.receiveEntityRecords( 'root', 'postType', [ postTypeEntity ] );
+	registry
+		.dispatch( coreDataStore )
+		.receiveEntityRecords( 'postType', 'post', [
+			{
+				id: 1,
+				type: 'post',
+				content: {
+					raw: `<!-- wp:paragraph --><p>${ OLD_HTML }</p><!-- /wp:paragraph -->`,
+					rendered: `<p>${ OLD_HTML }</p>`,
+				},
+				meta: {},
+			},
+		] );
+
+	return registry;
+}
+
+function readFirstBlockContentFromDoc( doc ) {
+	const ymap = getRootMap( doc, CRDT_RECORD_MAP_KEY );
+	const yblocks = ymap.get( 'blocks' );
+	const attrs = yblocks.get( 0 ).get( 'attributes' );
+	return attrs.get( 'content' ).toString();
+}
+
+describe( 'useEntityBlockEditor RTC rich-text offset-space bug', () => {
+	let crdtDoc;
+
+	beforeEach( () => {
+		crdtDoc = new Y.Doc();
+
+		registerBlockType( 'core/paragraph', {
+			apiVersion: 3,
+			title: 'Paragraph',
+			category: 'text',
+			attributes: {
+				content: {
+					type: 'rich-text',
+					source: 'rich-text',
+					selector: 'p',
+					role: 'content',
+				},
+			},
+			edit: () => null,
+			save: ( { attributes } ) => (
+				<p>
+					<RichText.Content value={ attributes.content } />
+				</p>
+			),
+		} );
+
+		mockGetSyncManager.mockReturnValue( {
+			update: jest.fn( ( _objectType, _objectId, changes ) => {
+				applyPostChangesToCRDTDoc(
+					crdtDoc,
+					changes,
+					SYNCED_PROPERTIES
+				);
+			} ),
+		} );
+	} );
+
+	afterEach( () => {
+		crdtDoc.destroy();
+		mockGetSyncManager.mockReset();
+		if (
+			getBlockTypes().some( ( block ) => block.name === 'core/paragraph' )
+		) {
+			unregisterBlockType( 'core/paragraph' );
+		}
+	} );
+
+	it( 'preserves formatted paragraph content when onInput forwards blocks plus selection', async () => {
+		const registry = createRegistryWithStores();
+		let blocks;
+		let onInput;
+
+		const TestComponent = () => {
+			[ blocks, onInput ] = useEntityBlockEditor( 'postType', 'post', {
+				id: 1,
+			} );
+
+			return <div />;
+		};
+
+		render(
+			<RegistryProvider value={ registry }>
+				<TestComponent />
+			</RegistryProvider>
+		);
+
+		await waitFor( () => expect( blocks ).toHaveLength( 1 ) );
+
+		const selection = {
+			selectionStart: {
+				clientId: blocks[ 0 ].clientId,
+				attributeKey: 'content',
+				offset: TEXT_OFFSET,
+			},
+			selectionEnd: {
+				clientId: blocks[ 0 ].clientId,
+				attributeKey: 'content',
+				offset: TEXT_OFFSET,
+			},
+		};
+
+		act( () => {
+			onInput( blocks, { selection } );
+		} );
+
+		const nextBlocks = [
+			{
+				...blocks[ 0 ],
+				attributes: {
+					...blocks[ 0 ].attributes,
+					content: NEW_HTML,
+				},
+			},
+		];
+
+		act( () => {
+			onInput( nextBlocks, { selection } );
+		} );
+
+		expect( readFirstBlockContentFromDoc( crdtDoc ) ).toBe( NEW_HTML );
+	} );
+} );

package/src/types.ts

@@ -32,18 +32,75 @@ export interface AnyFunction {
 export type AbsoluteBlockIndexPath = number[];
 
 /**
- * Avoid a circular dependency with @wordpress/editor
+ * Describes part of a visible selection in the editor. Namely, either a cursor
+ * position within a block or a block entirely contained within a selection.
  *
- * Additionaly, this type marks `attributeKey` and `offset` as possibly
- * `undefined`, which can happen in two known scenarios:
+ * This description covers multiple selection scenarios, each of which impacts
+ * how the `attributeKey` and `offset` are set. These two parameters indicate
+ * where in a RichText component the cursor sits and with which block attribute
+ * that RichText component is associated.
  *
- * 1. If a user has an entire block highlighted (e.g., a `core/image` block).
- * 2. If there's an intermediate selection state while inserting a block, those
- *    properties will be temporarily`undefined`.
+ *  - When a selection covers an entire block or covers multiple blocks, there
+ *    is no associated RichText, so both of the parameters are unset.
+ *
+ *  - When a selection starts, ends, or is a simple position within a block,
+ *    both parameters will be set accordingly.
+ *
+ *  - When a block is being inserted into a document, however, there are multiple
+ *    stages determining which parameters are set.
+ *
+ *      1. A block is created in the data store, but has no appearance in the
+ *         editor otherwise. Both parameters are unset.
+ *
+ *      2. The block has loaded into the editor and there is a RichText field,
+ *         but editor focus hasn’t yet placed a browser selection inside it.
+ *         Only the `attributeKey` is set.
+ *
+ *      3. The browser has focused into a RichText field and both parameters are set.
+ *
+ * Selections are thus dynamic because block creation itself loads through multiple
+ * intermediate stages before someone is able to highlight, type, or modify text.
+ *
+ * This type is duplicated to avoid creating circular dependencies.
+ * @see {import("@wordpress/block-editor/src/store/actions").WPBlockSelection}
+ * @see {import("@wordpress/block-editor/src/store/selectors").WPBlockSelection}
+ * @see {import("@wordpress/editor/src/store/selectors").WPBlockSelection}
+ *
+ * @todo Move this into a canonical types file which can be imported in separate
+ *       packages without causing circular dependencies.
  */
 export interface WPBlockSelection {
+	/**
+	 * The selection cursor (start or end) is found within this block.
+	 * or this entire block is contained within a multi-block selection.
+	 */
 	clientId: string;
+
+	/**
+	 * When a selection cursor appears within a RichText component which
+	 * maps back to a block’s attribute, e.g. a paragraph block’s `content`
+	 * attribute, this will hold the attribute key for that associated
+	 * block attribute.
+	 *
+	 * An attribute key is mostly the same as an attribute name, but in some
+	 * circumstances, such as in a multiline attribute, there can be multiple
+	 * RichText instances associated with a given attribute. The key will
+	 * usually be the attribute name verbatim, but in these cases, an index
+	 * will be appended to differentiate the multiple RichText instances
+	 * associated with the array-like attribute.
+	 *
+	 * Technically, the `attributeKey` is the value stored in the DOM node
+	 * for a RichText instance in the `data-wp-block-attribute-key` attribute.
+	 * This “key” links the actual instance with the block attribute, provided
+	 * by the `identifier` React prop when creating a `<RichText>` element.
+	 */
 	attributeKey?: string;
+
+	/**
+	 * When a selection cursor appears within a block, it can be found this
+	 * many Unicode code points into the RichText component’s decoded text
+	 * which is associated with the given attribute key.
+	 */
 	offset?: number;
 }
 

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

@@ -10,6 +10,7 @@ import { Y } from '@wordpress/sync';
  * Internal dependencies
  */
 import {
+	asRichTextOffset,
 	findBlockByClientIdInDoc,
 	richTextOffsetToHtmlIndex,
 } from './crdt-utils';
@@ -166,7 +167,10 @@ function convertWPBlockSelectionToSelection(
 	const offset = selection.offset ?? 0;
 	const relativePosition = Y.createRelativePositionFromTypeIndex(
 		changedYText,
-		richTextOffsetToHtmlIndex( changedYText.toString(), offset )
+		richTextOffsetToHtmlIndex(
+			changedYText.toString(),
+			asRichTextOffset( offset )
+		)
 	);
 
 	return {