@automattic/onboarding 1.0.0 → 1.0.1

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

@@ -0,0 +1,41 @@
+import { useContext, useRef, useLayoutEffect } from 'react';
+import { StepContainerV2Context, ContentProp } from '../StepContainerV2/context';
+
+export const StickyBottomBarRenderer = ( {
+	stickyBottomBar,
+}: {
+	stickyBottomBar?: ContentProp;
+} ) => {
+	const context = useContext( StepContainerV2Context );
+	const { setStickyBottomBarHeight } = context;
+
+	const stickyBottomBarRef = useRef< HTMLDivElement >( null );
+
+	useLayoutEffect( () => {
+		const resizeObserver = new ResizeObserver( ( [ entry ] ) => {
+			if ( entry ) {
+				setStickyBottomBarHeight( entry.contentRect.height );
+			}
+		} );
+
+		if ( stickyBottomBarRef.current ) {
+			setStickyBottomBarHeight( stickyBottomBarRef.current.clientHeight );
+			resizeObserver.observe( stickyBottomBarRef.current );
+		}
+
+		return () => {
+			resizeObserver.disconnect();
+		};
+	}, [ setStickyBottomBarHeight ] );
+
+	const content =
+		typeof stickyBottomBar === 'function'
+			? stickyBottomBar( context )
+			: ! context.isSmallViewport && stickyBottomBar;
+
+	return (
+		<div className="step-container-v2__sticky-bottom-bar-wrapper" ref={ stickyBottomBarRef }>
+			{ content }
+		</div>
+	);
+};

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

@@ -0,0 +1,56 @@
+.step-container-v2__sticky-bottom-bar {
+	&-wrapper {
+		position: sticky;
+		bottom: 0;
+		width: 100%;
+	}
+
+	width: 100%;
+	display: flex;
+	justify-content: space-between;
+	box-sizing: border-box;
+	align-items: center;
+	box-shadow: var( --color-border-subtle ) 0 1px 0 inset;
+	background-color: var( --color-surface );
+
+	&--no-box-shadow {
+		box-shadow: none;
+	}
+
+	&--has-transparent-background {
+		background-color: transparent;
+	}
+
+	&--center-text {
+		text-align: center;
+	}
+
+	&-left-element,
+	&-center-element,
+	&-right-element {
+		margin-block: 1rem;
+	}
+
+	&-left-element {
+		margin-left: 1rem;
+		margin-right: auto;
+	}
+
+	&-center-element {
+		margin-inline: 2rem;
+		min-width: 0;
+	}
+
+	&-right-element {
+		margin-left: auto;
+		margin-right: 1rem;
+	}
+
+	&--full-width {
+		.step-container-v2__sticky-bottom-bar-left-element,
+		.step-container-v2__sticky-bottom-bar-center-element,
+		.step-container-v2__sticky-bottom-bar-right-element {
+			flex-grow: 1;
+		}
+	}
+}

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

