@wordpress/core-data 7.38.0 → 7.39.0

package/src/awareness/post-editor-awareness.ts

@@ -0,0 +1,167 @@
+/**
+ * WordPress dependencies
+ */
+import { dispatch, select, subscribe } from '@wordpress/data';
+import type { Y } from '@wordpress/sync';
+// @ts-ignore No exported types for block editor store selectors.
+import { store as blockEditorStore } from '@wordpress/block-editor';
+
+/**
+ * Internal dependencies
+ */
+import { BaseAwarenessState, baseEqualityFieldChecks } from './base-awareness';
+import {
+	AWARENESS_CURSOR_UPDATE_THROTTLE_IN_MS,
+	LOCAL_CURSOR_UPDATE_DEBOUNCE_IN_MS,
+} from './config';
+import { STORE_NAME as coreStore } from '../name';
+import {
+	areSelectionsStatesEqual,
+	getSelectionState,
+} from '../utils/crdt-user-selections';
+
+import type { WPBlockSelection } from '../types';
+import type { EditorState, PostEditorState } from './types';
+
+export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
+	protected equalityFieldChecks = {
+		...baseEqualityFieldChecks,
+		editorState: this.areEditorStatesEqual,
+	};
+
+	public constructor(
+		doc: Y.Doc,
+		private kind: string,
+		private name: string,
+		private postId: number
+	) {
+		super( doc );
+	}
+
+	public setUp(): void {
+		super.setUp();
+
+		this.subscribeToUserSelectionChanges();
+	}
+
+	/**
+	 * Subscribe to user selection changes and update the selection state.
+	 */
+	private subscribeToUserSelectionChanges(): void {
+		const {
+			getSelectionStart,
+			getSelectionEnd,
+			getSelectedBlocksInitialCaretPosition,
+		} = select( blockEditorStore );
+
+		// Keep track of the current selection in the outer scope so we can compare
+		// in the subscription.
+		let selectionStart = getSelectionStart();
+		let selectionEnd = getSelectionEnd();
+		let localCursorTimeout: NodeJS.Timeout | null = null;
+
+		subscribe( () => {
+			const newSelectionStart = getSelectionStart();
+			const newSelectionEnd = getSelectionEnd();
+
+			if (
+				newSelectionStart === selectionStart &&
+				newSelectionEnd === selectionEnd
+			) {
+				return;
+			}
+
+			selectionStart = newSelectionStart;
+			selectionEnd = newSelectionEnd;
+
+			// Typically selection position is only persisted after typing in a block, which
+			// can cause selection position to be reset by other users making block updates.
+			// Ensure we update the controlled selection right away, persisting our cursor position locally.
+			const initialPosition = getSelectedBlocksInitialCaretPosition();
+			void this.updateSelectionInEntityRecord(
+				selectionStart,
+				selectionEnd,
+				initialPosition
+			);
+
+			// We receive two selection changes in quick succession
+			// from local selection events:
+			//   { clientId: "123...", attributeKey: "content", offset: undefined }
+			//   { clientId: "123...", attributeKey: "content", offset: 554 }
+			// Add a short debounce to avoid sending the first selection change.
+			if ( localCursorTimeout ) {
+				clearTimeout( localCursorTimeout );
+			}
+
+			localCursorTimeout = setTimeout( () => {
+				const selectionState = getSelectionState(
+					selectionStart,
+					selectionEnd,
+					this.doc
+				);
+
+				this.setThrottledLocalStateField(
+					'editorState',
+					{ selection: selectionState },
+					AWARENESS_CURSOR_UPDATE_THROTTLE_IN_MS
+				);
+			}, LOCAL_CURSOR_UPDATE_DEBOUNCE_IN_MS );
+		} );
+	}
+
+	/**
+	 * Update the entity record with the current user's selection.
+	 *
+	 * @param selectionStart  - The start position of the selection.
+	 * @param selectionEnd    - The end position of the selection.
+	 * @param initialPosition - The initial position of the selection.
+	 */
+	private async updateSelectionInEntityRecord(
+		selectionStart: WPBlockSelection,
+		selectionEnd: WPBlockSelection,
+		initialPosition: number | null
+	): Promise< void > {
+		// Send an entityRecord `selection` update if we have a selection.
+		//
+		// Normally WordPress updates the `selection` property of the post when changes are made to blocks.
+		// In a multi-user setup, block changes can occur from other users. When an entity is updated from another
+		// user's changes, useBlockSync() in Gutenberg will reset the user's selection to the last saved selection.
+		//
+		// Manually adding an edit for each movement ensures that other user's changes to the document will
+		// not cause the local user's selection to reset to the last local change location.
+		const edits = {
+			selection: { selectionStart, selectionEnd, initialPosition },
+		};
+
+		const options = {
+			undoIgnore: true,
+		};
+
+		// @ts-ignore Types are not provided when using store name instead of store instance.
+		dispatch( coreStore ).editEntityRecord(
+			this.kind,
+			this.name,
+			this.postId,
+			edits,
+			options
+		);
+	}
+
+	/**
+	 * Check if two editor states are equal.
+	 *
+	 * @param state1 - The first editor state.
+	 * @param state2 - The second editor state.
+	 * @return True if the editor states are equal, false otherwise.
+	 */
+	private areEditorStatesEqual(
+		state1?: EditorState,
+		state2?: EditorState
+	): boolean {
+		if ( ! state1 || ! state2 ) {
+			return state1 === state2;
+		}
+
+		return areSelectionsStatesEqual( state1.selection, state2.selection );
+	}
+}

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,9 +13,11 @@ import { __ } from '@wordpress/i18n';
 /**
  * Internal dependencies
  */
