@wordpress/core-data 7.41.2-next.v.202603102151.0 → 7.42.0

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

@@ -11,6 +11,9 @@ import {
 	useResolvedSelection,
 	useGetDebugData,
 	useIsDisconnected,
+	useOnCollaboratorJoin,
+	useOnCollaboratorLeave,
+	useOnPostSave,
 } from '../use-post-editor-awareness-state';
 import { getSyncManager } from '../../sync';
 import { SelectionType } from '../../utils/crdt-user-selections';
@@ -66,6 +69,9 @@ describe( 'use-post-editor-awareness-state hooks', () => {
 		onStateChange: jest.Mock;
 		convertSelectionStateToAbsolute: jest.Mock;
 		getDebugData: jest.Mock;
+		doc: {
+			getMap: jest.Mock;
+		};
 	};
 	let mockSyncManager: {
 		getAwareness: jest.Mock;
@@ -73,9 +79,29 @@ describe( 'use-post-editor-awareness-state hooks', () => {
 	let stateChangeCallback:
 		| ( ( newState: PostEditorAwarenessState[] ) => void )
 		| null;
+	let stateMapObserver:
+		| ( ( event: { keysChanged: Set< string > } ) => void )
+		| null;
+	let mockStateMapData: Record< string, unknown >;
+	let mockRecordMapData: Record< string, unknown >;
 
 	beforeEach( () => {
 		stateChangeCallback = null;
+		stateMapObserver = null;
+		mockStateMapData = {};
+		mockRecordMapData = {};
+
+		const mockStateMap = {
+			get: jest.fn( ( key: string ) => mockStateMapData[ key ] ),
+			observe: jest.fn( ( observer: typeof stateMapObserver ) => {
+				stateMapObserver = observer;
+			} ),
+			unobserve: jest.fn(),
+		};
+
+		const mockRecordMap = {
+			get: jest.fn( ( key: string ) => mockRecordMapData[ key ] ),
+		};
 
 		mockAwareness = {
 			setUp: jest.fn(),
@@ -86,6 +112,17 @@ describe( 'use-post-editor-awareness-state hooks', () => {
 			} ),
 			convertSelectionStateToAbsolute: jest.fn().mockReturnValue( null ),
 			getDebugData: jest.fn().mockReturnValue( createMockDebugData() ),
+			doc: {
+				getMap: jest.fn( ( name: string ) => {
+					if ( name === 'state' ) {
+						return mockStateMap;
+					}
+					if ( name === 'document' ) {
+						return mockRecordMap;
+					}
+					return null;
+				} ),
+			},
 		};
 
 		mockSyncManager = {
@@ -256,7 +293,7 @@ describe( 'use-post-editor-awareness-state hooks', () => {
 			};
 
 			expect( result.current( mockSelection ) ).toEqual( {
-				textIndex: null,
+				richTextOffset: null,
 				localClientId: null,
 			} );
 		} );
@@ -270,7 +307,7 @@ describe( 'use-post-editor-awareness-state hooks', () => {
 				},
 			};
 			mockAwareness.convertSelectionStateToAbsolute.mockReturnValue( {
-				textIndex: 10,
+				richTextOffset: 10,
 				localClientId: 'block-1',
 			} );
 
@@ -284,7 +321,7 @@ describe( 'use-post-editor-awareness-state hooks', () => {
 				mockAwareness.convertSelectionStateToAbsolute
 			).toHaveBeenCalledWith( mockSelection );
 			expect( position ).toEqual( {
-				textIndex: 10,
+				richTextOffset: 10,
 				localClientId: 'block-1',
 			} );
 		} );
@@ -481,4 +518,410 @@ describe( 'use-post-editor-awareness-state hooks', () => {
 			expect( result.current ).toBe( false );
 		} );
 	} );
+
+	describe( 'useOnCollaboratorJoin', () => {
+		const me = createMockActiveUser( {
+			clientId: 1,
+			isMe: true,
+			collaboratorInfo: {
+				id: 1,
+				name: 'Me',
+				slug: 'me',
+				avatar_urls: mockAvatarUrls,
+				browserType: 'Chrome',
+				enteredAt: 1704067200000,
+			},
+		} );
+
+		const alice = createMockActiveUser( {
+			clientId: 2,
+			isMe: false,
+			collaboratorInfo: {
+				id: 100,
+				name: 'Alice',
+				slug: 'alice',
+				avatar_urls: mockAvatarUrls,
+				browserType: 'Chrome',
+				enteredAt: 1704067300000,
+			},
+		} );
+
+		test( 'should not fire on initial mount', () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [ me, alice ] );
+
+			renderHook( () => useOnCollaboratorJoin( 123, 'post', callback ) );
+
+			expect( callback ).not.toHaveBeenCalled();
+		} );
+
+		test( 'should not fire when collaborators load after initially empty state', async () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [] );
+
+			renderHook( () => useOnCollaboratorJoin( 123, 'post', callback ) );
+
+			// Simulate store hydration: collaborators appear
+			act( () => {
+				stateChangeCallback?.( [ me, alice ] );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).not.toHaveBeenCalled();
+			} );
+		} );
+
+		test( 'should fire callback when a new collaborator joins', async () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [ me ] );
+
+			renderHook( () => useOnCollaboratorJoin( 123, 'post', callback ) );
+
+			// Alice joins
+			act( () => {
+				stateChangeCallback?.( [ me, alice ] );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).toHaveBeenCalledWith( alice, me );
+			} );
+		} );
+
+		test( 'should not fire callback for the current user', async () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [] );
+
+			renderHook( () => useOnCollaboratorJoin( 123, 'post', callback ) );
+
+			// First: hydrate with alice so prevCollaborators is non-empty
+			act( () => {
+				stateChangeCallback?.( [ alice ] );
+			} );
+
+			// Now "me" appears
+			act( () => {
+				stateChangeCallback?.( [ alice, me ] );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).not.toHaveBeenCalled();
+			} );
+		} );
+
+		test( 'should not fire when postId is null', () => {
+			const callback = jest.fn();
+
+			renderHook( () => useOnCollaboratorJoin( null, 'post', callback ) );
+
+			expect( callback ).not.toHaveBeenCalled();
+			expect( mockSyncManager.getAwareness ).not.toHaveBeenCalled();
+		} );
+	} );
+
+	describe( 'useOnCollaboratorLeave', () => {
+		const me = createMockActiveUser( {
+			clientId: 1,
+			isMe: true,
+		} );
+
+		const alice = createMockActiveUser( {
+			clientId: 2,
+			isMe: false,
+			isConnected: true,
+			collaboratorInfo: {
+				id: 100,
+				name: 'Alice',
+				slug: 'alice',
+				avatar_urls: mockAvatarUrls,
+				browserType: 'Chrome',
+				enteredAt: 1704067300000,
+			},
+		} );
+
+		test( 'should fire callback when a connected collaborator disconnects', async () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [ me, alice ] );
+
+			renderHook( () => useOnCollaboratorLeave( 123, 'post', callback ) );
+
+			// Alice disconnects
+			act( () => {
+				stateChangeCallback?.( [
+					me,
+					{ ...alice, isConnected: false },
+				] );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).toHaveBeenCalledWith( alice );
+			} );
+		} );
+
+		test( 'should fire callback when a connected collaborator disappears from the list', async () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [ me, alice ] );
+
+			renderHook( () => useOnCollaboratorLeave( 123, 'post', callback ) );
+
+			// Alice disappears entirely
+			act( () => {
+				stateChangeCallback?.( [ me ] );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).toHaveBeenCalledWith( alice );
+			} );
+		} );
+
+		test( 'should not fire callback when an already-disconnected collaborator is removed', async () => {
+			const callback = jest.fn();
+			const disconnectedAlice = { ...alice, isConnected: false };
+			mockAwareness.getCurrentState.mockReturnValue( [
+				me,
+				disconnectedAlice,
+			] );
+
+			renderHook( () => useOnCollaboratorLeave( 123, 'post', callback ) );
+
+			// Disconnected Alice is removed from list (cleanup after delay)
+			act( () => {
+				stateChangeCallback?.( [ me ] );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).not.toHaveBeenCalled();
+			} );
+		} );
+
+		test( 'should not fire callback for the current user disconnecting', async () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [ me, alice ] );
+
+			renderHook( () => useOnCollaboratorLeave( 123, 'post', callback ) );
+
+			// "Me" disconnects
+			act( () => {
+				stateChangeCallback?.( [
+					{ ...me, isConnected: false },
+					alice,
+				] );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).not.toHaveBeenCalled();
+			} );
+		} );
+
+		test( 'should not fire on initial mount', () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [ me, alice ] );
+
+			renderHook( () => useOnCollaboratorLeave( 123, 'post', callback ) );
+
+			expect( callback ).not.toHaveBeenCalled();
+		} );
+	} );
+
+	describe( 'useOnPostSave', () => {
+		const me = createMockActiveUser( {
+			clientId: 1,
+			isMe: true,
+		} );
+
+		const alice = createMockActiveUser( {
+			clientId: 2,
+			isMe: false,
+			collaboratorInfo: {
+				id: 100,
+				name: 'Alice',
+				slug: 'alice',
+				avatar_urls: mockAvatarUrls,
+				browserType: 'Chrome',
+				enteredAt: 1704067300000,
+			},
+		} );
+
+		test( 'should fire callback when a remote collaborator saves', async () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [ me, alice ] );
+
+			renderHook( () => useOnPostSave( 123, 'post', callback ) );
+
+			// Simulate a save event via the Y.Doc state map
+			const savedAt = Date.now() + 1000;
+			mockStateMapData = {
+				savedAt,
+				savedBy: alice.clientId,
+			};
+			mockRecordMapData = { status: 'draft' };
+
+			act( () => {
+				stateMapObserver?.( {
+					keysChanged: new Set( [ 'savedAt' ] ),
+				} );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).toHaveBeenCalledWith(
+					{
+						savedAt,
+						savedByClientId: alice.clientId,
+						postStatus: 'draft',
+					},
+					alice,
+					null
+				);
+			} );
+		} );
+
+		test( 'should pass previous save event on subsequent saves', async () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [ me, alice ] );
+
+			renderHook( () => useOnPostSave( 123, 'post', callback ) );
+
+			// First save
+			const firstSavedAt = Date.now() + 1000;
+			mockStateMapData = {
+				savedAt: firstSavedAt,
+				savedBy: alice.clientId,
+			};
+			mockRecordMapData = { status: 'draft' };
+
+			act( () => {
+				stateMapObserver?.( {
+					keysChanged: new Set( [ 'savedAt' ] ),
+				} );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).toHaveBeenCalledTimes( 1 );
+			} );
+
+			// Second save
+			const secondSavedAt = Date.now() + 2000;
+			mockStateMapData = {
+				savedAt: secondSavedAt,
+				savedBy: alice.clientId,
+			};
+			mockRecordMapData = { status: 'publish' };
+
+			act( () => {
+				stateMapObserver?.( {
+					keysChanged: new Set( [ 'savedAt' ] ),
+				} );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).toHaveBeenCalledTimes( 2 );
+			} );
+
+			expect( callback ).toHaveBeenLastCalledWith(
+				{
+					savedAt: secondSavedAt,
+					savedByClientId: alice.clientId,
+					postStatus: 'publish',
+				},
+				alice,
+				{
+					savedAt: firstSavedAt,
+					savedByClientId: alice.clientId,
+					postStatus: 'draft',
+				}
+			);
+		} );
+
+		test( 'should not fire callback when the current user saves', async () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [ me, alice ] );
+
+			renderHook( () => useOnPostSave( 123, 'post', callback ) );
+
+			// Simulate a save event by "me"
+			const savedAt = Date.now() + 1000;
+			mockStateMapData = {
+				savedAt,
+				savedBy: me.clientId,
+			};
+			mockRecordMapData = { status: 'draft' };
+
+			act( () => {
+				stateMapObserver?.( {
+					keysChanged: new Set( [ 'savedAt' ] ),
+				} );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).not.toHaveBeenCalled();
+			} );
+		} );
+
+		test( 'should not fire callback when saver is not in the collaborator list', async () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [ me ] );
+
+			renderHook( () => useOnPostSave( 123, 'post', callback ) );
+
+			// Simulate a save from an unknown client
+			const savedAt = Date.now() + 1000;
+			mockStateMapData = {
+				savedAt,
+				savedBy: 99999,
+			};
+			mockRecordMapData = { status: 'draft' };
+
+			act( () => {
+				stateMapObserver?.( {
+					keysChanged: new Set( [ 'savedAt' ] ),
+				} );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).not.toHaveBeenCalled();
+			} );
+		} );
+
+		test( 'should not fire duplicate callbacks for the same savedAt timestamp', async () => {
+			const callback = jest.fn();
+			mockAwareness.getCurrentState.mockReturnValue( [ me, alice ] );
+
+			renderHook( () => useOnPostSave( 123, 'post', callback ) );
+
+			const savedAt = Date.now() + 1000;
+			mockStateMapData = {
+				savedAt,
+				savedBy: alice.clientId,
+			};
+			mockRecordMapData = { status: 'draft' };
+
+			// First save event
+			act( () => {
+				stateMapObserver?.( {
+					keysChanged: new Set( [ 'savedAt' ] ),
+				} );
+			} );
+
+			await waitFor( () => {
+				expect( callback ).toHaveBeenCalledTimes( 1 );
+			} );
+
+			// Same savedAt again (e.g. component re-render)
+			act( () => {
+				stateMapObserver?.( {
+					keysChanged: new Set( [ 'savedAt' ] ),
+				} );
+			} );
+
+			// Should still be 1 call
+			expect( callback ).toHaveBeenCalledTimes( 1 );
+		} );
+
+		test( 'should not fire when postId is null', () => {
+			const callback = jest.fn();
+
+			renderHook( () => useOnPostSave( null, 'post', callback ) );
+
+			expect( callback ).not.toHaveBeenCalled();
+		} );
+	} );
 } );

