Iterations on the welcome guide

packages/components/CHANGELOG.md

@@ -1,5 +1,10 @@
 ## Master
 
+### Deprecations
+
+- The `Guide` component no longer supports passing pages as children. Use the `pages` prop instead.
+- The `GuidePage` component is deprecated. Use the `pages` prop in `Guide` instead.
+
 ## 9.2.0 (2020-02-10)
 
 ### Enhancements

packages/components/src/guide/README.md

@@ -1,7 +1,7 @@
 Guide
 ========
 
-`Guide` is a React component that renders a _user guide_ in a modal. The guide consists of several `GuidePage` components which the user can step through one by one. The guide is finished when the modal is closed or when the user clicks _Finish_ on the last page of the guide.
+`Guide` is a React component that renders a _user guide_ in a modal. The guide consists of several pages which the user can step through one by one. The guide is finished when the modal is closed or when the user clicks _Finish_ on the last page of the guide.
 
 ## Usage
 
@@ -13,14 +13,20 @@ function MyTutorial() {
 		return null;
 	}
 
-	<Guide onFinish={ () => setIsOpen( false ) }>
-		<GuidePage>
-			<p>Welcome to the ACME Store! Select a category to begin browsing our wares.</p>
-		</GuidePage>
-		<GuidePage>
-			<p>When you find something you love, click <i>Add to Cart</i> to add the product to your shopping cart.</p>
-		</GuidePage>
-	</Guide>
+	return (
+		<Guide
+			onFinish={ () => setIsOpen( false ) }
+			pages={ [
+				{
+					content: <p>Welcome to the ACME Store!</p>,
+				},
+				{
+					image: <img src="https://acmestore.com/add-to-cart.png" />,
+					content: <p>Click <i>Add to Cart</i> to buy a product.</p>,
+				},
+			] }
+		/>
+	);
 }
 ```
 
@@ -35,10 +41,11 @@ A function which is called when the guide is finished. The guide is finished whe
 - Type: `function`
 - Required: Yes
 
-### children
+### pages
 
-A list of `GuidePage` components. One page is shown at a time.
+A list of objects describining each page in the guide. Each object **must** contain a `'content'` property and may optionally contain a `'image'` property.
 
+- Type: `array`
 - Required: Yes
 
 ### className

packages/components/src/guide/icons.js

@@ -1,28 +1,14 @@
 /**
  * WordPress dependencies
  */
-import { SVG, Path, Circle } from '@wordpress/primitives';
-
-export const BackButtonIcon = () => (
-	<SVG xmlns="http://www.w3.org/2000/svg" width="24" height="24">
-		<Path d="M15.41 7.41L14 6l-6 6 6 6 1.41-1.41L10.83 12z" />
-		<Path d="M0 0h24v24H0z" fill="none" />
-	</SVG>
-);
-
-export const ForwardButtonIcon = () => (
-	<SVG xmlns="http://www.w3.org/2000/svg" width="24" height="24">
-		<Path d="M10 6L8.59 7.41 13.17 12l-4.58 4.59L10 18l6-6z" />
-		<Path d="M0 0h24v24H0z" fill="none" />
-	</SVG>
-);
+import { SVG, Circle } from '@wordpress/primitives';
 
 export const PageControlIcon = ( { isSelected } ) => (
-	<SVG width="12" height="12" fill="none" xmlns="http://www.w3.org/2000/svg">
+	<SVG width="8" height="8" fill="none" xmlns="http://www.w3.org/2000/svg">
 		<Circle
-			cx="6"
-			cy="6"
-			r="6"
+			cx="4"
+			cy="4"
+			r="4"
 			fill={ isSelected ? '#419ECD' : '#E1E3E6' }
 		/>
 	</SVG>

packages/components/src/guide/index.js

@@ -6,7 +6,8 @@ import classnames from 'classnames';
 /**
  * WordPress dependencies
  */
-import { useState, Children } from '@wordpress/element';
+import { useState, useEffect, Children } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
 import { __ } from '@wordpress/i18n';
 
 /**
@@ -16,7 +17,6 @@ import Modal from '../modal';
 import KeyboardShortcuts from '../keyboard-shortcuts';
 import Button from '../button';
 import PageControl from './page-control';
-import { BackButtonIcon, ForwardButtonIcon } from './icons';
 import FinishButton from './finish-button';
 
 export default function Guide( {
@@ -25,12 +25,24 @@ export default function Guide( {
 	contentLabel,
 	finishButtonText,
 	onFinish,
+	pages = [],
 } ) {
 	const [ currentPage, setCurrentPage ] = useState( 0 );
 
-	const numberOfPages = Children.count( children );
+	useEffect( () => {
+		if ( Children.count( children ) ) {
+			deprecated( 'Passing children to <Guide>', {
+				alternative: 'the `pages` prop',
+			} );
+		}
+	}, [ children ] );
+
+	if ( Children.count( children ) ) {
+		pages = Children.map( children, ( child ) => ( { content: child } ) );
+	}
+
 	const canGoBack = currentPage > 0;
-	const canGoForward = currentPage < numberOfPages - 1;
+	const canGoForward = currentPage < pages.length - 1;
 
 	const goBack = () => {
 		if ( canGoBack ) {
@@ -44,7 +56,7 @@ export default function Guide( {
 		}
 	};
 
-	if ( numberOfPages === 0 ) {
+	if ( pages.length === 0 ) {
 		return null;
 	}
 
@@ -63,36 +75,39 @@ export default function Guide( {
 			/>
 
 			<div className="components-guide__container">
-				{ children[ currentPage ] }
+				<div className="components-guide__page">
+					{ pages[ currentPage ].image }
 
-				{ ! canGoForward && (
-					<FinishButton
-						className="components-guide__inline-finish-button"
-						onClick={ onFinish }
-					>
-						{ finishButtonText || __( 'Finish' ) }
-					</FinishButton>
-				) }
+					<PageControl
+						currentPage={ currentPage }
+						numberOfPages={ pages.length }
+						setCurrentPage={ setCurrentPage }
+					/>
+
+					{ pages[ currentPage ].content }
+
+					{ ! canGoForward && (
+						<FinishButton
+							className="components-guide__inline-finish-button"
+							onClick={ onFinish }
+						>
+							{ finishButtonText || __( 'Finish' ) }
+						</FinishButton>
+					) }
+				</div>
 
 				<div className="components-guide__footer">
 					{ canGoBack && (
 						<Button
 							className="components-guide__back-button"
-							icon={ <BackButtonIcon /> }
 							onClick={ goBack }
 						>
 							{ __( 'Previous' ) }
 						</Button>
 					) }
-					<PageControl
-						currentPage={ currentPage }
-						numberOfPages={ numberOfPages }
-						setCurrentPage={ setCurrentPage }
-					/>
 					{ canGoForward && (
 						<Button
 							className="components-guide__forward-button"
-							icon={ <ForwardButtonIcon /> }
 							onClick={ goForward }
 						>
 							{ __( 'Next' ) }

packages/components/src/guide/page.js

@@ -1,3 +1,15 @@
+/**
+ * WordPress dependencies
+ */
+import { useEffect } from '@wordpress/element';
+import deprecated from '@wordpress/deprecated';
+
 export default function GuidePage( props ) {
+	useEffect( () => {
+		deprecated( '<GuidePage>', {
+			alternative: 'the `pages` prop in <Guide>',
+		} );
+	}, [] );
+
 	return <div { ...props } />;
 }

packages/components/src/guide/stories/index.js

@@ -14,7 +14,6 @@ import { useState } from '@wordpress/element';
  */
 import Button from '../../button';
 import Guide from '../';
-import GuidePage from '../page';
 
 export default { title: 'Components/Guide', component: Guide };
 
@@ -33,16 +32,20 @@ const ModalExample = ( { numberOfPages, ...props } ) => {
 				Open Guide
 			</Button>
 			{ isOpen && (
-				<Guide { ...props } onFinish={ closeGuide }>
-					{ times( numberOfPages, ( page ) => (
-						<GuidePage key={ page }>
-							<h1>
-								Page { page + 1 } of { numberOfPages }
-							</h1>
-							<p>{ loremIpsum }</p>
-						</GuidePage>
-					) ) }
-				</Guide>
+				<Guide
+					{ ...props }
+					onFinish={ closeGuide }
+					pages={ times( numberOfPages, ( page ) => ( {
+						content: (
+							<>
+								<h1>
+									Page { page + 1 } of { numberOfPages }
+								</h1>
+								<p>{ loremIpsum }</p>
+							</>
+						),
+					} ) ) }
+				/>
 			) }
 		</>
 	);