Real-time Collaboration: Add user and selection information to awareness

packages/core-data/package.json

@@ -72,6 +72,7 @@
 		"uuid": "^9.0.1"
 	},
 	"devDependencies": {
+		"@types/node": "^20.17.10",
 		"deep-freeze": "0.0.1"
 	},
 	"peerDependencies": {

packages/core-data/src/entities.js

@@ -9,6 +9,7 @@ import { capitalCase, pascalCase } from 'change-case';
 import apiFetch from '@wordpress/api-fetch';
 import { __unstableSerializeAndClean, parse } from '@wordpress/blocks';
 import { __ } from '@wordpress/i18n';
+import { generateUserInfo } from '@wordpress/sync';
 
 /**
  * Internal dependencies
@@ -18,6 +19,7 @@ import {
 	applyPostChangesToCRDTDoc,
 	getPostChangesFromCRDTDoc,
 } from './utils/crdt';
+import { PostEditorAwareness } from './post-editor-awareness';
 
 export const DEFAULT_ENTITY_KEY = 'id';
 const POST_RAW_ATTRIBUTES = [ 'title', 'excerpt', 'content' ];
@@ -381,6 +383,29 @@ async function loadPostTypeEntities() {
 				supports: {
 					crdtPersistence: true,
 				},
+
+				createAwareness: ( ydoc, recordHandlers, currentUser ) => {
+					const awareness = new PostEditorAwareness( ydoc );
+
+					const states = awareness.getStates();
+					const otherUserColors = Array.from( states.entries() )
+						.filter(
+							( [ clientId, state ] ) =>
+								state.userInfo &&
+								clientId !== awareness.clientID
+						)
+						.map( ( [ , state ] ) => state.userInfo.color )
+						.filter( Boolean );
+
+					const userInfo = generateUserInfo(
+						currentUser,
+						otherUserColors
+					);
+
+					awareness.setUp( recordHandlers, userInfo );
+
+					return awareness;
+				},
 			};
 		}
 

packages/core-data/src/post-editor-awareness.ts

@@ -0,0 +1,157 @@
+/**
+ * WordPress dependencies
+ */
+import { select, subscribe } from '@wordpress/data';
+import {
+	LOCAL_CURSOR_UPDATE_DEBOUNCE_IN_MS,
+	AWARENESS_CURSOR_UPDATE_THROTTLE_IN_MS,
+	type RecordHandlers,
+	AwarenessState,
+	type UserInfo,
+	areUserInfosEqual,
+} from '@wordpress/sync';
+// @ts-ignore No exported types for block editor store selectors.
+import { store as blockEditorStore } from '@wordpress/block-editor';
+
+/**
+ * Internal dependencies
+ */
+import {
+	areSelectionsStatesEqual,
+	getSelectionState,
+} from './utils/crdt-user-selections';
+import type { WPBlockSelection, PostEditorState, EditorState } from './types';
+
+export class PostEditorAwareness extends AwarenessState< PostEditorState > {
+	protected equalityFieldChecks = {
+		editorState: this.areEditorStatesEqual,
+		userInfo: areUserInfosEqual,
+	};
+
+	public setUp( recordHandlers: RecordHandlers, userInfo: UserInfo ): void {
+		super.setUp( recordHandlers, userInfo );
+
+		this.subscribeToUserSelectionChanges( recordHandlers );
+	}
+
+	/**
+	 * Subscribe to user selection changes and update the selection state.
+	 *
+	 * @param recordHandlers - The record handlers.
+	 */
+	private subscribeToUserSelectionChanges(
+		recordHandlers: RecordHandlers
+	): 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(
+				recordHandlers,
+				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 recordHandlers
+	 * @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(
+		recordHandlers: RecordHandlers,
+		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,
+		};
+
+		recordHandlers.editRecord( 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 );
+	}
+}

packages/core-data/src/resolvers.js

@@ -184,6 +184,8 @@ export const getEntityRecord =
 								transientConfig.read( recordWithTransients );
 						} );
 
+					const currentUser = await resolveSelect.getCurrentUser();
+
 					// Load the entity record for syncing.
 					await getSyncManager()?.load(
 						entityConfig.syncConfig,
@@ -192,7 +194,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 +208,7 @@ export const getEntityRecord =
 									meta: {
 										undo: undefined,
 									},
+									options,
 								} );
 							},
 							// Get the current entity record (with edits)
@@ -232,7 +235,8 @@ export const getEntityRecord =
 									key
 								);
 							},
-						}
+						},
+						currentUser
 					);
 				}
 			}

packages/core-data/src/types.ts

@@ -1,3 +1,8 @@
+/**
+ * External dependencies
+ */
+import type { Y, BaseState } from '@wordpress/sync';
+
 export interface AnyFunction {
 	( ...args: any[] ): any;
 }
@@ -13,3 +18,104 @@ export interface WPSelection {
 	selectionEnd: WPBlockSelection;
 	selectionStart: WPBlockSelection;
 }
+
+/**
+ * Convenience types to manage block values with a clientId, attributes, and innerBlocks.
+ */
+export type BlockInnerBlocks = Y.Array< SelectableBlock >;
+type BlockClientId = string;
+type BlockAttributes = Y.Map< Y.Text >;
+
+/**
+ * A block that can be selected.
+ */
+export type SelectableBlock = Y.Map<
+	BlockClientId | BlockAttributes | BlockInnerBlocks
+>;
+
+/**
+ * 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;
+
+/**
+ * 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;
+}