package/src/hooks/use-entity-prop.js

@@ -50,6 +50,8 @@ export default function useEntityProp( kind, name, prop, _id ) {
 					{
 						per_page: -1,
 						context: 'edit',
+						_fields:
+							'id,date,author,meta,title.raw,excerpt.raw,content.raw',
 					}
 				);
 				const entityConfig = select( STORE_NAME ).getEntityConfig(

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

@@ -1,6 +1,7 @@
 /**
  * External dependencies
  */
+import { usePrevious } from '@wordpress/compose';
 import { useEffect, useState } from '@wordpress/element';
 import type { Y } from '@wordpress/sync';
 
@@ -13,14 +14,9 @@ import type {
 	PostSaveEvent,
 	YDocDebugData,
 } from '../awareness/types';
-import type { SelectionState } from '../types';
+import type { SelectionState, ResolvedSelection } from '../types';
 import type { PostEditorAwareness } from '../awareness/post-editor-awareness';
 
-interface ResolvedSelection {
-	textIndex: number | null;
-	localClientId: string | null;
-}
-
 interface AwarenessState {
 	activeCollaborators: ActiveCollaborator[];
 	resolveSelection: ( selection: SelectionState ) => ResolvedSelection;
@@ -29,7 +25,7 @@ interface AwarenessState {
 }
 
 const defaultResolvedSelection: ResolvedSelection = {
-	textIndex: null,
+	richTextOffset: null,
 	localClientId: null,
 };
 
@@ -167,7 +163,7 @@ export function useIsDisconnected(
  * @param postId   The ID of the post.
  * @param postType The type of the post.
  */
-export function useLastPostSave(
+function useLastPostSave(
 	postId: number | null,
 	postType: string | null
 ): PostSaveEvent | null {
@@ -226,3 +222,159 @@ export function useLastPostSave(
 
 	return lastSave;
 }
+
+/**
+ * Hook that fires a callback when a new collaborator joins the post.
+ * Handles initial hydration and state diffing internally—consumers
+ * only receive "join" events for collaborators that appear after the
+ * initial state has loaded.
+ *
+ * The callback receives the joining collaborator and, when available,
+ * the current user's state (useful for comparing `enteredAt` timestamps).
+ *
+ * @param postId   The ID of the post.
+ * @param postType The type of the post.
+ * @param callback Invoked for each collaborator that joins.
+ */
+export function useOnCollaboratorJoin(
+	postId: number | null,
+	postType: string | null,
+	callback: (
+		collaborator: ActiveCollaborator,
+		me?: ActiveCollaborator
+	) => void
+): void {
+	const { activeCollaborators } = usePostEditorAwarenessState(
+		postId,
+		postType
+	);
+	const prevCollaborators = usePrevious( activeCollaborators );
+
+	useEffect( () => {
+		/*
+		 * On first render usePrevious returns undefined. On subsequent
+		 * renders the list may still be empty while the store hydrates.
+		 * In both cases, skip to avoid spurious "joined" callbacks for
+		 * users already present.
+		 */
+		if ( ! prevCollaborators || prevCollaborators.length === 0 ) {
+			return;
+		}
+
+		const prevMap = new Map< number, ActiveCollaborator >(
+			prevCollaborators.map( ( collaborator ) => [
+				collaborator.clientId,
+				collaborator,
+			] )
+		);
+		const me = activeCollaborators.find(
+			( collaborator ) => collaborator.isMe
+		);
+
+		for ( const collaborator of activeCollaborators ) {
+			if (
+				! prevMap.has( collaborator.clientId ) &&
+				! collaborator.isMe
+			) {
+				callback( collaborator, me );
+			}
+		}
+	}, [ activeCollaborators, prevCollaborators, callback ] );
+}
+
+/**
+ * Hook that fires a callback when a collaborator leaves the post.
+ * A "leave" is detected when a previously-connected collaborator either
+ * transitions to `isConnected = false` or disappears from the list
+ * entirely while still connected. Already-disconnected collaborators
+ * that are later removed from the list are silently ignored.
+ *
+ * @param postId   The ID of the post.
+ * @param postType The type of the post.
+ * @param callback Invoked for each collaborator that leaves.
+ */
+export function useOnCollaboratorLeave(
+	postId: number | null,
+	postType: string | null,
+	callback: ( collaborator: ActiveCollaborator ) => void
+): void {
+	const { activeCollaborators } = usePostEditorAwarenessState(
+		postId,
+		postType
+	);
+	const prevCollaborators = usePrevious( activeCollaborators );
+
+	useEffect( () => {
+		if ( ! prevCollaborators || prevCollaborators.length === 0 ) {
+			return;
+		}
+
+		const newMap = new Map< number, ActiveCollaborator >(
+			activeCollaborators.map( ( collaborator ) => [
+				collaborator.clientId,
+				collaborator,
+			] )
+		);
+
+		for ( const prevCollab of prevCollaborators ) {
+			if ( prevCollab.isMe || ! prevCollab.isConnected ) {
+				continue;
+			}
+
+			const newCollab = newMap.get( prevCollab.clientId );
+			if ( ! newCollab?.isConnected ) {
+				callback( prevCollab );
+			}
+		}
+	}, [ activeCollaborators, prevCollaborators, callback ] );
+}
+
+/**
+ * Hook that fires a callback when a remote collaborator saves the post.
+ * Only fires for saves by other collaborators (not the current user).
+ * Deduplicates by `savedAt` timestamp so the same save event is never
+ * reported twice.
+ *
+ * @param postId   The ID of the post.
+ * @param postType The type of the post.
+ * @param callback Invoked with the save event, the collaborator who saved,
+ *                 and the previous save event (if any) for transition detection.
+ */
+export function useOnPostSave(
+	postId: number | null,
+	postType: string | null,
+	callback: (
+		event: PostSaveEvent,
+		saver: ActiveCollaborator,
+		prevEvent: PostSaveEvent | null
+	) => void
+): void {
+	const { activeCollaborators } = usePostEditorAwarenessState(
+		postId,
+		postType
+	);
+	const lastPostSave = useLastPostSave( postId, postType );
+	const prevPostSave = usePrevious( lastPostSave );
+
+	useEffect( () => {
+		if ( ! lastPostSave ) {
+			return;
+		}
+
+		if ( prevPostSave && lastPostSave.savedAt === prevPostSave.savedAt ) {
+			return;
+		}
+
+		const saver = activeCollaborators.find(
+			( collaborator ) =>
+				collaborator.clientId === lastPostSave.savedByClientId &&
+				! collaborator.isMe
+		);
+
+		if ( ! saver ) {
+			return;
+		}
+
+		callback( lastPostSave, saver, prevPostSave ?? null );
+	}, [ lastPostSave, prevPostSave, activeCollaborators, callback ] );
+}

package/src/index.js

@@ -138,6 +138,7 @@ register( store ); // Register store after unlocking private selectors to allow
  * based on their values (they blur to string type).
  */
 export { SelectionType } from './utils/crdt-user-selections';
+export { SelectionDirection } from './types';
 
 export { default as EntityProvider } from './entity-provider';
 export * from './entity-provider';