+import { PostEditorAwareness } from './awareness/post-editor-awareness';
 import { getSyncManager } from './sync';
 import {
 	applyPostChangesToCRDTDoc,
+	defaultSyncConfig,
 	getPostChangesFromCRDTDoc,
 } from './utils/crdt';
 
@@ -218,7 +220,16 @@ export const rootEntitiesConfig = [
 		plural: 'fontCollections',
 		key: 'slug',
 	},
-];
+].map( ( entity ) => {
+	const syncEnabledRootEntities = new Set( [ 'comment' ] );
+
+	if ( globalThis.IS_GUTENBERG_PLUGIN ) {
+		if ( syncEnabledRootEntities.has( entity.name ) ) {
+			entity.syncConfig = defaultSyncConfig;
+		}
+	}
+	return entity;
+} );
 
 export const deprecatedEntities = {
 	root: {
@@ -358,6 +369,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.
@@ -399,7 +423,7 @@ async function loadTaxonomyEntities() {
 	} );
 	return Object.entries( taxonomies ?? {} ).map( ( [ name, taxonomy ] ) => {
 		const namespace = taxonomy?.rest_namespace ?? 'wp/v2';
-		return {
+		const entity = {
 			kind: 'taxonomy',
 			baseURL: `/${ namespace }/${ taxonomy.rest_base }`,
 			baseURLParams: { context: 'edit' },
@@ -408,6 +432,12 @@ async function loadTaxonomyEntities() {
 			getTitle: ( record ) => record?.name,
 			supportsPagination: true,
 		};
+
+		if ( globalThis.IS_GUTENBERG_PLUGIN ) {
+			entity.syncConfig = defaultSyncConfig;
+		}
+
+		return entity;
 	} );
 }
 

package/src/entity-types/test/attachment.test.ts

@@ -20,7 +20,7 @@ describe( 'Attachment type', () => {
 	describe( 'Image attachment', () => {
 		it( 'should validate against real image attachment from REST API', () => {
 			const attachment: Attachment< 'edit' > =
-				imageAttachmentFixture as Attachment< 'edit' >;
+				imageAttachmentFixture as unknown as Attachment< 'edit' >;
 
 			// Edit-context fields
 			expect( attachment.permalink_template ).toBeDefined();
@@ -38,7 +38,7 @@ describe( 'Attachment type', () => {
 	describe( 'Zip file attachment', () => {
 		it( 'should validate against real zip file attachment from REST API', () => {
 			const attachment: Attachment< 'edit' > =
-				zipAttachmentFixture as Attachment< 'edit' >;
+				zipAttachmentFixture as unknown as Attachment< 'edit' >;
 
 			// Edit-context fields
 			expect( attachment.permalink_template ).toBeDefined();
@@ -58,7 +58,7 @@ describe( 'Attachment type', () => {
 	describe( 'Audio file attachment', () => {
 		it( 'should validate against real audio attachment from REST API', () => {
 			const attachment: Attachment< 'edit' > =
-				audioAttachmentFixture as Attachment< 'edit' >;
+				audioAttachmentFixture as unknown as Attachment< 'edit' >;
 
 			// Edit-context fields
 			expect( attachment.permalink_template ).toBeDefined();
@@ -79,7 +79,7 @@ describe( 'Attachment type', () => {
 	describe( 'Video file attachment', () => {
 		it( 'should validate against real video attachment from REST API', () => {
 			const attachment: Attachment< 'edit' > =
-				videoAttachmentFixture as Attachment< 'edit' >;
+				videoAttachmentFixture as unknown as Attachment< 'edit' >;
 
 			// Edit-context fields
 			expect( attachment.permalink_template ).toBeDefined();

package/src/resolvers.js

@@ -26,6 +26,7 @@ import {
 	isNumericID,
 } from './utils';
 import { fetchBlockPatterns } from './fetch';
+import { restoreSelection, getSelectionHistory } from './utils/crdt-selection';
 
 /**
  * Requests authors from the REST API.
@@ -192,7 +193,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 +207,7 @@ export const getEntityRecord =
 									meta: {
 										undo: undefined,
 									},
+									options,
 								} );
 							},
 							// Get the current entity record (with edits)
@@ -232,6 +234,36 @@ export const getEntityRecord =
 									key
 								);
 							},
+							addUndoMeta: ( ydoc, meta ) => {
+								const selectionHistory =
+									getSelectionHistory( ydoc );
+
+								if ( selectionHistory ) {
+									meta.set(
+										'selectionHistory',
+										selectionHistory
+									);
+								}
+							},
+							restoreUndoMeta: ( ydoc, meta ) => {
+								const selectionHistory =
+									meta.get( 'selectionHistory' );
+
+								if ( selectionHistory ) {
+									// Because Yjs initiates an undo, we need to
+									// wait until the content is restored before
+									// we can update the selection.
+									// Use setTimeout() to wait until content is
+									// finished updating, and then set the correct
+									// selection.
+									setTimeout( () => {
+										restoreSelection(
+											selectionHistory,
+											ydoc
+										);
+									}, 0 );
+								}
+							},
 						}
 					);
 				}
@@ -430,6 +462,26 @@ export const getEntityRecords =
 				};
 			}
 
+			if ( globalThis.IS_GUTENBERG_PLUGIN ) {
+				if ( entityConfig.syncConfig && -1 === query.per_page ) {
+					const objectType = `${ kind }/${ name }`;
+					getSyncManager()?.loadCollection(
+						entityConfig.syncConfig,
+						objectType,
+						{
+							refetchRecords: async () => {
+								dispatch.receiveEntityRecords(
+									kind,
+									name,
+									await apiFetch( { path, parse: true } ),
+									query
+								);
+							},
+						}
+					);
+				}
+			}
+
 			// If we request fields but the result doesn't contain the fields,
 			// explicitly set these fields as "undefined"
 			// that way we consider the query "fulfilled".