@automattic/onboarding 1.0.0 → 1.0.1

package/src/step-container-v2/README.md

@@ -0,0 +1,235 @@
+# StepContainerV2
+
+Next-generation step composition utility.
+
+**Disclaimer: This is a work in progress and the API is not yet stable.**
+
+## Why
+
+This is a compilation of everything we've learned with `StepContainer`. Just like its predecessor, it focuses on aesthetics of the step (standardized components, margins, paddings, etc.), and not their content or functionality. The main difference is that it's more flexible and easier to extend.
+
+The new version focuses on modularity and composition instead of overrides through props and CSS. We've observed that the previous version accepted a variety of props that modified how a component looks. Most of the times these properties had to play nicely with each other, which increased complexity.
+
+This version, however, provides several "slots" that allow the developer to declare _which_ parts of the step will be rendered through the creation of wireframes, instead of imperatively specifying _what_ to render. `topBar`, `heading`, `stickyBottomBar`, and `footer` are example of slots.
+
+It also provides the elements to be used within these slots, such as `TopBar`, `Heading`, `StickyBottomBar`, and `Footer`, as well as their internal elements, such as buttons like `PrimaryButton`, `SkipButton`, and `BackButton`.
+
+Here's an example:
+
+```jsx
+import { Step } from '@automattic/onboarding';
+
+const MyStep = () => {
+	const nextButton = <Step.PrimaryButton onClick={ navigation.submit } />;
+
+	return (
+		<Step.CenteredColumnLayout
+			columnWidth={ 4 }
+			topBar={ <Step.TopBar /> }
+			heading={ <Step.Heading text="Heading" /> }
+			stickyBottomBar={ <Step.StickyBottomBar rightElement={ nextButton } /> }
+		>
+			{ ( { isSmallViewport } ) => (
+				<>
+					<p>Here comes the content of the step.</p>
+					{ isSmallViewport && nextButton }
+				</>
+			) }
+		</Step.CenteredColumnLayout>
+	);
+};
+```
+
+In the example above, the top bar won't have a skip nor a back button. There's a `stickyBottomBar` that will render the Next button on mobile, and the same button will also be rendered within the step's content, but only on smaller screens and above. Although it's possible, this particular step won't render a footer.
+
+It reduces the complexity of layouting by delegating the rendering responsibility to the components within the slots. A good example of what we mean here is the [`headerImageUrl` prop of `StepContainer`](../step-container/index.tsx), which should exist if `isHorizontalLayout` is `true`, but there is no explanation of that in the code, and it's not obvious to the developer reading code introduced by others.
+
+Read the [how to extend it](#how-to-extend-it) section to learn how to reproduce this behavior in `StepContainerV2`.
+
+## How to use it
+
+**You shouldn't use `StepContainerV2` directly. Instead, use the wireframes that are exported from this package.**
+
+Aside from the stories (run `yarn storybook:start`), you can follow the examples from `~/client/landing/stepper/declarative-flow/internals/steps-repository`.
+
+Please do NOT override the `Step.*` components with CSS as this creates inconsistencies between steps and becomes a maintenance nightmare. Ideally, you should not need to do this as the steps are designed to be composed, and the wireframes are approved by the designers.
+
+### What are wireframes?
+
+Wireframes are layout arrangements that have been approved by the Dotcom designers. They are exported from this package and can be used in the steps.
+
+Here are the wireframes specs: <https://www.figma.com/design/QFAYPvq4xYUZC5AFkrfJFM/Dotcom-Onboarding-(Open)?node-id=1-31&p=f&t=CX7AmXyb9CTsFGAI-0>.
+
+## How to extend it
+
+- Try to keep the components as generic as possible, and without adding overrides to components coming from `@wordpress/components` unless explicitly approved by the designers.
+- If the step has a unique UI element that does not exist in other steps, it probably does not belong in `StepContainerV2`. Try using some of the slots, or add a new one.
+- Do not add `is*` props to `StepContainerV2` as we want to stick to composition.
+- Do not export `StepContainerV2` directly. We're defining several wireframes that were approved by the designers, and these are the components you should be using in the steps.
+
+### Workshop: How to create the horizontal layout wireframe
+
+As a way to demonstrate how to create a new wireframe, let's re-create `HorizontalLayout`.
+
+This layout arranges two columns side by side. It has the heading on the left and the content on the right. Optionally, an image is rendered below the heading. One example of where this layout is used is in `/setup/site-setup/intent?siteSlug=%s`.
+
+Let's create a new wireframe named `HorizontalLayout`. Here's what its code looks like:
+
+```tsx
+interface HorizontalLayoutProps {
+	topBar?: ContentProp;
+	heading?: ReactNode;
+	imageUrl?: string;
+	className?: string;
+	children?: ContentProp;
+	footer?: ReactNode;
+	stickyBottomBar?: ContentProp;
+}
+
+export const HorizontalLayout = ( {
+	topBar,
+	heading,
+	imageUrl,
+	children,
+	footer,
+	stickyBottomBar,
+}: HorizontalLayoutProps ) => {
+	return (
+		<StepContainerV2>
+			{ ( context ) => {
+				const content = typeof children === 'function' ? children( context ) : children;
+
+				return (
+					<>
+						<TopBarRenderer topBar={ topBar } />
+						<ContentWrapper width="wide" centerAligned={ context.isSmallViewport }>
+							<ContentRow
+								columns={ 10 }
+								className="step-container-v2__content-row--horizontal-layout"
+							>
+								<div className="step-container-v2__content-row--horizontal-layout-left">
+									{ heading }
+									{ imageUrl && <img src={ imageUrl } alt="" /> }
+								</div>
+								<div className="step-container-v2__content-row--horizontal-layout-right">
+									{ content }
+								</div>
+							</ContentRow>
+							{ footer }
+						</ContentWrapper>
+						<StickyBottomBarRenderer stickyBottomBar={ stickyBottomBar } />
+					</>
+				);
+			} }
+		</StepContainerV2>
+	);
+};
+```
+
+Then, we need to add the styles for the new wireframe. Let's create a new file called `style.scss` and add the following code:
+
+```scss
+.step-container-v2__content-row--horizontal-layout {
+	display: flex;
+	flex-direction: column;
+	gap: 3rem;
+
+	@include break-large {
+		flex-direction: row;
+	}
+}
+
+.step-container-v2__content-row--horizontal-layout-left,
+.step-container-v2__content-row--horizontal-layout-right {
+	flex: 1;
+}
+
+.step-container-v2__content-row--horizontal-layout-left {
+	display: flex;
+	flex-direction: column;
+	align-items: flex-start;
+	gap: 3rem;
+}
+```
+
+> Notice that we're using the `@include break-large` mixin to target the large viewport and above. The Gutenberg breakpoints are matched within StepContainerV2, so we can use them to create responsive styles for the wireframe.
+
+One implementation detail is that the `HorizontalLayout` wireframe does not render the illustration on mobile. `StepContainerV2` accepts a render prop that can be used to render the content of the step. This is useful to conditionally render content based on the viewports defined for the wireframe. We can then modify the previous example to render the illustration only on medium and larger screens.
+
+Let's modify the `children` of `HorizontalLayout` to reflect this new requirement:
+
+```jsx
+( context ) => {
+	const content = typeof children === 'function' ? children( context ) : children;
+
+	return (
+		<>
+			<TopBarRenderer topBar={ topBar } />
+			<ContentWrapper width="wide" centerAligned={ context.isSmallViewport }>
+				<ContentRow columns={ 10 } className="step-container-v2__content-row--horizontal-layout">
+					<div className="step-container-v2__content-row--horizontal-layout-left">
+						{ heading }
+						{ context.isSmallViewport && imageUrl && <img src={ imageUrl } alt="" /> }
+					</div>
+					<div className="step-container-v2__content-row--horizontal-layout-right">{ content }</div>
+				</ContentRow>
+				{ footer }
+			</ContentWrapper>
+			<StickyBottomBarRenderer stickyBottomBar={ stickyBottomBar } />
+		</>
+	);
+};
+```
+
+The horizontal layout wireframe expects the heading element to be left-aligned. We can create a new compound component and expose that as part of the public API of the wireframe:
+
+```tsx
+HorizontalLayout.Heading = ( props: ComponentProps< typeof Heading > ) => (
+	<Heading { ...props } align="left" />
+);
+```
+
+Last but not least, let's export the wireframe so it can be used in a step:
+
+```tsx
+// In step-container-v2/index.ts
+// ...
+export { HorizontalLayout } from './wireframes/HorizontalLayout/HorizontalLayout';
+```
+
+Et voilà, we've created a new wireframe. Here's how to use it:
+
+```jsx
+<Step.HorizontalLayout
+	heading={ <Step.HorizontalLayout.Heading text="Heading" /> }
+	imageUrl={ imageUrl }
+>
+	<p>Here comes the content rendered in the right column of the step.</p>
+	<Step.PrimaryButton onClick={ navigation.submit } />
+</Step.HorizontalLayout>
+```
+
+This feels a bit more verbose, but it's fine since we won't be creating wireframes every day. Remember that a wireframe is the shell of a step, which is designed to be reusable. This longer process ensures that the wireframe is well-thought-out.
+
+## FAQ
+
+### Will this component be called `StepContainerV2` forever?
+
+Of course not! The plan is for this new version to replace `StepContainer` entirely. We'll do this migration gradually.
+
+### How can I adopt it in Stepper without breaking steps that are used in multiple flows?
+
+There's an utility called `shouldUseStepContainerV2` that allows, at a step level, to define which flows should render this version of the container vs. the original one.
+
+### How do I run storybook?
+
+Either:
+
+- `yarn storybook:start` from the root of this package, or
+- `yarn workspace @automattic/onboarding storybook:start` from the root of the monorepo.
+
+Storybook will open a browser window automatically.
+
+### Who can I contact if I have any questions?
+
+Ping @quake-team on Slack.

package/src/step-container-v2/components/ContentRow/ContentRow.tsx

@@ -0,0 +1,27 @@
+import clsx from 'clsx';
+import type { CSSProperties, ReactNode } from 'react';
+
+import './style.scss';
+
+export const ContentRow = ( {
+	children,
+	columns = 12,
+	className,
+	stretched,
+}: {
+	children: ReactNode;
+	columns?: number;
+	className?: string;
+	stretched?: boolean;
+} ) => {
+	return (
+		<div
+			className={ clsx( 'step-container-v2__content-row', className, {
+				stretched,
+			} ) }
+			style={ { '--columns': columns } as CSSProperties }
+		>
+			{ children }
+		</div>
+	);
+};

package/src/step-container-v2/components/ContentRow/style.scss

@@ -0,0 +1,26 @@
+@import '@wordpress/base-styles/breakpoints';
+@import '@wordpress/base-styles/mixins';
+
+.step-container-v2__content-row {
+	width: 100%;
+	max-width: 100%;
+
+	@include break-small {
+		--total-column-width: calc(
+			var( --columns ) * var( --step-container-v2-content-column-width )
+		);
+		--total-gap-width: calc(
+			( var( --columns ) - 1 ) * var( --step-container-v2-content-column-gap )
+		);
+
+		--step-container-v2-content-row-max-width: calc(
+			var( --total-gap-width ) + var( --total-column-width )
+		);
+
+		max-width: var( --step-container-v2-content-row-max-width );
+	}
+
+	&.stretched {
+		align-self: stretch;
+	}
+}

package/src/step-container-v2/components/ContentWrapper/ContentWrapper.tsx

@@ -0,0 +1,41 @@
+import clsx from 'clsx';
+import type { ReactNode } from 'react';
+
+import './style.scss';
+
+type ContentWrapperProps = {
+	children: ReactNode;
+	centerAligned?: boolean;
+	axisDirection?: 'vertical' | 'horizontal';
+	noTopPadding?: boolean;
+	noBottomPadding?: boolean;
+	noInlinePadding?: boolean;
+	isFullWidth?: boolean;
+	noGap?: boolean;
+};
+
+export const ContentWrapper = ( {
+	children,
+	centerAligned,
+	axisDirection = 'vertical',
+	noTopPadding = false,
+	noBottomPadding = false,
+	noInlinePadding = false,
+	isFullWidth = false,
+	noGap = false,
+}: ContentWrapperProps ) => {
+	return (
+		<div
+			className={ clsx( 'step-container-v2__content-wrapper', `axis-${ axisDirection }`, {
+				'center-aligned': centerAligned,
+				'no-top-padding': noTopPadding,
+				'no-bottom-padding': noBottomPadding,
+				'no-inline-padding': noInlinePadding,
+				'is-full-width': isFullWidth,
+				'no-gap': noGap,
+			} ) }
+		>
+			{ children }
+		</div>
+	);
+};

package/src/step-container-v2/components/ContentWrapper/style.scss

@@ -0,0 +1,70 @@
+@import '@wordpress/base-styles/breakpoints';
+@import '@wordpress/base-styles/mixins';
+
+.step-container-v2__content-wrapper {
+	display: flex;
+	align-items: center;
+	gap: 3rem;
+	width: 100%;
+	box-sizing: border-box;
+	flex: 1;
+
+	&.axis-vertical {
+		flex-direction: column;
+	}
+
+	&.axis-horizontal {
+		flex-direction: row;
+	}
+
+	padding: var( --step-container-v2-content-block-padding )
+		var( --step-container-v2-content-inline-padding );
+
+	&.no-top-padding {
+		padding-top: 0;
+	}
+
+	&.no-bottom-padding {
+		padding-bottom: 0;
+	}
+
+	&.no-inline-padding {
+		padding: 0;
+	}
+
+	&.no-gap {
+		gap: 0;
+	}
+
+	--step-container-v2-content-max-width: 1344px;
+
+	max-width: calc(
+		var( --step-container-v2-content-max-width ) + 2 *
+			var( --step-container-v2-content-inline-padding )
+	);
+
+	--step-container-v2-content-column-gap: 24px;
+
+	--step-container-v2-content-max-width-minus-column-gaps: calc(
+		var( --step-container-v2-content-max-width ) - 11 *
+			var( --step-container-v2-content-column-gap )
+	);
+
+	--step-container-v2-content-column-width: calc(
+		var( --step-container-v2-content-max-width-minus-column-gaps ) / 12
+	);
+
+	&.center-aligned {
+		@include break-small {
+			justify-content: center;
+			padding-bottom: calc(
+				var( --step-container-v2-content-block-padding ) + var( --step-container-v2-top-bar-height )
+			);
+		}
+	}
+
+	&.is-full-width {
+		--step-container-v2-content-max-width: 100%;
+		max-width: 100%;
+	}
+}

package/src/step-container-v2/components/Heading/Heading.tsx

@@ -0,0 +1,31 @@
+import clsx from 'clsx';
+import { ReactNode } from 'react';
+
+import './style.scss';
+
+interface HeadingProps {
+	text: ReactNode;
+	subText?: ReactNode;
+	align?: 'left' | 'center';
+	size?: 'small';
+}
+
+export const Heading = ( { text, subText, align, size }: HeadingProps ) => {
+	return (
+		<div
+			className={ clsx( 'step-container-v2__heading', {
+				left: align === 'left',
+				center: align === 'center',
+			} ) }
+		>
+			<h1
+				className={ clsx( 'wp-brand-font', {
+					small: size === 'small',
+				} ) }
+			>
+				{ text }
+			</h1>
+			{ subText && <p>{ subText }</p> }
+		</div>
+	);
+};

package/src/step-container-v2/components/Heading/style.scss

@@ -0,0 +1,47 @@
+@import '@wordpress/base-styles/breakpoints';
+@import '@wordpress/base-styles/mixins';
+@import "@automattic/typography/styles/fonts";
+
+.step-container-v2__heading {
+	width: 100%;
+	text-wrap: balance;
+
+	@include break-small {
+		text-align: center;
+	}
+
+	h1 {
+		margin-block: 0;
+		color: var( --color-neutral-100 );
+		font-size: 2rem;
+		line-height: 1.25;
+		text-wrap: balance;
+
+		&:not( .small ) {
+			@include break-large {
+				font-size: 2.75rem;
+				line-height: 1.15;
+			}
+		}
+	}
+
+	p {
+		margin-block: 0.5rem 0;
+		color: var( --color-text );
+		font-size: 0.875rem;
+		line-height: 1.5;
+		text-wrap: balance;
+
+		@include break-large {
+			font-size: 1rem;
+		}
+	}
+
+	&.left {
+		text-align: left !important;
+	}
+
+	&.center {
+		text-align: center !important;
+	}
+}

package/src/step-container-v2/components/StepContainerV2/StepContainerV2.tsx

@@ -0,0 +1,55 @@
+import { useViewportMatch } from '@wordpress/compose';
+import { useMemo, useState } from 'react';
+import { ContentProp, StepContainerV2Context } from './context';
+import './style.scss';
+
+export const StepContainerV2 = ( {
+	children,
+	initialTopBarHeight,
+}: {
+	children: ContentProp;
+	initialTopBarHeight?: string;
+} ) => {
+	const isSmallViewport = useViewportMatch( 'small', '>=' );
+	const isLargeViewport = useViewportMatch( 'large', '>=' );
+
+	const [ topBarHeight, setTopBarHeight ] = useState( initialTopBarHeight ?? '0px' );
+	const [ stickyBottomBarHeight, setStickyBottomBarHeight ] = useState( 0 );
+
+	const stepContainerContextValue = useMemo(
+		() => ( {
+			isSmallViewport,
+			isLargeViewport,
+			topBarHeight,
+			setTopBarHeight,
+			stickyBottomBarHeight,
+			setStickyBottomBarHeight,
+		} ),
+		[
+			isSmallViewport,
+			isLargeViewport,
+			topBarHeight,
+			setTopBarHeight,
+			stickyBottomBarHeight,
+			setStickyBottomBarHeight,
+		]
+	);
+
+	const content = typeof children === 'function' ? children( stepContainerContextValue ) : children;
+
+	return (
+		<StepContainerV2Context.Provider value={ stepContainerContextValue }>
+			<div
+				className="step-container-v2"
+				style={
+					{
+						'--step-container-v2-top-bar-height': topBarHeight,
+						'--step-container-v2-sticky-bottom-bar-height': `${ stickyBottomBarHeight }px`,
+					} as React.CSSProperties
+				}
+			>
+				{ content }
+			</div>
+		</StepContainerV2Context.Provider>
+	);
+};

package/src/step-container-v2/components/StepContainerV2/context.ts

@@ -0,0 +1,25 @@
+import { createContext, ReactNode } from 'react';
+
+export interface StepContainerV2InternalContextType {
+	isSmallViewport: boolean;
+	isLargeViewport: boolean;
+	topBarHeight: string;
+	setTopBarHeight: ( height: string ) => void;
+	stickyBottomBarHeight: number;
+	setStickyBottomBarHeight: ( height: number ) => void;
+}
+
+export type ContentProp< T = ReactNode > =
+	| ( (
+			context: Pick< StepContainerV2InternalContextType, 'isSmallViewport' | 'isLargeViewport' >
+	  ) => T )
+	| T;
+
+export const StepContainerV2Context = createContext< StepContainerV2InternalContextType >( {
+	isSmallViewport: false,
+	isLargeViewport: false,
+	topBarHeight: '0px',
+	setTopBarHeight: () => {},
+	stickyBottomBarHeight: 0,
+	setStickyBottomBarHeight: () => {},
+} );

package/src/step-container-v2/components/StepContainerV2/style.scss

@@ -0,0 +1,21 @@
+@import '@wordpress/base-styles/breakpoints';
+@import '@wordpress/base-styles/mixins';
+
+.step-container-v2 {
+	--step-container-v2-content-block-padding: 2rem;
+	--step-container-v2-content-inline-padding: 1rem;
+
+	--step-container-v2-top-bar-padding: 1rem;
+	--step-container-v2-top-bar-content-height: 24px;
+
+	@include break-small {
+		--step-container-v2-content-inline-padding: 3rem;
+	}
+
+	width: 100%;
+	min-height: 100vh;
+	margin: 0;
+	display: flex;
+	flex-direction: column;
+	align-items: center;
+}

package/src/step-container-v2/components/StepCounter/StepCounter.tsx

@@ -0,0 +1,32 @@
+import { sprintf } from '@wordpress/i18n';
+import { useI18n } from '@wordpress/react-i18n';
+
+import './style.scss';
+
+export interface StepCounterProps {
+	current: number;
+	total: number;
+}
+
+export const StepCounter = ( { current, total }: StepCounterProps ) => {
+	const { __ } = useI18n();
+
+	return (
+		<span
+			className="step-container-v2__step-counter"
+			aria-label={ sprintf(
+				/* translators: 1: current step number, 2: total number of steps. */
+				__( 'Step %1$d of %2$d', __i18n_text_domain__ ),
+				current,
+				total
+			) }
+		>
+			{ sprintf(
+				/* translators: 1: current step number, 2: total number of steps. */
+				__( '%1$d of %2$d', __i18n_text_domain__ ),
+				current,
+				total
+			) }
+		</span>
+	);
+};

package/src/step-container-v2/components/StepCounter/style.scss

@@ -0,0 +1,4 @@
+.step-container-v2__step-counter {
+	color: var( --color-text-subtle );
+	white-space: nowrap;
+}

package/src/step-container-v2/components/StickyBottomBar/StickyBottomBar.tsx

@@ -0,0 +1,46 @@
+import clsx from 'clsx';
+import type { ReactNode } from 'react';
+
+import './style.scss';
+
+interface StickyBottomBarProps {
+	leftElement?: ReactNode;
+	centerElement?: ReactNode;
+	rightElement?: ReactNode;
+	noBoxShadow?: boolean;
+	hasTransparentBackground?: boolean;
+	centerText?: boolean;
+	fullWidth?: boolean;
+}
+
+export const StickyBottomBar = ( {
+	leftElement,
+	centerElement,
+	rightElement,
+	noBoxShadow,
+	hasTransparentBackground,
+	centerText,
+	fullWidth,
+}: StickyBottomBarProps ) => {
+	return (
+		<div
+			className={ clsx( 'step-container-v2__sticky-bottom-bar', {
+				'step-container-v2__sticky-bottom-bar--no-box-shadow': noBoxShadow === true,
+				'step-container-v2__sticky-bottom-bar--center-text': centerText === true,
+				'step-container-v2__sticky-bottom-bar--full-width': fullWidth === true,
+				'step-container-v2__sticky-bottom-bar--has-transparent-background':
+					hasTransparentBackground === true,
+			} ) }
+		>
+			{ leftElement && (
+				<div className="step-container-v2__sticky-bottom-bar-left-element">{ leftElement }</div>
+			) }
+			{ centerElement && (
+				<div className="step-container-v2__sticky-bottom-bar-center-element">{ centerElement }</div>
+			) }
+			{ rightElement && (
+				<div className="step-container-v2__sticky-bottom-bar-right-element">{ rightElement }</div>
+			) }
+		</div>
+	);
+};