@automattic/onboarding 1.0.0

package/src/mshots-image/index.tsx

@@ -0,0 +1,368 @@
+import { addQueryArgs } from '@wordpress/url';
+import clsx from 'clsx';
+import debugFactory from 'debug';
+import { useState, useEffect, useRef } from 'react';
+
+import './style.scss';
+
+interface MShotsImageProps {
+	url: string;
+	alt: string;
+	'aria-labelledby': string;
+	options: MShotsOptions;
+	scrollable?: boolean;
+}
+
+export type MShotsOptions = {
+	vpw: number;
+	vph: number;
+	w: number;
+	h?: number;
+	screen_height?: number;
+	format?: 'png' | 'jpeg';
+	oldHighResImageLoading?: boolean;
+};
+
+const debug = debugFactory( 'design-picker:mshots-image' );
+
+export function mshotsUrl( targetUrl: string, options: MShotsOptions, count = 0 ): string {
+	const mshotsUrl = 'https://s0.wp.com/mshots/v1/';
+	const mshotsRequest = addQueryArgs( mshotsUrl + encodeURIComponent( targetUrl ), {
+		...options,
+		count,
+	} );
+	return mshotsRequest;
+}
+
+const MAXTRIES = 10;
+
+// This custom react hook returns null while the image is loading and the page
+// (not image) URL once loading is complete.
+//
+// It also triggers a re-render (via setState()) when the value changes, so just
+// check that the requested URL matches the returned URL.
+//
+// Note the loading may occur immediately if the image is already available, or
+// may take several seconds if mshots has to generate and cache new images.
+//
+// The calling code doesn't need to worry about the details except that you'll
+// want some sort of loading display.
+//
+// Inspired by https://stackoverflow.com/a/60458593
+const useMshotsImg = (
+	src: string,
+	options: MShotsOptions,
+	imgRef: React.MutableRefObject< HTMLImageElement | null >
+): string | null => {
+	const [ loadedImg, setLoadedImg ] = useState< string | null >( null );
+	const [ count, setCount ] = useState( 0 );
+	const previousSrc = useRef( src );
+
+	const timeoutIdRef = useRef< number >();
+
+	const previousImg = useRef< HTMLImageElement | null >( null );
+	const previousOptions = useRef< MShotsOptions >();
+	// Oddly, we need to assign to current here after ref creation in order to
+	// pass the equivalence check and avoid a spurious reset
+	previousOptions.current = options;
+
+	// Note: Mshots doesn't care about the "count" param, but it is important
+	// to browser caching. Getting this wrong looks like the url resolving
+	// before the image is ready.
+	useEffect( () => {
+		// If there's been a "props" change we need to reset everything:
+		if (
+			options !== previousOptions.current ||
+			( src !== previousSrc.current && imgRef.current )
+		) {
+			// Make sure an old image can't trigger a spurious state update
+			debug( 'resetting mShotsUrl request' );
+			if ( src !== previousSrc.current ) {
+				debug( 'src changed\nfrom', previousSrc.current, '\nto', src );
+			}
+			if ( options !== previousOptions.current ) {
+				debug( 'options changed\nfrom', previousOptions.current, '\nto', options );
+			}
+			if ( previousImg.current && previousImg.current.onload ) {
+				previousImg.current.onload = null;
+				if ( timeoutIdRef.current ) {
+					clearTimeout( timeoutIdRef.current );
+					timeoutIdRef.current = undefined;
+				}
+			}
+
+			setCount( 0 );
+			if ( previousImg.current !== imgRef.current ) {
+				previousImg.current = imgRef.current;
+			}
+
+			previousOptions.current = options;
+			previousSrc.current = src;
+		}
+
+		const srcUrl = mshotsUrl( src, options, count );
+
+		if ( imgRef.current ) {
+			imgRef.current.onload = () => {
+				// Detect default image (Don't request a 400x300 image).
+				//
+				// If this turns out to be a problem, it might help to know that the
+				// http request status for the default is a 307. Unfortunately we
+				// don't get the request through an img element so we'd need to
+				// take a completely different approach using ajax.
+				if ( imgRef.current?.naturalWidth !== 400 || imgRef.current?.naturalHeight !== 300 ) {
+					setLoadedImg( src );
+				} else if ( count < MAXTRIES ) {
+					// Only refresh 10 times
+					// Triggers a target.src change with increasing timeouts
+					timeoutIdRef.current = window.setTimeout(
+						() => setCount( ( count ) => count + 1 ),
+						count * 500
+					);
+				}
+			};
+			imgRef.current.src = srcUrl;
+		}
+
+		return () => {
+			if ( imgRef.current && imgRef.current.onload ) {
+				imgRef.current.onload = null;
+			}
+			if ( previousImg.current && previousImg.current.onload ) {
+				previousImg.current.onload = null;
+			}
+			clearTimeout( timeoutIdRef.current );
+		};
+	}, [ src, count, options, imgRef ] );
+
+	return loadedImg;
+};
+
+// Temporary for A/B test.
+const useMshotsImgTreatment = (
+	src: string,
+	options: MShotsOptions
+): HTMLImageElement | undefined => {
+	const [ loadedImg, setLoadedImg ] = useState< HTMLImageElement >();
+	const [ count, setCount ] = useState( 0 );
+	const previousSrc = useRef( src );
+
+	const imgRef = useRef< HTMLImageElement >();
+	const timeoutIdRef = useRef< number >();
+
+	const previousImg = useRef< HTMLImageElement >();
+	const previousOptions = useRef< MShotsOptions >();
+	// Oddly, we need to assign to current here after ref creation in order to
+	// pass the equivalence check and avoid a spurious reset
+	previousOptions.current = options;
+
+	// Note: Mshots doesn't care about the "count" param, but it is important
+	// to browser caching. Getting this wrong looks like the url resolving
+	// before the image is ready.
+	useEffect( () => {
+		// If there's been a "props" change we need to reset everything:
+		if (
+			options !== previousOptions.current ||
+			( src !== previousSrc.current && imgRef.current )
+		) {
+			// Make sure an old image can't trigger a spurious state update
+			debug( 'resetting mShotsUrl request' );
+			if ( src !== previousSrc.current ) {
+				debug( 'src changed\nfrom', previousSrc.current, '\nto', src );
+			}
+			if ( options !== previousOptions.current ) {
+				debug( 'options changed\nfrom', previousOptions.current, '\nto', options );
+			}
+			if ( previousImg.current && previousImg.current.onload ) {
+				previousImg.current.onload = null;
+				if ( timeoutIdRef.current ) {
+					clearTimeout( timeoutIdRef.current );
+					timeoutIdRef.current = undefined;
+				}
+			}
+
+			setLoadedImg( undefined );
+			setCount( 0 );
+			previousImg.current = imgRef.current;
+
+			previousOptions.current = options;
+			previousSrc.current = src;
+		}
+
+		const srcUrl = mshotsUrl( src, options, count );
+		const newImage = new Image();
+		newImage.onload = () => {
+			// Detect default image (Don't request a 400x300 image).
+			//
+			// If this turns out to be a problem, it might help to know that the
+			// http request status for the default is a 307. Unfortunately we
+			// don't get the request through an img element so we'd need to
+			// take a completely different approach using ajax.
+			if ( newImage.naturalWidth !== 400 || newImage.naturalHeight !== 300 ) {
+				// Note we're using the naked object here, not the ref, because
+				// this is the callback on the image itself. We'd never want
+				// the image to finish loading and set some other image.
+				setLoadedImg( newImage );
+			} else if ( count < MAXTRIES ) {
+				// Only refresh 10 times
+				// Triggers a target.src change with increasing timeouts
+				timeoutIdRef.current = window.setTimeout(
+					() => setCount( ( count ) => count + 1 ),
+					count * 500
+				);
+			}
+		};
+		newImage.src = srcUrl;
+		imgRef.current = newImage;
+
+		return () => {
+			if ( imgRef.current && imgRef.current.onload ) {
+				imgRef.current.onload = null;
+			}
+			clearTimeout( timeoutIdRef.current );
+		};
+	}, [ src, count, options ] );
+
+	return loadedImg;
+};
+
+const MShotsImageControl = ( {
+	url,
+	'aria-labelledby': labelledby,
+	alt,
+	options,
+	scrollable = false,
+}: MShotsImageProps ) => {
+	const imgRef = useRef< HTMLImageElement | null >( null );
+	const currentlyLoadedUrl = useMshotsImg( url, options, imgRef );
+	const src: string = imgRef.current?.src || '';
+	const visible = src && url === currentlyLoadedUrl;
+	const backgroundImage = src && `url( ${ src } )`;
+
+	const animationScrollSpeedInPixelsPerSecond = 400;
+	const animationDuration =
+		( imgRef.current?.naturalHeight || 600 ) / animationScrollSpeedInPixelsPerSecond;
+
+	const scrollableStyles = {
+		backgroundImage,
+		transition: `background-position ${ animationDuration }s`,
+	};
+
+	const style = {
+		...( scrollable ? scrollableStyles : {} ),
+	};
+
+	const className = clsx(
+		'mshots-image__container',
+		scrollable && 'hover-scroll',
+		visible ? 'mshots-image-visible' : 'mshots-image__loader'
+	);
+
+	if ( options?.oldHighResImageLoading ) {
+		return scrollable ? (
+			<div className={ className } style={ style } aria-labelledby={ labelledby }>
+				<img ref={ imgRef } className="mshots-dummy-image" aria-hidden="true" alt="" />
+			</div>
+		) : (
+			<img
+				ref={ imgRef }
+				{ ...{ className, style, src, alt } }
+				aria-labelledby={ labelledby }
+				alt={ alt }
+			/>
+		);
+	} // else, prettier doesn't like having an else after a return
+	return scrollable ? (
+		<div className={ className } style={ style } aria-labelledby={ labelledby }>
+			<img ref={ imgRef } loading="lazy" className="mshots-dummy-image" aria-hidden="true" alt="" />
+		</div>
+	) : (
+		<img
+			loading="lazy"
+			ref={ imgRef }
+			{ ...{ className, style, src, alt } }
+			aria-labelledby={ labelledby }
+			alt={ alt }
+		/>
+	);
+};
+
+// Temporary for A/B test.
+const MShotsImageTreatment = ( {
+	url,
+	'aria-labelledby': labelledby,
+	alt,
+	options,
+	scrollable = false,
+}: MShotsImageProps ) => {
+	const maybeImage = useMshotsImgTreatment( url, options );
+	const src: string = maybeImage?.src || '';
+	const visible = !! src;
+	const backgroundImage = maybeImage?.src && `url( ${ maybeImage?.src } )`;
+
+	const animationScrollSpeedInPixelsPerSecond = 400;
+	const animationDuration =
+		( maybeImage?.naturalHeight || 600 ) / animationScrollSpeedInPixelsPerSecond;
+
+	const scrollableStyles = {
+		backgroundImage,
+		transition: `background-position ${ animationDuration }s`,
+	};
+
+	const style = {
+		...( scrollable ? scrollableStyles : {} ),
+	};
+
+	const className = clsx(
+		'mshots-image__container',
+		scrollable && 'hover-scroll',
+		visible ? 'mshots-image-visible' : 'mshots-image__loader'
+	);
+
+	// The "! visible" here is only to dodge a particularly specific css
+	// rule effecting the placeholder while loading static images:
+	// '.design-picker .design-picker__image-frame img { ..., height: auto }'
+	return scrollable || ! visible ? (
+		<div className={ className } style={ style } aria-labelledby={ labelledby } />
+	) : (
+		<img { ...{ className, style, src, alt } } aria-labelledby={ labelledby } alt={ alt } />
+	);
+};
+
+// For hover-scroll, we use a div with a background image (rather than an img element)
+// in order to use transitions between `top` and `bottom` on the
+// `background-position` property.
+// The "normal" top & bottom properties are problematic individually because we
+// don't know how big the images will be, and using both gets the
+// right positions but with no transition (as they're different properties).
+const MShotsImage = ( {
+	url,
+	'aria-labelledby': labelledby,
+	alt,
+	options,
+	scrollable = false,
+}: MShotsImageProps ) => {
+	// Return MShotsImageControl or MShotsImageTreatment depending on options.oldHighResImageLoading
+	if ( options?.oldHighResImageLoading ) {
+		return (
+			<MShotsImageTreatment
+				url={ url }
+				aria-labelledby={ labelledby }
+				alt={ alt }
+				options={ options }
+				scrollable={ scrollable }
+			/>
+		);
+	}
+	return (
+		<MShotsImageControl
+			url={ url }
+			aria-labelledby={ labelledby }
+			alt={ alt }
+			options={ options }
+			scrollable={ scrollable }
+		/>
+	);
+};
+
+export default MShotsImage;

