@wordpress/core-data 7.39.1-next.v.0 → 7.39.1-next.v.202602091733.0

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

@@ -22,7 +22,7 @@ import {
 
 import type { SelectionCursor, WPBlockSelection } from '../types';
 import type {
-	DebugUserData,
+	DebugCollaboratorData,
 	EditorState,
 	PostEditorState,
 	SerializableYItem,
@@ -47,13 +47,13 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 	protected onSetUp(): void {
 		super.onSetUp();
 
-		this.subscribeToUserSelectionChanges();
+		this.subscribeToCollaboratorSelectionChanges();
 	}
 
 	/**
-	 * Subscribe to user selection changes and update the selection state.
+	 * Subscribe to collaborator selection changes and update the selection state.
 	 */
-	private subscribeToUserSelectionChanges(): void {
+	private subscribeToCollaboratorSelectionChanges(): void {
 		const {
 			getSelectionStart,
 			getSelectionEnd,
@@ -116,7 +116,7 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 	}
 
 	/**
-	 * Update the entity record with the current user's selection.
+	 * Update the entity record with the current collaborator's selection.
 	 *
 	 * @param selectionStart  - The start position of the selection.
 	 * @param selectionEnd    - The end position of the selection.
@@ -213,14 +213,14 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 			] )
 		);
 
-		// Build userMap from awareness store (all users seen this session)
-		const userMapData = new Map< string, DebugUserData >(
+		// Build collaboratorMap from awareness store (all collaborators seen this session)
+		const collaboratorMapData = new Map< string, DebugCollaboratorData >(
 			Array.from( this.getSeenStates().entries() ).map(
-				( [ clientId, userState ] ) => [
+				( [ clientId, collaboratorState ] ) => [
 					String( clientId ),
 					{
-						name: userState.userInfo.name,
-						wpUserId: userState.userInfo.id,
+						name: collaboratorState.collaboratorInfo.name,
+						wpUserId: collaboratorState.collaboratorInfo.id,
 					},
 				]
 			)
@@ -264,7 +264,7 @@ export class PostEditorAwareness extends BaseAwarenessState< PostEditorState > {
 		return {
 			doc: docData,
 			clients: serializableClientItems,
-			userMap: Object.fromEntries( userMapData ),
+			collaboratorMap: Object.fromEntries( collaboratorMapData ),
 		};
 	}
 }

package/src/awareness/typed-awareness.ts

@@ -0,0 +1,44 @@
+/**
+ * External dependencies
+ */
+import { Awareness } from '@wordpress/sync';
+
+/**
+ * Internal dependencies
+ */
+import { getRecordValue } from './utils';
+
+/**
+ * Extended Awareness class with typed state accessors.
+ */
+export class TypedAwareness< State extends object > extends Awareness {
+	/**
+	 * Get the states from an awareness document.
+	 */
+	public getStates(): Map< number, State > {
+		return super.getStates() as Map< number, State >;
+	}
+
+	/**
+	 * Get a local state field from an awareness document.
+	 * @param field
+	 */
+	public getLocalStateField< FieldName extends keyof State >(
+		field: FieldName
+	): State[ FieldName ] | null {
+		const state: State | null = this.getLocalState() as State | null;
+		return getRecordValue< State, FieldName >( state, field );
+	}
+
+	/**
+	 * Set a local state field on an awareness document.
+	 * @param field
+	 * @param value
+	 */
+	public setLocalStateField< FieldName extends string & keyof State >(
+		field: FieldName,
+		value: State[ FieldName ]
+	): void {
+		super.setLocalStateField( field, value );
+	}
+}

package/src/awareness/types.ts

@@ -1,7 +1,7 @@
 /**
  * WordPress dependencies
  */
-import type { EnhancedState, Y } from '@wordpress/sync';
+import type { Y } from '@wordpress/sync';
 
 /**
  * Internal dependencies
@@ -9,7 +9,7 @@ import type { EnhancedState, Y } from '@wordpress/sync';
 import type { SelectionState } from '../types';
 import type { User } from '../entity-types';
 
-export type UserInfo = Pick<
+export type CollaboratorInfo = Pick<
 	User< 'view' >,
 	'id' | 'name' | 'slug' | 'avatar_urls'
 > & {
@@ -19,16 +19,16 @@ export type UserInfo = Pick<
 };
 
 /**
- * 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 base state represents the presence of the collaborator. We expect it to be
+ * extended to include additional state describing the collaborator's current activity.
  * This state must be serializable and compact.
  */
 export interface BaseState {
-	userInfo: UserInfo;
+	collaboratorInfo: CollaboratorInfo;
 }
 
 /**
- * The editor state includes information about the user's current selection.
+ * The editor state includes information about the collaborator's current selection.
  */
 export interface EditorState {
 	selection: SelectionState;
@@ -42,21 +42,30 @@ export interface PostEditorState extends BaseState {
 	editorState?: EditorState;
 }
 
+/**
+ * An enhanced state includes additional metadata about the collaborator's connection.
+ */
+export type EnhancedState< State > = State & {
+	clientId: number;
+	isConnected: boolean;
+	isMe: boolean;
+};
+
 /**
  * An enhanced post editor awareness state includes additional metadata about
- * the user and their connection.
+ * the collaborator and their connection.
  */
 export type PostEditorAwarenessState = EnhancedState< PostEditorState >;
 
-// WordPress user info for debug export (subset of UserInfo)
-export type DebugUserData = Pick< UserInfo, 'name' > & {
-	wpUserId: UserInfo[ 'id' ];
+// WordPress collaborator info for debug export (subset of CollaboratorInfo)
+export type DebugCollaboratorData = Pick< CollaboratorInfo, 'name' > & {
+	wpUserId: CollaboratorInfo[ 'id' ];
 };
 
 export interface YDocDebugData {
 	doc: Record< string, unknown >;
 	clients: Record< number, Array< SerializableYItem > >;
-	userMap: Record< string, DebugUserData >;
+	collaboratorMap: Record< string, DebugCollaboratorData >;
 }
 
 // Type for serializable left/right item references to avoid deep nesting
@@ -81,3 +90,8 @@ export type SerializableYItem = Pick<
 	left: SerializableYItemRef | null;
 	right: SerializableYItemRef | null;
 };
+
+export type EqualityFieldCheck< State, FieldName extends keyof State > = (
+	value1?: State[ FieldName ],
+	value2?: State[ FieldName ]
+) => boolean;

package/src/awareness/utils.ts

@@ -2,10 +2,10 @@
  * Internal dependencies
  */
 import type { User } from '../entity-types';
-import type { UserInfo } from './types';
+import type { CollaboratorInfo } from './types';
 
 /**
- * The color palette for the user highlight.
+ * The color palette for the collaborator highlight.
  */
 const COLOR_PALETTE = [
 	'#3858E9', // blueberry
@@ -30,13 +30,13 @@ function generateRandomInt( min: number, max: number ): number {
 }
 
 /**
- * Get a unique user color from the palette, or generate a variation if none are available.
+ * Get a unique collaborator 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.
+ * @return The new collaborator color, in hex format.
  */
-function getNewUserColor( existingColors: string[] ): string {
+function getNewCollaboratorColor( existingColors: string[] ): string {
 	const availableColors = COLOR_PALETTE.filter(
 		( color ) => ! existingColors.includes( color )
 	);
@@ -114,46 +114,86 @@ function getBrowserName(): string {
 	return browserName;
 }
 
+export function areMapsEqual< Key, Value >(
+	map1: Map< Key, Value >,
+	map2: Map< Key, Value >,
+	comparatorFn: ( value1: Value, value2: Value ) => boolean
+): boolean {
+	if ( map1.size !== map2.size ) {
+		return false;
+	}
+
+	for ( const [ key, value1 ] of map1.entries() ) {
+		if ( ! map2.has( key ) ) {
+			return false;
+		}
+
+		if ( ! comparatorFn( value1, map2.get( key )! ) ) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
 /**
- * Check if two user infos are equal.
+ * Check if two collaborator 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.
+ * @param collaboratorInfo1 - The first collaborator info.
+ * @param collaboratorInfo2 - The second collaborator info.
+ * @return True if the collaborator infos are equal, false otherwise.
  */
-export function areUserInfosEqual(
-	userInfo1?: UserInfo,
-	userInfo2?: UserInfo
+export function areCollaboratorInfosEqual(
+	collaboratorInfo1?: CollaboratorInfo,
+	collaboratorInfo2?: CollaboratorInfo
 ): boolean {
-	if ( ! userInfo1 || ! userInfo2 ) {
-		return userInfo1 === userInfo2;
+	if ( ! collaboratorInfo1 || ! collaboratorInfo2 ) {
+		return collaboratorInfo1 === collaboratorInfo2;
 	}
 
-	if ( Object.keys( userInfo1 ).length !== Object.keys( userInfo2 ).length ) {
+	if (
+		Object.keys( collaboratorInfo1 ).length !==
+		Object.keys( collaboratorInfo2 ).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 ];
+	return Object.entries( collaboratorInfo1 ).every( ( [ key, value ] ) => {
+		// Update this function with any non-primitive fields added to CollaboratorInfo.
+		return value === collaboratorInfo2[ key as keyof CollaboratorInfo ];
 	} );
 }
 
 /**
- * Generate a user info object from a current user and a list of existing colors.
+ * Generate a collaborator info object from a current collaborator and a list of existing colors.
  *
- * @param currentUser    - The current user.
- * @param existingColors - The existing colors.
- * @return The user info object.
+ * @param currentCollaborator - The current collaborator.
+ * @param existingColors      - The existing colors.
+ * @return The collaborator info object.
  */
-export function generateUserInfo(
-	currentUser: User< 'view' >,
+export function generateCollaboratorInfo(
+	currentCollaborator: User< 'view' >,
 	existingColors: string[]
-): UserInfo {
+): CollaboratorInfo {
 	return {
-		...currentUser,
+		...currentCollaborator,
 		browserType: getBrowserName(),
-		color: getNewUserColor( existingColors ),
+		color: getNewCollaboratorColor( existingColors ),
 		enteredAt: Date.now(),
 	};
 }
+
+export function getRecordValue< RecordType, Key extends keyof RecordType >(
+	obj: unknown,
+	key: Key
+): RecordType[ Key ] | null {
+	if ( 'object' === typeof obj && null !== obj && key in obj ) {
+		return ( obj as RecordType )[ key ];
+	}
+
+	return null;
+}
+
+export function getTypedKeys< T extends object >( obj: T ): Array< keyof T > {
+	return Object.keys( obj ) as Array< keyof T >;
+}

package/src/entities.js

@@ -374,7 +374,7 @@ async function loadPostTypeEntities() {
 				 *
 				 * @param {import('@wordpress/sync').CRDTDoc}  ydoc
 				 * @param {import('@wordpress/sync').ObjectID} objectId
-				 * @return {import('@wordpress/sync').AwarenessState} AwarenessState instance
+				 * @return {import('@wordpress/sync').Awareness} Awareness instance
 				 */
 				createAwareness: ( ydoc, objectId ) => {
 					const kind = 'postType';

package/src/hooks/use-post-editor-awareness-state.ts

@@ -8,43 +8,44 @@ import { useEffect, useState } from '@wordpress/element';
  */
 import { getSyncManager } from '../sync';
 import type {
-	PostEditorAwarenessState as ActiveUser,
+	PostEditorAwarenessState as ActiveCollaborator,
 	YDocDebugData,
 } from '../awareness/types';
 import type { SelectionCursor } from '../types';
 import type { PostEditorAwareness } from '../awareness/post-editor-awareness';
 
 interface AwarenessState {
-	activeUsers: ActiveUser[];
+	activeCollaborators: ActiveCollaborator[];
 	getAbsolutePositionIndex: ( selection: SelectionCursor ) => number | null;
 	getDebugData: () => YDocDebugData;
-	isCurrentUserDisconnected: boolean;
+	isCurrentCollaboratorDisconnected: boolean;
 }
 
 const defaultState: AwarenessState = {
-	activeUsers: [],
+	activeCollaborators: [],
 	getAbsolutePositionIndex: () => null,
 	getDebugData: () => ( {
 		doc: {},
 		clients: {},
-		userMap: {},
+		collaboratorMap: {},
 	} ),
-	isCurrentUserDisconnected: false,
+	isCurrentCollaboratorDisconnected: false,
 };
 
 function getAwarenessState(
 	awareness: PostEditorAwareness,
-	newState?: ActiveUser[]
+	newState?: ActiveCollaborator[]
 ): AwarenessState {
-	const activeUsers = newState ?? awareness.getCurrentState();
+	const activeCollaborators = newState ?? awareness.getCurrentState();
 
 	return {
-		activeUsers,
+		activeCollaborators,
 		getAbsolutePositionIndex: ( selection: SelectionCursor ) =>
 			awareness.getAbsolutePositionIndex( selection ),
 		getDebugData: () => awareness.getDebugData(),
-		isCurrentUserDisconnected:
-			activeUsers.find( ( user ) => user.isMe )?.isConnected === false,
+		isCurrentCollaboratorDisconnected:
+			activeCollaborators.find( ( collaborator ) => collaborator.isMe )
+				?.isConnected === false,
 	};
 }
 
@@ -78,7 +79,7 @@ function usePostEditorAwarenessState(
 		setState( getAwarenessState( awareness ) );
 
 		const unsubscribe = awareness?.onStateChange(
-			( newState: ActiveUser[] ) => {
+			( newState: ActiveCollaborator[] ) => {
 				setState( getAwarenessState( awareness, newState ) );
 			}
 		);
@@ -90,17 +91,17 @@ function usePostEditorAwarenessState(
 }
 
 /**
- * Hook to get the active users for a post editor.
+ * Hook to get the active collaborators for a post editor.
  *
  * @param  postId   - The ID of the post.
  * @param  postType - The type of the post.
- * @return {ActiveUser[]} The active users.
+ * @return {ActiveCollaborator[]} The active collaborators.
  */
-export function useActiveUsers(
+export function useActiveCollaborators(
 	postId: number | null,
 	postType: string | null
-): ActiveUser[] {
-	return usePostEditorAwarenessState( postId, postType ).activeUsers;
+): ActiveCollaborator[] {
+	return usePostEditorAwarenessState( postId, postType ).activeCollaborators;
 }
 
 /**
@@ -133,16 +134,16 @@ export function useGetDebugData(
 }
 
 /**
- * Hook to check if the current user is disconnected.
+ * Hook to check if the current collaborator is disconnected.
  *
  * @param  postId   - The ID of the post.
  * @param  postType - The type of the post.
- * @return {boolean} Whether the current user is disconnected.
+ * @return {boolean} Whether the current collaborator is disconnected.
  */
 export function useIsDisconnected(
 	postId: number | null,
 	postType: string | null
 ): boolean {
 	return usePostEditorAwarenessState( postId, postType )
-		.isCurrentUserDisconnected;
+		.isCurrentCollaboratorDisconnected;
 }

package/src/index.js

@@ -136,6 +136,7 @@ register( store ); // Register store after unlocking private selectors to allow
 export { default as EntityProvider } from './entity-provider';
 export * from './entity-provider';
 export * from './entity-types';
+export * from './awareness/types';
 export * from './fetch';
 export * from './hooks';
 export * from './private-apis';

package/src/private-apis.js

@@ -3,10 +3,12 @@
  */
 import { useEntityRecordsWithPermissions } from './hooks/use-entity-records';
 import { RECEIVE_INTERMEDIATE_RESULTS } from './utils';
+import { useActiveCollaborators } from './hooks/use-post-editor-awareness-state';
 import { lock } from './lock-unlock';
 
 export const privateApis = {};
 lock( privateApis, {
 	useEntityRecordsWithPermissions,
 	RECEIVE_INTERMEDIATE_RESULTS,
+	useActiveCollaborators,
 } );

package/src/sync.ts

@@ -2,16 +2,27 @@
  * WordPress dependencies
  */
 import {
+	privateApis as syncPrivateApis,
+	type SyncManager,
+} from '@wordpress/sync';
+
+/**
+ * Internal dependencies
+ */
+import { unlock } from './lock-unlock';
+
+const {
+	createSyncManager,
+	Delta,
 	CRDT_DOC_META_PERSISTENCE_KEY,
 	CRDT_RECORD_MAP_KEY,
 	LOCAL_EDITOR_ORIGIN,
 	LOCAL_SYNC_MANAGER_ORIGIN,
 	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
-	type SyncManager,
-	createSyncManager,
-} from '@wordpress/sync';
+} = unlock( syncPrivateApis );
 
 export {
+	Delta,
 	CRDT_DOC_META_PERSISTENCE_KEY,
 	CRDT_RECORD_MAP_KEY,
 	LOCAL_EDITOR_ORIGIN,

package/src/utils/crdt-blocks.ts

@@ -10,12 +10,13 @@ import fastDeepEqual from 'fast-deep-equal/es6/index.js';
 // @ts-expect-error No exported types.
 import { getBlockTypes } from '@wordpress/blocks';
 import { RichTextData } from '@wordpress/rich-text';
-import { Y, Delta } from '@wordpress/sync';
+import { Y } from '@wordpress/sync';
 
 /**
  * Internal dependencies
  */
 import { createYMap, type YMapRecord, type YMapWrap } from './crdt-utils';
+import { Delta } from '../sync';
 
 interface BlockAttributes {
 	[ key: string ]: unknown;

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

@@ -1,11 +1,12 @@
 /**
- * External dependencies
+ * WordPress dependencies
  */
-import { Y, CRDT_RECORD_MAP_KEY } from '@wordpress/sync';
+import { Y } from '@wordpress/sync';
 
 /**
  * Internal dependencies
  */
+import { CRDT_RECORD_MAP_KEY } from '../sync';
 import type { YPostRecord } from './crdt';
 import type { YBlock, YBlocks } from './crdt-blocks';
 import { getRootMap } from './crdt-utils';

package/src/utils/crdt.ts

@@ -19,7 +19,6 @@ import {
  * Internal dependencies
  */
 import { BaseAwareness } from '../awareness/base-awareness';
-import { type BaseState } from '../awareness/types';
 import {
 	mergeCrdtBlocks,
 	type Block,
@@ -409,7 +408,7 @@ export function getPostChangesFromCRDTDoc(
  * This default sync config can be used for entities that are flat maps of
  * primitive values and do not require custom logic to merge changes.
  */
-export const defaultSyncConfig: SyncConfig< BaseState > = {
+export const defaultSyncConfig: SyncConfig = {
 	applyChangesToCRDTDoc: defaultApplyChangesToCRDTDoc,
 	createAwareness: ( ydoc: CRDTDoc ) => new BaseAwareness( ydoc ),
 	getChangesFromCRDTDoc: defaultGetChangesFromCRDTDoc,

package/src/utils/test/crdt.ts

@@ -1,11 +1,7 @@
 /**
  * WordPress dependencies
  */
-import {
-	CRDT_RECORD_MAP_KEY,
-	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
-	Y,
-} from '@wordpress/sync';
+import { Y } from '@wordpress/sync';
 
 /**
  * External dependencies
@@ -15,6 +11,10 @@ import { describe, expect, it, jest, beforeEach } from '@jest/globals';
 /**
  * Internal dependencies
  */
+import {
+	CRDT_RECORD_MAP_KEY,
+	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
+} from '../../sync';
 import {
 	applyPostChangesToCRDTDoc,
 	getPostChangesFromCRDTDoc,