Real-time Collaboration: Add sync connection error handling

docs/reference-guides/data/data-core.md

@@ -264,6 +264,18 @@ _Returns_
 
 -   `string`: The default template id for the given query.
 
+### getDisconnectedSyncConnectionState
+
+Returns the first disconnected sync connection state, if any.
+
+_Parameters_
+
+-   _state_ `State`: Data state.
+
+_Returns_
+
+-   `SyncConnectionState | undefined`: The first disconnected connection state, or undefined if all connected.
+
 ### getEditedEntityRecord
 
 Returns the specified entity record, merged with its edits.
@@ -443,6 +455,21 @@ _Returns_
 
 -   `number | null`: number | null.
 
+### getEntitySyncConnectionState
+
+Returns the sync connection state for a specific entity record or collection.
+
+_Parameters_
+
+-   _state_ `State`: Data state.
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _key_ `string | number | null`: Entity key, or null for collections.
+
+_Returns_
+
+-   `SyncConnectionState | undefined`: The sync connection state, or undefined if not set.
+
 ### getLastEntityDeleteError
 
 Returns the specified entity record's last delete error.
@@ -782,6 +809,20 @@ _Returns_
 
 -   `Object`: Action object.
 
+### clearEntitySyncConnectionState
+
+Returns an action object used to clear the sync connection state for an entity or collection.
+
+_Parameters_
+
+-   _kind_ `string`: Kind of the entity.
+-   _name_ `string`: Name of the entity.
+-   _key_ `number|string|null`: The entity key, or null for collections.
+
+_Returns_
+
+-   `Object`: Action object.
+
 ### deleteEntityRecord
 
 Action triggered to delete an entity record.
@@ -923,6 +964,21 @@ _Parameters_
 -   _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a promise.
 -   _options.throwOnError_ `[boolean]`: If false, this action suppresses all the exceptions. Defaults to false.
 
+### setEntitySyncConnectionState
+
+Returns an action object used to set the sync connection state for an entity or collection.
+
+_Parameters_
+
+-   _kind_ `string`: Kind of the entity.
+-   _name_ `string`: Name of the entity.
+-   _key_ `number|string|null`: The entity key, or null for collections.
+-   _connectionState_ `Object`: The connection state object.
+
+_Returns_
+
+-   `Object`: Action object.
+
 ### undo
 
 Action triggered to undo the last edit to an entity record, if any.

packages/core-data/README.md

@@ -174,6 +174,20 @@ _Returns_
 
 -   `Object`: Action object.
 
+### clearEntitySyncConnectionState
+
+Returns an action object used to clear the sync connection state for an entity or collection.
+
+_Parameters_
+
+-   _kind_ `string`: Kind of the entity.
+-   _name_ `string`: Name of the entity.
+-   _key_ `number|string|null`: The entity key, or null for collections.
+
+_Returns_
+
+-   `Object`: Action object.
+
 ### deleteEntityRecord
 
 Action triggered to delete an entity record.
@@ -315,6 +329,21 @@ _Parameters_
 -   _options.\_\_unstableFetch_ `[Function]`: Internal use only. Function to call instead of `apiFetch()`. Must return a promise.
 -   _options.throwOnError_ `[boolean]`: If false, this action suppresses all the exceptions. Defaults to false.
 
+### setEntitySyncConnectionState
+
+Returns an action object used to set the sync connection state for an entity or collection.
+
+_Parameters_
+
+-   _kind_ `string`: Kind of the entity.
+-   _name_ `string`: Name of the entity.
+-   _key_ `number|string|null`: The entity key, or null for collections.
+-   _connectionState_ `Object`: The connection state object.
+
+_Returns_
+
+-   `Object`: Action object.
+
 ### undo
 
 Action triggered to undo the last edit to an entity record, if any.
@@ -486,6 +515,18 @@ _Returns_
 
 -   `string`: The default template id for the given query.
 
+### getDisconnectedSyncConnectionState
+
+Returns the first disconnected sync connection state, if any.
+
+_Parameters_
+
+-   _state_ `State`: Data state.
+
+_Returns_
+
+-   `SyncConnectionState | undefined`: The first disconnected connection state, or undefined if all connected.
+
 ### getEditedEntityRecord
 
 Returns the specified entity record, merged with its edits.
@@ -665,6 +706,21 @@ _Returns_
 
 -   `number | null`: number | null.
 
+### getEntitySyncConnectionState
+
+Returns the sync connection state for a specific entity record or collection.
+
+_Parameters_
+
+-   _state_ `State`: Data state.
+-   _kind_ `string`: Entity kind.
+-   _name_ `string`: Entity name.
+-   _key_ `string | number | null`: Entity key, or null for collections.
+
+_Returns_
+
+-   `SyncConnectionState | undefined`: The sync connection state, or undefined if not set.
+
 ### getLastEntityDeleteError
 
 Returns the specified entity record's last delete error.

packages/core-data/src/actions.js

@@ -1050,3 +1050,46 @@ export const receiveRevisions =
 			invalidateCache,
 		} );
 	};
+
+/**
+ * Returns an action object used to set the sync connection state 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}             connectionState The connection state object.
+ *
+ * @return {Object} Action object.
+ */
+export function setEntitySyncConnectionState(
+	kind,
+	name,
+	key,
+	connectionState
+) {
+	return {
+		type: 'SET_ENTITY_SYNC_CONNECTION_STATE',
+		kind,
+		name,
+		key,
+		connectionState,
+	};
+}
+
+/**
+ * Returns an action object used to clear the sync connection state 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.
+ *
+ * @return {Object} Action object.
+ */
+export function clearEntitySyncConnectionState( kind, name, key ) {
+	return {
+		type: 'CLEAR_ENTITY_SYNC_CONNECTION_STATE',
+		kind,
+		name,
+		key,
+	};
+}

