feat: do not start a tour/hint flow until the anchor is visible (#414)

* feat: do not start a tour/hint flow until the anchor is visible

* pr feedback

* add interaction tests

Author: christianmat

apps/smithy/src/stories/Tour/Tour.stories.tsx

@@ -109,6 +109,46 @@ export const Default = {
   ],
 };
 
+export const AnchorNotFound = {
+  args: {
+    autoScroll: true,
+    flowId: "flow_U63A5pndRrvCwxNs",
+    defaultOpen: true,
+  },
+  decorators: [
+    (_: StoryFn, options: StoryContext) => {
+      return (
+        <>
+          <Box
+            style={{
+              alignItems: "center",
+              display: "flex",
+              flexDirection: "column",
+              justifyContent: "center",
+              height: "calc(100vh - 32px)",
+            }}
+          >
+            <Box
+              borderRadius="10px"
+              id="tooltip-storybook-nonexistent"
+              p={4}
+              style={{ background: "red", width: "200px" }}
+            >
+              <Button.Primary
+                title="Non-existent Anchor"
+                onClick={() => {
+                  // no-op
+                }}
+              />
+            </Box>
+            <Tour {...(options.args as TourProps)} />
+          </Box>
+        </>
+      );
+    },
+  ],
+};
+
 export const WithScrollContainer = {
   args: {
     autoScroll: true,

apps/smithy/src/stories/Tour/TourInteractionTests.stories.tsx

@@ -16,14 +16,15 @@ const StoryMeta: Meta<typeof Tour> = {
 
 export default StoryMeta;
 
-export const InteractionTests: TourStory = {
+export const AnchorFoundInteractionTests: TourStory = {
   args: {
     flowId: "flow_U63A5pndRrvCwxNs",
   },
 
   decorators: [
     (Story, { args }) => {
       const { flow } = useFlow(args.flowId);
+      args.flow = flow;
 
       const lateAnchorRef = useRef(null);
 
@@ -52,7 +53,7 @@ export const InteractionTests: TourStory = {
           <button
             id="reset-flow"
             onClick={() => {
-              flow.restart();
+              flow?.restart();
             }}
             style={{ marginTop: "36px" }}
           >
@@ -103,12 +104,22 @@ export const InteractionTests: TourStory = {
     },
   ],
 
-  play: async ({ step }) => {
+  play: async ({ step, args }) => {
+    console.log("args", args);
+
     await step("Test paginating through the Tour", async () => {
       const canvas = within(document.body);
+      await waitFor(() => {
+        expect(args.flow).toBeDefined();
+      });
+
       let TourElement = await canvas.findByRole("dialog");
       let Tour = within(TourElement);
 
+      await waitFor(() => {
+        expect(args.flow?.isStarted).toBe(true);
+      });
+
       await userEvent.click(Tour.getByRole("button", { name: "Let's go!" }));
       await sleep(100);
 
@@ -120,7 +131,6 @@ export const InteractionTests: TourStory = {
       );
 
       await sleep(100);
-
       TourElement = await canvas.findByRole("dialog");
       Tour = within(TourElement);
 
@@ -140,3 +150,46 @@ export const InteractionTests: TourStory = {
     });
   },
 };
+
+export const AnchorNotFoundInteractionTests: TourStory = {
+  args: {
+    flowId: "flow_U63A5pndRrvCwxNs",
+  },
+
+  decorators: [
+    (Story, { args }) => {
+      const { flow } = useFlow(args.flowId);
+      args.flow = flow;
+
+      return (
+        <>
+          <Story {...args} />
+          <button
+            id="reset-flow"
+            onClick={() => {
+              flow?.restart();
+            }}
+            style={{ marginTop: "36px" }}
+          >
+            Reset Flow
+          </button>
+          <Box id="anchor-not-found" />
+        </>
+      );
+    },
+  ],
+
+  play: async ({ step, args }) => {
+    console.log("args", args);
+
+    await step("Test Anchor Not Found", async () => {
+      // Wait for flow to be defined
+      await waitFor(() => {
+        expect(args.flow).toBeDefined();
+      });
+
+      // Verify the flow is started
+      expect(args.flow?.isStarted).toBe(false);
+    });
+  },
+};

packages/react/src/components/Flow/FlowProps.ts

@@ -10,6 +10,26 @@ import type { StepHandler, StepHandlerProp } from '@/hooks/useStepHandlers'
 export interface BoxPropsWithoutChildren extends Omit<BoxProps, 'children'> {}
 
 export interface FlowPropsWithoutChildren extends BoxPropsWithoutChildren {
+  /**
+   * Whether to automatically mark the Flow started (i.e. in progress) when the Flow is eligible to be shown.
+   * You will need to call `flow.start()` or `step.start()` from the parent component if you set this to `false`. Most components should not need to override this behavior.
+   *
+   * Defaults to `true`.
+   */
+  autoStart?: boolean
+  /**
+   * Optional component to wrap the child components in, e.g. `as={Dialog}` will render the Flow in a modal Dialog. Defaults to `Box`.
+   */
+  as?: React.ElementType
+  /**
+   * Emotion CSS prop to apply to the component. See [Theming documentation](https://docs.frigade.com/v2/sdk/styling/css-overrides) for more information.
+   *
+   * Example usage:
+   * ```
+   * <Frigade.Checklist css={{ backgroundColor: "pink", ".fr-button-primary": { backgroundColor: "fuchsia" } }} />
+   * ```
+   */
+  css?: React.Attributes['css']
   /**
    * Whether the Flow is dismissible or not
    *
@@ -51,21 +71,6 @@ export interface FlowPropsWithoutChildren extends BoxPropsWithoutChildren {
    * For instance, you can use `title: Hello, ${name}!` in the Flow configuration and pass `variables={{name: 'John'}}` to customize the copy.
    */
   variables?: Record<string, unknown>
-
-  /**
-   * Optional component to wrap the child components in, e.g. `as={Dialog}` will render the Flow in a modal Dialog. Defaults to `Box`.
-   */
-  as?: React.ElementType
-
-  /**
-   * Emotion CSS prop to apply to the component. See [Theming documentation](https://docs.frigade.com/v2/sdk/styling/css-overrides) for more information.
-   *
-   * Example usage:
-   * ```
-   * <Frigade.Checklist css={{ backgroundColor: "pink", ".fr-button-primary": { backgroundColor: "fuchsia" } }} />
-   * ```
-   */
-  css?: React.Attributes['css']
 }
 
 export interface FlowProps extends FlowPropsWithoutChildren {

packages/react/src/components/Flow/index.tsx

@@ -24,14 +24,14 @@ function isDialog(component) {
 
 export function Flow({
   as,
+  autoStart = true,
   children,
   flowId,
   onComplete,
   onDismiss,
   onPrimary,
   onSecondary,
   variables,
-
   ...props
 }: FlowProps) {
   // const [hasProcessedRules, setHasProcessedRules] = useState(false)
@@ -123,7 +123,7 @@ export function Flow({
   //   return null
   // }
 
-  if (shouldForceMount || (!flow.isCompleted && !flow.isSkipped)) {
+  if (shouldForceMount || (!flow.isCompleted && !flow.isSkipped && autoStart)) {
     step?.start()
   }
 

packages/react/src/components/Hint/index.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 
 import { Box, type BoxProps } from '@/components/Box'
 import { Overlay } from '@/components/Overlay'
@@ -21,6 +21,7 @@ export interface HintProps extends BoxProps {
   children?: React.ReactNode
   defaultOpen?: boolean
   modal?: boolean
+  onMount?: () => void
   onOpenChange?: (open: boolean) => void
   open?: boolean
   side?: SideValue
@@ -37,6 +38,7 @@ export function Hint({
   css = {},
   defaultOpen = true,
   modal = false,
+  onMount,
   onOpenChange = () => {},
   open,
   part,
@@ -73,6 +75,7 @@ export function Hint({
   const referenceProps = getReferenceProps()
 
   const { isVisible } = useVisibility(refs.reference.current as Element | null)
+  const isMounted = useRef(false)
 
   useEffect(() => {
     if (!scrollComplete && autoScroll && refs.reference.current instanceof Element) {
@@ -105,8 +108,14 @@ export function Hint({
     }
   }, [autoScroll, refs.reference, scrollComplete])
 
-  if (refs.reference.current == null || !scrollComplete || !isVisible) {
+  const shouldMount = refs.reference.current !== null && scrollComplete && isVisible
+
+  if (!shouldMount) {
+    isMounted.current = false
     return null
+  } else if (isMounted.current === false) {
+    isMounted.current = true
+    onMount?.()
   }
 
   return (

packages/react/src/components/Tour/Tour.tsx

@@ -74,7 +74,7 @@ export function Tour({ as, flowId, ...props }: TourProps) {
   const { onDismiss, onPrimary, onSecondary } = props
 
   return (
-    <Flow as={null} flowId={flowId} {...props}>
+    <Flow as={null} flowId={flowId} autoStart={false} {...props}>
       {({ flow, handleDismiss, parentProps, step }) => {
         const {
           align = 'after',

packages/react/src/components/Tour/TourStep.tsx

@@ -68,6 +68,11 @@ export function TourStep({
       side={side}
       sideOffset={sideOffset}
       spotlight={spotlight}
+      onMount={() => {
+        if (defaultOpen && !disabled) {
+          step?.start()
+        }
+      }}
       {...otherProps}
     >
       <Card