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

packages/core-data/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)
@@ -232,6 +233,9 @@ export const getEntityRecord =
 									key
 								);
 							},
+							// Get the current user.
+							getCurrentUser: async () =>
+								await resolveSelect.getCurrentUser(),
 						}
 					);
 				}

packages/sync/package.json

@@ -44,6 +44,8 @@
 	"sideEffects": false,
 	"dependencies": {
 		"@types/diff": "7.0.2",
+		"@wordpress/block-editor": "file:../block-editor",
+		"@wordpress/data": "file:../data",
 		"@wordpress/hooks": "file:../hooks",
 		"@wordpress/undo-manager": "file:../undo-manager",
 		"@wordpress/url": "file:../url",

packages/sync/src/awareness/awareness-manager.ts

@@ -6,9 +6,11 @@ import type * as Y from 'yjs';
 /**
  * Internal dependencies
  */
-import type { ObjectID, ObjectType } from '../types';
+import type { ObjectID, ObjectType, RecordHandlers } from '../types';
 import type { AwarenessState } from './awareness-state';
 import { PostEditorAwarenessState } from './post-editor-awareness-state';
+import type { UserInfo, WordPressUserInfo } from './awareness-types';
+import { getBrowserName, getNewUserColor } from '../user-utils';
 
 const awarenessInstances: Map< string, AwarenessState > = new Map();
 
@@ -26,6 +28,28 @@ function getAwarenessInstance(
 	return awarenessInstances.get( getAwarenessId( objectType, objectId ) );
 }
 
+function getUserInfo(
+	awareness: AwarenessState,
+	wpUser: WordPressUserInfo
+): UserInfo {
+	const states = awareness.getStates();
+	// TODO: There is a timing issue here. The other users aren't yet synced, and as a result the same color could be assigned to multiple users.
+	const otherUserColors = Array.from( states.entries() )
+		.filter(
+			( [ clientId, state ] ) =>
+				state.userInfo && clientId !== awareness.clientID
+		)
+		.map( ( [ , state ] ) => state.userInfo.color )
+		.filter( Boolean );
+
+	return {
+		...wpUser,
+		browserType: getBrowserName(),
+		color: getNewUserColor( otherUserColors ),
+		enteredAt: Date.now(),
+	};
+}
+
 /**
  * Get the post editor awareness instance for the given post ID and post type.
  * @param postId   Post ID.
@@ -49,32 +73,41 @@ export function getPostEditorAwareness(
 
 /**
  * Create an awareness instance for the given object type and object ID.
- * @param objectType Object type.
- * @param objectId   Object ID.
- * @param ydoc       Yjs document.
+ * @param objectType     Object type.
+ * @param objectId       Object ID.
+ * @param ydoc           Yjs document.
+ * @param recordHandlers Record handlers.
  * @return Awareness instance.
  */
 export async function createAwareness(
 	objectType: ObjectType,
 	objectId: ObjectID | null,
-	ydoc: Y.Doc
+	ydoc: Y.Doc,
+	recordHandlers: RecordHandlers
 ): Promise< AwarenessState | undefined > {
 	if ( objectId && objectType.startsWith( 'postType/' ) ) {
 		const awareness = new PostEditorAwarenessState( ydoc );
-		awareness.setUp();
+
+		// TODO: Is there still a need to memoize the current user?
+		const currentUser = await recordHandlers.getCurrentUser();
+		const userInfo = getUserInfo( awareness, currentUser );
+
+		awareness.setUp( recordHandlers, userInfo );
 		awarenessInstances.set(
 			getAwarenessId( objectType, objectId ),
 			awareness
 		);
 
 		return awareness;
 	}
-
 	return undefined;
 }
 
 /**
  * Set the current user's connection status in the awareness instance for the given object type and object ID.
+ *
+ * TODO: Use this in a generic way with each provider so it doesn't need to be exported externally.
+ *
  * @param objectType  Object type.
  * @param objectId    Object ID.
  * @param isConnected Connection status.

packages/sync/src/awareness/awareness-state.ts

@@ -1,6 +1,7 @@
 /**
  * Internal dependencies
  */
+import type { UserInfo } from './awareness-types';
 import {
 	TypedAwareness,
 	type BaseState,
@@ -9,6 +10,7 @@ import {
 } from './awareness-types';
 import { getTypedKeys, areMapsEqual } from '../utils';
 import { REMOVAL_DELAY_IN_MS } from '../config';
+import type { RecordHandlers } from '../types';
 
 type AwarenessClientID = number;
 
@@ -28,8 +30,8 @@ abstract class AwarenessWithEqualityChecks<
 	 * trigger rerenders of any subscribed components.
 	 *
 	 * Equality checks are provided by the abstract `equalityFieldChecks` property.
-	 * @param field
-	 * @param value
+	 * @param field - The field to set.
+	 * @param value - The value to set.
 	 */
 	public setLocalStateField< FieldName extends string & keyof State >(
 		field: FieldName,
@@ -62,9 +64,9 @@ abstract class AwarenessWithEqualityChecks<
 
 	/**
 	 * Determine if a field value has changed using the provided equality checks.
-	 * @param field
-	 * @param value1
-	 * @param value2
+	 * @param field  - The field to check.
+	 * @param value1 - The first value to compare.
+	 * @param value2 - The second value to compare.
 	 */
 	protected isFieldEqual< FieldName extends keyof State >(
 		field: FieldName,
@@ -90,8 +92,8 @@ abstract class AwarenessWithEqualityChecks<
 	/**
 	 * Determine if two states are equal by comparing each field using the
 	 * provided equality checks.
-	 * @param state1
-	 * @param state2
+	 * @param state1 - The first state to compare.
+	 * @param state2 - The second state to compare.
 	 */
 	protected isStateEqual( state1: State, state2: State ): boolean {
 		return [
@@ -144,13 +146,18 @@ export abstract class AwarenessState<
 	 * value -- even if it hasn't yet been set on the awareness instance.
 	 */
 	private myThrottledState: Partial< State > = {};
+	private throttleTimeouts: Map< string, NodeJS.Timeout > = new Map();
 
 	/** CUSTOM METHODS */
 
 	/**
-	 * Set up.
+	 * Set up the awareness state.
+	 * @param _recordHandlers - Record handlers.
+	 * @param userInfo        - User info.
 	 */
-	public setUp(): void {
+	public setUp( _recordHandlers: RecordHandlers, userInfo: UserInfo ): void {
+		this.setLocalStateField( 'userInfo', userInfo );
+
 		this.on(
 			'change',
 			( { added, removed, updated }: AwarenessStateChange ) => {
@@ -183,7 +190,7 @@ export abstract class AwarenessState<
 
 	/**
 	 * Allow external code to subscribe to awareness state changes.
-	 * @param callback
+	 * @param callback - The callback to subscribe to.
 	 */
 	public onStateChange(
 		callback: ( newState: EnhancedState< State >[] ) => void
@@ -197,9 +204,37 @@ export abstract class AwarenessState<
 		};
 	}
 
+	/**
+	 * Set a local state field on an awareness document with throttle. See caveats
+	 * of this.setLocalStateField.
+	 * @param field - The field to set.
+	 * @param value - The value to set.
+	 * @param wait  - The wait time in milliseconds.
+	 */
+	public setThrottledLocalStateField<
+		FieldName extends string & keyof State,
+	>( field: FieldName, value: State[ FieldName ], wait: number ): void {
+		this.setLocalStateField( field, value );
+
+		this.throttleTimeouts.set(
+			field,
+			setTimeout( () => {
+				this.throttleTimeouts.delete( field );
+				if ( this.myThrottledState[ field ] ) {
+					this.setLocalStateField(
+						field,
+						this.myThrottledState[ field ]
+					);
+
+					delete this.myThrottledState[ field ];
+				}
+			}, wait )
+		);
+	}
+
 	/**
 	 * Set the current user's connection status as awareness state.
-	 * @param isConnected
+	 * @param isConnected - The connection status.
 	 */
 	public setConnectionStatus( isConnected: boolean ): void {
 		if ( isConnected ) {
@@ -213,7 +248,7 @@ export abstract class AwarenessState<
 
 	/**
 	 * Update all subscribed listeners with the latest awareness state.
-	 * @param forceUpdate
+	 * @param forceUpdate - Whether to force an update.
 	 */
 	protected updateSubscribers( forceUpdate = false ): void {
 		if ( ! this.stateSubscriptions.length ) {
@@ -228,8 +263,15 @@ export abstract class AwarenessState<
 		] );
 
 		const updatedStates = new Map< number, EnhancedState< State > >(
-			[ ...this.disconnectedUsers, ...states.keys() ].map(
-				( clientId ) => {
+			[ ...this.disconnectedUsers, ...states.keys() ]
+				.filter( ( clientId ) => {
+					// Exclude any users without `userInfo`.
+					// This can happen from the Yjs inspector, which joins the awareness
+					// state without providing user data.
+					return Boolean( this.seenStates.get( clientId )?.userInfo );
+				} )
+				.map( ( clientId ) => {
+					// The filter above ensures that seenStates has the clientId.
 					const rawState: State = this.seenStates.get( clientId )!;
 
 					const isConnected =
@@ -247,8 +289,7 @@ export abstract class AwarenessState<
 					};
 
 					return [ clientId, state ];
-				}
-			)
+				} )
 		);
 
 		if ( ! forceUpdate ) {

packages/sync/src/awareness/awareness-types.ts

@@ -1,6 +1,7 @@
 import { Awareness } from 'y-protocols/awareness';
 
 import { getRecordValue } from '../utils';
+import type { SelectionState } from '../selection-utils';
 
 /**
  * Extended Awareness class with typed state accessors.
@@ -37,14 +38,39 @@ export class TypedAwareness< State extends BaseState > extends Awareness {
 	}
 }
 
+/**
+ * This base user info is a subset of the User interface from @wordpress/core-data.
+ *
+ * In order to avoid circular dependencies, we define it here instead of importing
+ * the User interface from @wordpress/core-data.
+ *
+ * The avatarUrl is an additional field that is not part of the User interface.
+ */
+export interface WordPressUserInfo {
+	id: number;
+	name: string;
+	slug: string;
+	avatar_urls: Record< string, string >;
+}
+
+/**
+ * The user info interface extends the base user info with additional fields used for presence
+ * indicators.
+ */
+export interface UserInfo extends WordPressUserInfo {
+	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.
- *
- * TODO: Add in the user information.
  */
-export interface BaseState {}
+export interface BaseState {
+	userInfo: UserInfo;
+}
 
 /**
  * An enhanced state includes additional metadata about the user's connection
@@ -56,15 +82,44 @@ export type EnhancedState< State extends BaseState > = State & {
 	isMe: boolean;
 };
 
+/**
+ * A block selection object.
+ *
+ * In order to avoid circular dependencies, we define it here instead of importing
+ * the WPBlockSelection interface from @wordpress/editor.
+ */
+export type WPBlockSelection = {
+	/**
+	 * A block client ID.
+	 */
+	clientId: string;
+	/**
+	 * A block attribute key.
+	 */
+	attributeKey: string;
+	/**
+	 * An attribute value offset, based on the rich
+	 * text value. See `wp.richText.create`.
+	 */
+	offset: number;
+};
+
 export type EqualityFieldCheck<
 	State extends BaseState,
 	FieldName extends keyof State,
 > = ( value1?: State[ FieldName ], value2?: State[ FieldName ] ) => boolean;
 
+/**
+ * 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.
- *
- * TODO: Add in the presence indicators.
  */
-export interface PostEditorState extends BaseState {}
+export interface PostEditorState extends BaseState {
+	editorState?: EditorState;
+}