package/src/mshots-image/style.scss

@@ -0,0 +1,43 @@
+@import "../../styles/mixins";
+
+.mshots-image__loader {
+	@include onboarding-placeholder();
+}
+
+.mshots-image__container {
+	height: 100%;
+}
+
+.hover-scroll {
+	background-size: 100%;
+	background-position: top;
+	background-repeat: no-repeat;
+	margin-left: auto;
+	margin-right: auto;
+
+	&:hover {
+		background-position: bottom;
+	}
+}
+
+.mshots-image-visible {
+	animation: fadein 300ms;
+}
+
+// Increase specificity by repeating class name.
+.mshots-dummy-image.mshots-dummy-image {
+	position: absolute;
+	display: block;
+	visibility: hidden;
+	height: 0;
+	width: 0;
+}
+
+@keyframes fadein {
+	from {
+		opacity: 0;
+	}
+	to {
+		opacity: 1;
+	}
+}

package/src/mshots-image/test/mshots-image.tsx

@@ -0,0 +1,5 @@
+describe( 'mshots-image', () => {
+	it( 'should be replaced with real tests', () => {
+		expect( 1 ).toBeTruthy();
+	} );
+} );

package/src/navigator/hooks/index.tsx

@@ -0,0 +1,2 @@
+export { default as useNavigatorListener } from './use-navigator-listener';
+export type { OnNavigatorPathChange } from './use-navigator-listener';

