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/awareness/config.ts

@@ -0,0 +1,9 @@
+/**
+ * Delay in milliseconds before throttling the cursor position updates.
+ */
+export const AWARENESS_CURSOR_UPDATE_THROTTLE_IN_MS = 100;
+
+/**
+ * Delay in milliseconds before updating the cursor position.
+ */
+export const LOCAL_CURSOR_UPDATE_DEBOUNCE_IN_MS = 5;

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

@@ -0,0 +1,187 @@
+/**
+ * WordPress dependencies
+ */
+import { dispatch, select, subscribe } from '@wordpress/data';
+import { AwarenessState, 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 {
+	AWARENESS_CURSOR_UPDATE_THROTTLE_IN_MS,
+	LOCAL_CURSOR_UPDATE_DEBOUNCE_IN_MS,
+} from './config';
+import { STORE_NAME as coreStore } from '../name';
+import { generateUserInfo, areUserInfosEqual } from './utils';
+import {
+	areSelectionsStatesEqual,
+	getSelectionState,
+} from '../utils/crdt-user-selections';
+
+import type { WPBlockSelection } from '../types';
+import type { EditorState, PostEditorState } from './types';
+
+export class PostEditorAwareness extends AwarenessState< PostEditorState > {
+	protected equalityFieldChecks = {
+		editorState: this.areEditorStatesEqual,
+		userInfo: areUserInfosEqual,
+	};
+
+	public constructor(
+		doc: Y.Doc,
+		private kind: string,
+		private name: string,
+		private postId: number
+	) {
+		super( doc );
+	}
+
+	public setUp(): void {
+		super.setUp();
+
+		this.setCurrentUserInfo();
+		this.subscribeToUserSelectionChanges();
+	}
+
+	/**
+	 * Set the current user info in the local state.
+	 */
+	private setCurrentUserInfo(): void {
+		const states = this.getStates();
+		const otherUserColors = Array.from( states.entries() )
+			.filter(
+				( [ clientId, state ] ) =>
+					state.userInfo && clientId !== this.clientID
+			)
+			.map( ( [ , state ] ) => state.userInfo.color )
+			.filter( Boolean );
+
+		// Get current user info and set it in local state.
+		const currentUser = select( coreStore ).getCurrentUser();
+		const userInfo = generateUserInfo( currentUser, otherUserColors );
+		this.setLocalStateField( 'userInfo', userInfo );
+	}
+
+	/**
+	 * 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 );
+	}
+}

packages/core-data/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;
+}