@wordpress/core-data 7.38.0 → 7.38.1-next.v.0

package/src/awareness/types.ts

@@ -0,0 +1,38 @@
+/**
+ * Internal dependencies
+ */
+import type { SelectionState } from '../utils/crdt-user-selections';
+import type { User } from '../entity-types';
+
+export type UserInfo = Pick<
+	User< 'view' >,
+	'id' | 'name' | 'slug' | 'avatar_urls'
+> & {
+	browserType: string;
+	color: string;
+	enteredAt: number;
+};
+
+/**
+ * This base state represents the presence of the user. We expect it to be
+ * extended to include additional state describing the user's current activity.
+ * This state must be serializable and compact.
+ */
+export interface BaseState {
+	userInfo: UserInfo;
+}
+
+/**
+ * The editor state includes information about the user's current selection.
+ */
+export interface EditorState {
+	selection: SelectionState;
+}
+
+/**
+ * The post editor state extends the base state with information used to render
+ * presence indicators in the post editor.
+ */
+export interface PostEditorState extends BaseState {
+	editorState?: EditorState;
+}

package/src/awareness/utils.ts

@@ -0,0 +1,159 @@
+/**
+ * Internal dependencies
+ */
+import type { User } from '../entity-types';
+import type { UserInfo } from './types';
+
+/**
+ * The color palette for the user highlight.
+ */
+const COLOR_PALETTE = [
+	'#3858E9', // blueberry
+	'#B42AED', // purple
+	'#E33184', // pink
+	'#F3661D', // orange
+	'#ECBD3A', // yellow
+	'#97FE17', // green
+	'#00FDD9', // teal
+	'#37C5F0', // cyan
+];
+
+/**
+ * Generate a random integer between min and max, inclusive.
+ *
+ * @param min - The minimum value.
+ * @param max - The maximum value.
+ * @return A random integer between min and max.
+ */
+function generateRandomInt( min: number, max: number ): number {
+	return Math.floor( Math.random() * ( max - min + 1 ) ) + min;
+}
+
+/**
+ * Get a unique user color from the palette, or generate a variation if none are available.
+ * If the previously used color is available from localStorage, use it.
+ *
+ * @param existingColors - Colors that are already in use.
+ * @return The new user color, in hex format.
+ */
+function getNewUserColor( existingColors: string[] ): string {
+	const availableColors = COLOR_PALETTE.filter(
+		( color ) => ! existingColors.includes( color )
+	);
+
+	let hexColor: string;
+
+	if ( availableColors.length > 0 ) {
+		const randomIndex = generateRandomInt( 0, availableColors.length - 1 );
+		hexColor = availableColors[ randomIndex ];
+	} else {
+		// All colors are used, generate a variation of a random palette color
+		const randomIndex = generateRandomInt( 0, COLOR_PALETTE.length - 1 );
+		const baseColor = COLOR_PALETTE[ randomIndex ];
+		hexColor = generateColorVariation( baseColor );
+	}
+
+	return hexColor;
+}
+
+/**
+ * Generate a variation of a hex color by adjusting its lightness.
+ *
+ * @param hexColor - The base hex color (e.g., '#3858E9').
+ * @return A varied hex color.
+ */
+function generateColorVariation( hexColor: string ): string {
+	// Parse hex to RGB
+	const r = parseInt( hexColor.slice( 1, 3 ), 16 );
+	const g = parseInt( hexColor.slice( 3, 5 ), 16 );
+	const b = parseInt( hexColor.slice( 5, 7 ), 16 );
+
+	// Apply a random lightness shift (-30 to +30)
+	const shift = generateRandomInt( -30, 30 );
+	const newR = Math.min( 255, Math.max( 0, r + shift ) );
+	const newG = Math.min( 255, Math.max( 0, g + shift ) );
+	const newB = Math.min( 255, Math.max( 0, b + shift ) );
+
+	// Convert back to hex
+	const toHex = ( n: number ) =>
+		n.toString( 16 ).padStart( 2, '0' ).toUpperCase();
+	return `#${ toHex( newR ) }${ toHex( newG ) }${ toHex( newB ) }`;
+}
+
+/**
+ * Get the browser name from the user agent.
+ * @return The browser name.
+ */
+function getBrowserName(): string {
+	const userAgent = window.navigator.userAgent;
+	let browserName = 'Unknown';
+
+	if ( userAgent.includes( 'Firefox' ) ) {
+		browserName = 'Firefox';
+	} else if ( userAgent.includes( 'Edg' ) ) {
+		browserName = 'Microsoft Edge';
+	} else if (
+		userAgent.includes( 'Chrome' ) &&
+		! userAgent.includes( 'Edg' )
+	) {
+		browserName = 'Chrome';
+	} else if (
+		userAgent.includes( 'Safari' ) &&
+		! userAgent.includes( 'Chrome' )
+	) {
+		browserName = 'Safari';
+	} else if (
+		userAgent.includes( 'MSIE' ) ||
+		userAgent.includes( 'Trident' )
+	) {
+		browserName = 'Internet Explorer';
+	} else if ( userAgent.includes( 'Opera' ) || userAgent.includes( 'OPR' ) ) {
+		browserName = 'Opera';
+	}
+
+	return browserName;
+}
+
+/**
+ * Check if two user infos are equal.
+ *
+ * @param userInfo1 - The first user info.
+ * @param userInfo2 - The second user info.
+ * @return True if the user infos are equal, false otherwise.
+ */
+export function areUserInfosEqual(
+	userInfo1?: UserInfo,
+	userInfo2?: UserInfo
+): boolean {
+	if ( ! userInfo1 || ! userInfo2 ) {
+		return userInfo1 === userInfo2;
+	}
+
+	if ( Object.keys( userInfo1 ).length !== Object.keys( userInfo2 ).length ) {
+		return false;
+	}
+
+	return Object.entries( userInfo1 ).every( ( [ key, value ] ) => {
+		// Update this function with any non-primitive fields added to UserInfo.
+		return value === userInfo2[ key as keyof UserInfo ];
+	} );
+}
+
+/**
+ * Generate a user info object from a current user and a list of existing colors.
+ *
+ * @param currentUser    - The current user.
+ * @param existingColors - The existing colors.
+ * @return The user info object.
+ */
+export function generateUserInfo(
+	currentUser: User< 'view' >,
+	existingColors: string[]
+): UserInfo {
+	return {
+		...currentUser,
+		browserType: getBrowserName(),
+		color: getNewUserColor( existingColors ),
+		enteredAt: Date.now(),
+	};
+}