package/src/navigator/hooks/use-navigator-listener.tsx

@@ -0,0 +1,18 @@
+import { __experimentalUseNavigator as useNavigator } from '@wordpress/components';
+import { useEffect, useRef } from 'react';
+
+export type OnNavigatorPathChange = ( path?: string ) => void;
+
+const useNavigatorListener = ( onNavigatorPathChange?: OnNavigatorPathChange ) => {
+	const { location } = useNavigator();
+	const previousPathRef = useRef( '' );
+
+	useEffect( () => {
+		if ( location.path && location.path !== previousPathRef.current ) {
+			onNavigatorPathChange?.( location.path );
+			previousPathRef.current = location.path;
+		}
+	}, [ location.path, onNavigatorPathChange ] );
+};
+
+export default useNavigatorListener;

package/src/navigator/index.ts

@@ -0,0 +1,7 @@
+export * from './hooks';
+export { NavigatorButtonAsItem, NavigatorItem } from './navigator-buttons';
+export { default as NavigatorHeader } from './navigator-header';
+export { default as NavigatorItemGroup } from './navigator-item-group';
+export { default as NavigatorListener } from './navigator-listener';
+export { default as NavigatorScreen } from './navigator-screen';
+export * from './navigator-screens';

package/src/navigator/navigator-buttons/index.tsx