@@ -0,0 +1,116 @@
+import { WordPressLogo, WordPressWordmark } from '@automattic/components';
+import clsx from 'clsx';
+import { isValidElement, useLayoutEffect, useRef, type ReactElement, type ReactNode } from 'react';
+import { useStepContainerV2Context } from '../../contexts/StepContainerV2Context';
+
+import './style.scss';
+
+export interface TopBarProps {
+	leftElement?: ReactNode;
+	rightElement?: ReactNode;
+
+	/**
+	 * Customize the TopBar logo. If this is not passed, the default logo will
+	 * be used unless `hideLogo` is set.
+	 */
+	logo?: ReactNode;
+
+	/**
+	 * Hide the WordPress wordmark when `compactLogo` is set.
+	 * Always show the WordPress logo instead.
+	 * - This is critical for current Login views, where the logo (WordPressLogo) is always visible
+	 * - Confirm with Design before changing functionality around this
+	 */
+	compactLogo?: 'always';
+
+	/**
+	 * Hide the logo entirely.
+	 */
+	hideLogo?: boolean;
+}
+
+export const TopBar = ( {
+	leftElement,
+	rightElement,
+	logo,
+	compactLogo,
+	hideLogo = false,
+}: TopBarProps ) => {
+	const context = useStepContainerV2Context();
+	const topBarRef = useRef< HTMLDivElement >( null );
+
+	// Publish the rendered height to `:root --masterbar-height` so consumers that
+	// expect "the current route's top bar height" (e.g. the Help Center mobile
+	// sheet, layout sidebars) get the right value. Without this, routes that
+	// render `Step.TopBar` but also force `<EmptyMasterbar />` (e.g. checkout
+	// invoked from a stepper-v2 flow) report `--masterbar-height: 0`, leaving the
+	// overlay misaligned. Uses `!important` to beat EmptyMasterbar's stylesheet,
+	// and runs before paint so first-frame consumers don't see the stale value.
+	useLayoutEffect( () => {
+		const element = topBarRef.current;
+
+		if ( ! element ) {
+			return;
+		}
+
+		const root = document.documentElement;
+
+		const publishHeight = () => {
+			const height = Math.round( element.getBoundingClientRect().height );
+			root.style.setProperty( '--masterbar-height', `${ height }px`, 'important' );
+		};
+
+		publishHeight();
+
+		let observer: ResizeObserver | undefined;
+		if ( typeof ResizeObserver !== 'undefined' ) {
+			observer = new ResizeObserver( publishHeight );
+			observer.observe( element );
+		}
+
+		return () => {
+			observer?.disconnect();
+			root.style.removeProperty( '--masterbar-height' );
+		};
+	}, [] );
+
+	// Context logo takes precedence over default WordPress logo.
+	// The `logo` prop provides an explicit override for both.
+	const defaultWordPressLogo = (
+		<div
+			className={ clsx( 'step-container-v2__top-bar-wordpress-logo-wrapper', {
+				'is-compact': compactLogo,
+			} ) }
+		>
+			{ ! compactLogo && (
+				<WordPressWordmark
+					className="step-container-v2__top-bar-wordpress-logo step-container-v2__top-bar-wordpress-logo--wordmark"
+					color="currentColor"
+				/>
+			) }
+			<WordPressLogo
+				size={ 21 }
+				className="step-container-v2__top-bar-wordpress-logo step-container-v2__top-bar-wordpress-logo--logo"
+			/>
+		</div>
+	);
+
+	const resolvedLogo = logo ?? context.logo ?? defaultWordPressLogo;
+
+	return (
+		<div ref={ topBarRef } className="step-container-v2__top-bar">
+			{ ! hideLogo && resolvedLogo }
+
+			{ leftElement && (
+				<div className="step-container-v2__top-bar-left-element">{ leftElement }</div>
+			) }
+			{ rightElement && (
+				<div className="step-container-v2__top-bar-right-element">{ rightElement }</div>
+			) }
+		</div>
+	);
+};
+
+export const isTopBar = ( element?: ReactNode ): element is ReactElement< TopBarProps > => {
+	return isValidElement( element ) && element.type === TopBar;
+};

package/src/step-container-v2/components/TopBar/TopBarRenderer.tsx

