@wordpress/core-data 7.51.0 → 7.53.0

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

@@ -1,14 +1,7 @@
-/**
- * WordPress dependencies
- */
 import { select } from '@wordpress/data';
 import { Y } from '@wordpress/sync';
-// @ts-ignore No exported types for block editor store selectors.
+// @ts-expect-error `@wordpress/block-editor` does not expose type declarations for its entry point.
 import { store as blockEditorStore } from '@wordpress/block-editor';
-
-/**
- * Internal dependencies
- */
 import { CRDT_RECORD_MAP_KEY } from '../sync';
 import type { YPostRecord } from './crdt';
 import type { YBlock, YBlocks } from './crdt-blocks';
@@ -28,6 +21,7 @@ import type {
 	SelectionInMultipleBlocks,
 	SelectionWholeBlock,
 	CursorPosition,
+	SelectionEndpoint,
 } from '../types';
 
 /**
@@ -145,18 +139,20 @@ export function getSelectionState(
 		};
 	}
 
-	// Case 5: Selection in multiple blocks
-	const cursorStartPosition = getCursorPosition( selectionStart, yBlocks );
-	const cursorEndPosition = getCursorPosition( selectionEnd, yBlocks );
-	if ( ! cursorStartPosition || ! cursorEndPosition ) {
-		// If we can't find the cursor positions in block text, treat it as a non-selection.
+	// Case 5: Selection in multiple blocks.
+	// Each endpoint is resolved independently — text fields get a CursorEndpoint
+	// (character-level anchor), everything else gets a WholeBlockEndpoint
+	// (block-slot anchor). Mixed combinations across block types are valid.
+	const startEndpoint = getSelectionEndpoint( selectionStart, yBlocks );
+	const endEndpoint = getSelectionEndpoint( selectionEnd, yBlocks );
+	if ( ! startEndpoint || ! endEndpoint ) {
 		return noSelection;
 	}
 
 	return {
 		type: SelectionType.SelectionInMultipleBlocks,
-		cursorStartPosition,
-		cursorEndPosition,
+		startEndpoint,
+		endEndpoint,
 		selectionDirection,
 	};
 }
@@ -207,6 +203,42 @@ function getCursorPosition(
 	};
 }
 
+/**
+ * Build a SelectionEndpoint for one side of a multi-block selection.
+ *
+ * WHY two shapes: Yjs relative positions must be anchored to the right node
+ * type. If the block has a RichText field with a known character offset, we
+ * anchor to a Y.Text position (CursorEndpoint) so the cursor survives
+ * concurrent text edits. If there is no text offset (whole-block selection,
+ * or a block type with no RichText), we anchor to the block's index slot in
+ * its parent Y.Array (WholeBlockEndpoint) so it survives block insertions and
+ * deletions above or below it.
+ *
+ * @param selection - The WPBlockSelection for this side.
+ * @param blocks    - The root-level Yjs blocks array.
+ * @return A SelectionEndpoint, or null if the block cannot be located in Yjs.
+ */
+function getSelectionEndpoint(
+	selection: WPBlockSelection,
+	blocks: YBlocks
+): SelectionEndpoint | null {
+	const cursorPosition = getCursorPosition( selection, blocks );
+	if ( cursorPosition ) {
+		return { type: SelectionType.Cursor, cursorPosition };
+	}
+
+	// No character offset available — anchor to the block's slot in its
+	// parent Y.Array instead.
+	const path = getBlockPathForLocalClientId( selection.clientId );
+	const blockPosition = path
+		? createRelativePositionForBlockPath( path, blocks )
+		: null;
+	if ( blockPosition ) {
+		return { type: SelectionType.WholeBlock, blockPosition };
+	}
+	return null;
+}
+
 /**
  * Resolves a local block-editor clientId to its index path relative to the
  * post content blocks. This allows finding the corresponding block in the Yjs
@@ -349,15 +381,13 @@ export function areSelectionsStatesEqual(
 
 		case SelectionType.SelectionInMultipleBlocks:
 			return (
-				areCursorPositionsEqual(
-					selection1.cursorStartPosition,
-					( selection2 as SelectionInMultipleBlocks )
-						.cursorStartPosition
+				areEndpointsEqual(
+					selection1.startEndpoint,
+					( selection2 as SelectionInMultipleBlocks ).startEndpoint
 				) &&
-				areCursorPositionsEqual(
-					selection1.cursorEndPosition,
-					( selection2 as SelectionInMultipleBlocks )
-						.cursorEndPosition
+				areEndpointsEqual(
+					selection1.endEndpoint,
+					( selection2 as SelectionInMultipleBlocks ).endEndpoint
 				) &&
 				selection1.selectionDirection ===
 					( selection2 as SelectionInMultipleBlocks )
@@ -374,6 +404,38 @@ export function areSelectionsStatesEqual(
 	}
 }
 
+/**
+ * Check if two SelectionEndpoints are equal.
+ *
+ * Endpoints of different kinds (cursor vs whole-block) are never equal.
+ *
+ * @param ep1 - First endpoint.
+ * @param ep2 - Second endpoint.
+ * @return True if the endpoints represent the same position.
+ */
+function areEndpointsEqual(
+	ep1: SelectionEndpoint,
+	ep2: SelectionEndpoint
+): boolean {
+	if ( ep1.type !== ep2.type ) {
+		return false;
+	}
+	if (
+		ep1.type === SelectionType.Cursor &&
+		ep2.type === SelectionType.Cursor
+	) {
+		return areCursorPositionsEqual(
+			ep1.cursorPosition,
+			ep2.cursorPosition
+		);
+	}
+	// Both SelectionType.WholeBlock.
+	return Y.compareRelativePositions(
+		( ep1 as SelectionWholeBlock ).blockPosition,
+		( ep2 as SelectionWholeBlock ).blockPosition
+	);
+}
+
 /**
  * Check if two cursor positions are equal.
  *

package/src/utils/crdt-utils.ts

@@ -1,12 +1,5 @@
-/**
- * WordPress dependencies
- */
 import { Y } from '@wordpress/sync';
 import { create, insert, toHTMLString } from '@wordpress/rich-text';
