@wordpress/core-data 7.40.2-next.v.202602241322.0 → 7.40.2

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

@@ -1,7 +1,9 @@
 /**
  * External dependencies
  */
+import { usePrevious } from '@wordpress/compose';
 import { useEffect, useState } from '@wordpress/element';
+import type { Y } from '@wordpress/sync';
 
 /**
  * Internal dependencies
@@ -9,16 +11,12 @@ import { useEffect, useState } from '@wordpress/element';
 import { getSyncManager } from '../sync';
 import type {
 	PostEditorAwarenessState as ActiveCollaborator,
+	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;
@@ -27,7 +25,7 @@ interface AwarenessState {
 }
 
 const defaultResolvedSelection: ResolvedSelection = {
-	textIndex: null,
+	richTextOffset: null,
 	localClientId: null,
 };
 
@@ -156,3 +154,227 @@ export function useIsDisconnected(
 	return usePostEditorAwarenessState( postId, postType )
 		.isCurrentCollaboratorDisconnected;
 }
+
+/**
+ * Hook that subscribes to the CRDT state map and returns the most recent
+ * save event (timestamp + client ID). The state map is updated by
+ * `markEntityAsSaved` in `@wordpress/sync`
+ *
+ * @param postId   The ID of the post.
+ * @param postType The type of the post.
+ */
+function useLastPostSave(
+	postId: number | null,
+	postType: string | null
+): PostSaveEvent | null {
+	const [ lastSave, setLastSave ] = useState< PostSaveEvent | null >( null );
+
+	useEffect( () => {
+		if ( null === postId || null === postType ) {
+			setLastSave( null );
+			return;
+		}
+
+		const awareness = getSyncManager()?.getAwareness< PostEditorAwareness >(
+			`postType/${ postType }`,
+			postId.toString()
+		);
+
+		if ( ! awareness ) {
+			setLastSave( null );
+			return;
+		}
+
+		awareness.setUp();
+
+		const stateMap = awareness.doc.getMap( 'state' );
+		const recordMap = awareness.doc.getMap( 'document' );
+
+		// Only notify for saves that occur after the observer is
+		// set up. This prevents false notifications when the Y.Doc
+		// syncs historical state on page load or peer reconnect.
+		const setupTime = Date.now();
+
+		const observer = ( event: Y.YMapEvent< unknown > ) => {
+			if ( event.keysChanged.has( 'savedAt' ) ) {
+				const savedAt = stateMap.get( 'savedAt' ) as number;
+				const savedByClientId = stateMap.get( 'savedBy' ) as number;
+
+				if (
+					typeof savedAt === 'number' &&
+					typeof savedByClientId === 'number' &&
+					savedAt > setupTime
+				) {
+					const postStatus = recordMap.get( 'status' ) as
+						| string
+						| undefined;
+					setLastSave( { savedAt, savedByClientId, postStatus } );
+				}
+			}
+		};
+
+		stateMap.observe( observer );
+
+		return () => {
+			stateMap.unobserve( observer );
+		};
+	}, [ postId, postType ] );
+
+	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

@@ -133,12 +133,6 @@ unlock( store ).registerPrivateSelectors( privateSelectors );
 unlock( store ).registerPrivateActions( privateActions );
 register( store ); // Register store after unlocking private selectors to allow resolvers to use them.
 
-/**
- * Enums cannot be exported private without losing the ability to narrow types
- * based on their values (they blur to string type).
- */
-export { SelectionType } from './utils/crdt-user-selections';
-
 export { default as EntityProvider } from './entity-provider';
 export * from './entity-provider';
 export * from './entity-types';

package/src/private-actions.js

@@ -103,7 +103,7 @@ export const editMediaEntity =
 					dispatch.receiveEntityRecords(
 						kind,
 						name,
-						[ newRecord ],
+						newRecord,
 						undefined,
 						true,
 						undefined,
@@ -160,3 +160,45 @@ export function receiveEditorAssets( assets ) {
 		assets,
 	};
 }
+
+/**
+ * Returns an action object used to set whether collaboration is supported.
+ *
+ * @param {boolean} supported Whether collaboration is supported.
+ *
+ * @return {Object} Action object.
+ */
+export const setCollaborationSupported =
+	( supported ) =>
+	( { dispatch } ) => {
+		dispatch( { type: 'SET_COLLABORATION_SUPPORTED', supported } );
+	};
+
+/**
+ * Returns an action object used to set the sync connection status for an entity or collection.
+ *
+ * @param {string}             kind   Kind of the entity.
+ * @param {string}             name   Name of the entity.
+ * @param {number|string|null} key    The entity key, or null for collections.
+ * @param {Object|null}        status The connection state object or null on unload.
+ *
+ * @return {Object} Action object.
+ */
+export function setSyncConnectionStatus( kind, name, key, status ) {
+	if ( ! status ) {
+		return {
+			type: 'CLEAR_SYNC_CONNECTION_STATUS',
+			kind,
+			name,
+			key,
+		};
+	}
+
+	return {
+		type: 'SET_SYNC_CONNECTION_STATUS',
+		kind,
+		name,
+		key,
+		status,
+	};
+}

package/src/{private-apis.js → private-apis.ts}

@@ -6,13 +6,31 @@ import { RECEIVE_INTERMEDIATE_RESULTS } from './utils';
 import {
 	useActiveCollaborators,
 	useResolvedSelection,
+	useOnCollaboratorJoin,
+	useOnCollaboratorLeave,
+	useOnPostSave,
 } from './hooks/use-post-editor-awareness-state';
 import { lock } from './lock-unlock';
+import { retrySyncConnection } from './sync';
+import {
+	SelectionType,
+	SelectionDirection,
+} from './utils/crdt-user-selections';
 
-export const privateApis = {};
-lock( privateApis, {
+const lockedApis = {
 	useEntityRecordsWithPermissions,
 	RECEIVE_INTERMEDIATE_RESULTS,
+	retrySyncConnection,
 	useActiveCollaborators,
 	useResolvedSelection,
-} );
+	useOnCollaboratorJoin,
+	useOnCollaboratorLeave,
+	useOnPostSave,
+	SelectionType,
+	SelectionDirection,
+};
+
+export type CoreDataPrivateApis = typeof lockedApis;
+
+export const privateApis = {};
+lock( privateApis, lockedApis );

package/src/private-selectors.ts

@@ -2,6 +2,7 @@
  * WordPress dependencies
  */
 import { createSelector, createRegistrySelector } from '@wordpress/data';
+import type { ConnectionStatus } from '@wordpress/sync';
 
 /**
  * Internal dependencies
@@ -304,3 +305,45 @@ export function getEditorSettings(
 export function getEditorAssets( state: State ): Record< string, any > | null {
 	return state.editorAssets;
 }
+
+/**
+ * Returns whether collaboration is supported.
+ *
+ * @param state Data state.
+ * @return Whether collaboration is supported.
+ */
+export function isCollaborationSupported( state: State ): boolean {
+	return state.collaborationSupported;
+}
+
+/**
+ * Returns the current sync connection status across all entities. Prioritizes
+ * disconnected states, then connecting, then connected.
+ *
+ * @param state Data state.
+ *
+ * @return The current sync connection state, prioritized by importance.
+ */
+export function getSyncConnectionStatus(
+	state: State
+): ConnectionStatus | undefined {
+	if ( ! state.syncConnectionStatuses ) {
+		return undefined;
+	}
+
+	const PRIORITIZED_STATUSES = [ 'disconnected', 'connecting', 'connected' ];
+
+	let coalesced: ConnectionStatus | undefined;
+
+	for ( const status of Object.values( state.syncConnectionStatuses ) ) {
+		if (
+			! coalesced ||
+			PRIORITIZED_STATUSES.indexOf( status.status ) <
+				PRIORITIZED_STATUSES.indexOf( coalesced.status )
+		) {
+			coalesced = status;
+		}
+	}
+
+	return coalesced;
+}

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/reducer.js

@@ -16,6 +16,7 @@ import { createUndoManager } from '@wordpress/undo-manager';
 import { ifMatchingAction, replaceAction } from './utils';
 import { reducer as queriedDataReducer } from './queried-data';
 import { rootEntitiesConfig, DEFAULT_ENTITY_KEY } from './entities';
+import { ConnectionErrorCode } from './sync';
 
 /** @typedef {import('./types').AnyFunction} AnyFunction */
 
@@ -214,8 +215,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 ) {
@@ -687,6 +691,36 @@ export function syncConnectionStatuses( state = {}, action ) {
 	return state;
 }
 
+/**
+ * Reducer managing whether collaboration is supported.
+ *
+ * Default to true, as collaboration is supported by default
+ * unless explicitly disabled due to unsupported conditions
+ * such as metaboxes.
+ *
+ * @param {boolean} state  Current state.
+ * @param {Object}  action Dispatched action.
+ *
+ * @return {boolean} Updated state.
+ */
+export function collaborationSupported( state = true, action ) {
+	switch ( action.type ) {
+		case 'SET_COLLABORATION_SUPPORTED':
+			return action.supported;
+
+		case 'SET_SYNC_CONNECTION_STATUS':
+			if (
+				ConnectionErrorCode.DOCUMENT_SIZE_LIMIT_EXCEEDED ===
+				action.status?.error?.code
+			) {
+				return false;
+			}
+
+			return state;
+	}
+	return state;
+}
+
 export default combineReducers( {
 	users,
 	currentTheme,
@@ -710,4 +744,5 @@ export default combineReducers( {
 	editorSettings,
 	editorAssets,
 	syncConnectionStatuses,
+	collaborationSupported,
 } );

package/src/resolvers.js

@@ -229,12 +229,26 @@ export const getEntityRecord =
 								query
 							);
 						},
-						// Save the current entity record, whether or not it has unsaved
-						// edits. This is used to trigger a persisted CRDT document.
-						saveRecord: () => {
+						// Persist the CRDT document.
+						//
+						// TODO: Currently, persisted CRDT documents are stored in post meta.
+						// This effectively means that only post entities support CRDT
+						// persistence. As we add support for syncing additional entity,
+						// we'll need to revisit where persisted CRDT documents are stored.
+						persistCRDTDoc: () => {
 							resolveSelect
 								.getEditedEntityRecord( kind, name, key )
 								.then( ( editedRecord ) => {
+									// Don't persist the CRDT document if the record is still an
+									// auto-draft or if the entity does not support meta.
+									const { meta, status } = editedRecord;
+									if ( 'auto-draft' === status || ! meta ) {
+										return;
+									}
+
+									// Trigger a save to persist the CRDT document. The entity's
+									// pre-persist hooks will create the persisted CRDT document
+									// and apply it to the record's meta.
 									dispatch.saveEntityRecord(
 										kind,
 										name,
@@ -985,9 +999,11 @@ export const getDefaultTemplateId =
 			template.id = id;
 			registry.batch( () => {
 				dispatch.receiveDefaultTemplateId( query, id );
-				dispatch.receiveEntityRecords( 'postType', template.type, [
-					template,
-				] );
+				dispatch.receiveEntityRecords(
+					'postType',
+					template.type,
+					template
+				);
 				// Avoid further network requests.
 				dispatch.finishResolution( 'getEntityRecord', [
 					'postType',
@@ -1099,7 +1115,7 @@ export const getRevisions =
 				// When requesting all fields, the list of results can be used to
 				// resolve the `getRevision` selector in addition to `getRevisions`.
 				if ( ! query?._fields && ! query.context ) {
-					const key = entityConfig.key || DEFAULT_ENTITY_KEY;
+					const key = entityConfig.revisionKey || DEFAULT_ENTITY_KEY;
 					const resolutionsArgs = records
 						.filter( ( record ) => record[ key ] )
 						.map( ( record ) => [

package/src/selectors.ts

@@ -54,6 +54,7 @@ export interface State {
 	editorSettings: Record< string, any > | null;
 	editorAssets: Record< string, any > | null;
 	syncConnectionStatuses?: Record< string, ConnectionStatus >;
+	collaborationSupported: boolean;
 }
 
 type EntityRecordKey = string | number;
@@ -1597,35 +1598,3 @@ export const getRevision = createSelector(
 		];
 	}
 );
-
-/**
- * Returns the current sync connection status across all entities. Prioritizes
- * disconnected states, then connecting, then connected.
- *
- * @param state Data state.
- *
- * @return The current sync connection state, prioritized by importance.
- */
-export function getSyncConnectionStatus(
-	state: State
-): ConnectionStatus | undefined {
-	if ( ! state.syncConnectionStatuses ) {
-		return undefined;
-	}
-
-	const PRIORITIZED_STATUSES = [ 'disconnected', 'connecting', 'connected' ];
-
-	let coalesced: ConnectionStatus | undefined;
-
-	for ( const status of Object.values( state.syncConnectionStatuses ) ) {
-		if (
-			! coalesced ||
-			PRIORITIZED_STATUSES.indexOf( status.status ) <
-				PRIORITIZED_STATUSES.indexOf( coalesced.status )
-		) {
-			coalesced = status;
-		}
-	}
-
-	return coalesced;
-}

package/src/sync.ts

@@ -12,20 +12,24 @@ import {
 import { unlock } from './lock-unlock';
 
 const {
+	ConnectionErrorCode,
 	createSyncManager,
 	Delta,
 	CRDT_DOC_META_PERSISTENCE_KEY,
 	CRDT_RECORD_MAP_KEY,
 	LOCAL_EDITOR_ORIGIN,
-	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
+	LOCAL_UNDO_IGNORED_ORIGIN,
+	retrySyncConnection,
 } = unlock( syncPrivateApis );
 
 export {
+	ConnectionErrorCode,
 	Delta,
 	CRDT_DOC_META_PERSISTENCE_KEY,
 	CRDT_RECORD_MAP_KEY,
 	LOCAL_EDITOR_ORIGIN,
-	WORDPRESS_META_KEY_FOR_CRDT_DOC_PERSISTENCE,
+	LOCAL_UNDO_IGNORED_ORIGIN,
+	retrySyncConnection,
 };
 
 let syncManager: SyncManager;