@@ -0,0 +1,58 @@
+import {
+	__experimentalNavigatorButton as NavigatorButton,
+	__experimentalHStack as HStack,
+	__experimentalItem as Item,
+	FlexItem,
+} from '@wordpress/components';
+import { isRTL } from '@wordpress/i18n';
+import { Icon, chevronLeft, chevronRight, check } from '@wordpress/icons';
+import clsx from 'clsx';
+import './style.scss';
+
+interface NavigatorItemProps {
+	className?: string;
+	icon?: JSX.Element;
+	children: React.ReactNode;
+	onClick?: () => void;
+	checked?: boolean;
+	active?: boolean;
+}
+
+interface NavigatorButtonAsItemProps extends NavigatorItemProps {
+	path: string;
+}
+
+export function NavigatorItem( { icon, checked, active, children, ...props }: NavigatorItemProps ) {
+	const content = icon ? (
+		<HStack justify="flex-start">
+			<Icon className="navigator-item__icon" icon={ checked ? check : icon } size={ 24 } />
+			<FlexItem className="navigator-item__text" display="flex" isBlock>
+				{ children }
+			</FlexItem>
+		</HStack>
+	) : (
+		<FlexItem display="flex" isBlock>
+			{ children }
+		</FlexItem>
+	);
+
+	const forwardIcon = isRTL() ? chevronLeft : chevronRight;
+
+	return (
+		<Item
+			{ ...props }
+			className={ clsx( 'navigator-item', {
+				'navigator-item--active': active,
+			} ) }
+		>
+			<HStack justify="space-between">
+				{ content }
+				<Icon icon={ forwardIcon } size={ 24 } />
+			</HStack>
+		</Item>
+	);
+}
+
+export const NavigatorButtonAsItem = ( { ...props }: NavigatorButtonAsItemProps ) => {
+	return <NavigatorButton as={ NavigatorItem } { ...props } />;
+};

package/src/navigator/navigator-buttons/style.scss

@@ -0,0 +1,47 @@
+@import "@automattic/typography/styles/fonts";
+
+.components-item.navigator-item {
+	height: 44px;
+	line-height: 44px;
+	padding: 0 5px 0 8px;
+	margin: 0 -5px 0 -8px;
+	font-size: $font-body-small;
+	font-weight: 400;
+	letter-spacing: -0.15px;
+	color: var(--studio-gray-100);
+	border: none;
+	background: transparent;
+	cursor: pointer;
+
+	svg {
+		flex-shrink: 0;
+		fill: currentColor;
+	}
+
+	&:hover,
+	&:focus-visible {
+		color: var(--studio-blue-50);
+	}
+
+	&:focus {
+		box-shadow: none;
+	}
+
+	&:focus-visible {
+		border-color: var(--color-primary);
+		box-shadow: 0 0 0 2px var(--color-primary-light);
+	}
+
+	&:active {
+		background-color: var(--studio-blue-0);
+	}
+
+	.navigator-item__text {
+		padding-left: 1px;
+	}
+
+	&--active {
+		background-color: var(--studio-blue-0);
+		color: var(--studio-blue-50);
+	}
+}

