Restructure feed hover state machine code (#3550)

src/components/ProfileHoverCard/index.web.tsx

@@ -59,9 +59,9 @@ type Action =
   | 'pressed'
   | 'hovered'
   | 'unhovered'
-  | 'show-timer-elapsed'
+  | 'hovered-long-enough'
-  | 'hide-timer-elapsed'
+  | 'unhovered-long-enough'
-  | 'hide-animation-completed'
+  | 'finished-animating-hide'
 
 const SHOW_DELAY = 350
 const SHOW_DURATION = 300
@@ -76,90 +76,110 @@ export function ProfileHoverCardInner(props: ProfileHoverCardProps) {
   const [currentState, dispatch] = React.useReducer(
     // Tip: console.log(state, action) when debugging.
     (state: State, action: Action): State => {
-      // Regardless of which stage we're in, pressing always hides the card.
+      // Pressing within a card should always hide it.
+      // No matter which stage we're in.
       if (action === 'pressed') {
+        return hidden()
+      }
+
+      // --- Hidden ---
+      // In the beginning, the card is not displayed.
+      function hidden(): State {
         return {stage: 'hidden'}
       }
 
+      // The user can kick things off by hovering a target.
       if (state.stage === 'hidden') {
-        // Our story starts when the card is hidden.
-        // If the user hovers, we kick off a grace period before showing the card.
         if (action === 'hovered') {
+          return mightShow(SHOW_DELAY)
+        }
+      }
+
+      // --- Might Show ---
+      // The card is not visible yet but we're considering showing it.
+      function mightShow(waitMs: number): State {
         return {
           stage: 'might-show',
           effect() {
-              const id = setTimeout(
+            const id = setTimeout(() => dispatch('hovered-long-enough'), waitMs)
-                () => dispatch('show-timer-elapsed'),
-                SHOW_DELAY,
-              )
             return () => {
               clearTimeout(id)
             }
           },
         }
       }
+
+      // We'll make a decision at the end of a grace period timeout.
+      if (state.stage === 'might-show') {
+        if (action === 'unhovered') {
+          return hidden()
+        }
+        if (action === 'hovered-long-enough') {
+          return showing()
+        }
       }
 
-      if (state.stage === 'might-show') {
+      // --- Showing ---
-        // We're in the grace period when we decide whether to show the card.
+      // The card is beginning to show up and then will remain visible.
-        // At this point, two things can happen. Either the user unhovers, and
+      function showing(): State {
-        // we go back to hidden--or they linger enough that we'll show the card.
-        if (action === 'unhovered') {
-          return {stage: 'hidden'}
-        }
-        if (action === 'show-timer-elapsed') {
         return {stage: 'showing'}
       }
+
+      // If the user moves the pointer away, we'll begin to consider hiding it.
+      if (state.stage === 'showing') {
+        if (action === 'unhovered') {
+          return mightHide(HIDE_DELAY)
+        }
       }
 
-      if (state.stage === 'showing') {
+      // --- Might Hide ---
-        // We're showing the card now.
+      // The user has moved hover away from a visible card.
-        // If the user unhovers, we'll start a grace period before hiding the card.
+      function mightHide(waitMs: number): State {
-        if (action === 'unhovered') {
         return {
           stage: 'might-hide',
           effect() {
             const id = setTimeout(
-                () => dispatch('hide-timer-elapsed'),
+              () => dispatch('unhovered-long-enough'),
-                HIDE_DELAY,
+              waitMs,
             )
             return () => clearTimeout(id)
           },
         }
       }
+
+      // We'll make a decision based on whether it received hover again in time.
+      if (state.stage === 'might-hide') {
+        if (action === 'hovered') {
+          return showing()
+        }
+        if (action === 'unhovered-long-enough') {
+          return hiding(HIDE_DURATION)
+        }
       }
 
-      if (state.stage === 'might-hide') {
+      // --- Hiding ---
-        // We're in the grace period when we decide whether to hide the card.
+      // The user waited enough outside that we're hiding the card.
-        // At this point, two things can happen. Either the user hovers, and
+      function hiding(animationDurationMs: number): State {
-        // we go back to showing it--or they linger enough that we'll start hiding the card.
-        if (action === 'hovered') {
-          return {stage: 'showing'}
-        }
-        if (action === 'hide-timer-elapsed') {
         return {
           stage: 'hiding',
           effect() {
             const id = setTimeout(
-                () => dispatch('hide-animation-completed'),
+              () => dispatch('finished-animating-hide'),
-                HIDE_DURATION,
+              animationDurationMs,
             )
             return () => clearTimeout(id)
           },
         }
       }
-      }
 
+      // While hiding, we don't want to be interrupted by anything else.
+      // When the animation finishes, we loop back to the initial hidden state.
       if (state.stage === 'hiding') {
-        // We're currently playing the hiding animation.
+        if (action === 'finished-animating-hide') {
-        // We'll ignore all inputs now and wait for the animation to finish.
+          return hidden()
-        // At that point, we'll hide the entire thing, going back to square one.
-        if (action === 'hide-animation-completed') {
-          return {stage: 'hidden'}
         }
       }
 
-      // Something else happened. Keep calm and carry on.
       return state
     },
     {stage: 'hidden'},