-
-/**
- * Internal dependencies
- */
 import type { YBlock, YBlocks } from './crdt-blocks';
 import type { YPostRecord } from './crdt';
 import { CRDT_RECORD_MAP_KEY } from '../sync';

package/src/utils/crdt.ts

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import fastDeepEqual from 'fast-deep-equal/es6/index.js';
-
-/**
- * WordPress dependencies
- */
 import {
 	__unstableSerializeAndClean,
 	parse,
@@ -19,10 +12,6 @@ import {
 	type SyncConfig,
 	Y,
 } from '@wordpress/sync';
-
-/**
- * Internal dependencies
- */
 import { BaseAwareness } from '../awareness/base-awareness';
 import {
 	type Block,
@@ -577,7 +566,7 @@ export const defaultCollectionSyncConfig: SyncConfig = {
  * @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 {
+export 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;

package/src/utils/get-template-info.js

@@ -0,0 +1,46 @@
+import { layout } from '@wordpress/icons';
+import { getTemplatePartIcon } from './get-template-part-icon';
+const EMPTY_OBJECT = {};
+
+/**
+ * Helper function to retrieve the corresponding template info for a given template.
+ * @param {Object} params
+ * @param {Array}  params.templateTypes
+ * @param {Array}  [params.templateAreas]
+ * @param {Object} params.template
+ */
+export const getTemplateInfo = ( params ) => {
+	if ( ! params ) {
+		return EMPTY_OBJECT;
+	}
+
+	const { templateTypes, templateAreas, template } = params;
+
+	const { description, slug, title, area } = template;
+
+	const { title: defaultTitle, description: defaultDescription } =
+		Object.values( templateTypes ).find( ( type ) => type.slug === slug ) ??
+		EMPTY_OBJECT;
+
+	const templateTitle = typeof title === 'string' ? title : title?.rendered;
+	const templateDescription =
+		typeof description === 'string' ? description : description?.raw;
+
+	const templateAreasWithIcon = templateAreas?.map( ( item ) => ( {
+		...item,
+		icon: getTemplatePartIcon( item.icon ),
+	} ) );
+
+	const templateIcon =
+		templateAreasWithIcon?.find( ( item ) => area === item.area )?.icon ||
+		layout;
+
+	return {
+		title:
+			templateTitle && templateTitle !== slug
+				? templateTitle
+				: defaultTitle || slug,
+		description: templateDescription || defaultDescription,
+		icon: templateIcon,
+	};
+};

package/src/utils/get-template-part-icon.js

@@ -0,0 +1,27 @@
+import {
+	header as headerIcon,
+	footer as footerIcon,
+	sidebar as sidebarIcon,
+	navigationOverlay as navigationOverlayIcon,
+	symbolFilled as symbolFilledIcon,
+} from '@wordpress/icons';
+
+/**
+ * Helper function to retrieve the corresponding icon by area name.
+ *
+ * @param {string} areaOrIconName The area name (e.g., 'header', 'navigation-overlay').
+ *
+ * @return {Object} The corresponding icon.
+ */
+export function getTemplatePartIcon( areaOrIconName ) {
+	if ( 'header' === areaOrIconName ) {
+		return headerIcon;
+	} else if ( 'footer' === areaOrIconName ) {
+		return footerIcon;
+	} else if ( 'sidebar' === areaOrIconName ) {
+		return sidebarIcon;
+	} else if ( 'navigation-overlay' === areaOrIconName ) {
+		return navigationOverlayIcon;
+	}
+	return symbolFilledIcon;
+}

package/src/utils/log-entity-deprecation.ts

@@ -1,11 +1,4 @@
-/**
- * WordPress dependencies
- */
 import deprecated from '@wordpress/deprecated';
-
-/**
- * Internal dependencies
- */
 import { deprecatedEntities } from '../entities';
 
 let loggedAlready = false;

package/src/utils/save-crdt-doc.js

@@ -1,11 +1,4 @@
-/**
- * WordPress dependencies
- */
 import apiFetch from '@wordpress/api-fetch';
-
-/**
- * Internal dependencies
- */
 import { getSyncManager } from '../sync';
 
 const SYNC_SAVE_API_PATH = '/wp-sync/v1/save';

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

@@ -1,11 +1,4 @@
-/**
- * External dependencies
- */
 import { Y } from '@wordpress/sync';
-
-/**
- * Internal dependencies
- */
 import {
 	createBlockSelectionHistory,
 	YSelectionType,

package/src/utils/test/clear-unchanged-edits.js

@@ -1,6 +1,3 @@
-/**
- * Internal dependencies
- */
 import clearUnchangedEdits from '../clear-unchanged-edits';
 
 describe( 'clearUnchangedEdits', () => {

package/src/utils/test/conservative-map-item.js

@@ -1,6 +1,3 @@
-/**
- * Internal dependencies
- */
 import conservativeMapItem from '../conservative-map-item';
 
 describe( 'conservativeMapItem', () => {

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

@@ -1,11 +1,4 @@
-/**
- * WordPress dependencies
- */
 import { Y } from '@wordpress/sync';
-
-/**
- * External dependencies
- */
 import {
 	describe,
 	expect,
@@ -14,14 +7,12 @@ import {
 	beforeEach,
 	afterEach,
 } from '@jest/globals';
-
 /**
  * Mock uuid module
  */
 jest.mock( 'uuid', () => ( {
 	v4: () => 'mocked-uuid-' + Math.random(),
 } ) );
-
 /**
  * Mock @wordpress/blocks module
  */
@@ -101,15 +92,7 @@ jest.mock( '@wordpress/blocks', () => ( {
 		},
 	],
 } ) );
-
-/**
- * WordPress dependencies
- */
 import { RichTextData } from '@wordpress/rich-text';
-
-/**
- * Internal dependencies
- */
 import {
 	mergeCrdtBlocks,
 	mergeRichTextUpdate,

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

@@ -1,19 +1,11 @@
-/**
- * External dependencies
- */
 import { Y } from '@wordpress/sync';
 import { select } from '@wordpress/data';
-
-/**
- * Internal dependencies
- */
 import {
 	areSelectionsStatesEqual,
 	getSelectionState,
 	SelectionType,
 } from '../crdt-user-selections';
 import { CRDT_RECORD_MAP_KEY } from '../../sync';
-
 jest.mock( '@wordpress/data', () => ( {
 	select: jest.fn(),
 	// Needed because @wordpress/rich-text initialises its store at import time.
@@ -22,7 +14,6 @@ jest.mock( '@wordpress/data', () => ( {
 	register: jest.fn(),
 	createSelector: ( selector: Function ) => selector,
 } ) );
-
 jest.mock( '@wordpress/block-editor', () => ( {
 	store: 'core/block-editor',
 } ) );
@@ -269,21 +260,49 @@ describe( 'areSelectionsStatesEqual', () => {
 	} );
 
 	describe( 'SelectionType.SelectionInMultipleBlocks', () => {
-		test( 'returns true when selections in multiple blocks are identical', () => {
-			const cursorStartPosition = createCursorPosition(
-				'first block',
-				5
+		test( 'returns true when both endpoints are identical cursor endpoints', () => {
+			const startEndpoint: SelectionCursor = {
+				type: SelectionType.Cursor,
+				cursorPosition: createCursorPosition( 'first block', 5 ),
+			};
+			const endEndpoint: SelectionCursor = {
+				type: SelectionType.Cursor,
+				cursorPosition: createCursorPosition( 'second block', 3 ),
+			};
+			const selection1: SelectionInMultipleBlocks = {
+				type: SelectionType.SelectionInMultipleBlocks,
+				startEndpoint,
+				endEndpoint,
+			};
+			const selection2: SelectionInMultipleBlocks = {
+				type: SelectionType.SelectionInMultipleBlocks,
+				startEndpoint,
+				endEndpoint,
+			};
+
+			expect( areSelectionsStatesEqual( selection1, selection2 ) ).toBe(
+				true
 			);
-			const cursorEndPosition = createCursorPosition( 'second block', 3 );
+		} );
+
+		test( 'returns true when both endpoints are identical whole-block endpoints', () => {
+			const startEndpoint: SelectionWholeBlock = {
+				type: SelectionType.WholeBlock,
+				blockPosition: createBlockPosition( 0 ),
+			};
+			const endEndpoint: SelectionWholeBlock = {
+				type: SelectionType.WholeBlock,
+				blockPosition: createBlockPosition( 1 ),
+			};
 			const selection1: SelectionInMultipleBlocks = {
 				type: SelectionType.SelectionInMultipleBlocks,
-				cursorStartPosition,
-				cursorEndPosition,
+				startEndpoint,
+				endEndpoint,
 			};
 			const selection2: SelectionInMultipleBlocks = {
 				type: SelectionType.SelectionInMultipleBlocks,
-				cursorStartPosition,
-				cursorEndPosition,
+				startEndpoint,
+				endEndpoint,
 			};
 
 			expect( areSelectionsStatesEqual( selection1, selection2 ) ).toBe(
@@ -291,16 +310,28 @@ describe( 'areSelectionsStatesEqual', () => {
 			);
 		} );
 
-		test( 'returns false when start cursor position differs', () => {
+		test( 'returns false when start cursor endpoint position differs', () => {
 			const selection1: SelectionInMultipleBlocks = {
 				type: SelectionType.SelectionInMultipleBlocks,
-				cursorStartPosition: createCursorPosition( 'first block', 5 ),
-				cursorEndPosition: createCursorPosition( 'second block', 3 ),
+				startEndpoint: {
+					type: SelectionType.Cursor,
+					cursorPosition: createCursorPosition( 'first block', 5 ),
+				},
+				endEndpoint: {
+					type: SelectionType.Cursor,
+					cursorPosition: createCursorPosition( 'second block', 3 ),
+				},
 			};
 			const selection2: SelectionInMultipleBlocks = {
 				type: SelectionType.SelectionInMultipleBlocks,
-				cursorStartPosition: createCursorPosition( 'first block', 6 ),
-				cursorEndPosition: createCursorPosition( 'second block', 3 ),
+				startEndpoint: {
+					type: SelectionType.Cursor,
+					cursorPosition: createCursorPosition( 'first block', 6 ),
+				},
+				endEndpoint: {
+					type: SelectionType.Cursor,
+					cursorPosition: createCursorPosition( 'second block', 3 ),
+				},
 			};
 
 			expect( areSelectionsStatesEqual( selection1, selection2 ) ).toBe(
@@ -308,16 +339,57 @@ describe( 'areSelectionsStatesEqual', () => {
 			);
 		} );
 
-		test( 'returns false when end cursor position differs', () => {
+		test( 'returns false when end cursor endpoint position differs', () => {
 			const selection1: SelectionInMultipleBlocks = {
 				type: SelectionType.SelectionInMultipleBlocks,
-				cursorStartPosition: createCursorPosition( 'first block', 5 ),
-				cursorEndPosition: createCursorPosition( 'second block', 3 ),
+				startEndpoint: {
+					type: SelectionType.Cursor,
+					cursorPosition: createCursorPosition( 'first block', 5 ),
+				},
+				endEndpoint: {
+					type: SelectionType.Cursor,
+					cursorPosition: createCursorPosition( 'second block', 3 ),
+				},
 			};
 			const selection2: SelectionInMultipleBlocks = {
 				type: SelectionType.SelectionInMultipleBlocks,
-				cursorStartPosition: createCursorPosition( 'first block', 5 ),
-				cursorEndPosition: createCursorPosition( 'second block', 4 ),
+				startEndpoint: {
+					type: SelectionType.Cursor,
+					cursorPosition: createCursorPosition( 'first block', 5 ),
+				},
+				endEndpoint: {
+					type: SelectionType.Cursor,
+					cursorPosition: createCursorPosition( 'second block', 4 ),
+				},
+			};
+
+			expect( areSelectionsStatesEqual( selection1, selection2 ) ).toBe(
+				false
+			);
+		} );
+
+		test( 'returns false when endpoint types differ (text vs block)', () => {
+			const selection1: SelectionInMultipleBlocks = {
+				type: SelectionType.SelectionInMultipleBlocks,
+				startEndpoint: {
+					type: SelectionType.Cursor,
+					cursorPosition: createCursorPosition( 'first block', 5 ),
+				},
+				endEndpoint: {
+					type: SelectionType.Cursor,
+					cursorPosition: createCursorPosition( 'second block', 3 ),
+				},
+			};
+			const selection2: SelectionInMultipleBlocks = {
+				type: SelectionType.SelectionInMultipleBlocks,
+				startEndpoint: {
+					type: SelectionType.WholeBlock,
+					blockPosition: createBlockPosition( 0 ),
+				},
+				endEndpoint: {
+					type: SelectionType.Cursor,
+					cursorPosition: createCursorPosition( 'second block', 3 ),
+				},
 			};
 
 			expect( areSelectionsStatesEqual( selection1, selection2 ) ).toBe(
@@ -732,12 +804,17 @@ describe( 'getSelectionState', () => {
 			expect( result.type ).toBe(
 				SelectionType.SelectionInMultipleBlocks
 			);
+			const multiBlock = result as SelectionInMultipleBlocks;
+			expect( multiBlock.startEndpoint.type ).toBe(
+				SelectionType.Cursor
+			);
+			expect( multiBlock.endEndpoint.type ).toBe( SelectionType.Cursor );
 			expect(
-				( result as SelectionInMultipleBlocks ).cursorStartPosition
+				( multiBlock.startEndpoint as SelectionCursor ).cursorPosition
 					.absoluteOffset
 			).toBe( 5 );
 			expect(
-				( result as SelectionInMultipleBlocks ).cursorEndPosition
+				( multiBlock.endEndpoint as SelectionCursor ).cursorPosition
 					.absoluteOffset
 			).toBe( 3 );
 		} );

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

@@ -1,12 +1,5 @@
-/**
- * External dependencies
- */
 import { describe, expect, it } from '@jest/globals';
 import { Y } from '@wordpress/sync';
-
-/**
- * Internal dependencies
- */
 import {
 	asHtmlStringIndex,
 	asRichTextOffset,

package/src/utils/test/crdt.ts

@@ -1,13 +1,5 @@
-/**
- * WordPress dependencies
- */
 import { Y } from '@wordpress/sync';
-
-/**
- * External dependencies
- */
 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
@@ -54,16 +46,8 @@ jest.mock( '@wordpress/blocks', () => {
 		),
 	};
 } );
-
-/**
- * WordPress dependencies
- */
 import { parse } from '@wordpress/blocks';
 import { RichTextData } from '@wordpress/rich-text';
-
-/**
- * Internal dependencies
- */
 import { CRDT_RECORD_MAP_KEY } from '../../sync';
 import {
 	applyPostChangesToCRDTDoc,

package/src/utils/test/get-nested-value.js

@@ -1,6 +1,3 @@
-/**
- * Internal dependencies
- */
 import getNestedValue from '../get-nested-value';
 
 describe( 'getNestedValue', () => {

package/src/utils/test/get-normalized-comma-separable.js

@@ -1,6 +1,3 @@
-/**
- * Internal dependencies
- */
 import getNormalizedCommaSeparable from '../get-normalized-comma-separable';
 
 describe( 'getNormalizedCommaSeparable', () => {