@@ -0,0 +1,43 @@
+import { useContext, useLayoutEffect, useRef } from 'react';
+import {
+	StepContainerV2Context,
+	type ContentProp,
+	type StepContainerV2InternalContextType,
+} from '../StepContainerV2/context';
+
+export const renderTopBar = (
+	topBar: ContentProp,
+	context: Pick< StepContainerV2InternalContextType, 'isSmallViewport' | 'isLargeViewport' >
+) => {
+	return typeof topBar === 'function' ? topBar( context ) : topBar;
+};
+
+export const TopBarRenderer = ( { topBar }: { topBar?: ContentProp } ) => {
+	const context = useContext( StepContainerV2Context );
+	const { setTopBarHeight } = context;
+
+	const topBarRef = useRef< HTMLDivElement >( null );
+
+	useLayoutEffect( () => {
+		const resizeObserver = new ResizeObserver( ( [ entry ] ) => {
+			if ( entry ) {
+				setTopBarHeight( `${ entry.contentRect.height }px` );
+			}
+		} );
+
+		if ( topBarRef.current ) {
+			setTopBarHeight( `${ topBarRef.current.clientHeight }px` );
+			resizeObserver.observe( topBarRef.current );
+		}
+
+		return () => {
+			resizeObserver.disconnect();
+		};
+	}, [ setTopBarHeight ] );
+
+	return (
+		<div ref={ topBarRef } className="step-container-v2__top-bar-wrapper">
+			{ renderTopBar( topBar, context ) }
+		</div>
+	);
+};

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

@@ -0,0 +1,75 @@
+@import '@wordpress/base-styles/breakpoints';
+@import '@wordpress/base-styles/mixins';
+
+.step-container-v2__top-bar {
+	width: 100%;
+	box-sizing: border-box;
+	display: flex;
+	align-items: center;
+	gap: 1rem;
+	padding: var( --step-container-v2-top-bar-padding );
+
+	@include break-small {
+		padding-inline: 1.5rem;
+	}
+}
+
+.step-container-v2__top-bar-wrapper {
+	width: 100%;
+}
+
+.step-container-v2__top-bar-left-element,
+.step-container-v2__top-bar-right-element,
+.step-container-v2__top-bar-wordpress-logo {
+	height: var( --step-container-v2-top-bar-content-height );
+}
+
+.step-container-v2__top-bar-left-element,
+.step-container-v2__top-bar-right-element {
+	display: flex;
+	align-items: center;
+}
+
+.step-container-v2__top-bar-wordpress-logo {
+	color: var( --color-text );
+	margin: 0;
+}
+
+.step-container-v2__top-bar-wordpress-logo--wordmark {
+	display: none;
+
+	@include break-small {
+		display: block;
+	}
+}
+
+.step-container-v2__top-bar-wordpress-logo--logo {
+	display: block;
+
+	@include break-small {
+		/**
+		 * Hide the logo only when the wrapper is not compact.
+		 * This is important for current Login views, where the logo is always visible.
+		 * -- Confirm with Design before changing this --
+		 */
+		.step-container-v2__top-bar-wordpress-logo-wrapper:not( .is-compact ) & {
+			display: none;
+		}
+	}
+}
+
+.step-container-v2__top-bar-right-element {
+	display: flex;
+	align-items: center;
+	gap: 1rem;
+	margin-left: auto;
+	font-size: 0.875rem;
+	line-height: 1;
+
+	a,
+	button {
+		&.components-button:not( .is-destructive ).is-link {
+			--wp-components-color-accent: var( --color-neutral-100 );
+		}
+	}
+}

package/src/step-container-v2/components/buttons/BackButton/BackButton.tsx

@@ -0,0 +1,32 @@
+import { Button } from '@wordpress/components';
+import { chevronLeft } from '@wordpress/icons';
+import { useI18n } from '@wordpress/react-i18n';
+import { useStepContainerV2Context } from '../../../contexts/StepContainerV2Context';
+import { decorateButtonWithTracksEventRecording } from '../../../helpers/decorateButtonWithTracksEventRecording';
+import { normalizeButtonProps } from '../../../helpers/normalizeButtonProps';
+import { ButtonProps } from '../../../types';
+
+import './style.scss';
+
+export const BackButton = ( {
+	enableTracksEvent = true,
+	...originalProps
+}: ButtonProps & { enableTracksEvent?: boolean } ) => {
+	const { __ } = useI18n();
+	const stepContext = useStepContainerV2Context();
+
+	const backButtonProps = normalizeButtonProps( originalProps, {
+		children: __( 'Back', __i18n_text_domain__ ),
+		className: 'step-container-v2__back-button',
+		icon: chevronLeft,
+	} );
+
+	const buttonProps = enableTracksEvent
+		? decorateButtonWithTracksEventRecording( backButtonProps, {
+				tracksEventName: 'calypso_signup_previous_step_button_click',
+				stepContext,
+		  } )
+		: backButtonProps;
+
+	return <Button { ...buttonProps } />;
+};

