Widgets Customizer: Add Welcome messaging (#31968)

* Widgets Customizer: Add Welcome component

* Widgets Customizer: Show different message when new user and area contains entirely blocks

* Widgets Customizer: Rename Welcome to WelcomeGuide and hook it up to welcomeGuide setting

* Disable welcome guide in Widgets Customizer E2E tests

* Adjust line heights and margins in Customizer WelcomeGuide

packages/customize-widgets/src/components/sidebar-block-editor/index.js

@@ -29,6 +29,7 @@ import Header from '../header';
 import useInserter from '../inserter/use-inserter';
 import SidebarEditorProvider from './sidebar-editor-provider';
 import { store as customizeWidgetsStore } from '../../store';
+import WelcomeGuide from '../welcome-guide';
 
 export default function SidebarBlockEditor( {
 	blockEditorSettings,
@@ -41,6 +42,7 @@ export default function SidebarBlockEditor( {
 		hasUploadPermissions,
 		isFixedToolbarActive,
 		keepCaretInsideBlock,
+		isWelcomeGuideActive,
 	} = useSelect( ( select ) => {
 		return {
 			hasUploadPermissions: defaultTo(
@@ -53,6 +55,9 @@ export default function SidebarBlockEditor( {
 			keepCaretInsideBlock: select(
 				customizeWidgetsStore
 			).__unstableIsFeatureActive( 'keepCaretInsideBlock' ),
+			isWelcomeGuideActive: select(
+				customizeWidgetsStore
+			).__unstableIsFeatureActive( 'welcomeGuide' ),
 		};
 	}, [] );
 	const settings = useMemo( () => {
@@ -81,6 +86,10 @@ export default function SidebarBlockEditor( {
 		keepCaretInsideBlock,
 	] );
 
+	if ( isWelcomeGuideActive ) {
+		return <WelcomeGuide sidebar={ sidebar } />;
+	}
+
 	return (
 		<>
 			<BlockEditorKeyboardShortcuts.Register />

packages/customize-widgets/src/components/welcome-guide/index.js

@@ -0,0 +1,72 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { Button, ExternalLink } from '@wordpress/components';
+import { useDispatch } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { EditorImage } from './images';
+import { store as customizeWidgetsStore } from '../../store';
+
+export default function WelcomeGuide( { sidebar } ) {
+	const { __unstableToggleFeature: toggleFeature } = useDispatch(
+		customizeWidgetsStore
+	);
+
+	const isEntirelyBlockWidgets = sidebar
+		.getWidgets()
+		.every( ( widget ) => widget.id.startsWith( 'block-' ) );
+
+	return (
+		<div className="customize-widgets-welcome-guide">
+			<EditorImage />
+			<h1 className="customize-widgets-welcome-guide__heading">
+				{ __( 'Welcome to block Widgets' ) }
+			</h1>
+			<p className="customize-widgets-welcome-guide__text">
+				{ isEntirelyBlockWidgets
+					? __(
+							'Your theme provides different “block” areas for you to add and edit content. Try adding a search bar, social icons, or other types of blocks here and see how they’ll look on your site.'
+					  )
+					: __(
+							'You can now add any block to your site’s widget areas. Don’t worry, all of your favorite widgets still work flawlessly.'
+					  ) }
+			</p>
+			<Button
+				className="customize-widgets-welcome-guide__button"
+				isPrimary
+				onClick={ () => toggleFeature( 'welcomeGuide' ) }
+			>
+				{ __( 'Got it' ) }
+			</Button>
+			<hr className="customize-widgets-welcome-guide__separator" />
+			{ ! isEntirelyBlockWidgets && (
+				<p className="customize-widgets-welcome-guide__more-info">
+					{ __( 'Want to stick with the old widgets?' ) }
+					<br />
+					<ExternalLink
+						href={ __(
+							'https://wordpress.org/plugins/classic-widgets/'
+						) }
+					>
+						{ __( 'Get the Classic Widgets plugin.' ) }
+					</ExternalLink>
+				</p>
+			) }
+			<p className="customize-widgets-welcome-guide__more-info">
+				{ __( 'New to the block editor?' ) }
+				<br />
+				<ExternalLink
+					href={ __(
+						'https://wordpress.org/support/article/wordpress-editor/'
+					) }
+				>
+					{ __( "Here's a detailed guide." ) }
+				</ExternalLink>
+			</p>
+		</div>
+	);
+}

packages/customize-widgets/src/components/welcome-guide/style.scss

@@ -0,0 +1,45 @@
+.customize-widgets-welcome-guide {
+	&__image {
+		background: #00a0d2;
+		height: 240px;
+		margin: 0 0 $grid-unit-10;
+
+		&__prm-r {
+			display: none;
+		}
+
+		@media (prefers-reduced-motion: reduce) {
+			&__prm-r {
+				display: block;
+			}
+
+			&__prm-np {
+				display: none;
+			}
+		}
+	}
+
+	// Extra specificity to override `.wrap h1` styles.
+	.wrap &__heading {
+		font-size: 18px;
+		font-weight: 600;
+	}
+
+	&__text {
+		line-height: 1.7;
+	}
+
+	&__button {
+		justify-content: center;
+		margin: 1em 0;
+		width: 100%;
+	}
+
+	&__separator {
+		margin: 1em 0;
+	}
+
+	&__more-info {
+		line-height: 1.4;
+	}
+}

packages/customize-widgets/src/style.scss

@@ -1,9 +1,10 @@
-@import "./components/sidebar-block-editor/style.scss";
 @import "./components/block-inspector-button/style.scss";
 @import "./components/header/style.scss";
 @import "./components/inserter/style.scss";
 @import "./components/keyboard-shortcut-help-modal/style.scss";
 @import "./components/more-menu/style.scss";
+@import "./components/sidebar-block-editor/style.scss";
+@import "./components/welcome-guide/style.scss";
 @import "./controls/style.scss";
 
 // Modals need a higher z-index in the customizer.

packages/e2e-tests/specs/experiments/customizing-widgets.test.js

@@ -20,6 +20,20 @@ describe( 'Widgets Customizer', () => {
 	beforeEach( async () => {
 		await cleanupWidgets();
 		await visitAdminPage( 'customize.php' );
+
+		// Disable welcome guide if it is enabled.
+		const isWelcomeGuideActive = await page.evaluate( () =>
+			wp.data
+				.select( 'core/customize-widgets' )
+				.__unstableIsFeatureActive( 'welcomeGuide' )
+		);
+		if ( isWelcomeGuideActive ) {
+			await page.evaluate( () =>
+				wp.data
+					.dispatch( 'core/customize-widgets' )
+					.__unstableToggleFeature( 'welcomeGuide' )
+			);
+		}
 	} );
 
 	beforeAll( async () => {