feat(app): save RTP list scroll position when selecting RTPs on ODD (#17816)

closes AUTH-1586
closes https://opentrons.atlassian.net/browse/RQA-3523

Author: shlokamin

app/src/App/ODDProviders/ScrollRefProvider.tsx

@@ -0,0 +1,32 @@
+import { createContext, useCallback, useState } from 'react'
+import type { FC, ReactNode } from 'react'
+
+export interface SharedScrollRefContextType {
+  refCallback: (node: HTMLElement | null) => void
+  element: HTMLElement | null
+}
+
+export const SharedScrollRefContext = createContext<SharedScrollRefContextType | null>(
+  null
+)
+
+// This provider exists to capture the ref of the main scrollable Box element in the ODD
+// This is so that we can do things like auto scroll (using the ref) across components
+export const SharedScrollRefProvider: FC<{
+  children: ReactNode
+}> = ({ children }) => {
+  const [element, setCurrentElement] = useState<HTMLElement | null>(null)
+
+  // Callback ref that updates both the state and the ref
+  // This is necessary because we need a ref to be attached to the DOM
+  // But also refs don't trigger rerenders, which we need in order to detect scrolling
+  const refCallback = useCallback((node: HTMLElement | null) => {
+    setCurrentElement(node)
+  }, [])
+
+  return (
+    <SharedScrollRefContext.Provider value={{ refCallback, element }}>
+      {children}
+    </SharedScrollRefContext.Provider>
+  )
+}

app/src/App/OnDeviceDisplayApp.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState, useCallback } from 'react'
+import { useEffect } from 'react'
 import { useDispatch, useSelector } from 'react-redux'
 import { Routes, Route, Navigate, useLocation } from 'react-router-dom'
 import { css } from 'styled-components'
@@ -9,7 +9,6 @@ import {
   COLORS,
   OVERFLOW_AUTO,
   POSITION_RELATIVE,
-  useScrolling,
 } from '@opentrons/components'
 import { ApiHostProvider } from '@opentrons/react-api-client'
 import NiceModal from '@ebay/nice-modal-react'
@@ -46,13 +45,18 @@ import { Welcome } from '/app/pages/ODD/Welcome'
 import { InitialLoadingScreen } from '/app/pages/ODD/InitialLoadingScreen'
 import { DeckConfigurationEditor } from '/app/pages/ODD/DeckConfiguration'
 import { PortalRoot as ModalPortalRoot } from './portal'
+import { SharedScrollRefProvider } from './ODDProviders/ScrollRefProvider'
 import {
   getOnDeviceDisplaySettings,
   updateConfigValue,
 } from '/app/redux/config'
 import { updateBrightness } from '/app/redux/shell'
 import { useScreenIdle, SLEEP_NEVER_MS } from '/app/local-resources/dom-utils'
-import { useProtocolReceiptToast, useSoftwareUpdatePoll } from './hooks'
+import {
+  useProtocolReceiptToast,
+  useScrollRef,
+  useSoftwareUpdatePoll,
+} from './hooks'
 import { ODDTopLevelRedirects } from './ODDTopLevelRedirects'
 import { ReactQueryDevtools } from '/app/App/tools'
 