package/src/step-container-v2/components/buttons/BackButton/style.scss

@@ -0,0 +1,16 @@
+.step-container-v2__back-button.components-button {
+	--wp-components-color-accent: var(--color-neutral-100);
+	--color-link: var(--color-neutral-100);
+	font-size: 0.875rem;
+	font-weight: 500;
+	line-height: 1;
+	text-decoration: underline;
+	gap: 4px;
+	padding: 0 !important;
+	min-width: 0;
+	height: auto;
+
+	svg {
+		margin-inline-end: 0;
+	}
+}

package/src/step-container-v2/components/buttons/LinkButton/LinkButton.tsx

@@ -0,0 +1,17 @@
+import { Button } from '@wordpress/components';
+import { useI18n } from '@wordpress/react-i18n';
+import { normalizeButtonProps } from '../../../helpers/normalizeButtonProps';
+import { ButtonProps } from '../../../types';
+
+import './style.scss';
+
+export const LinkButton = ( originalProps: ButtonProps ) => {
+	const { __ } = useI18n();
+
+	const linkButtonProps = normalizeButtonProps( originalProps, {
+		children: __( 'Link', __i18n_text_domain__ ),
+		className: 'step-container-v2__link-button',
+	} );
+
+	return <Button variant="link" { ...linkButtonProps } />;
+};

package/src/step-container-v2/components/buttons/LinkButton/style.scss

@@ -0,0 +1,6 @@
+.step-container-v2__link-button.components-button {
+	font-size: inherit;
+	line-height: inherit;
+	font-weight: 500;
+	text-decoration: underline;
+}

package/src/step-container-v2/components/buttons/PrimaryButton/PrimaryButton.tsx

@@ -0,0 +1,17 @@
+import { Button } from '@wordpress/components';
+import { useI18n } from '@wordpress/react-i18n';
+import { normalizeButtonProps } from '../../../helpers/normalizeButtonProps';
+import { ButtonProps } from '../../../types';
+
+import './style.scss';
+
+export const PrimaryButton = ( originalProps: ButtonProps ) => {
+	const { __ } = useI18n();
+
+	const primaryButtonProps = normalizeButtonProps( originalProps, {
+		children: __( 'Next', __i18n_text_domain__ ),
+		className: 'step-container-v2__primary-button',
+	} );
+
+	return <Button __next40pxDefaultSize variant="primary" { ...primaryButtonProps } />;
+};

package/src/step-container-v2/components/buttons/PrimaryButton/style.scss

@@ -0,0 +1,6 @@
+.step-container-v2__content-wrapper .step-container-v2__primary-button {
+	padding: 0.5rem 3rem;
+	font-size: 0.875rem;
+	line-height: 1;
+	justify-content: center;
+}

package/src/step-container-v2/components/buttons/SecondaryButton/SecondaryButton.tsx

@@ -0,0 +1,17 @@
+import { Button } from '@wordpress/components';
+import { useI18n } from '@wordpress/react-i18n';
+import { normalizeButtonProps } from '../../../helpers/normalizeButtonProps';
+import { ButtonProps } from '../../../types';
+
+import './style.scss';
+
+export const SecondaryButton = ( originalProps: ButtonProps ) => {
+	const { __ } = useI18n();
+
+	const secondaryButtonProps = normalizeButtonProps( originalProps, {
+		children: __( 'Secondary', __i18n_text_domain__ ),
+		className: 'step-container-v2__secondary-button',
+	} );
+
+	return <Button __next40pxDefaultSize variant="secondary" { ...secondaryButtonProps } />;
+};