packages/core-data/src/reducer.js

@@ -660,6 +660,33 @@ export function editorAssets( state = null, action ) {
 	return state;
 }
 
+/**
+ * Reducer managing sync connection states for entities.
+ * Keyed by "kind/name:id" (e.g., "postType/post:123").
+ *
+ * @param {Object} state  Current state.
+ * @param {Object} action Dispatched action.
+ *
+ * @return {Object} Updated state.
+ */
+export function syncConnectionStates( state = {}, action ) {
+	switch ( action.type ) {
+		case 'SET_ENTITY_SYNC_CONNECTION_STATE': {
+			const key = `${ action.kind }/${ action.name }:${ action.key }`;
+			return {
+				...state,
+				[ key ]: action.connectionState,
+			};
+		}
+		case 'CLEAR_ENTITY_SYNC_CONNECTION_STATE': {
+			const key = `${ action.kind }/${ action.name }:${ action.key }`;
+			const { [ key ]: _, ...rest } = state;
+			return rest;
+		}
+	}
+	return state;
+}
+
 export default combineReducers( {
 	users,
 	currentTheme,
@@ -682,4 +709,5 @@ export default combineReducers( {
 	registeredPostMeta,
 	editorSettings,
 	editorAssets,
+	syncConnectionStates,
 } );

packages/core-data/src/resolvers.js

@@ -263,6 +263,15 @@ export const getEntityRecord =
 									}, 0 );
 								}
 							},
+							// Handle sync connection state changes.
+							onStateChange: ( connectionState ) => {
+								dispatch.setEntitySyncConnectionState(
+									kind,
+									name,
+									key,
+									connectionState
+								);
+							},
 						}
 					);
 				}
@@ -476,6 +485,15 @@ export const getEntityRecords =
 									query
 								);
 							},
+							// Handle sync connection state changes for collections.
+							onStateChange: ( connectionState ) => {
+								dispatch.setEntitySyncConnectionState(
+									kind,
+									name,
+									null,
+									connectionState
+								);
+							},
 						}
 					);
 				}

packages/core-data/src/selectors.ts

@@ -5,6 +5,7 @@ import { createSelector, createRegistrySelector } from '@wordpress/data';
 import { addQueryArgs } from '@wordpress/url';
 import type { UndoManager } from '@wordpress/undo-manager';
 import deprecated from '@wordpress/deprecated';
+import type { SyncConnectionState } from '@wordpress/sync';
 
 /**
  * Internal dependencies
@@ -52,6 +53,7 @@ export interface State {
 	registeredPostMeta: Record< string, Object >;
 	editorSettings: Record< string, any > | null;
 	editorAssets: Record< string, any > | null;
+	syncConnectionStates?: Record< string, SyncConnectionState >;
 }
 
 type EntityRecordKey = string | number;
@@ -1595,3 +1597,48 @@ export const getRevision = createSelector(
 		];
 	}
 );
+
+/**
+ * Returns the sync connection state for a specific entity record or collection.
+ *
+ * @param state Data state.
+ * @param kind  Entity kind.
+ * @param name  Entity name.
+ * @param key   Entity key, or null for collections.
+ *
+ * @return The sync connection state, or undefined if not set.
+ */
+export function getEntitySyncConnectionState(
+	state: State,
+	kind: string,
+	name: string,
+	key: string | number | null
+): SyncConnectionState | undefined {
+	const stateKey = `${ kind }/${ name }:${ key }`;
+	return state.syncConnectionStates?.[ stateKey ];
+}
+
+/**
+ * Returns the first disconnected sync connection state, if any.
+ *
+ * @param state Data state.
+ *
+ * @return The first disconnected connection state, or undefined if all connected.
+ */
+export function getDisconnectedSyncConnectionState(
+	state: State
+): SyncConnectionState | undefined {
+	if ( ! state.syncConnectionStates ) {
+		return undefined;
+	}
+
+	for ( const connectionState of Object.values(
+		state.syncConnectionStates
+	) ) {
+		if ( connectionState?.status === 'disconnected' ) {
+			return connectionState;
+		}
+	}
+
+	return undefined;
+}

packages/core-data/src/test/resolvers.js

@@ -171,6 +171,7 @@ describe( 'getEntityRecord', () => {
 				addUndoMeta: expect.any( Function ),
 				editRecord: expect.any( Function ),
 				getEditedRecord: expect.any( Function ),
+				onStateChange: expect.any( Function ),
 				refetchRecord: expect.any( Function ),
 				restoreUndoMeta: expect.any( Function ),
 				saveRecord: expect.any( Function ),
@@ -226,6 +227,7 @@ describe( 'getEntityRecord', () => {
 				addUndoMeta: expect.any( Function ),
 				editRecord: expect.any( Function ),
 				getEditedRecord: expect.any( Function ),
+				onStateChange: expect.any( Function ),
 				refetchRecord: expect.any( Function ),
 				restoreUndoMeta: expect.any( Function ),
 				saveRecord: expect.any( Function ),

packages/core-data/src/utils/test/crdt-blocks.ts

@@ -6,7 +6,14 @@ import { Y } from '@wordpress/sync';
 /**
  * External dependencies
  */
-import { describe, expect, it, jest, beforeEach } from '@jest/globals';
+import {
+	describe,
+	expect,
+	it,
+	jest,
+	beforeEach,
+	afterEach,
+} from '@jest/globals';
 
 /**
  * Mock uuid module