Onboarding: Guided tour checklist

code/.storybook/main.ts

@@ -81,6 +81,9 @@ const config = defineMain({
       directory: '../addons/onboarding/src',
       titlePrefix: 'addons/onboarding',
     },
+    {
+      directory: '../addons/onboarding/example-stories',
+    },
     {
       directory: '../addons/pseudo-states/src',
       titlePrefix: 'addons/pseudo-states',
@@ -100,6 +103,7 @@ const config = defineMain({
     },
   ],
   addons: [
+    '@storybook/addon-onboarding',
     '@storybook/addon-themes',
     '@storybook/addon-docs',
     '@storybook/addon-designs',

code/addons/onboarding/example-stories/Button.stories.tsx

@@ -0,0 +1,53 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { fn } from 'storybook/test';
+
+import { Button } from './Button';
+
+const meta = {
+  title: 'Example/Button',
+  component: Button,
+  parameters: {
+    layout: 'centered',
+    parameters: {
+      chromatic: {
+        disableSnapshot: true,
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    backgroundColor: { control: 'color' },
+  },
+  args: { onClick: fn() },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Primary: Story = {
+  args: {
+    primary: true,
+    label: 'Button',
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    label: 'Button',
+  },
+};
+
+export const Large: Story = {
+  args: {
+    size: 'large',
+    label: 'Button',
+  },
+};
+
+export const Small: Story = {
+  args: {
+    size: 'small',
+    label: 'Button',
+  },
+};

code/addons/onboarding/example-stories/Button.tsx

@@ -0,0 +1,37 @@
+import React from 'react';
+
+import './button.css';
+
+export interface ButtonProps {
+  /** Is this the principal call to action on the page? */
+  primary?: boolean;
+  /** What background color to use */
+  backgroundColor?: string;
+  /** How large should the button be? */
+  size?: 'small' | 'medium' | 'large';
+  /** Button contents */
+  label: string;
+  /** Optional click handler */
+  onClick?: () => void;
+}
+
+/** Primary UI component for user interaction */
+export const Button = ({
+  primary = false,
+  size = 'medium',
+  backgroundColor,
+  label,
+  ...props
+}: ButtonProps) => {
+  const mode = primary ? 'storybook-button--primary' : 'storybook-button--secondary';
+  return (
+    <button
+      type="button"
+      className={['storybook-button', `storybook-button--${size}`, mode].join(' ')}
+      style={{ backgroundColor }}
+      {...props}
+    >
+      {label}
+    </button>
+  );
+};

code/addons/onboarding/example-stories/button.css

@@ -0,0 +1,30 @@
+.storybook-button {
+  display: inline-block;
+  cursor: pointer;
+  border: 0;
+  border-radius: 3em;
+  font-weight: 700;
+  line-height: 1;
+  font-family: 'Nunito Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
+}
+.storybook-button--primary {
+  background-color: #555ab9;
+  color: white;
+}
+.storybook-button--secondary {
+  box-shadow: rgba(0, 0, 0, 0.15) 0px 0px 0px 1px inset;
+  background-color: transparent;
+  color: #333;
+}
+.storybook-button--small {
+  padding: 10px 16px;
+  font-size: 12px;
+}
+.storybook-button--medium {
+  padding: 11px 20px;
+  font-size: 14px;
+}
+.storybook-button--large {
+  padding: 12px 24px;
+  font-size: 16px;
+}

code/addons/onboarding/src/Onboarding.tsx

@@ -3,15 +3,14 @@ import React, { useCallback, useEffect, useState } from 'react';
 import { SyntaxHighlighter } from 'storybook/internal/components';
 import { SAVE_STORY_RESPONSE } from 'storybook/internal/core-events';
 
-import type { Step } from 'react-joyride';
 import { type API } from 'storybook/manager-api';
 import { ThemeProvider, convert, styled, themes } from 'storybook/theming';
 
+import { HighlightElement } from '../../../core/src/manager/components/TourGuide/HighlightElement';
+import { TourGuide } from '../../../core/src/manager/components/TourGuide/TourGuide';
 import { Confetti } from './components/Confetti/Confetti';
-import { HighlightElement } from './components/HighlightElement/HighlightElement';
 import type { STORYBOOK_ADDON_ONBOARDING_STEPS } from './constants';
-import { ADDON_CONTROLS_ID, STORYBOOK_ADDON_ONBOARDING_CHANNEL } from './constants';
-import { GuidedTour } from './features/GuidedTour/GuidedTour';
+import { ADDON_CONTROLS_ID, ADDON_ONBOARDING_CHANNEL } from './constants';
 import { IntentSurvey } from './features/IntentSurvey/IntentSurvey';
 import { SplashScreen } from './features/SplashScreen/SplashScreen';
 
@@ -44,30 +43,14 @@ const CodeWrapper = styled.div(({ theme }) => ({
 const theme = convert();
 
 export type StepKey = (typeof STORYBOOK_ADDON_ONBOARDING_STEPS)[number];
-export type StepDefinition = {
-  key: StepKey;
-  hideNextButton?: boolean;
-  onNextButtonClick?: () => void;
-} & Partial<
-  Pick<
-    // Unfortunately we can't use ts-expect-error here for some reason
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-ignore Ignore circular reference
-    Step,
-    | 'content'
-    | 'disableBeacon'
-    | 'disableOverlay'
-    | 'floaterProps'
-    | 'offset'
-    | 'placement'
-    | 'spotlightClicks'
-    | 'styles'
-    | 'target'
-    | 'title'
-  >
->;
 
-export default function Onboarding({ api }: { api: API }) {
+export default function Onboarding({
+  api,
+  hasCompletedSurvey,
+}: {
+  api: API;
+  hasCompletedSurvey: boolean;
+}) {
   const [enabled, setEnabled] = useState(true);
   const [showConfetti, setShowConfetti] = useState(false);
   const [step, setStep] = useState<StepKey>('1:Intro');
@@ -98,33 +81,36 @@ export default function Onboarding({ api }: { api: API }) {
     [api]
   );
 
-  const disableOnboarding = useCallback(() => {
-    // remove onboarding query parameter from current url
-    const url = new URL(window.location.href);
-    // @ts-expect-error (not strict)
-    const path = decodeURIComponent(url.searchParams.get('path'));
-    url.search = `?path=${path}&onboarding=false`;
-    history.replaceState({}, '', url.href);
-    api.setQueryParams({ onboarding: 'false' });
-    setEnabled(false);
-  }, [api, setEnabled]);
+  const disableOnboarding = useCallback(
+    (dismissedStep?: StepKey) => {
+      if (dismissedStep) {
+        api.emit(ADDON_ONBOARDING_CHANNEL, {
+          dismissedStep,
+          type: 'dismiss',
+          userAgent,
+        });
+      }
+      // remove onboarding query parameter from current url
+      const url = new URL(window.location.href);
+      url.searchParams.set('onboarding', 'false');
+      history.replaceState({}, '', url.href);
+      api.setQueryParams({ onboarding: 'false' });
+      setEnabled(false);
+    },
+    [api, setEnabled, userAgent]
+  );
 
-  const completeOnboarding = useCallback(
+  const completeSurvey = useCallback(
     (answers: Record<string, unknown>) => {
-      api.emit(STORYBOOK_ADDON_ONBOARDING_CHANNEL, {
-        step: '7:FinishedOnboarding' satisfies StepKey,
-        type: 'telemetry',
-        userAgent,
-      });
-      api.emit(STORYBOOK_ADDON_ONBOARDING_CHANNEL, {
+      api.emit(ADDON_ONBOARDING_CHANNEL, {
         answers,
         type: 'survey',
         userAgent,
       });
+      setStep('7:FinishedOnboarding');
       selectStory('configure-your-project--docs');
-      disableOnboarding();
     },
-    [api, selectStory, disableOnboarding, userAgent]
+    [api, selectStory, userAgent]
   );
 
   useEffect(() => {
@@ -148,6 +134,10 @@ export default function Onboarding({ api }: { api: API }) {
 
   useEffect(() => {
     setStep((current) => {
+      if (hasCompletedSurvey && current === '6:IntentSurvey') {
+        return '7:FinishedOnboarding';
+      }
+
       if (
         ['1:Intro', '5:StoryCreated', '6:IntentSurvey', '7:FinishedOnboarding'].includes(current)
       ) {
@@ -162,12 +152,13 @@ export default function Onboarding({ api }: { api: API }) {
         return '3:SaveFromControls';
       }
 
-      if (primaryControl) {
+      if (primaryControl || current === '2:Controls') {
         return '2:Controls';
       }
+
       return '1:Intro';
     });
-  }, [createNewStoryForm, primaryControl, saveFromControls]);
+  }, [hasCompletedSurvey, createNewStoryForm, primaryControl, saveFromControls]);
 
   useEffect(() => {
     return api.on(SAVE_STORY_RESPONSE, ({ payload, success }) => {
@@ -183,7 +174,7 @@ export default function Onboarding({ api }: { api: API }) {
   }, [api]);
 
   useEffect(
-    () => api.emit(STORYBOOK_ADDON_ONBOARDING_CHANNEL, { step, type: 'telemetry', userAgent }),
+    () => api.emit(ADDON_ONBOARDING_CHANNEL, { step, type: 'telemetry', userAgent }),
     [api, step, userAgent]
   );
 
@@ -196,7 +187,7 @@ export default function Onboarding({ api }: { api: API }) {
   const snippet = source?.slice(startIndex).trim();
   const startingLineNumber = source?.slice(0, startIndex).split('\n').length;
 
-  const steps: StepDefinition[] = [
+  const controlsTour = [
     {
       key: '2:Controls',
       target: '#control-primary',
@@ -213,7 +204,7 @@ export default function Onboarding({ api }: { api: API }) {
       disableBeacon: true,
       disableOverlay: true,
       spotlightClicks: true,
-      onNextButtonClick: () => {
+      onNext: () => {
         const input = document.querySelector('#control-primary') as HTMLInputElement;
         input.click();
       },
@@ -234,7 +225,7 @@ export default function Onboarding({ api }: { api: API }) {
       disableBeacon: true,
       disableOverlay: true,
       spotlightClicks: true,
-      onNextButtonClick: () => {
+      onNext: () => {
         const button = document.querySelector(
           'button[aria-label="Create new story with these settings"]'
         ) as HTMLButtonElement;
@@ -280,21 +271,59 @@ export default function Onboarding({ api }: { api: API }) {
         },
       },
     },
-  ] as const;
+  ];
+
+  const checklistTour = [
+    {
+      key: '7:FinishedOnboarding',
+      target: '#storybook-checklist-module',
+      title: 'Continue at your own pace using the guide',
+      content: (
+        <>
+          Nice! You've got the essentials. You can continue at your own pace using the guide to
+          discover more of Storybook's capabilities.
+          <HighlightElement targetSelector="#storybook-checklist-module" pulsating />
+        </>
+      ),
+      offset: 0,
+      placement: 'right-start',
+      disableBeacon: true,
+      disableOverlay: true,
+      styles: {
+        tooltip: {
+          width: 350,
+        },
+      },
+    },
+  ];
 
   return (
     <ThemeProvider theme={theme}>
       {showConfetti && <Confetti />}
       {step === '1:Intro' ? (
         <SplashScreen onDismiss={() => setStep('2:Controls')} />
       ) : step === '6:IntentSurvey' ? (
-        <IntentSurvey onComplete={completeOnboarding} onDismiss={disableOnboarding} />
+        <IntentSurvey
+          onComplete={completeSurvey}
+          onDismiss={() => disableOnboarding('6:IntentSurvey')}
+        />
+      ) : step === '7:FinishedOnboarding' ? (
+        <TourGuide
+          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          // @ts-ignore Circular reference in Step type
+          step={step}
+          steps={checklistTour}
+          onComplete={() => disableOnboarding()}
+          onDismiss={() => disableOnboarding(step)}
+        />
       ) : (
-        <GuidedTour
+        <TourGuide
+          // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+          // @ts-ignore Circular reference in Step type
           step={step}
-          steps={steps}
-          onClose={disableOnboarding}
-          onComplete={() => setStep('6:IntentSurvey')}
+          steps={controlsTour}
+          onComplete={() => setStep(hasCompletedSurvey ? '7:FinishedOnboarding' : '6:IntentSurvey')}
+          onDismiss={() => disableOnboarding(step)}
         />
       )}
     </ThemeProvider>