package/src/step-container-v2/components/buttons/SecondaryButton/style.scss

@@ -0,0 +1,6 @@
+.step-container-v2__content-wrapper .step-container-v2__secondary-button {
+	padding: 0.5rem 3rem;
+	font-size: 0.875rem;
+	line-height: 1;
+	justify-content: center;
+}

package/src/step-container-v2/components/buttons/SkipButton/SkipButton.tsx

@@ -0,0 +1,30 @@
+import { useI18n } from '@wordpress/react-i18n';
+import { useStepContainerV2Context } from '../../../contexts/StepContainerV2Context';
+import { decorateButtonWithTracksEventRecording } from '../../../helpers/decorateButtonWithTracksEventRecording';
+import { normalizeButtonProps } from '../../../helpers/normalizeButtonProps';
+import { ButtonProps } from '../../../types';
+import { LinkButton } from '../LinkButton/LinkButton';
+
+/**
+ * Do NOT use this button if you don't intend to skip the step.
+ *
+ * This button is visually identical to {@link LinkButton}.
+ * The difference between them is that this one fires a Tracks event when clicked.
+ */
+export const SkipButton = ( originalProps: ButtonProps ) => {
+	const { __ } = useI18n();
+	const stepContext = useStepContainerV2Context();
+
+	const skipButtonProps = normalizeButtonProps( originalProps, {
+		children: __( 'Skip', __i18n_text_domain__ ),
+	} );
+
+	return (
+		<LinkButton
+			{ ...decorateButtonWithTracksEventRecording( skipButtonProps, {
+				tracksEventName: 'calypso_signup_skip_step',
+				stepContext,
+			} ) }
+		/>
+	);
+};

package/src/step-container-v2/contexts/StepContainerV2Context.ts

@@ -0,0 +1,23 @@
+import { createContext, useContext, type ReactNode } from 'react';
+
+export type StepContainerV2ContextType = {
+	flowName: string;
+	stepName: string;
+	recordTracksEvent: ( eventName: string, eventProperties: Record< string, unknown > ) => void;
+	logo: ReactNode;
+};
+
+const defaultContextValue: StepContainerV2ContextType = {
+	flowName: '',
+	stepName: '',
+	recordTracksEvent: () => {},
+	logo: null,
+};
+
+const StepContainerV2Context = createContext< StepContainerV2ContextType >( defaultContextValue );
+
+export const StepContainerV2Provider = StepContainerV2Context.Provider;
+
+export const useStepContainerV2Context = () => {
+	return useContext( StepContainerV2Context );
+};

package/src/step-container-v2/helpers/decorateButtonWithTracksEventRecording.ts

@@ -0,0 +1,28 @@
+import { Onboard, OnboardSelect } from '@automattic/data-stores';
+import { Button } from '@wordpress/components';
+import { select } from '@wordpress/data';
+import { ComponentProps } from 'react';
+import { StepContainerV2ContextType } from '../contexts/StepContainerV2Context';
+
+export const decorateButtonWithTracksEventRecording = (
+	{ onClick, ...props }: ComponentProps< typeof Button >,
+	{
+		tracksEventName,
+		stepContext,
+	}: { tracksEventName: string; stepContext: StepContainerV2ContextType }
+): ComponentProps< typeof Button > => {
+	const onClickHandler = (
+		event: React.MouseEvent< HTMLAnchorElement, MouseEvent > &
+			React.MouseEvent< HTMLButtonElement, MouseEvent >
+	) => {
+		onClick?.( event );
+
+		stepContext?.recordTracksEvent?.( tracksEventName, {
+			flow: stepContext?.flowName,
+			step: stepContext?.stepName,
+			intent: ( select( Onboard.register() ) as unknown as OnboardSelect ).getIntent(),
+		} );
+	};
+
+	return { ...props, onClick: onClickHandler };
+};