@@ -199,7 +203,9 @@ export const OnDeviceDisplayApp = (): JSX.Element => {
                     <NiceModal.Provider>
                       <ToasterOven>
                         <ProtocolReceiptToasts />
-                        <OnDeviceDisplayAppRoutes />
+                        <SharedScrollRefProvider>
+                          <OnDeviceDisplayAppRoutes />
+                        </SharedScrollRefProvider>
                       </ToasterOven>
                     </NiceModal.Provider>
                   </MaintenanceRunTakeover>
@@ -225,14 +231,10 @@ const getTargetPath = (unfinishedUnboxingFlowRoute: string | null): string => {
 // split to a separate function because scrollRef rerenders on every route change
 // this avoids rerendering parent providers as well
 export function OnDeviceDisplayAppRoutes(): JSX.Element {
-  const [currentNode, setCurrentNode] = useState<null | HTMLElement>(null)
-  const scrollRef = useCallback((node: HTMLElement | null) => {
-    setCurrentNode(node)
-  }, [])
-  const isScrolling = useScrolling(currentNode)
+  const { isScrolling, refCallback, element } = useScrollRef()
   const location = useLocation()
   useEffect(() => {
-    currentNode?.scrollTo({
+    element?.scrollTo({
       top: 0,
       left: 0,
       behavior: 'auto',
@@ -271,7 +273,7 @@ export function OnDeviceDisplayAppRoutes(): JSX.Element {
           key={path}
           path={path}
           element={
-            <Box css={TOUCH_SCREEN_STYLE} ref={scrollRef}>
+            <Box css={TOUCH_SCREEN_STYLE} ref={refCallback}>
               <ModalPortalRoot />
               {getPathComponent(path)}
             </Box>

app/src/App/__tests__/OnDeviceDisplayApp.test.tsx

@@ -27,7 +27,7 @@ import { getOnDeviceDisplaySettings } from '/app/redux/config'
 import { getIsShellReady } from '/app/redux/shell'
 import { getLocalRobot } from '/app/redux/discovery'
 import { mockConnectedRobot } from '/app/redux/discovery/__fixtures__'
-import { useProtocolReceiptToast } from '../hooks'
+import { useProtocolReceiptToast, useScrollRef } from '../hooks'
 import { useNotifyCurrentMaintenanceRun } from '/app/resources/maintenance_runs'
 import { ODDTopLevelRedirects } from '../ODDTopLevelRedirects'
 
@@ -93,6 +93,11 @@ describe('OnDeviceDisplayApp', () => {
     vi.mocked(getIsShellReady).mockReturnValue(true)
     vi.mocked(ODDTopLevelRedirects).mockReturnValue(null)
     vi.mocked(getLocalRobot).mockReturnValue(mockConnectedRobot)
+    vi.mocked(useScrollRef).mockReturnValue({
+      isScrolling: false,
+      refCallback: () => null,
+      element: null,
+    })
     vi.mocked(useNotifyCurrentMaintenanceRun).mockReturnValue({
       data: {
         data: {

app/src/App/hooks.ts

@@ -1,17 +1,21 @@
-import { useCallback, useRef, useEffect } from 'react'
+import { useCallback, useRef, useEffect, useContext } from 'react'
 import difference from 'lodash/difference'
 import { useTranslation } from 'react-i18next'
 import { useQueryClient } from 'react-query'
 import { useDispatch } from 'react-redux'
 
-import { useInterval, truncateString } from '@opentrons/components'
+import {
+  useInterval,
+  truncateString,
+  useScrolling,
+} from '@opentrons/components'
 import {
   useAllProtocolIdsQuery,
   useHost,
   useCreateLiveCommandMutation,
 } from '@opentrons/react-api-client'
 import { getProtocol } from '@opentrons/api-client'
-
+import { SharedScrollRefContext } from './ODDProviders/ScrollRefProvider'
 import { checkShellUpdate } from '/app/redux/shell'
 import { useToaster } from '/app/organisms/ToasterOven'
 
@@ -113,3 +117,32 @@ export function useProtocolReceiptToast(): void {
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [protocolIds])
 }
+
+export function useScrollRef(): {
+  isScrolling: boolean
+  refCallback: (node: HTMLElement | null) => void
+  element: HTMLElement | null
+} {
+  const refData = useContext(SharedScrollRefContext)
+  const isScrolling = useScrolling(refData?.element ?? null) // Assuming useScrolling is properly handling scroll state
+
+  if (refData == null) {
+    // log non critical error instead of throwing error to prevent white screens
+    console.error(
+      'useScrollRef must be used within a SharedScrollRefProvider. Falling back to dummy refs.'
+    )
+    return {
+      refCallback: () => null,
+      isScrolling: false,
+      element: null,
+    }
+  }
+
+  const { refCallback, element } = refData
+
+  return {
+    refCallback,
+    isScrolling,
+    element,
+  }
+}

app/src/organisms/ODD/ProtocolSetup/ProtocolSetupParameters/ProtocolSetupParameters.tsx

@@ -1,4 +1,4 @@
-import { useState, Fragment } from 'react'
+import { useEffect, useState, Fragment } from 'react'
 import { useTranslation } from 'react-i18next'
 import { useNavigate } from 'react-router-dom'
 import {
@@ -30,6 +30,7 @@ import { ChooseNumber } from './ChooseNumber'
 import { ChooseCsvFile } from './ChooseCsvFile'
 import { useToaster } from '/app/organisms/ToasterOven'
 import { ProtocolSetupStep } from '../ProtocolSetupStep'
+import { useScrollRef } from '/app/App/hooks'
 import type {
   CompletedProtocolAnalysis,
   ChoiceParameter,
@@ -68,6 +69,10 @@ export function ProtocolSetupParameters({
     chooseCsvFileScreen,
     setChooseCsvFileScreen,
   ] = useState<CsvFileParameter | null>(null)
+  const [prevScrollPosition, setPrevScrollPosition] = useState<number | null>(
+    null
+  )
+  const { element } = useScrollRef()
   const [resetValuesModal, showResetValuesModal] = useState<boolean>(false)
   const [startSetup, setStartSetup] = useState<boolean>(false)
   const [runTimeParametersOverrides, setRunTimeParametersOverrides] = useState<
@@ -82,6 +87,27 @@ export function ProtocolSetupParameters({
     )
   )
 
+  // Scroll back to the place where the user was before they went into a specific RTP selection screen
+  useEffect(() => {
+    const isShowingParametersList =
+      chooseValueScreen == null &&
+      chooseCsvFileScreen == null &&
+      showNumericalInputScreen == null
+    const canRestoreScrollPosition =
+      prevScrollPosition != null && element != null
+
+    if (isShowingParametersList && canRestoreScrollPosition) {
+      element.scrollTop = prevScrollPosition
+      setPrevScrollPosition(null) // Reset scroll position
+    }
+  }, [
+    chooseCsvFileScreen,
+    chooseValueScreen,
+    element,
+    prevScrollPosition,
+    showNumericalInputScreen,
+  ])
+
   const hasMissingFileParam =
     runTimeParametersOverrides?.some((parameter): boolean => {
       if (parameter.type !== 'csv_file') {
@@ -300,6 +326,7 @@ export function ProtocolSetupParameters({
                       : parameter.displayName
                   }
                   onClickSetupStep={() => {
+                    setPrevScrollPosition(element?.scrollTop ?? null)
                     handleSetParameter(parameter)
                   }}
                   detail={detail}