) }
+ >
+ { showArrowIndicator() && (
+
+
+ );
+};
+
+export default TourKitFrame;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-minimized.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-minimized.tsx
new file mode 100644
index 0000000000000..6831fbf8f6051
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-minimized.tsx
@@ -0,0 +1,30 @@
+/**
+ * Internal Dependencies
+ */
+import { MinimizedTourRendererProps } from '../types';
+import type { Config } from '../types';
+
+interface Props extends MinimizedTourRendererProps {
+ config: Config;
+}
+
+const TourKitMinimized: React.FunctionComponent< Props > = ( {
+ config,
+ steps,
+ currentStepIndex,
+ onMaximize,
+ onDismiss,
+} ) => {
+ return (
+ ) }
+ />
+ ) }
+ { ! isMinimized ? (
+
+
+
+ );
+};
+
+export default TourKitMinimized;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-overlay.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-overlay.tsx
new file mode 100644
index 0000000000000..3c440bcdc2de7
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-overlay.tsx
@@ -0,0 +1,20 @@
+/**
+ * External Dependencies
+ */
+import clsx from 'clsx';
+
+interface Props {
+ visible: boolean;
+}
+
+const TourKitOverlay: React.FunctionComponent< Props > = ( { visible } ) => {
+ return (
+
+ );
+};
+
+export default TourKitOverlay;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-spotlight-interactivity.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-spotlight-interactivity.tsx
new file mode 100644
index 0000000000000..61b7e94bca203
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-spotlight-interactivity.tsx
@@ -0,0 +1,38 @@
+import { SPOTLIT_ELEMENT_CLASS } from './tour-kit-spotlight';
+
+export interface SpotlightInteractivityConfiguration {
+ /** If true, the user will be allowed to interact with the spotlit element. Defaults to false. */
+ enabled?: boolean;
+ /**
+ * This element is the root element within which all children will have
+ * pointer-events disabled during the tour. Defaults to '#wpwrap'
+ */
+ rootElementSelector?: string;
+}
+
+export const SpotlightInteractivity: React.VFC< SpotlightInteractivityConfiguration > = ( {
+ enabled = false,
+ rootElementSelector = '#wpwrap',
+}: SpotlightInteractivityConfiguration ) => {
+ if ( ! enabled ) {
+ return null;
+ }
+ return (
+
+ );
+};
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-spotlight.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-spotlight.tsx
new file mode 100644
index 0000000000000..81e9ed80ff131
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-spotlight.tsx
@@ -0,0 +1,122 @@
+import { useMemo, useState, useEffect } from '@wordpress/element';
+import clsx from 'clsx';
+import { usePopper } from 'react-popper';
+import { LiveResizeConfiguration, liveResizeModifier } from '../utils/live-resize-modifier';
+import Overlay from './tour-kit-overlay';
+import {
+ SpotlightInteractivity,
+ SpotlightInteractivityConfiguration,
+} from './tour-kit-spotlight-interactivity';
+import type { Rect, Placement } from '@popperjs/core';
+
+export const SPOTLIT_ELEMENT_CLASS = 'wp-tour-kit-spotlit';
+interface Props {
+ referenceElement: HTMLElement | null;
+ styles?: React.CSSProperties;
+ interactivity?: SpotlightInteractivityConfiguration;
+ liveResize?: LiveResizeConfiguration;
+}
+
+const TourKitSpotlight: React.FunctionComponent< Props > = ( {
+ referenceElement,
+ styles,
+ interactivity,
+ liveResize,
+} ) => {
+ const [ popperElement, sePopperElement ] = useState< HTMLElement | null >( null );
+ const referenceRect = referenceElement?.getBoundingClientRect();
+
+ const modifiers = [
+ {
+ name: 'flip',
+ enabled: false,
+ },
+ {
+ name: 'preventOverflow',
+ options: {
+ mainAxis: false, // true by default
+ },
+ },
+ useMemo(
+ () => ( {
+ name: 'offset',
+ options: {
+ offset: ( {
+ placement,
+ reference,
+ popper,
+ }: {
+ placement: Placement;
+ reference: Rect;
+ popper: Rect;
+ } ): [ number, number ] => {
+ if ( placement === 'bottom' ) {
+ return [ 0, -( reference.height + ( popper.height - reference.height ) / 2 ) ];
+ }
+ return [ 0, 0 ];
+ },
+ },
+ } ),
+ []
+ ),
+ // useMemo because https://popper.js.org/react-popper/v2/faq/#why-i-get-render-loop-whenever-i-put-a-function-inside-the-popper-configuration
+ useMemo( () => {
+ return liveResizeModifier( liveResize );
+ }, [ liveResize ] ),
+ ];
+
+ const { styles: popperStyles, attributes: popperAttributes } = usePopper(
+ referenceElement,
+ popperElement,
+ {
+ strategy: 'fixed',
+ placement: 'bottom',
+ modifiers,
+ }
+ );
+
+ const clipDimensions = referenceRect
+ ? {
+ width: `${ referenceRect.width }px`,
+ height: `${ referenceRect.height }px`,
+ }
+ : null;
+
+ const clipRepositionProps = referenceElement
+ ? {
+ style: {
+ ...( clipDimensions && clipDimensions ),
+ ...popperStyles?.popper,
+ ...( styles && styles ),
+ },
+ ...popperAttributes?.popper,
+ }
+ : null;
+
+ /**
+ * Add a .wp-spotlit class to the referenced element so that we can
+ * apply CSS styles to it, for whatever purposes such as interactivity
+ */
+ useEffect( () => {
+ referenceElement?.classList.add( SPOTLIT_ELEMENT_CLASS );
+ return () => {
+ referenceElement?.classList.remove( SPOTLIT_ELEMENT_CLASS );
+ };
+ }, [ referenceElement ] );
+
+ return (
+ <>
+ ) }
+ />
+
+ );
+};
+
+export default TourKitSpotlight;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-step.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-step.tsx
new file mode 100644
index 0000000000000..ded21b229ed03
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit-step.tsx
@@ -0,0 +1,52 @@
+/**
+ * External Dependencies
+ */
+import { useViewportMatch } from '@wordpress/compose';
+import clsx from 'clsx';
+/**
+ * Internal Dependencies
+ */
+import { classParser } from '../utils';
+import type { Config, TourStepRendererProps } from '../types';
+
+interface Props extends TourStepRendererProps {
+ config: Config;
+}
+
+const TourKitStep: React.FunctionComponent< Props > = ( {
+ config,
+ steps,
+ currentStepIndex,
+ onMinimize,
+ onDismiss,
+ onNextStep,
+ onPreviousStep,
+ setInitialFocusedElement,
+ onGoToStep,
+} ) => {
+ const isMobile = useViewportMatch( 'mobile', '<' );
+ const classes = clsx(
+ 'tour-kit-step',
+ `is-step-${ currentStepIndex }`,
+ classParser(
+ config.steps[ currentStepIndex ].options?.classNames?.[ isMobile ? 'mobile' : 'desktop' ]
+ )
+ );
+
+ return (
+
+
+
+
+ );
+};
+
+export default TourKit;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/constants.ts b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/constants.ts
new file mode 100644
index 0000000000000..b8522601535a0
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/constants.ts
@@ -0,0 +1,3 @@
+// Copied from https://github.com/Automattic/wp-calypso/blob/ce1a376af4bcc8987855ced4c961efacda6e1d32/packages/onboarding/src/utils/flows.ts#L32-L33
+export const START_WRITING_FLOW = 'start-writing';
+export const DESIGN_FIRST_FLOW = 'design-first';
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/has-seen-seller-celebration-modal-context.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/has-seen-seller-celebration-modal-context.tsx
new file mode 100644
index 0000000000000..94bc6c49e7e13
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/has-seen-seller-celebration-modal-context.tsx
@@ -0,0 +1,68 @@
+import apiFetch from '@wordpress/api-fetch';
+import { useState, useEffect } from '@wordpress/element';
+import * as React from 'react';
+import { useContext } from 'react';
+
+type HasSeenSCModalResult = {
+ has_seen_seller_celebration_modal: boolean;
+};
+
+type HasSeenSellerCelebrationModalContextType = {
+ hasSeenSellerCelebrationModal: boolean;
+ updateHasSeenSellerCelebrationModal: ( value: boolean ) => void;
+};
+
+const HasSeenSCModalContext = React.createContext< HasSeenSellerCelebrationModalContextType >( {
+ hasSeenSellerCelebrationModal: false,
+ // eslint-disable-next-line @typescript-eslint/no-empty-function
+ updateHasSeenSellerCelebrationModal: () => {},
+} );
+
+export const useHasSeenSellerCelebrationModal = () => {
+ return useContext( HasSeenSCModalContext );
+};
+
+export const HasSeenSellerCelebrationModalProvider: React.FC< { children: JSX.Element } > =
+ function ( { children } ) {
+ const [ hasSeenSellerCelebrationModal, setHasSeenSellerCelebrationModal ] = useState( false );
+
+ /**
+ * Fetch the value that whether the video celebration modal has been seen.
+ */
+ function fetchHasSeenSellerCelebrationModal() {
+ apiFetch< HasSeenSCModalResult >( {
+ path: '/wpcom/v2/block-editor/has-seen-seller-celebration-modal',
+ } )
+ .then( ( result: HasSeenSCModalResult ) =>
+ setHasSeenSellerCelebrationModal( result.has_seen_seller_celebration_modal )
+ )
+ .catch( () => setHasSeenSellerCelebrationModal( false ) );
+ }
+
+ /**
+ * Update the value that whether the video celebration modal has been seen.
+ *
+ * @param value - The value to update.
+ */
+ function updateHasSeenSellerCelebrationModal( value: boolean ) {
+ apiFetch( {
+ method: 'PUT',
+ path: '/wpcom/v2/block-editor/has-seen-seller-celebration-modal',
+ data: { has_seen_seller_celebration_modal: value },
+ } ).finally( () => {
+ setHasSeenSellerCelebrationModal( true );
+ } );
+ }
+
+ useEffect( () => {
+ fetchHasSeenSellerCelebrationModal();
+ }, [] );
+
+ return (
+
+ { children }
+
+ );
+ };
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/has-seen-video-celebration-modal-context.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/has-seen-video-celebration-modal-context.tsx
new file mode 100644
index 0000000000000..18b9345434ec6
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/has-seen-video-celebration-modal-context.tsx
@@ -0,0 +1,68 @@
+import apiFetch from '@wordpress/api-fetch';
+import { useState, useEffect } from '@wordpress/element';
+import * as React from 'react';
+import { useContext } from 'react';
+
+type HasSeenVCModalResult = {
+ has_seen_video_celebration_modal: boolean;
+};
+
+type HasSeenVideoCelebrationModalContextType = {
+ hasSeenVideoCelebrationModal: boolean;
+ updateHasSeenVideoCelebrationModal: ( value: boolean ) => void;
+};
+
+const HasSeenVCModalContext = React.createContext< HasSeenVideoCelebrationModalContextType >( {
+ hasSeenVideoCelebrationModal: false,
+ // eslint-disable-next-line @typescript-eslint/no-empty-function
+ updateHasSeenVideoCelebrationModal: () => {},
+} );
+
+export const useHasSeenVideoCelebrationModal = () => {
+ return useContext( HasSeenVCModalContext );
+};
+
+export const HasSeenVideoCelebrationModalProvider: React.FC< { children: JSX.Element } > =
+ function ( { children } ) {
+ const [ hasSeenVideoCelebrationModal, setHasSeenVideoCelebrationModal ] = useState( false );
+
+ useEffect( () => {
+ fetchHasSeenVideoCelebrationModal();
+ }, [] );
+
+ /**
+ * Fetch the value that whether the video celebration modal has been seen.
+ */
+ function fetchHasSeenVideoCelebrationModal() {
+ apiFetch< HasSeenVCModalResult >( {
+ path: '/wpcom/v2/block-editor/has-seen-video-celebration-modal',
+ } )
+ .then( ( result: HasSeenVCModalResult ) =>
+ setHasSeenVideoCelebrationModal( result.has_seen_video_celebration_modal )
+ )
+ .catch( () => setHasSeenVideoCelebrationModal( false ) );
+ }
+
+ /**
+ * Update the value that whether the video celebration modal has been seen.
+ *
+ * @param value - The value to update.
+ */
+ function updateHasSeenVideoCelebrationModal( value: boolean ) {
+ apiFetch( {
+ method: 'PUT',
+ path: '/wpcom/v2/block-editor/has-seen-video-celebration-modal',
+ data: { has_seen_video_celebration_modal: value },
+ } ).finally( () => {
+ setHasSeenVideoCelebrationModal( value );
+ } );
+ }
+
+ return (
+
+ { children }
+
+ );
+ };
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/should-show-first-post-published-modal-context.jsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/should-show-first-post-published-modal-context.jsx
new file mode 100644
index 0000000000000..d9b5b30e8ee0f
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/should-show-first-post-published-modal-context.jsx
@@ -0,0 +1,31 @@
+import { useSelect, useDispatch } from '@wordpress/data';
+import { useEffect } from '@wordpress/element';
+import * as React from 'react';
+import { useContext } from 'react';
+
+const ShouldShowFPPModalContext = React.createContext( false );
+
+export const useShouldShowFirstPostPublishedModal = () => {
+ return useContext( ShouldShowFPPModalContext );
+};
+
+export const ShouldShowFirstPostPublishedModalProvider = ( { children } ) => {
+ const value = useSelect(
+ select => select( 'automattic/wpcom-welcome-guide' ).getShouldShowFirstPostPublishedModal(),
+ []
+ );
+
+ const { fetchShouldShowFirstPostPublishedModal } = useDispatch(
+ 'automattic/wpcom-welcome-guide'
+ );
+
+ useEffect( () => {
+ fetchShouldShowFirstPostPublishedModal();
+ }, [ fetchShouldShowFirstPostPublishedModal ] );
+
+ return (
+
+ { children }
+
+ );
+};
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/tour-kit-context.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/tour-kit-context.tsx
new file mode 100644
index 0000000000000..f9524abecdbd7
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/contexts/tour-kit-context.tsx
@@ -0,0 +1,18 @@
+import { createContext, useContext } from '@wordpress/element';
+import type { Config } from '../types';
+
+interface TourKitContext {
+ config: Config;
+}
+
+const TourKitContext = createContext< TourKitContext >( {} as TourKitContext );
+
+const TourKitContextProvider: React.FunctionComponent<
+ TourKitContext & { children?: React.ReactNode }
+> = ( { config, children } ) => {
+ return { children } ;
+};
+
+export const useTourKitContext = (): TourKitContext => useContext( TourKitContext );
+
+export default TourKitContextProvider;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/error-boundary.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/error-boundary.tsx
new file mode 100644
index 0000000000000..250ce916b1496
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/error-boundary.tsx
@@ -0,0 +1,33 @@
+import React, { ErrorInfo } from 'react';
+
+type State = {
+ hasError: boolean;
+};
+
+class ErrorBoundary extends React.Component< { children: React.ReactNode }, State > {
+ state = {
+ hasError: false,
+ };
+
+ static getDerivedStateFromError() {
+ // Update state so the next render will show the fallback UI.
+ return { hasError: true };
+ }
+
+ componentDidCatch( error: Error, errorInfo: ErrorInfo ) {
+ // You can also log the error to an error reporting service
+ // eslint-disable-next-line no-console
+ console.error( error, errorInfo );
+ }
+
+ render() {
+ if ( this.state.hasError ) {
+ // You can render any custom fallback UI
+ return
+
+
+
+ );
+};
+
+export default WpcomTourKitMinimized;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-pagination-control.scss b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-pagination-control.scss
new file mode 100644
index 0000000000000..fe9a19fc4b508
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-pagination-control.scss
@@ -0,0 +1,44 @@
+@import "@automattic/calypso-color-schemes";
+
+.wpcom-tour-kit-pagination-control {
+ margin: 0;
+ display: flex;
+ justify-content: center;
+ width: 100%;
+
+ li {
+ display: inline-flex;
+ margin: auto 4px;
+ height: 18px;
+ align-items: center;
+ border: none;
+ }
+
+ li.pagination-control__last-item {
+ margin-left: auto;
+ height: 32px;
+ }
+
+ button.pagination-control__page {
+ border: none;
+ padding: 0;
+ width: 6px;
+ height: 6px;
+ border-radius: 50%;
+ cursor: pointer;
+ transition: all 0.2s ease-in-out;
+ background-color: var(--color-neutral-10);
+
+ &:hover {
+ background-color: var(--color-neutral-40);
+ }
+
+ &:disabled {
+ cursor: default;
+ }
+
+ &.is-current {
+ background-color: var(--wp-admin-theme-color);
+ }
+ }
+}
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-pagination-control.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-pagination-control.tsx
new file mode 100644
index 0000000000000..5d9c48bca0fb1
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-pagination-control.tsx
@@ -0,0 +1,49 @@
+import { __, sprintf } from '@wordpress/i18n';
+import clsx from 'clsx';
+import './wpcom-tour-kit-pagination-control.scss';
+
+interface Props {
+ onChange: ( page: number ) => void;
+ activePageIndex: number;
+ numberOfPages: number;
+ classNames?: string | string[];
+ children?: React.ReactNode;
+}
+
+const WpcomTourKitPaginationControl: React.FunctionComponent< Props > = ( {
+ activePageIndex,
+ numberOfPages,
+ onChange,
+ classNames,
+ children,
+} ) => {
+ const classes = clsx( 'wpcom-tour-kit-pagination-control', classNames );
+
+ return (
+
+ { isFirstStep ? (
+
+
+ );
+};
+
+export default WpcomTourKitStepCardNavigation;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step-card-overlay-controls.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step-card-overlay-controls.tsx
new file mode 100644
index 0000000000000..bfad1e0204dc7
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step-card-overlay-controls.tsx
@@ -0,0 +1,41 @@
+import { Button, Flex } from '@wordpress/components';
+import { close } from '@wordpress/icons';
+import { useI18n } from '@wordpress/react-i18n';
+import minimize from '../icons/minimize';
+import type { TourStepRendererProps } from '../../../types';
+
+interface Props {
+ onMinimize: TourStepRendererProps[ 'onMinimize' ];
+ onDismiss: TourStepRendererProps[ 'onDismiss' ];
+}
+
+const WpcomTourKitStepCardOverlayControls: React.FunctionComponent< Props > = ( {
+ onMinimize,
+ onDismiss,
+} ) => {
+ const { __ } = useI18n();
+
+ return (
+
+
+
+ { imgSrc.mobile && (
+ 
+
+ { imgLink && (
+
+
+
+ ) }
+
+ ) }
+
+
+
+ { isLastStep ? (
+
+
+ );
+};
+
+export default WpcomTourKitStepCard;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step.tsx
new file mode 100644
index 0000000000000..24064230211d2
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step.tsx
@@ -0,0 +1,28 @@
+import WpcomTourKitStepCard from './wpcom-tour-kit-step-card';
+import type { WpcomTourStepRendererProps } from '../../../types';
+
+const WpcomTourKitStep: React.FunctionComponent< WpcomTourStepRendererProps > = ( {
+ steps,
+ currentStepIndex,
+ onDismiss,
+ onNextStep,
+ onPreviousStep,
+ onMinimize,
+ setInitialFocusedElement,
+ onGoToStep,
+} ) => {
+ return (
+
+
+ );
+};
+
+export default TourKitStep;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit.tsx
new file mode 100644
index 0000000000000..d8b19a648d14c
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/components/tour-kit.tsx
@@ -0,0 +1,40 @@
+import { createPortal, useEffect, useRef } from '@wordpress/element';
+import React from 'react';
+import TourKitContextProvider from '../contexts/tour-kit-context';
+import ErrorBoundary from '../error-boundary';
+import TourKitFrame from './tour-kit-frame';
+import type { Config } from '../types';
+
+import '../styles.scss';
+
+interface Props {
+ config: Config;
+ __temp__className?: string;
+}
+
+const TourKit: React.FunctionComponent< Props > = ( { config, __temp__className } ) => {
+ const portalParent = useRef( document.createElement( 'div' ) ).current;
+
+ useEffect( () => {
+ const classes = [ 'tour-kit', ...( __temp__className ? [ __temp__className ] : [] ) ];
+
+ portalParent.classList.add( ...classes );
+
+ const portalParentElement = config.options?.portalParentElement || document.body;
+ portalParentElement.appendChild( portalParent );
+
+ return () => {
+ portalParentElement.removeChild( portalParent );
+ };
+ }, [ __temp__className, portalParent, config.options?.portalParentElement ] );
+
+ return (
+ { createPortal(
+ Something went wrong.
; + } + + return this.props.children; + } +} + +export default ErrorBoundary; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/index.ts b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/index.ts new file mode 100644 index 0000000000000..7c2fc8e6c2b2b --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/index.ts @@ -0,0 +1,9 @@ +export { default as useFocusHandle } from './use-focus-handler'; +export { default as useFocusTrap } from './use-focus-trap'; +export { default as useHasSelectedPaymentBlockOnce } from './use-has-selected-payment-block-once'; +export { default as useKeydownHandler } from './use-keydown-handler'; +export { default as useShouldShowSellerCelebrationModal } from './use-should-show-seller-celebration-modal'; +export { default as useShouldShowVideoCelebrationModal } from './use-should-show-video-celebration-modal'; +export { default as useSiteIntent } from './use-site-intent'; +export { default as useSitePlan } from './use-site-plan'; +export { default as useStepTracking } from './use-step-tracking'; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-focus-handler.ts b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-focus-handler.ts new file mode 100644 index 0000000000000..7e54ac45673dc --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-focus-handler.ts @@ -0,0 +1,60 @@ +/** + * External Dependencies + */ +import { useEffect, useCallback, useState } from '@wordpress/element'; + +/** + * A hook that returns true/false if ref node receives focus by either tabbing or clicking into any of its children. + * @param ref - React.MutableRefObject< null | HTMLElement > + */ +const useFocusHandler = ( ref: React.MutableRefObject< null | HTMLElement > ): boolean => { + const [ hasFocus, setHasFocus ] = useState( false ); + + const handleFocus = useCallback( () => { + if ( document.hasFocus() && ref.current?.contains( document.activeElement ) ) { + setHasFocus( true ); + } else { + setHasFocus( false ); + } + }, [ ref ] ); + + const handleMousedown = useCallback( + ( event: MouseEvent ) => { + if ( ref.current?.contains( event.target as Node ) ) { + setHasFocus( true ); + } else { + setHasFocus( false ); + } + }, + [ ref ] + ); + + const handleKeyup = useCallback( + ( event: KeyboardEvent ) => { + if ( event.key === 'Tab' ) { + if ( ref.current?.contains( event.target as Node ) ) { + setHasFocus( true ); + } else { + setHasFocus( false ); + } + } + }, + [ ref ] + ); + + useEffect( () => { + document.addEventListener( 'focusin', handleFocus ); + document.addEventListener( 'mousedown', handleMousedown ); + document.addEventListener( 'keyup', handleKeyup ); + + return () => { + document.removeEventListener( 'focusin', handleFocus ); + document.removeEventListener( 'mousedown', handleMousedown ); + document.removeEventListener( 'keyup', handleKeyup ); + }; + }, [ ref, handleFocus, handleKeyup, handleMousedown ] ); + + return hasFocus; +}; + +export default useFocusHandler; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-focus-trap.ts b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-focus-trap.ts new file mode 100644 index 0000000000000..b8e0bc7b313a9 --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-focus-trap.ts @@ -0,0 +1,56 @@ +/** + * External Dependencies + */ +import { focus } from '@wordpress/dom'; +import { useEffect, useCallback, useState } from '@wordpress/element'; +/** + * A hook that constraints tabbing/focus on focuable elements in the given element ref. + * @param ref - React.MutableRefObject< null | HTMLElement > + */ +const useFocusTrap = ( ref: React.MutableRefObject< null | HTMLElement > ): void => { + const [ firstFocusableElement, setFirstFocusableElement ] = useState< HTMLElement | undefined >(); + const [ lastFocusableElement, setLastFocusableElement ] = useState< HTMLElement | undefined >(); + + const handleTrapFocus = useCallback( + ( event: KeyboardEvent ) => { + let handled = false; + + if ( event.key === 'Tab' ) { + if ( event.shiftKey ) { + // Shift + Tab + if ( document.activeElement === firstFocusableElement ) { + lastFocusableElement?.focus(); + handled = true; + } + } else if ( document.activeElement === lastFocusableElement ) { + // Tab + firstFocusableElement?.focus(); + handled = true; + } + } + + if ( handled ) { + event.preventDefault(); + event.stopPropagation(); + } + }, + [ firstFocusableElement, lastFocusableElement ] + ); + + useEffect( () => { + const focusableElements = ref.current ? focus.focusable.find( ref.current as HTMLElement ) : []; + + if ( focusableElements && focusableElements.length ) { + setFirstFocusableElement( focusableElements[ 0 ] as HTMLElement ); + setLastFocusableElement( focusableElements[ focusableElements.length - 1 ] as HTMLElement ); + } + + document.addEventListener( 'keydown', handleTrapFocus ); + + return () => { + document.removeEventListener( 'keydown', handleTrapFocus ); + }; + }, [ ref, handleTrapFocus ] ); +}; + +export default useFocusTrap; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-has-selected-payment-block-once.js b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-has-selected-payment-block-once.js new file mode 100644 index 0000000000000..f8060b9a2d232 --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-has-selected-payment-block-once.js @@ -0,0 +1,62 @@ +import { useSelect } from '@wordpress/data'; +import { useState, useEffect } from '@wordpress/element'; + +/** + * Watch the user's block selection and keep a note if they ever select a payments + * block. + * A payments block is any block with 'payments' in the name, like jetpack/simple-payments + * or jetpack/recurring-payments. + * Selecting a block whose direct parent has 'payments' in the name also counts. + * This is to account for clicking inside the button in a payments block, for example. + * @returns {boolean} Has the user selected a payments block (or a direct descendant) at least once? + */ +const useHasSelectedPaymentBlockOnce = () => { + const [ hasSelectedPaymentsOnce, setHasSelectedPaymentsOnce ] = useState( false ); + + // Get the name of the currently selected block + const selectedBlockName = useSelect( select => { + // Special case: We know we're returning true, so we don't need to find block names. + if ( hasSelectedPaymentsOnce ) { + return ''; + } + + const selectedBlock = select( 'core/block-editor' ).getSelectedBlock(); + return selectedBlock?.name ?? ''; + } ); + + // Get the name of the currently selected block's direct parent, if one exists + const parentSelectedBlockName = useSelect( select => { + // Special case: We know we're returning true, so we don't need to find block names. + if ( hasSelectedPaymentsOnce ) { + return ''; + } + + const selectedBlock = select( 'core/block-editor' ).getSelectedBlock(); + if ( selectedBlock?.clientId ) { + const parentIds = select( 'core/block-editor' ).getBlockParents( selectedBlock?.clientId ); + if ( parentIds && parentIds.length ) { + const parent = select( 'core/block-editor' ).getBlock( parentIds[ parentIds.length - 1 ] ); + return parent?.name ?? ''; + } + } + return ''; + } ); + + // On selection change, set hasSelectedPaymentsOnce=true if block name or parent's block name contains 'payments' + useEffect( () => { + if ( + ! hasSelectedPaymentsOnce && + ( selectedBlockName.includes( 'payments' ) || parentSelectedBlockName.includes( 'payments' ) ) + ) { + setHasSelectedPaymentsOnce( true ); + } + }, [ + selectedBlockName, + parentSelectedBlockName, + hasSelectedPaymentsOnce, + setHasSelectedPaymentsOnce, + ] ); + + return hasSelectedPaymentsOnce; +}; +export default useHasSelectedPaymentBlockOnce; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-keydown-handler.ts b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-keydown-handler.ts new file mode 100644 index 0000000000000..6ea129fe08f2e --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-keydown-handler.ts @@ -0,0 +1,52 @@ +/* eslint-disable jsdoc/require-param */ +/** + * External Dependencies + */ +import { useEffect, useCallback } from '@wordpress/element'; + +interface Props { + onEscape?: () => void; + onArrowRight?: () => void; + onArrowLeft?: () => void; +} + +/** + * A hook the applies the respective callbacks in response to keydown events. + */ +const useKeydownHandler = ( { onEscape, onArrowRight, onArrowLeft }: Props ): void => { + const handleKeydown = useCallback( + ( event: KeyboardEvent ) => { + let handled = false; + + switch ( event.key ) { + case 'Escape': + onEscape && ( onEscape(), ( handled = true ) ); + break; + case 'ArrowRight': + onArrowRight && ( onArrowRight(), ( handled = true ) ); + break; + case 'ArrowLeft': + onArrowLeft && ( onArrowLeft(), ( handled = true ) ); + break; + default: + break; + } + + if ( handled ) { + event.preventDefault(); + event.stopPropagation(); + } + }, + [ onEscape, onArrowRight, onArrowLeft ] + ); + + useEffect( () => { + document.addEventListener( 'keydown', handleKeydown ); + + return () => { + document.removeEventListener( 'keydown', handleKeydown ); + }; + }, [ handleKeydown ] ); +}; + +export default useKeydownHandler; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-should-show-seller-celebration-modal.js b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-should-show-seller-celebration-modal.js new file mode 100644 index 0000000000000..80f37b3b530cf --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-should-show-seller-celebration-modal.js @@ -0,0 +1,67 @@ +import { useSelect } from '@wordpress/data'; +import { useState, useEffect } from '@wordpress/element'; +import { useHasSeenSellerCelebrationModal } from '../contexts/has-seen-seller-celebration-modal-context'; +import useHasSelectedPaymentBlockOnce from './use-has-selected-payment-block-once'; +import useSiteIntent from './use-site-intent'; + +const useShouldShowSellerCelebrationModal = () => { + const [ shouldShowSellerCelebrationModal, setShouldShowSellerCelebrationModal ] = + useState( false ); + + const { siteIntent: intent } = useSiteIntent(); + const hasSelectedPaymentsOnce = useHasSelectedPaymentBlockOnce(); + + const { hasSeenSellerCelebrationModal } = useHasSeenSellerCelebrationModal(); + + const hasPaymentsBlock = useSelect( select => { + const isSiteEditor = !! select( 'core/edit-site' ); + + if ( isSiteEditor ) { + const page = select( 'core/edit-site' ).getPage(); + const pageId = parseInt( page?.context?.postId ); + const pageEntity = select( 'core' ).getEntityRecord( 'postType', 'page', pageId ); + + let paymentsBlock = false; + // Only check for payment blocks if we haven't seen the celebration modal text yet + if ( ! hasSeenSellerCelebrationModal ) { + const didCountRecurringPayments = + select( 'core/block-editor' ).getGlobalBlockCount( 'jetpack/recurring-payments' ) > 0; + const didCountSimplePayments = + select( 'core/block-editor' ).getGlobalBlockCount( 'jetpack/simple-payments' ) > 0; + paymentsBlock = + ( pageEntity?.content?.raw?.includes( '' ) || + pageEntity?.content?.raw?.includes( '' ) || + didCountRecurringPayments || + didCountSimplePayments ) ?? + false; + } + + return paymentsBlock; + } + + let paymentBlockCount = 0; + // Only check for payment blocks if we haven't seen the celebration modal yet + if ( ! hasSeenSellerCelebrationModal ) { + paymentBlockCount += select( 'core/block-editor' ).getGlobalBlockCount( + 'jetpack/recurring-payments' + ); + paymentBlockCount += + select( 'core/block-editor' ).getGlobalBlockCount( 'jetpack/simple-payments' ); + } + + return paymentBlockCount > 0; + } ); + + useEffect( () => { + if ( + intent === 'sell' && + hasPaymentsBlock && + hasSelectedPaymentsOnce && + ! hasSeenSellerCelebrationModal + ) { + setShouldShowSellerCelebrationModal( true ); + } + }, [ intent, hasPaymentsBlock, hasSelectedPaymentsOnce, hasSeenSellerCelebrationModal ] ); + return shouldShowSellerCelebrationModal; +}; +export default useShouldShowSellerCelebrationModal; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-should-show-video-celebration-modal.ts b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-should-show-video-celebration-modal.ts new file mode 100644 index 0000000000000..ebbc5ce2ce1d2 --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-should-show-video-celebration-modal.ts @@ -0,0 +1,51 @@ +import { useState, useEffect } from '@wordpress/element'; +import request from 'wpcom-proxy-request'; +import { useHasSeenVideoCelebrationModal } from '../contexts/has-seen-video-celebration-modal-context'; +import useSiteIntent from './use-site-intent'; + +declare global { + interface Window { + _currentSiteId: number; + _currentSiteType: string; + } +} + +interface Site { + options?: { + launchpad_checklist_tasks_statuses?: { + video_uploaded: boolean; + }; + }; +} +const useShouldShowVideoCelebrationModal = ( isEditorSaving: boolean ) => { + const { siteIntent: intent } = useSiteIntent(); + + const [ shouldShowVideoCelebrationModal, setShouldShowVideoCelebrationModal ] = useState( false ); + const { hasSeenVideoCelebrationModal } = useHasSeenVideoCelebrationModal(); + + useEffect( () => { + const maybeRenderVideoCelebrationModal = async () => { + // Get latest site options since the video may have just been uploaded. + const siteObj = ( await request( { + path: `/sites/${ window._currentSiteId }?http_envelope=1`, + apiVersion: '1.1', + } ) ) as Site; + + if ( siteObj?.options?.launchpad_checklist_tasks_statuses?.video_uploaded ) { + setShouldShowVideoCelebrationModal( true ); + } + }; + + if ( 'videopress' === intent && ! hasSeenVideoCelebrationModal ) { + maybeRenderVideoCelebrationModal(); + } else if ( hasSeenVideoCelebrationModal ) { + setShouldShowVideoCelebrationModal( false ); + } + }, [ + isEditorSaving, // included so that we check whether the video has been uploaded on save. + intent, + hasSeenVideoCelebrationModal, + ] ); + return shouldShowVideoCelebrationModal; +}; +export default useShouldShowVideoCelebrationModal; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-site-intent.js b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-site-intent.js new file mode 100644 index 0000000000000..496ee2bc23bbd --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-site-intent.js @@ -0,0 +1,14 @@ +// FIXME: We can use `useSiteIntent` from `@automattic/data-stores` and remove this. +// https://github.com/Automattic/wp-calypso/pull/73565#discussion_r1113839120 +const useSiteIntent = () => { + // We can skip the request altogether since this information is already added to the window in + // https://github.com/Automattic/jetpack/blob/e135711f9a130946dae1bca6c9c0967350331067/projects/plugins/jetpack/extensions/plugins/launchpad-save-modal/launchpad-save-modal.php#LL31C8-L31C34 + // We could update this to use the launchpad endpoint in jetpack-mu-wpcom, but that may require + // permissions changes as it requires 'manage_options' to read + // https://github.com/Automattic/jetpack/blob/e135711f9a130946dae1bca6c9c0967350331067/projects/packages/jetpack-mu-wpcom/src/features/wpcom-endpoints/class-wpcom-rest-api-v2-endpoint-launchpad.php#L121. + return { + siteIntent: window.Jetpack_LaunchpadSaveModal?.siteIntentOption, + siteIntentFetched: true, + }; +}; +export default useSiteIntent; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-site-plan.js b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-site-plan.js new file mode 100644 index 0000000000000..d3c64400da453 --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-site-plan.js @@ -0,0 +1,24 @@ +import { useState, useEffect } from '@wordpress/element'; +import { useCallback } from 'react'; +import request from 'wpcom-proxy-request'; + +const useSitePlan = siteIdOrSlug => { + const [ sitePlan, setSitePlan ] = useState( {} ); + + const fetchSite = useCallback( async () => { + const siteObj = await request( { + path: `/sites/${ siteIdOrSlug }?http_envelope=1`, + apiVersion: '1.1', + } ); + if ( siteObj?.plan ) { + setSitePlan( siteObj.plan ); + } + }, [ siteIdOrSlug ] ); + + useEffect( () => { + fetchSite(); + }, [ fetchSite ] ); + + return sitePlan; +}; +export default useSitePlan; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-step-tracking.ts b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-step-tracking.ts new file mode 100644 index 0000000000000..a1e231ace668c --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/hooks/use-step-tracking.ts @@ -0,0 +1,26 @@ +/** + * External Dependencies + */ +import { useState, useEffect } from '@wordpress/element'; +/** + * Internal Dependencies + */ +import { Callback } from '../types'; + +const useStepTracking = ( + currentStepIndex: number, + onStepViewOnce: Callback | undefined +): void => { + const [ stepsViewed, setStepsViewed ] = useState< number[] >( [] ); + + useEffect( () => { + if ( stepsViewed.includes( currentStepIndex ) ) { + return; + } + + setStepsViewed( prev => [ ...prev, currentStepIndex ] ); + onStepViewOnce?.( currentStepIndex ); + }, [ currentStepIndex, onStepViewOnce, stepsViewed ] ); +}; + +export default useStepTracking; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/index.ts b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/index.ts new file mode 100644 index 0000000000000..44cc9252724ed --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/index.ts @@ -0,0 +1,6 @@ +export { default } from './components/tour-kit'; +export * from './constants'; +export { default as WpcomTourKit, usePrefetchTourAssets } from './variants/wpcom'; +export { useTourKitContext } from './contexts/tour-kit-context'; +export * from './types'; +export * from './hooks'; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/styles.scss b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/styles.scss new file mode 100644 index 0000000000000..ef38a0c05b1e1 --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/styles.scss @@ -0,0 +1,91 @@ +.tour-kit-frame { + visibility: hidden; + + &.is-visible { + visibility: visible; + } +} + +.tour-kit-frame__container { + border-radius: 2px; + bottom: 44px; + display: inline; + left: 16px; + position: fixed; + z-index: 9999; + // Avoid the text cursor when the text is not selectable + cursor: default; + box-shadow: 0 0 3px 0 rgba(0, 0, 0, 0.25); + background: var(--studio-white); +} + +.tour-kit-overlay { + position: fixed; + width: 100vw; + height: 100vh; + top: 0; + left: 0; + background: rgba(0, 0, 0); + opacity: 0; + + &.is-visible { + opacity: 0.5; + } +} + +.tour-kit-spotlight { + &.is-visible { + position: fixed; + overflow: hidden; + // box-shadow: 0 0 0 9999px rgba(0, 0, 255, 0.2); + outline: 99999px solid rgba(0, 0, 0, 0.5); + z-index: 1; + } +} + +.tour-kit-frame__arrow { + visibility: hidden; +} + +.tour-kit-frame__arrow, +.tour-kit-frame__arrow::before { + position: absolute; + width: 12px; + height: 12px; + background: inherit; + z-index: -1; +} + +.tour-kit-frame__arrow::before { + visibility: visible; + content: ""; + transform: rotate(45deg); +} + +.tour-kit-frame__container[data-popper-placement^="top"] > .tour-kit-frame__arrow { + bottom: -6px; + &::before { + box-shadow: 1px 1px 2px -1px rgb(0 0 0 / 25%); + } +} + +.tour-kit-frame__container[data-popper-placement^="bottom"] > .tour-kit-frame__arrow { + top: -6px; + &::before { + box-shadow: -1px -1px 2px -1px rgb(0 0 0 / 25%); + } +} + +.tour-kit-frame__container[data-popper-placement^="left"] > .tour-kit-frame__arrow { + right: -6px; + &::before { + box-shadow: 1px -1px 2px -1px rgb(0 0 0 / 25%); + } +} + +.tour-kit-frame__container[data-popper-placement^="right"] > .tour-kit-frame__arrow { + left: -6px; + &::before { + box-shadow: -1px 1px 2px -1px rgb(0 0 0 / 25%); + } +} diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/types.ts b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/types.ts new file mode 100644 index 0000000000000..3f4ec5c080a13 --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/types.ts @@ -0,0 +1,164 @@ +import * as PopperJS from '@popperjs/core'; +import React from 'react'; +import { SpotlightInteractivityConfiguration } from './components/tour-kit-spotlight-interactivity'; +import { LiveResizeConfiguration } from './utils/live-resize-modifier'; +import type { Modifier } from 'react-popper'; + +export interface Step { + slug?: string; + referenceElements?: { + desktop?: string; + mobile?: string; + }; + meta: { + [ key: string ]: unknown; + // | React.FunctionComponent< Record< string, unknown > > + // | HTMLElement + // | string + // | ... + }; + options?: { + classNames?: { + /** + * `desktop` classes are applied when min-width is larger or equal to 480px. + */ + desktop?: string | string[]; + /** + * `mobile` classes are applied when max-width is smaller than 480px. + */ + mobile?: string | string[]; + }; + }; +} + +export interface TourStepRendererProps { + steps: Step[]; + currentStepIndex: number; + onDismiss: ( source: string ) => () => void; + onNextStep: () => void; + onPreviousStep: () => void; + onMinimize: () => void; + setInitialFocusedElement: React.Dispatch< React.SetStateAction< HTMLElement | null > >; + onGoToStep: ( stepIndex: number ) => void; +} + +export interface MinimizedTourRendererProps { + steps: Step[]; + currentStepIndex: number; + onMaximize: () => void; + onDismiss: ( source: string ) => () => void; +} + +export type TourStepRenderer = React.FunctionComponent< TourStepRendererProps >; +export type MinimizedTourRenderer = React.FunctionComponent< MinimizedTourRendererProps >; +export type Callback = ( currentStepIndex: number ) => void; +export type CloseHandler = ( steps: Step[], currentStepIndex: number, source: string ) => void; +export type PopperModifier = Partial< Modifier< unknown, Record< string, unknown > > >; + +export interface Callbacks { + onMinimize?: Callback; + onMaximize?: Callback; + onGoToStep?: Callback; + onNextStep?: Callback; + onPreviousStep?: Callback; + onStepViewOnce?: Callback; + onStepView?: Callback; +} + +export interface Options { + classNames?: string | string[]; + callbacks?: Callbacks; + /** An object to enable/disable/combine various tour effects, such as spotlight, overlay, and autoscroll */ + effects?: { + /** + * Adds a semi-transparent overlay and highlights the reference element + * when provided with a transparent box over it. The existence of this configuration + * key implies enabling the spotlight effect. + */ + spotlight?: { + /** An object that configures whether the user is allowed to interact with the referenced element during the tour */ + interactivity?: SpotlightInteractivityConfiguration; + /** CSS properties that configures the styles applied to the spotlight overlay */ + styles?: React.CSSProperties; + }; + /** Shows a little triangle that points to the referenced element. Defaults to true */ + arrowIndicator?: boolean; + /** + * Includes the semi-transparent overlay for all the steps Also blocks interactions for everything except the tour dialogues, + * including the referenced elements. Refer to spotlight interactivity configuration to affect this. + * + * Defaults to false, but if spotlight is enabled it implies this is enabled as well. + */ + overlay?: boolean; + /** Configures the autoscroll behaviour. Defaults to False. More information about the configuration at: https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollIntoView */ + autoScroll?: ScrollIntoViewOptions | boolean; + /** Configures the behaviour for automatically resizing the tour kit elements (TourKitFrame and Spotlight). Defaults to disabled. */ + liveResize?: LiveResizeConfiguration; + }; + popperModifiers?: PopperModifier[]; + portalParentElement?: HTMLElement | null; +} + +export interface Config { + steps: Step[]; + renderers: { + tourStep: TourStepRenderer; + tourMinimized: MinimizedTourRenderer; + }; + closeHandler: CloseHandler; + isMinimized?: boolean; + options?: Options; + placement?: PopperJS.Placement; +} + +export type Tour = React.FunctionComponent< { config: Config } >; + +/************************ + * WPCOM variant types: * + ************************/ + +export type OnTourRateCallback = ( currentStepIndex: number, liked: boolean ) => void; + +export interface WpcomStep extends Step { + meta: { + heading: string | null; + descriptions: { + desktop: string | React.ReactElement | null; + mobile: string | React.ReactElement | null; + }; + imgSrc?: { + desktop?: { + src: string; + type: string; + }; + mobile?: { + src: string; + type: string; + }; + }; + imgLink?: { + href: string; + playable?: boolean; + onClick?: () => void; + }; + }; +} + +export interface WpcomTourStepRendererProps extends TourStepRendererProps { + steps: WpcomStep[]; +} + +export interface WpcomOptions extends Options { + tourRating?: { + enabled: boolean; + useTourRating?: () => 'thumbs-up' | 'thumbs-down' | undefined; + onTourRate?: ( rating: 'thumbs-up' | 'thumbs-down' ) => void; + }; +} + +export interface WpcomConfig extends Omit< Config, 'renderers' > { + steps: WpcomStep[]; + options?: WpcomOptions; +} + +export type WpcomTour = React.FunctionComponent< { config: WpcomConfig } >; diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/utils/index.ts b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/utils/index.ts new file mode 100644 index 0000000000000..3f00a820d1703 --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/utils/index.ts @@ -0,0 +1,16 @@ +import debugFactory from 'debug'; + +/** + * Helper to convert CSV of `classes` to an array. + * @param classes - String or array of classes to format. + * @returns Array of classes + */ +export function classParser( classes?: string | string[] ): string[] | null { + if ( classes?.length ) { + return classes.toString().split( ',' ); + } + + return null; +} + +export const debug = debugFactory( 'tour-kit' ); diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/utils/live-resize-modifier.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/utils/live-resize-modifier.tsx new file mode 100644 index 0000000000000..ab1a14cf8568b --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/utils/live-resize-modifier.tsx @@ -0,0 +1,111 @@ +import { debug } from '../utils'; +import type { ModifierArguments, Options, State } from '@popperjs/core'; +import type { Modifier } from 'react-popper'; + +// Adds the resizeObserver and mutationObserver properties to the popper effect function argument +type ModifierArgumentsWithObserversProp = ModifierArguments< Options > & { + state: State & { + elements: State[ 'elements' ] & { + reference: State[ 'elements' ][ 'reference' ] & { + [ key: symbol ]: { + resizeObserver: ResizeObserver; + mutationObserver: MutationObserver; + }; + }; + }; + }; +}; + +export interface LiveResizeConfiguration { + /** CSS Selector for the the DOM node (and children) to observe for mutations */ + rootElementSelector?: string; + /** True to enable update on reference element resize, defaults to false */ + resize?: boolean; + /** True to enable update on node and subtree mutation, defaults to false. May be performance intensive */ + mutation?: boolean; +} + +type liveResizeModifierFactory = ( + params: LiveResizeConfiguration | undefined +) => Modifier< 'liveResizeModifier', Record< string, unknown > >; + +/** + * Function that returns a Popper modifier that observes the specified root element as well as + * reference element for any changes. The reason for being a currying function is so that + * we can customise the root element selector, otherwise observing at a higher than necessary + * level might cause unnecessary performance penalties. + * + * The Popper modifier queues an asynchronous update on the Popper instance whenever either of the + * Observers trigger its callback. + * + * @param config - The config. + * @param config.rootElementSelector - The selector of the root element. + * @param config.mutation - Whether to mutate. + * @param config.resize - Whether to resize. + * @returns custom Popper modifier. + */ +export const liveResizeModifier: liveResizeModifierFactory = ( + { rootElementSelector, mutation = false, resize = false }: LiveResizeConfiguration = { + mutation: false, + resize: false, + } +) => ( { + name: 'liveResizeModifier', + enabled: true, + phase: 'main', + fn: () => { + return; + }, + effect: arg0 => { + try { + const { state, instance } = arg0 as ModifierArgumentsWithObserversProp; // augment types here because we are mutating the properties on the argument that is passed in + + const ObserversProp = Symbol(); // use a symbol here so that we don't clash with multiple poppers using this modifier on the same reference node + const { reference } = state.elements; + + reference[ ObserversProp ] = { + resizeObserver: new ResizeObserver( () => { + instance.update(); + } ), + + mutationObserver: new MutationObserver( () => { + instance.update(); + } ), + }; + + if ( resize ) { + if ( reference instanceof Element ) { + reference[ ObserversProp ].resizeObserver.observe( reference ); + } else { + debug( + 'Error: ResizeObserver does not work with virtual elements, Tour Kit will not resize automatically if the size of the referenced element changes.' + ); + } + } + + if ( mutation ) { + const rootElementNode = document.querySelector( rootElementSelector || '#wpwrap' ); + if ( rootElementNode instanceof Element ) { + reference[ ObserversProp ].mutationObserver.observe( rootElementNode, { + attributes: true, + characterData: true, + childList: true, + subtree: true, + } ); + } else { + debug( + `Error: ${ rootElementSelector } selector did not find a valid DOM element, Tour Kit will not update automatically if the DOM layout changes.` + ); + } + } + + return () => { + reference[ ObserversProp ].resizeObserver.disconnect(); + reference[ ObserversProp ].mutationObserver.disconnect(); + delete reference[ ObserversProp ]; + }; + } catch ( error ) { + debug( 'Error: Tour Kit live resize modifier failed unexpectedly:', error ); + } + }, +} ); diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-minimized.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-minimized.tsx new file mode 100644 index 0000000000000..1afd5ce37fca4 --- /dev/null +++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-minimized.tsx @@ -0,0 +1,50 @@ +import { Button, Flex } from '@wordpress/components'; +import { createInterpolateElement } from '@wordpress/element'; +import { sprintf } from '@wordpress/i18n'; +import { Icon, close } from '@wordpress/icons'; +import { useI18n } from '@wordpress/react-i18n'; +import maximize from '../icons/maximize'; +import type { MinimizedTourRendererProps } from '../../../types'; + +const WpcomTourKitMinimized: React.FunctionComponent< MinimizedTourRendererProps > = ( { + steps, + onMaximize, + onDismiss, + currentStepIndex, +} ) => { + const { __ } = useI18n(); + const lastStepIndex = steps.length - 1; + const page = currentStepIndex + 1; + const numberOfPages = lastStepIndex + 1; + + return ( +-
+ { Array.from( { length: numberOfPages } ).map( index => (
+
- + + ) ) } + { children &&
- { children } } +
+ { __( 'Did you find this guide helpful?', 'jetpack-mu-wpcom' ) } +
+
+
+
+ );
+};
+
+export default WpcomTourKitRating;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step-card-navigation.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step-card-navigation.tsx
new file mode 100644
index 0000000000000..e324f0b2a4380
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step-card-navigation.tsx
@@ -0,0 +1,62 @@
+import { Button } from '@wordpress/components';
+import { useI18n } from '@wordpress/react-i18n';
+import WpcomTourKitPaginationControl from './wpcom-tour-kit-pagination-control';
+import type { WpcomTourStepRendererProps } from '../../../types';
+
+type Props = Omit< WpcomTourStepRendererProps, 'onMinimize' >;
+
+const WpcomTourKitStepCardNavigation: React.FunctionComponent< Props > = ( {
+ currentStepIndex,
+ onDismiss,
+ onGoToStep,
+ onNextStep,
+ onPreviousStep,
+ setInitialFocusedElement,
+ steps,
+} ) => {
+ const { __ } = useI18n();
+ const isFirstStep = currentStepIndex === 0;
+ const lastStepIndex = steps.length - 1;
+
+ return (
+ <>
+
+
+
+
+ ) : (
+
+
+
+
+ ) }
+
+
+
+
+
+
+ );
+};
+
+export default WpcomTourKitStepCardOverlayControls;
diff --git a/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step-card.tsx b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step-card.tsx
new file mode 100644
index 0000000000000..743d4f1cce9ac
--- /dev/null
+++ b/projects/packages/jetpack-mu-wpcom/src/common/tour-kit/variants/wpcom/components/wpcom-tour-kit-step-card.tsx
@@ -0,0 +1,109 @@
+import { Button, Card, CardBody, CardFooter, CardMedia } from '@wordpress/components';
+import { useViewportMatch } from '@wordpress/compose';
+import { Icon } from '@wordpress/icons';
+import { useI18n } from '@wordpress/react-i18n';
+import clsx from 'clsx';
+import WpcomTourKitRating from './wpcom-tour-kit-rating';
+import WpcomTourKitStepCardNavigation from './wpcom-tour-kit-step-card-navigation';
+import WpcomTourKitStepCardOverlayControls from './wpcom-tour-kit-step-card-overlay-controls';
+import type { WpcomTourStepRendererProps } from '../../../types';
+
+const WpcomTourKitStepCard: React.FunctionComponent< WpcomTourStepRendererProps > = ( {
+ steps,
+ currentStepIndex,
+ onMinimize,
+ onDismiss,
+ onGoToStep,
+ onNextStep,
+ onPreviousStep,
+ setInitialFocusedElement,
+} ) => {
+ const { __ } = useI18n();
+ const lastStepIndex = steps.length - 1;
+ const { descriptions, heading, imgSrc, imgLink } = steps[ currentStepIndex ].meta;
+ const isLastStep = currentStepIndex === lastStepIndex;
+ const isMobile = useViewportMatch( 'mobile', '<' );
+ const description = descriptions[ isMobile ? 'mobile' : 'desktop' ] ?? descriptions.desktop;
+
+ return (
+ { heading }
++ { description } + { isLastStep ? ( + + ) : null } +
+