@wordpress/core-data 7.41.0 → 7.41.2-next.v.202603161435.0

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;
@@ -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';

package/src/private-actions.js

@@ -103,7 +103,7 @@ export const editMediaEntity =
 					dispatch.receiveEntityRecords(
 						kind,
 						name,
-						[ newRecord ],
+						newRecord,
 						undefined,
 						true,
 						undefined,

package/src/private-apis.js

@@ -6,7 +6,9 @@ import { RECEIVE_INTERMEDIATE_RESULTS } from './utils';
 import {
 	useActiveCollaborators,
 	useResolvedSelection,
-	useLastPostSave,
+	useOnCollaboratorJoin,
+	useOnCollaboratorLeave,
+	useOnPostSave,
 } from './hooks/use-post-editor-awareness-state';
 import { lock } from './lock-unlock';
 import { retrySyncConnection } from './sync';
@@ -18,5 +20,7 @@ lock( privateApis, {
 	retrySyncConnection,
 	useActiveCollaborators,
 	useResolvedSelection,
-	useLastPostSave,
+	useOnCollaboratorJoin,
+	useOnCollaboratorLeave,
+	useOnPostSave,
 } );

package/src/queried-data/actions.js

@@ -10,7 +10,7 @@
 export function receiveItems( items, edits, meta ) {
 	return {
 		type: 'RECEIVE_ITEMS',
-		items: Array.isArray( items ) ? items : [ items ],
+		items,
 		persistedEdits: edits,
 		meta,
 	};

package/src/queried-data/reducer.js

@@ -105,19 +105,22 @@ export function items( state = {}, action ) {
 		case 'RECEIVE_ITEMS': {
 			const context = getContextFromAction( action );
 			const key = action.key || DEFAULT_ENTITY_KEY;
+			const itemsList = Array.isArray( action.items )
+				? action.items
+				: [ action.items ];
 			return {
 				...state,
 				[ context ]: {
 					...state[ context ],
-					...action.items.reduce( ( accumulator, value ) => {
-						const itemId = value?.[ key ];
-
-						accumulator[ itemId ] = conservativeMapItem(
-							state?.[ context ]?.[ itemId ],
-							value
-						);
-						return accumulator;
-					}, {} ),
+					...Object.fromEntries(
+						itemsList.map( ( item ) => [
+							item?.[ key ],
+							conservativeMapItem(
+								state?.[ context ]?.[ item?.[ key ] ],
+								item
+							),
+						] )
+					),
 				},
 			};
 		}
@@ -149,6 +152,9 @@ export function itemIsComplete( state = {}, action ) {
 		case 'RECEIVE_ITEMS': {
 			const context = getContextFromAction( action );
 			const { query, key = DEFAULT_ENTITY_KEY } = action;
+			const itemsList = Array.isArray( action.items )
+				? action.items
+				: [ action.items ];
 
 			// An item is considered complete if it is received without an associated
 			// fields query. Ideally, this would be implemented in such a way where the
@@ -164,7 +170,7 @@ export function itemIsComplete( state = {}, action ) {
 				...state,
 				[ context ]: {
 					...state[ context ],
-					...action.items.reduce( ( result, item ) => {
+					...itemsList.reduce( ( result, item ) => {
 						const itemId = item?.[ key ];
 
 						// Defer to completeness if already assigned. Technically the
@@ -224,18 +230,24 @@ const receiveQueries = compose( [
 	// reducer tracks only a single query object.
 	onSubKey( 'stableKey' ),
 ] )( ( state = {}, action ) => {
-	const { type, page, perPage, key = DEFAULT_ENTITY_KEY } = action;
+	if ( action.type !== 'RECEIVE_ITEMS' ) {
+		return state;
+	}
 
-	if ( type !== 'RECEIVE_ITEMS' ) {
+	// Single items don't have page or total count metadata
+	// (only collection query responses do), so skip updating itemIds.
+	if ( ! Array.isArray( action.items ) ) {
 		return state;
 	}
 
+	const key = action.key ?? DEFAULT_ENTITY_KEY;
+
 	return {
 		itemIds: getMergedItemIds(
 			state?.itemIds || [],
 			action.items.map( ( item ) => item?.[ key ] ).filter( Boolean ),
-			page,
-			perPage
+			action.page,
+			action.perPage
 		),
 		meta: action.meta,
 	};

package/src/queried-data/selectors.js

@@ -34,12 +34,8 @@ const queriedItemsCacheByState = new WeakMap();
 function getQueriedItemsUncached( state, query ) {
 	const { stableKey, page, perPage, include, fields, context } =
 		getQueryParts( query );
-	let itemIds;
-
-	if ( state.queries?.[ context ]?.[ stableKey ] ) {
-		itemIds = state.queries[ context ][ stableKey ].itemIds;
-	}
 
+	const itemIds = state.queries?.[ context ]?.[ stableKey ]?.itemIds;
 	if ( ! itemIds ) {
 		return null;
 	}
@@ -50,6 +46,17 @@ function getQueriedItemsUncached( state, query ) {
 			? itemIds.length
 			: Math.min( startOffset + perPage, itemIds.length );
 
+	// If the requested page range exceeds the stored itemIds, the data for
+	// this specific pagination window may not have been fetched yet. Return
+	// null unless totalItems confirms we already have all available items.
+	if ( perPage !== -1 && itemIds.length < startOffset + perPage ) {
+		const totalItems =
+			state.queries[ context ][ stableKey ].meta?.totalItems;
+		if ( Number.isFinite( totalItems ) && itemIds.length < totalItems ) {
+			return null;
+		}
+	}
+
 	const items = [];
 	for ( let i = startOffset; i < endOffset; i++ ) {
 		const itemId = itemIds[ i ];

package/src/queried-data/test/selectors.js

@@ -239,4 +239,29 @@ describe( 'getQueriedItems', () => {
 
 		expect( result ).toBe( null );
 	} );
+
+	it( 'should return null when per_page exceeds stored itemIds and more items exist', () => {
+		const state = {
+			items: {
+				default: {
+					1: { id: 1 },
+					2: { id: 2 },
+				},
+			},
+			itemIsComplete: {
+				default: { 1: true, 2: true },
+			},
+			queries: {
+				default: {
+					'': {
+						itemIds: [ 1, 2 ],
+						meta: { totalItems: 5 },
+					},
+				},
+			},
+		};
+
+		const result = getQueriedItems( state, { per_page: 3 } );
+		expect( result ).toBe( null );
+	} );
 } );

package/src/reducer.js

@@ -214,8 +214,11 @@ function entity( entityConfig ) {
 						}
 
 						const nextState = { ...state };
+						const itemsList = Array.isArray( action.items )
+							? action.items
+							: [ action.items ];
 
-						for ( const record of action.items ) {
+						for ( const record of itemsList ) {
 							const recordId = record?.[ action.key ];
 							const edits = nextState[ recordId ];
 							if ( ! edits ) {