package/src/entities.js

@@ -13,6 +13,7 @@ import { __ } from '@wordpress/i18n';
 /**
  * Internal dependencies
  */
+import { PostEditorAwareness } from './awareness/post-editor-awareness';
 import { getSyncManager } from './sync';
 import {
 	applyPostChangesToCRDTDoc,
@@ -358,6 +359,19 @@ async function loadPostTypeEntities() {
 				applyChangesToCRDTDoc: ( crdtDoc, changes ) =>
 					applyPostChangesToCRDTDoc( crdtDoc, changes, postType ),
 
+				/**
+				 * Create the awareness instance for the entity's CRDT document.
+				 *
+				 * @param {import('@wordpress/sync').CRDTDoc}  ydoc
+				 * @param {import('@wordpress/sync').ObjectID} objectId
+				 * @return {import('@wordpress/sync').AwarenessState} AwarenessState instance
+				 */
+				createAwareness: ( ydoc, objectId ) => {
+					const kind = 'postType';
+					const id = parseInt( objectId, 10 );
+					return new PostEditorAwareness( ydoc, kind, name, id );
+				},
+
 				/**
 				 * Extract changes from a CRDT document that can be used to update the
 				 * local editor state.

package/src/resolvers.js

@@ -192,7 +192,7 @@ export const getEntityRecord =
 						recordWithTransients,
 						{
 							// Handle edits sourced from the sync manager.
-							editRecord: ( edits ) => {
+							editRecord: ( edits, options = {} ) => {
 								if ( ! Object.keys( edits ).length ) {
 									return;
 								}
@@ -206,6 +206,7 @@ export const getEntityRecord =
 									meta: {
 										undo: undefined,
 									},
+									options,
 								} );
 							},
 							// Get the current entity record (with edits)

package/src/test/entity-provider.js

@@ -86,6 +86,7 @@ describe( 'useEntityBlockEditor', () => {
 		const edit = ( { children } ) => <>{ children }</>;
 
 		registerBlockType( 'core/test-block', {
+			apiVersion: 3,
 			supports: {
 				className: false,
 			},
@@ -112,6 +113,7 @@ describe( 'useEntityBlockEditor', () => {
 		} );
 
 		registerBlockType( 'core/test-block-with-array-of-strings', {
+			apiVersion: 3,
 			supports: {
 				className: false,
 			},

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

@@ -0,0 +1,332 @@
+/**
+ * External dependencies
+ */
+import { Y, CRDT_RECORD_MAP_KEY } from '@wordpress/sync';
+
+/**
+ * Internal dependencies
+ */
+import type { YPostRecord } from './crdt';
+import type { YBlock, YBlocks } from './crdt-blocks';
+import { getRootMap } from './crdt-utils';
+import type { WPBlockSelection } from '../types';
+
+/**
+ * The type of selection.
+ */
+export enum SelectionType {
+	None = 'none',
+	Cursor = 'cursor',
+	SelectionInOneBlock = 'selection-in-one-block',
+	SelectionInMultipleBlocks = 'selection-in-multiple-blocks',
+	WholeBlock = 'whole-block',
+}
+
+/**
+ * The position of the cursor.
+ */
+export type CursorPosition = {
+	relativePosition: Y.RelativePosition;
+
+	// Also store the absolute offset index of the cursor from the perspective
+	// of the user who is updating the selection.
+	//
+	// Do not use this value directly, instead use `createAbsolutePositionFromRelativePosition()`
+	// on relativePosition for the most up-to-date positioning.
+	//
+	// This is used because local Y.Text changes (e.g. adding or deleting a character)
+	// can result in the same relative position if it is pinned to an unchanged
+	// character. With both of these values as editor state, a change in perceived
+	// position will always result in a redraw.
+	absoluteOffset: number;
+};
+
+export type SelectionNone = {
+	// The user has not made a selection.
+	type: SelectionType.None;
+};
+
+export type SelectionCursor = {
+	// The user has a cursor position in a block with no text highlighted.
+	type: SelectionType.Cursor;
+	blockId: string;
+	cursorPosition: CursorPosition;
+};
+
+export type SelectionInOneBlock = {
+	// The user has highlighted text in a single block.
+	type: SelectionType.SelectionInOneBlock;
+	blockId: string;
+	cursorStartPosition: CursorPosition;
+	cursorEndPosition: CursorPosition;
+};
+
+export type SelectionInMultipleBlocks = {
+	// The user has highlighted text over multiple blocks.
+	type: SelectionType.SelectionInMultipleBlocks;
+	blockStartId: string;
+	blockEndId: string;
+	cursorStartPosition: CursorPosition;
+	cursorEndPosition: CursorPosition;
+};
+
+export type SelectionWholeBlock = {
+	// The user has a non-text block selected, like an image block.
+	type: SelectionType.WholeBlock;
+	blockId: string;
+};
+
+export type SelectionState =
+	| SelectionNone
+	| SelectionCursor
+	| SelectionInOneBlock
+	| SelectionInMultipleBlocks
+	| SelectionWholeBlock;
+
+/**
+ * Converts WordPress block editor selection to a SelectionState.
+ *
+ * @param selectionStart - The start position of the selection
+ * @param selectionEnd   - The end position of the selection
+ * @param yDoc           - The Yjs document
+ * @return The SelectionState
+ */
+export function getSelectionState(
+	selectionStart: WPBlockSelection,
+	selectionEnd: WPBlockSelection,
+	yDoc: Y.Doc
+): SelectionState {
+	const ymap = getRootMap< YPostRecord >( yDoc, CRDT_RECORD_MAP_KEY );
+	const yBlocks = ymap.get( 'blocks' ) ?? new Y.Array< YBlock >();
+
+	const isSelectionEmpty = Object.keys( selectionStart ).length === 0;
+	const noSelection: SelectionNone = {
+		type: SelectionType.None,
+	};
+
+	if ( isSelectionEmpty ) {
+		// Case 1: No selection
+		return noSelection;
+	}
+
+	// When the page initially loads, selectionStart can contain an empty object `{}`.
+	const isSelectionInOneBlock =
+		selectionStart.clientId === selectionEnd.clientId;
+	const isCursorOnly =
+		isSelectionInOneBlock && selectionStart.offset === selectionEnd.offset;
+	const isSelectionAWholeBlock =
+		isSelectionInOneBlock &&
+		selectionStart.offset === undefined &&
+		selectionEnd.offset === undefined;
+
+	if ( isSelectionAWholeBlock ) {
+		// Case 2: A whole block is selected.
+		return {
+			type: SelectionType.WholeBlock,
+			blockId: selectionStart.clientId,
+		};
+	} else if ( isCursorOnly ) {
+		// Case 3: Cursor only, no text selected
+		const cursorPosition = getCursorPosition( selectionStart, yBlocks );
+
+		if ( ! cursorPosition ) {
+			// If we can't find the cursor position in block text, treat it as a non-selection.
+			return noSelection;
+		}
+
+		return {
+			type: SelectionType.Cursor,
+			blockId: selectionStart.clientId,
+			cursorPosition,
+		};
+	} else if ( isSelectionInOneBlock ) {
+		// Case 4: Selection in a single block
+		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.
+			return noSelection;
+		}
+
+		return {
+			type: SelectionType.SelectionInOneBlock,
+			blockId: selectionStart.clientId,
+			cursorStartPosition,
+			cursorEndPosition,
+		};
+	}
+
+	// Caes 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.
+		return noSelection;
+	}
+
+	return {
+		type: SelectionType.SelectionInMultipleBlocks,
+		blockStartId: selectionStart.clientId,
+		blockEndId: selectionEnd.clientId,
+		cursorStartPosition,
+		cursorEndPosition,
+	};
+}
+
+/**
+ * Get the cursor position from a selection.
+ *
+ * @param selection - The selection.
+ * @param blocks    - The blocks to search through.
+ * @return The cursor position, or null if not found.
+ */
+function getCursorPosition(
+	selection: WPBlockSelection,
+	blocks: YBlocks
+): CursorPosition | null {
+	const block = findBlockByClientId( selection.clientId, blocks );
+	if ( ! block ) {
+		return null;
+	}
+
+	const attributes = block.get( 'attributes' ) as Y.Map< Y.Text >;
+	const currentYText = attributes.get( selection.attributeKey ) as Y.Text;
+
+	const relativePosition = Y.createRelativePositionFromTypeIndex(
+		currentYText,
+		selection.offset
+	);
+
+	return {
+		relativePosition,
+		absoluteOffset: selection.offset,
+	};
+}
+
+/**
+ * Find a block by its client ID.
+ *
+ * @param blockId - The client ID of the block.
+ * @param blocks  - The blocks to search through.
+ * @return The block if found, null otherwise.
+ */
+function findBlockByClientId(
+	blockId: string,
+	blocks: YBlocks
+): YBlock | null {
+	for ( const block of blocks ) {
+		if ( block.get( 'clientId' ) === blockId ) {
+			return block;
+		}
+
+		const innerBlocks = block.get( 'innerBlocks' );
+
+		if ( innerBlocks && innerBlocks.length > 0 ) {
+			const innerBlock = findBlockByClientId( blockId, innerBlocks );
+
+			if ( innerBlock ) {
+				return innerBlock;
+			}
+		}
+	}
+
+	return null;
+}
+
+/**
+ * Check if two selection states are equal.
+ *
+ * @param selection1 - The first selection state.
+ * @param selection2 - The second selection state.
+ * @return True if the selection states are equal, false otherwise.
+ */
+export function areSelectionsStatesEqual(
+	selection1: SelectionState,
+	selection2: SelectionState
+): boolean {
+	if ( selection1.type !== selection2.type ) {
+		return false;
+	}
+
+	switch ( selection1.type ) {
+		case SelectionType.None:
+			return true;
+
+		case SelectionType.Cursor:
+			return (
+				selection1.blockId ===
+					( selection2 as SelectionCursor ).blockId &&
+				areCursorPositionsEqual(
+					selection1.cursorPosition,
+					( selection2 as SelectionCursor ).cursorPosition
+				)
+			);
+
+		case SelectionType.SelectionInOneBlock:
+			return (
+				selection1.blockId ===
+					( selection2 as SelectionInOneBlock ).blockId &&
+				areCursorPositionsEqual(
+					selection1.cursorStartPosition,
+					( selection2 as SelectionInOneBlock ).cursorStartPosition
+				) &&
+				areCursorPositionsEqual(
+					selection1.cursorEndPosition,
+					( selection2 as SelectionInOneBlock ).cursorEndPosition
+				)
+			);
+
+		case SelectionType.SelectionInMultipleBlocks:
+			return (
+				selection1.blockStartId ===
+					( selection2 as SelectionInMultipleBlocks ).blockStartId &&
+				selection1.blockEndId ===
+					( selection2 as SelectionInMultipleBlocks ).blockEndId &&
+				areCursorPositionsEqual(
+					selection1.cursorStartPosition,
+					( selection2 as SelectionInMultipleBlocks )
+						.cursorStartPosition
+				) &&
+				areCursorPositionsEqual(
+					selection1.cursorEndPosition,
+					( selection2 as SelectionInMultipleBlocks )
+						.cursorEndPosition
+				)
+			);
+		case SelectionType.WholeBlock:
+			return (
+				selection1.blockId ===
+				( selection2 as SelectionWholeBlock ).blockId
+			);
+
+		default:
+			return false;
+	}
+}
+
+/**
+ * Check if two cursor positions are equal.
+ *
+ * @param cursorPosition1 - The first cursor position.
+ * @param cursorPosition2 - The second cursor position.
+ * @return True if the cursor positions are equal, false otherwise.
+ */
+function areCursorPositionsEqual(
+	cursorPosition1: CursorPosition,
+	cursorPosition2: CursorPosition
+): boolean {
+	const isRelativePositionEqual =
+		JSON.stringify( cursorPosition1.relativePosition ) ===
+		JSON.stringify( cursorPosition2.relativePosition );
+
+	// Ensure a change in calculated absolute offset results in a treating the cursor as modified.
+	// This is necessary because Y.Text relative positions can remain the same after text changes.
+	const isAbsoluteOffsetEqual =
+		cursorPosition1.absoluteOffset === cursorPosition2.absoluteOffset;
+
+	return isRelativePositionEqual && isAbsoluteOffsetEqual;
+}

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

@@ -6,25 +6,32 @@ import { Y } from '@wordpress/sync';
 /**
  * External dependencies
  */
-import { describe, expect, it, jest, beforeEach } from '@jest/globals';
+import {
+	describe,
+	expect,
+	it,
+	jest,
+	beforeEach,
+	afterEach,
+} from '@jest/globals';
 
 /**
  * Mock uuid module
  */
 jest.mock( 'uuid', () => ( {
-	v4: jest.fn( () => 'mocked-uuid-' + Math.random() ),
+	v4: () => 'mocked-uuid-' + Math.random(),
 } ) );
 
 /**
  * Mock @wordpress/blocks module
  */
 jest.mock( '@wordpress/blocks', () => ( {
-	getBlockTypes: jest.fn( () => [
+	getBlockTypes: () => [
 		{
 			name: 'core/paragraph',
 			attributes: { content: { type: 'rich-text' } },
 		},
-	] ),
+	],
 } ) );
 
 /**