package/src/navigator/navigator-header/index.tsx

@@ -0,0 +1,40 @@
+import { Button, Gridicon } from '@automattic/components';
+import {
+	__experimentalHStack as HStack,
+	__experimentalNavigatorBackButton as NavigatorBackButton,
+} from '@wordpress/components';
+import { useTranslate, TranslateResult } from 'i18n-calypso';
+import './style.scss';
+
+interface Props {
+	title: JSX.Element;
+	description?: TranslateResult;
+	hideBack?: boolean;
+	onBack?: () => void;
+}
+
+const NavigatorHeader = ( { title, description, hideBack, onBack }: Props ) => {
+	const translate = useTranslate();
+
+	return (
+		<div className="navigator-header">
+			<HStack className="navigator-header__heading" spacing={ 2 } justify="flex-start">
+				{ ! hideBack && (
+					<NavigatorBackButton
+						as={ Button }
+						title={ translate( 'Back' ) }
+						borderless
+						aria-label={ translate( 'Navigate to the previous view' ) }
+						onClick={ onBack }
+					>
+						<Gridicon icon="chevron-left" size={ 16 } />
+					</NavigatorBackButton>
+				) }
+				<h2>{ title }</h2>
+			</HStack>
+			{ description && <p className="navigator-header__description">{ description }</p> }
+		</div>
+	);
+};
+
+export default NavigatorHeader;

package/src/navigator/navigator-header/style.scss

@@ -0,0 +1,45 @@
+@import "@wordpress/base-styles/breakpoints";
+@import "@wordpress/base-styles/mixins";
+@import "@automattic/typography/styles/fonts";
+
+.navigator-header {
+	display: none;
+	margin-bottom: 30px;
+
+	@include break-large {
+		display: block;
+	}
+}
+
+.navigator-header__heading {
+	margin-bottom: 8px;
+	color: var(--color-neutral-100);
+	text-wrap: pretty;
+
+	h2 {
+		font-family: Recoleta, sans-serif;
+		font-style: normal;
+		font-weight: 400;
+		font-size: $font-title-large;
+		line-height: 40px;
+		letter-spacing: -0.32px;
+	}
+
+	.button.is-borderless .gridicon {
+		top: 4px;
+	}
+
+	.premium-badge {
+		margin-inline-start: 2px;
+	}
+}
+
+.navigator-header__description {
+	font-size: $font-body-small;
+	font-weight: 400;
+	line-height: 20px;
+	letter-spacing: -0.15px;
+	color: var(--color-neutral-60);
+	margin: 0;
+	text-wrap: pretty;
+}

package/src/navigator/navigator-item-group/index.tsx

@@ -0,0 +1,23 @@
+import {
+	__experimentalVStack as VStack,
+	__experimentalItemGroup as ItemGroup,
+} from '@wordpress/components';
+import './style.scss';
+
+type Props = {
+	children: React.ReactNode;
+	title?: string;
+};
+
+const NavigatorItemGroup = ( { children, title }: Props ) => {
+	return (
+		<section className="navigator-item-group">
+			<VStack direction="column" justify="flex-start" alignment="stretch">
+				{ title && <h3 className="navigator-item-group__title">{ title }</h3> }
+				<ItemGroup>{ children }</ItemGroup>
+			</VStack>
+		</section>
+	);
+};
+
+export default NavigatorItemGroup;

package/src/navigator/navigator-item-group/style.scss

@@ -0,0 +1,28 @@
+@import "@automattic/typography/styles/fonts";
+
+.navigator-item-group {
+	flex-shrink: 0;
+
+	.components-item-group > div[role="listitem"] {
+		display: flex;
+	}
+
+	.navigator-item {
+		flex-grow: 1;
+	}
+
+	&:nth-child(1 of &):nth-last-child(1 of &) {
+		.navigator-item-group__title {
+			display: none;
+		}
+	}
+}
+
+.navigator-item-group__title {
+	color: var(--color-neutral-100);
+	font-size: $font-body-small;
+	font-weight: 500;
+	letter-spacing: -0.15px;
+	line-height: 1.4;
+	margin-bottom: 8px;
+}