package/src/step-container-v2/helpers/normalizeButtonProps.ts

@@ -0,0 +1,14 @@
+import { Button } from '@wordpress/components';
+import clsx from 'clsx';
+import { ComponentProps } from 'react';
+import { ButtonProps } from '../types';
+
+export const normalizeButtonProps = < T extends ComponentProps< typeof Button > >(
+	button: ButtonProps,
+	standardProps: T
+): T => ( {
+	...standardProps,
+	...button,
+	children: button.children ?? standardProps.children,
+	className: clsx( standardProps.className, button.className ),
+} );

package/src/step-container-v2/helpers/wireframe-placeholder.tsx

@@ -0,0 +1,28 @@
+export function WireframePlaceholder( {
+	height,
+	children,
+	className,
+	style: additionalStyle,
+}: {
+	height?: React.CSSProperties[ 'height' ];
+	children?: React.ReactNode;
+	className?: string;
+	style?: React.CSSProperties;
+} ) {
+	const style = {
+		background: '#ff80ff',
+		borderRadius: 10,
+		display: 'flex',
+		flexDirection: 'column',
+		alignItems: 'center',
+		justifyContent: 'center',
+		...( height && { height } ),
+		...additionalStyle,
+	} as const;
+
+	return (
+		<div className={ className } style={ style }>
+			{ children }
+		</div>
+	);
+}

package/src/step-container-v2/helpers/withStepContainerV2ContextDecorator.tsx

@@ -0,0 +1,16 @@
+import { StepContainerV2Provider } from '..';
+
+export const withStepContainerV2ContextDecorator = ( Story: React.ComponentType ) => {
+	return (
+		<StepContainerV2Provider
+			value={ {
+				flowName: 'flowName',
+				stepName: 'stepName',
+				recordTracksEvent: () => {},
+				logo: null,
+			} }
+		>
+			<Story />
+		</StepContainerV2Provider>
+	);
+};

package/src/step-container-v2/index.tsx

@@ -0,0 +1,24 @@
+/**
+ * NEVER export StepContainerV2 directly.
+ *
+ * Export only components and wireframes.
+ */
+
+export { StepContainerV2Provider } from './contexts/StepContainerV2Context';
+
+export { BackButton } from './components/buttons/BackButton/BackButton';
+export { PrimaryButton } from './components/buttons/PrimaryButton/PrimaryButton';
+export { SecondaryButton } from './components/buttons/SecondaryButton/SecondaryButton';
+export { SkipButton } from './components/buttons/SkipButton/SkipButton';
+export { LinkButton } from './components/buttons/LinkButton/LinkButton';
+export { Heading } from './components/Heading/Heading';
+export { StepCounter } from './components/StepCounter/StepCounter';
+export { TopBar } from './components/TopBar/TopBar';
+export { StickyBottomBar } from './components/StickyBottomBar/StickyBottomBar';
+
+export { CenteredColumnLayout } from './wireframes/CenteredColumnLayout/CenteredColumnLayout';
+export { TwoColumnLayout } from './wireframes/TwoColumnLayout/TwoColumnLayout';
+export { WideLayout } from './wireframes/WideLayout/WideLayout';
+export { Loading } from './wireframes/Loading/Loading';
+export { PlaygroundLayout } from './wireframes/PlaygroundLayout/PlaygroundLayout';
+export { FixedColumnOnTheLeftLayout } from './wireframes/FixedColumnOnTheLeftLayout/FixedColumnOnTheLeftLayout';

package/src/step-container-v2/types.ts

@@ -0,0 +1,4 @@
+import { Button } from '@wordpress/components';
+import { ComponentProps } from 'react';
+
+export type ButtonProps = ComponentProps< typeof Button >;