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

package/src/utils/crdt-utils.ts

@@ -84,6 +84,47 @@ export function isYMap< T extends YMapRecord >(
 	return value instanceof Y.Map;
 }
 
+declare const richTextOffsetBrand: unique symbol;
+declare const htmlStringIndexBrand: unique symbol;
+
+/**
+ * Branded type to prevent confusion between HTML string indices and RichText offsets.
+ *
+ * @see asRichTextOffset()
+ */
+export type RichTextOffset = number & {
+	readonly [ richTextOffsetBrand ]: 'RichTextOffset';
+};
+
+/**
+ * Branded type to prevent confusion between HTML string indices and RichText offsets.
+ *
+ * @see asHtmlStringIndex()
+ */
+export type HtmlStringIndex = number & {
+	readonly [ htmlStringIndexBrand ]: 'HtmlStringIndex';
+};
+
+/**
+ * Brand a number as an offset into a RichText’s text content.
+ *
+ * @param offset The rich-text offset to brand.
+ * @return The branded rich-text offset.
+ */
+export function asRichTextOffset( offset: number ): RichTextOffset {
+	return offset as RichTextOffset;
+}
+
+/**
+ * Brand a number as a string index into serialized HTML.
+ *
+ * @param index The HTML string index to brand.
+ * @return The branded HTML string index.
+ */
+export function asHtmlStringIndex( index: number ): HtmlStringIndex {
+	return index as HtmlStringIndex;
+}
+
 /**
  * Given a block ID and a Y.Doc, find the block in the document.
  *
@@ -141,15 +182,15 @@ function pickMarker( text: string ): string | null {
  */
 export function htmlIndexToRichTextOffset(
 	html: string,
-	htmlIndex: number
-): number {
+	htmlIndex: HtmlStringIndex
+): RichTextOffset {
 	if ( ! html.includes( '<' ) && ! html.includes( '&' ) ) {
-		return htmlIndex;
+		return asRichTextOffset( htmlIndex );
 	}
 
 	const marker = pickMarker( html );
 	if ( ! marker ) {
-		return htmlIndex;
+		return asRichTextOffset( htmlIndex );
 	}
 
 	// Insert marker and let create() do the parsing.
@@ -158,7 +199,7 @@ export function htmlIndexToRichTextOffset(
 	const value = create( { html: withMarker } );
 	const markerPos = value.text.indexOf( marker );
 
-	return markerPos === -1 ? htmlIndex : markerPos;
+	return asRichTextOffset( markerPos === -1 ? htmlIndex : markerPos );
 }
 
 /**
@@ -172,15 +213,15 @@ export function htmlIndexToRichTextOffset(
  */
 export function richTextOffsetToHtmlIndex(
 	html: string,
-	richTextOffset: number
-): number {
+	richTextOffset: RichTextOffset
+): HtmlStringIndex {
 	if ( ! html.includes( '<' ) && ! html.includes( '&' ) ) {
-		return richTextOffset;
+		return asHtmlStringIndex( richTextOffset );
 	}
 
 	const marker = pickMarker( html );
 	if ( ! marker ) {
-		return richTextOffset;
+		return asHtmlStringIndex( richTextOffset );
 	}
 
 	const value = create( { html } );
@@ -200,7 +241,9 @@ export function richTextOffsetToHtmlIndex(
 
 	const htmlWithMarker = toHTMLString( { value: withMarker } );
 	const markerIndex = htmlWithMarker.indexOf( marker );
-	return markerIndex === -1 ? richTextOffset : markerIndex;
+	return asHtmlStringIndex(
+		markerIndex === -1 ? richTextOffset : markerIndex
+	);
 }
 
 function findBlockByClientIdInBlocks(

package/src/utils/crdt.ts

@@ -21,10 +21,11 @@ import {
  */
 import { BaseAwareness } from '../awareness/base-awareness';
 import {
+	type Block,
 	deserializeBlockAttributes,
 	mergeCrdtBlocks,
+	type MergeCursorPosition,
 	mergeRichTextUpdate,
-	type Block,
 	type YBlock,
 	type YBlocks,
 } from './crdt-blocks';
@@ -37,6 +38,7 @@ import {
 	updateSelectionHistory,
 } from './crdt-selection';
 import {
+	asRichTextOffset,
 	createYMap,
 	getRootMap,
 	isYMap,
@@ -161,12 +163,13 @@ export function applyPostChangesToCRDTDoc(
 
 				// Block changes from typing are bundled with a 'selection' update.
 				// Pass the resulting cursor position to the mergeCrdtBlocks function.
-				const cursorPosition =
-					changes.selection?.selectionStart?.offset ?? null;
+				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, cursorPosition );
+				mergeCrdtBlocks( currentBlocks, newValue, newCursorPosition );
 				break;
 			}
 
@@ -260,6 +263,29 @@ export function applyPostChangesToCRDTDoc(
 	}
 }
 
+/**
+ * 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.
+ *
+ * @param selection Selection object which might represent a selection within a block,
+ *                  within a RichText field associated with a particular attribute of
+ *                  that block, or none at all.
+ */
+function parseCursorSelection( selection?: WPSelection ): MergeCursorPosition {
+	const selectionStart = selection?.selectionStart;
+
+	return selectionStart?.clientId &&
+		selectionStart.attributeKey &&
+		'number' === typeof selectionStart.offset &&
+		Number.isInteger( selectionStart.offset )
+		? {
+				attributeKey: selectionStart.attributeKey,
+				clientId: selectionStart.clientId,
+				offset: asRichTextOffset( selectionStart.offset ),
+		  }
+		: null;
+}
+
 function defaultGetChangesFromCRDTDoc( crdtDoc: CRDTDoc ): ObjectData {
 	return getRootMap( crdtDoc, CRDT_RECORD_MAP_KEY ).toJSON();
 }

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

@@ -119,6 +119,16 @@ import {
 	type YBlockAttributes,
 } from '../crdt-blocks';
 import { getCachedRichTextData, createRichTextDataCache } from '../crdt-text';
+import { asHtmlStringIndex, asRichTextOffset } from '../crdt-utils';
+import { type WPBlockSelection } from '../../types';
+
+function createCursorSelection( offset: number ): WPBlockSelection {
+	return {
+		attributeKey: 'content',
+		clientId: 'block-1',
+		offset: asRichTextOffset( offset ),
+	};
+}
 
 describe( 'crdt-blocks', () => {
 	let doc: Y.Doc;
@@ -1006,6 +1016,7 @@ describe( 'crdt-blocks', () => {
 					name: 'core/paragraph',
 					attributes: { content: 'Hello World' },
 					innerBlocks: [],
+					clientId: 'block-1',
 				},
 			];
 
@@ -1016,10 +1027,15 @@ describe( 'crdt-blocks', () => {
 					name: 'core/paragraph',
 					attributes: { content: 'XHello World' },
 					innerBlocks: [],
+					clientId: 'block-1',
 				},
 			];
 
-			mergeCrdtBlocks( yblocks, updatedBlocks, 0 );
+			mergeCrdtBlocks(
+				yblocks,
+				updatedBlocks,
+				createCursorSelection( 0 )
+			);
 
 			const block = yblocks.get( 0 );
 			const content = (
@@ -1034,6 +1050,7 @@ describe( 'crdt-blocks', () => {
 					name: 'core/paragraph',
 					attributes: { content: 'Hello World' },
 					innerBlocks: [],
+					clientId: 'block-1',
 				},
 			];
 
@@ -1044,10 +1061,15 @@ describe( 'crdt-blocks', () => {
 					name: 'core/paragraph',
 					attributes: { content: 'Hello World!' },
 					innerBlocks: [],
+					clientId: 'block-1',
 				},
 			];
 
-			mergeCrdtBlocks( yblocks, updatedBlocks, 11 );
+			mergeCrdtBlocks(
+				yblocks,
+				updatedBlocks,
+				createCursorSelection( 11 )
+			);
 
 			const block = yblocks.get( 0 );
 			const content = (
@@ -1062,6 +1084,7 @@ describe( 'crdt-blocks', () => {
 					name: 'core/paragraph',
 					attributes: { content: 'Hello' },
 					innerBlocks: [],
+					clientId: 'block-1',
 				},
 			];
 
@@ -1072,10 +1095,15 @@ describe( 'crdt-blocks', () => {
 					name: 'core/paragraph',
 					attributes: { content: 'Hello World' },
 					innerBlocks: [],
+					clientId: 'block-1',
 				},
 			];
 
-			mergeCrdtBlocks( yblocks, updatedBlocks, 999 );
+			mergeCrdtBlocks(
+				yblocks,
+				updatedBlocks,
+				createCursorSelection( 999 )
+			);
 
 			const block = yblocks.get( 0 );
 			const content = (
@@ -2602,7 +2630,11 @@ describe( 'crdt-blocks', () => {
 			];
 
 			// Cursor after 'Hello 😀' = 6 + 2 = 8
-			mergeCrdtBlocks( yblocks, updatedBlocks, 8 );
+			mergeCrdtBlocks(
+				yblocks,
+				updatedBlocks,
+				createCursorSelection( 8 )
+			);
 
 			const block = yblocks.get( 0 );
 			const content = (
@@ -2633,7 +2665,11 @@ describe( 'crdt-blocks', () => {
 			];
 
 			// Cursor at position 6 (after 'Hello ', emoji was deleted)
-			mergeCrdtBlocks( yblocks, updatedBlocks, 6 );
+			mergeCrdtBlocks(
+				yblocks,
+				updatedBlocks,
+				createCursorSelection( 6 )
+			);
 
 			const block = yblocks.get( 0 );
 			const content = (
@@ -2664,7 +2700,11 @@ describe( 'crdt-blocks', () => {
 			];
 
 			// Cursor after 'a😀x' = 1 + 2 + 1 = 4
-			mergeCrdtBlocks( yblocks, updatedBlocks, 4 );
+			mergeCrdtBlocks(
+				yblocks,
+				updatedBlocks,
+				createCursorSelection( 4 )
+			);
 
 			const block = yblocks.get( 0 );
 			const content = (
@@ -2696,7 +2736,11 @@ describe( 'crdt-blocks', () => {
 			];
 
 			// Cursor after '😀 hello ' = 2 + 7 = 9
-			mergeCrdtBlocks( yblocks, updatedBlocks, 9 );
+			mergeCrdtBlocks(
+				yblocks,
+				updatedBlocks,
+				createCursorSelection( 9 )
+			);
 
 			const block = yblocks.get( 0 );
 			const content = (
@@ -2729,7 +2773,7 @@ describe( 'crdt-blocks', () => {
 			const yText = doc.getText( 'test' );
 			yText.insert( 0, 'a😀b' );
 
-			mergeRichTextUpdate( yText, 'a😀c', 4 );
+			mergeRichTextUpdate( yText, 'a😀c', asHtmlStringIndex( 4 ) );
 
 			expect( yText.toString() ).toBe( 'a😀c' );
 		} );
@@ -2738,7 +2782,7 @@ describe( 'crdt-blocks', () => {
 			const yText = doc.getText( 'test' );
 			yText.insert( 0, 'ab' );
 
-			mergeRichTextUpdate( yText, 'a😀b', 3 );
+			mergeRichTextUpdate( yText, 'a😀b', asHtmlStringIndex( 3 ) );
 
 			expect( yText.toString() ).toBe( 'a😀b' );
 		} );
@@ -2747,7 +2791,7 @@ describe( 'crdt-blocks', () => {
 			const yText = doc.getText( 'test' );
 			yText.insert( 0, 'a😀b' );
 
-			mergeRichTextUpdate( yText, 'ab', 1 );
+			mergeRichTextUpdate( yText, 'ab', asHtmlStringIndex( 1 ) );
 
 			expect( yText.toString() ).toBe( 'ab' );
 		} );
@@ -2756,7 +2800,11 @@ describe( 'crdt-blocks', () => {
 			const yText = doc.getText( 'test' );
 			yText.insert( 0, 'Hello 😀 World 🎉' );
 
-			mergeRichTextUpdate( yText, 'Hello 😀 Beautiful World 🎉', 19 );
+			mergeRichTextUpdate(
+				yText,
+				'Hello 😀 Beautiful World 🎉',
+				asHtmlStringIndex( 19 )
+			);
 
 			expect( yText.toString() ).toBe( 'Hello 😀 Beautiful World 🎉' );
 		} );
@@ -2766,7 +2814,7 @@ describe( 'crdt-blocks', () => {
 			const yText = doc.getText( 'test' );
 			yText.insert( 0, 'a🏳️‍🌈b' );
 
-			mergeRichTextUpdate( yText, 'a🏳️‍🌈xb', 7 );
+			mergeRichTextUpdate( yText, 'a🏳️‍🌈xb', asHtmlStringIndex( 7 ) );
 
 			expect( yText.toString() ).toBe( 'a🏳️‍🌈xb' );
 		} );
@@ -2776,7 +2824,7 @@ describe( 'crdt-blocks', () => {
 			const yText = doc.getText( 'test' );
 			yText.insert( 0, 'Hi 👋🏽' );
 
-			mergeRichTextUpdate( yText, 'Hi 👋🏽!', 6 );
+			mergeRichTextUpdate( yText, 'Hi 👋🏽!', asHtmlStringIndex( 6 ) );
 
 			expect( yText.toString() ).toBe( 'Hi 👋🏽!' );
 		} );
@@ -2812,7 +2860,11 @@ describe( 'crdt-blocks', () => {
 				];
 
 				// Cursor after '𠮷野家は美味しい' = 2+1+1+1+1+1+1+1 = 9
-				mergeCrdtBlocks( yblocks, updatedBlocks, 9 );
+				mergeCrdtBlocks(
+					yblocks,
+					updatedBlocks,
+					createCursorSelection( 9 )
+				);
 
 				const block = yblocks.get( 0 );
 				const content = (
@@ -2843,7 +2895,11 @@ describe( 'crdt-blocks', () => {
 					},
 				];
 
-				mergeCrdtBlocks( yblocks, updatedBlocks, 18 );
+				mergeCrdtBlocks(
+					yblocks,
+					updatedBlocks,
+					createCursorSelection( 18 )
+				);
 
 				const block = yblocks.get( 0 );
 				const content = (
@@ -2867,7 +2923,7 @@ describe( 'crdt-blocks', () => {
 				const yText = doc.getText( 'test' );
 				yText.insert( 0, 'a𠮷b' );
 
-				mergeRichTextUpdate( yText, 'a𠮷xb', 4 );
+				mergeRichTextUpdate( yText, 'a𠮷xb', asHtmlStringIndex( 4 ) );
 
 				expect( yText.toString() ).toBe( 'a𠮷xb' );
 			} );
@@ -2877,7 +2933,7 @@ describe( 'crdt-blocks', () => {
 				const yText = doc.getText( 'test' );
 				yText.insert( 0, 'a𝐀b' );
 
-				mergeRichTextUpdate( yText, 'a𝐀xb', 4 );
+				mergeRichTextUpdate( yText, 'a𝐀xb', asHtmlStringIndex( 4 ) );
 
 				expect( yText.toString() ).toBe( 'a𝐀xb' );
 			} );
@@ -2897,7 +2953,7 @@ describe( 'crdt-blocks', () => {
 				const yText = doc.getText( 'test' );
 				yText.insert( 0, 'a𝄞b' );
 
-				mergeRichTextUpdate( yText, 'a𝄞xb', 4 );
+				mergeRichTextUpdate( yText, 'a𝄞xb', asHtmlStringIndex( 4 ) );
 
 				expect( yText.toString() ).toBe( 'a𝄞xb' );
 			} );

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

@@ -7,10 +7,26 @@ import { describe, expect, it } from '@jest/globals';
  * Internal dependencies
  */
 import {
-	htmlIndexToRichTextOffset,
-	richTextOffsetToHtmlIndex,
+	asHtmlStringIndex,
+	asRichTextOffset,
+	htmlIndexToRichTextOffset as typedHtmlIndexToRichTextOffset,
+	richTextOffsetToHtmlIndex as typedRichTextOffsetToHtmlIndex,
 } from '../crdt-utils';
 
+function htmlIndexToRichTextOffset( html: string, htmlIndex: number ) {
+	return typedHtmlIndexToRichTextOffset(
+		html,
+		asHtmlStringIndex( htmlIndex )
+	);
+}
+
+function richTextOffsetToHtmlIndex( html: string, richTextOffset: number ) {
+	return typedRichTextOffsetToHtmlIndex(
+		html,
+		asRichTextOffset( richTextOffset )
+	);
+}
+
 describe( 'htmlIndexToRichTextOffset', () => {
 	it( 'returns the index unchanged when there are no tags', () => {
 		expect( htmlIndexToRichTextOffset( 'hello world', 5 ) ).toBe( 5 );