Sync connection modal: Redesign with error-specific actions

Redesign the sync disconnection modal to follow the standard Modal
pattern with a header title, left-aligned body, and right-aligned
footer buttons — replacing the previous centered splash layout.

- Use Modal `title` prop instead of hidden header with large icon
- Add "Back to {PostType}" button with dynamic post type label
- Add manual "Retry" button alongside auto-retry countdown
- Promote "Copy Post Content" to primary when Retry is hidden
- Add `canRetry` flag to error messages: `authentication-failed`
  hides Retry (permissions can't be resolved by retrying)
- Stabilize useEffect dependencies with primitive values
- Replace hardcoded colors with `@wordpress/base-styles` tokens
- Add unit tests for `getSyncErrorMessages`

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: dabowman

packages/editor/src/components/sync-connection-modal/index.js

@@ -15,18 +15,17 @@ import {
 import {
 	Button,
 	Modal,
-	Icon,
 	__experimentalHStack as HStack,
 	__experimentalVStack as VStack,
 } from '@wordpress/components';
 import { useState, useEffect, useRef } from '@wordpress/element';
 import { __, sprintf, _n } from '@wordpress/i18n';
-import { error as errorIcon } from '@wordpress/icons';
 
 /**
  * Internal dependencies
  */
 import { getSyncErrorMessages } from '../../utils/sync-error-messages';
+import { store as editorStore } from '../../store';
 import { unlock } from '../../lock-unlock';
 import { useRetryCountdown } from './use-retry-countdown';
 
@@ -35,6 +34,7 @@ const { retrySyncConnection } = unlock( coreDataPrivateApis );
 
 // Debounce time for initial disconnected status to allow connection to establish.
 const INITIAL_DISCONNECTED_DEBOUNCE_MS = 5000;
+const noop = () => {};
 
 /**
  * Sync connection modal that displays when any entity reports a disconnection.
@@ -43,8 +43,15 @@ const INITIAL_DISCONNECTED_DEBOUNCE_MS = 5000;
  * @return {Element|null} The modal component or null if not disconnected.
  */
 export function SyncConnectionModal() {
-	const connectionState = useSelect( ( selectFn ) => {
-		return selectFn( coreDataStore ).getSyncConnectionStatus() || null;
+	const { connectionState, postType } = useSelect( ( selectFn ) => {
+		const currentPostType = selectFn( editorStore ).getCurrentPostType();
+		return {
+			connectionState:
+				selectFn( coreDataStore ).getSyncConnectionStatus() || null,
+			postType: currentPostType
+				? selectFn( coreDataStore ).getPostType( currentPostType )
+				: null,
+		};
 	}, [] );
 
 	const { secondsRemaining, markRetrying } = useRetryCountdown(
@@ -63,23 +70,24 @@ export function SyncConnectionModal() {
 	// Once true, disconnected status will show immediately without debounce.
 	const hasInitializedRef = useRef( false );
 
-	useEffect( () => {
-		const status = connectionState?.status;
+	const connectionStatus = connectionState?.status;
+	const connectionErrorCode = connectionState?.error?.code;
 
+	useEffect( () => {
 		// Clear any pending debounce timer when status changes.
 		if ( debounceTimerRef.current ) {
 			clearTimeout( debounceTimerRef.current );
 			debounceTimerRef.current = null;
 		}
 
-		if ( status === 'connected' ) {
+		if ( connectionStatus === 'connected' ) {
 			hasInitializedRef.current = true;
 			setSyncConnectionMessage( null );
-		} else if ( status === 'disconnected' ) {
+		} else if ( connectionStatus === 'disconnected' ) {
 			const showModal = () => {
 				hasInitializedRef.current = true;
 				setSyncConnectionMessage(
-					getSyncErrorMessages( connectionState.error ?? {} )
+					getSyncErrorMessages( { code: connectionErrorCode } )
 				);
 			};
 
@@ -99,97 +107,89 @@ export function SyncConnectionModal() {
 				clearTimeout( debounceTimerRef.current );
 			}
 		};
-	}, [ connectionState ] );
+	}, [ connectionStatus, connectionErrorCode ] );
 
 	if ( ! syncConnectionMessage ) {
 		return null;
 	}
 
-	const { title, description } = syncConnectionMessage;
+	const { title, description, canRetry } = syncConnectionMessage;
 
 	let retryCountdownText;
 	if ( secondsRemaining > 0 ) {
 		retryCountdownText = sprintf(
 			/* translators: %d: number of seconds until retry */
 			_n(
-				'Retrying in %d second\u2026',
-				'Retrying in %d seconds\u2026',
+				'Retrying connection in %d second\u2026',
+				'Retrying connection in %d seconds\u2026',
 				secondsRemaining
 			),
 			secondsRemaining
 		);
 	} else if ( secondsRemaining === 0 ) {
 		retryCountdownText = __( 'Retrying\u2026' );
-	} else {
-		//   to preserve layout when countdown is hidden
-		retryCountdownText = '\u00A0';
 	}
 
+	let editPostHref = 'edit.php';
+	if ( postType?.slug ) {
+		editPostHref = `edit.php?post_type=${ postType.slug }`;
+	}
+
+	const isRetrying = secondsRemaining === 0;
+
 	return (
 		<BlockCanvasCover.Fill>
 			<Modal
-				__experimentalHideHeader
-				icon={ errorIcon }
+				className="editor-sync-connection-modal"
 				isDismissible={ false }
-				isFullScreen={ false }
-				onRequestClose={ () => {} }
+				onRequestClose={ noop }
 				shouldCloseOnClickOutside={ false }
 				shouldCloseOnEsc={ false }
+				size="medium"
+				title={ title }
 			>
-				<div className="editor-sync-connection-modal__container">
-					<VStack alignment="center" justify="center" spacing={ 1 }>
-						<Icon fill="#ccc" icon={ errorIcon } size={ 64 } />
-						<h1>{ title }</h1>
-						<div
-							className="editor-sync-connection-modal__retry"
-							style={ {
-								visibility:
-									secondsRemaining !== null
-										? 'visible'
-										: 'hidden',
-							} }
+				<VStack spacing={ 6 }>
+					<p>{ description }</p>
+					{ retryCountdownText && (
+						<p className="editor-sync-connection-modal__retry-countdown">
+							{ retryCountdownText }
+						</p>
+					) }
+					<HStack justify="right">
+						<Button
+							__next40pxDefaultSize
+							href={ editPostHref }
+							isDestructive
+							variant="tertiary"
+						>
+							{ sprintf(
+								/* translators: %s: Post type name (e.g., "Posts", "Pages"). */
+								__( 'Back to %s' ),
+								postType?.labels?.name ?? __( 'Posts' )
+							) }
+						</Button>
+						<Button
+							__next40pxDefaultSize
+							ref={ copyButtonRef }
+							variant={ canRetry ? 'secondary' : 'primary' }
 						>
-							<p className="editor-sync-connection-modal__retry-countdown">
-								{ retryCountdownText }
-							</p>
+							{ __( 'Copy Post Content' ) }
+						</Button>
+						{ canRetry && (
 							<Button
-								variant="link"
-								style={ {
-									visibility:
-										secondsRemaining === 0
-											? 'hidden'
-											: 'visible',
-								} }
+								__next40pxDefaultSize
+								isBusy={ isRetrying }
+								variant="primary"
 								onClick={ () => {
 									markRetrying();
 									retrySyncConnection();
 								} }
 							>
-								{ __( 'Retry now' ) }
-							</Button>
-						</div>
-						<p className="editor-sync-connection-modal__description">
-							{ description }
-						</p>
-						<HStack spacing={ 2 } justify="center">
-							<Button
-								__next40pxDefaultSize
-								ref={ copyButtonRef }
-								variant="primary"
-							>
-								{ __( 'Copy post content' ) }
-							</Button>
-							<Button
-								__next40pxDefaultSize
-								href="edit.php"
-								isDestructive
-								variant="secondary"
-							>
-								{ __( 'Edit another post' ) }
+								{ __( 'Retry' ) }
 							</Button>
-						</HStack>
-					</VStack>
-				</div>
+						) }
+					</HStack>
+				</VStack>
 			</Modal>
 		</BlockCanvasCover.Fill>
 	);

packages/editor/src/components/sync-connection-modal/style.scss

@@ -1,21 +1,9 @@
-.editor-sync-connection-modal__container {
-	align-items: center;
-	display: flex;
-	margin: auto;
-	max-width: 30rem;
-}
-
-.editor-sync-connection-modal__description {
-	font-size: 1.3rem;
-	text-align: center;
-}
+@use "@wordpress/base-styles/colors" as *;
 
-.editor-sync-connection-modal__retry {
-	text-align: center;
-	min-height: 3em;
+.editor-sync-connection-modal p {
+	margin: 0;
 }
 
 .editor-sync-connection-modal__retry-countdown {
-	margin-top: 0;
-	margin-bottom: 0;
+	color: $gray-700;
 }

packages/editor/src/utils/sync-error-messages.js

@@ -8,31 +8,36 @@ import { __ } from '@wordpress/i18n';
  */
 const ERROR_MESSAGES = {
 	'authentication-failed': {
-		title: __( 'Authentication Failed' ),
+		title: __( 'Unable to connect' ),
 		description: __(
-			'Authentication with the collaborative editing server failed. ' +
-				'Please verify that you have the necessary permissions.'
+			"Real-time collaboration couldn't verify your permissions. " +
+				'Check that you have access to edit this post, or contact your site administrator.'
 		),
+		canRetry: false,
 	},
 	'connection-expired': {
-		title: __( 'Connection Expired' ),
+		title: __( 'Connection expired' ),
 		description: __(
-			'The connection to the collaborative editing server has expired.'
+			'Your connection to real-time collaboration has timed out. ' +
+				'Editing is paused to prevent conflicts with other editors.'
 		),
+		canRetry: true,
 	},
 	'connection-limit-exceeded': {
-		title: __( 'Connection Limit Exceeded' ),
+		title: __( 'Too many editors connected' ),
 		description: __(
-			'The collaborative editing server has reached its maximum connection capacity. ' +
-				'Please try again later or contact your site administrator.'
+			'Real-time collaboration has reached its connection limit. ' +
+				'Try again later or contact your site administrator.'
 		),
+		canRetry: true,
 	},
 	'unknown-error': {
-		title: __( 'Disconnected' ),
+		title: __( 'Connection lost' ),
 		description: __(
-			'You are currently disconnected from the collaborative editing server. ' +
-				'Editing is temporarily disabled to prevent conflicts.'
+			'The connection to real-time collaboration was interrupted. ' +
+				'Editing is paused to prevent conflicts with other editors.'
 		),
+		canRetry: true,
 	},
 };
 
@@ -42,7 +47,7 @@ const ERROR_MESSAGES = {
  * Provides default messages based on error.code.
  *
  * @param {Object} error - Connection error object.
- * @return {Object} Object with title and description strings.
+ * @return {Object} Object with title, description, and canRetry flag.
  */
 export function getSyncErrorMessages( error ) {
 	if ( ERROR_MESSAGES[ error?.code ] ) {

packages/editor/src/utils/test/sync-error-messages.js

@@ -0,0 +1,57 @@
+/**
+ * Internal dependencies
+ */
+import { getSyncErrorMessages } from '../sync-error-messages';
+
+describe( 'getSyncErrorMessages', () => {
+	it.each( [
+		'authentication-failed',
+		'connection-expired',
+		'connection-limit-exceeded',
+		'unknown-error',
+	] )(
+		'should return title, description, and canRetry for "%s"',
+		( code ) => {
+			const result = getSyncErrorMessages( { code } );
+			expect( result ).toEqual(
+				expect.objectContaining( {
+					title: expect.any( String ),
+					description: expect.any( String ),
+					canRetry: expect.any( Boolean ),
+				} )
+			);
+		}
+	);
+
+	it( 'should set canRetry to false for authentication-failed', () => {
+		const result = getSyncErrorMessages( {
+			code: 'authentication-failed',
+		} );
+		expect( result.canRetry ).toBe( false );
+	} );
+
+	it( 'should set canRetry to true for retryable errors', () => {
+		expect(
+			getSyncErrorMessages( { code: 'connection-expired' } ).canRetry
+		).toBe( true );
+		expect(
+			getSyncErrorMessages( { code: 'connection-limit-exceeded' } )
+				.canRetry
+		).toBe( true );
+		expect(
+			getSyncErrorMessages( { code: 'unknown-error' } ).canRetry
+		).toBe( true );
+	} );
+
+	it( 'should fall back to unknown-error for unrecognized codes', () => {
+		const result = getSyncErrorMessages( { code: 'some-new-error' } );
+		const unknownResult = getSyncErrorMessages( { code: 'unknown-error' } );
+		expect( result ).toBe( unknownResult );
+	} );
+
+	it( 'should fall back to unknown-error when error is undefined', () => {
+		const result = getSyncErrorMessages( undefined );
+		const unknownResult = getSyncErrorMessages( { code: 'unknown-error' } );
+		expect( result ).toBe( unknownResult );
+	} );
+} );