feat(protocol-designer): add warning about dangerous submerge/retract position (#18825)

In analysis, we determine whether the submerge/retract location for a
given liquid transfer is deemed to be within the specified well's
liquid. We are afforded this since the API calculates the liquid
meniscus height in a all wells throughout the protocol. However, we do
not have access to this logic in Protocol Designer. Due to this reality,
we cannot know for sure whether a submerge/retract position set inside a
well is safely above the meniscus level. The resolution is to warn the
user that their submerge/retract position may result in analysis failure
if the tip is in fact below the calculated liquid meniscus at the time
of the pipette movement.

Closes RQA-4334

Author: ncdiehl11

protocol-designer/src/assets/localization/en/modal.json

@@ -15,6 +15,7 @@ import {
 import { TipPositionSideView } from '../TipPositionSideView'
 
 import type { ComponentProps } from 'react'
+import type { MoveLiquidPrefixType } from '../../../../resources/types'
 
 vi.mock('../TipPositionSideView')
 vi.mock('../../../../file-data/selectors')
@@ -51,7 +52,7 @@ describe('TipPositionModal', () => {
       specs: {
         z: {
           name: 'aspirate_mmFromBottom',
-          value: null,
+          value: 0,
           updateValue: mockUpdateZSpec,
         },
         y: {
@@ -95,6 +96,27 @@ describe('TipPositionModal', () => {
       'Tip position is close to the edge of the well and may cause collisions.'
     )
   })
+  describe('submerge/retract in well warning', () => {
+    const prefixes = [
+      'aspirate_submerge',
+      'dispense_submerge',
+      'aspirate_retract',
+      'dispense_retract',
+    ] as MoveLiquidPrefixType[]
+    prefixes.forEach(prefix => {
+      it(`renders the banner if the prefix is ${prefix} and the z value is inside the well`, () => {
+        props.prefix = prefix
+        props.specs.z.value = -1
+        props.specs.y.value = 0
+        props.specs.x.value = 0
+        render(props)
+        screen.getByText('The tip position may be inside the liquid')
+        screen.getByText(
+          'The tip must be above the ending height of the liquid for a valid transfer command'
+        )
+      })
+    })
+  })
   it('renders the captions, and visual', () => {
     render(props)
     screen.getByText('X position')

protocol-designer/src/components/organisms/TipPositionModal/__tests__/TipPositionModal.test.tsx

@@ -1,3 +1,15 @@
+import type { MoveLiquidPrefixType } from '../../../resources/types'
+
 export const DECIMALS_ALLOWED = 1
 export const TOO_MANY_DECIMALS: 'TOO_MANY_DECIMALS' = 'TOO_MANY_DECIMALS'
 export const PERCENT_RANGE_TO_SHOW_WARNING = 0.9
+
+export const MoveLiquidPrefixToAction: Record<MoveLiquidPrefixType, string> = {
+  aspirate: 'aspirate',
+  dispense: 'dispense',
+  mix: 'mix',
+  aspirate_retract: 'retract',
+  dispense_retract: 'retract',
+  aspirate_submerge: 'submerge',
+  dispense_submerge: 'submerge',
+}

protocol-designer/src/components/organisms/TipPositionModal/constants.ts

@@ -21,7 +21,7 @@ interface UsePositionReferenceResult {
 
 export function usePositionReference(args: {
   zValue: number
-  updateZValue: Dispatch<SetStateAction<string | null>>
+  updateZValue: Dispatch<SetStateAction<string>>
   wellDepth: number
   initialReference?: unknown
 }): UsePositionReferenceResult {

protocol-designer/src/components/organisms/TipPositionModal/hooks/usePositionReference.tsx

@@ -27,13 +27,17 @@ import {
 } from '@opentrons/shared-data'
 
 import { getIsTouchTipField } from '../../../form-types'
-import { prefixMap } from '../../../resources/utils'
 import { LINK_BUTTON_STYLE } from '../../atoms'
 import { getMainPagePortalEl } from '../Portal'
-import { PERCENT_RANGE_TO_SHOW_WARNING, TOO_MANY_DECIMALS } from './constants'
+import {
+  MoveLiquidPrefixToAction,
+  PERCENT_RANGE_TO_SHOW_WARNING,
+  TOO_MANY_DECIMALS,
+} from './constants'
 import { useDefaultPosition, usePositionReference } from './hooks'
 import { TipPositionSideView } from './TipPositionSideView'
 import { TipPositionTopView } from './TipPositionTopView'
+import { getIsTipInWell } from './utils'
 import * as utils from './utils'
 
 import type { ChangeEvent, Dispatch, SetStateAction } from 'react'
@@ -45,8 +49,8 @@ import type { MoveLiquidPrefixType } from '../../../resources/types'
 type Offset = 'x' | 'y' | 'z'
 interface PositionSpec {
   name: StepFieldName
-  value: number | null
-  updateValue: (val?: number | null) => void
+  value: number
+  updateValue: (val: number) => void
 }
 export type PositionSpecs = Record<Offset, PositionSpec>
 
@@ -99,7 +103,7 @@ export function TipPositionModal(
   })
   const defaultPosition = useDefaultPosition(formData, prefix)
 
-  const [zValue, setZValue] = useState<string | null>(
+  const [zValue, setZValue] = useState<string>(
     zSpec?.value == null
       ? String(
           referenceSpec?.value === POSITION_REFERENCE_BOTTOM
@@ -108,11 +112,11 @@ export function TipPositionModal(
         )
       : String(zSpec?.value)
   )
-  const [yValue, setYValue] = useState<string | null>(
-    ySpec?.value == null ? null : String(ySpec?.value)
+  const [yValue, setYValue] = useState<string>(
+    ySpec?.value == null ? '0' : String(ySpec?.value)
   )
-  const [xValue, setXValue] = useState<string | null>(
-    xSpec?.value == null ? null : String(xSpec?.value)
+  const [xValue, setXValue] = useState<string>(
+    xSpec?.value == null ? '0' : String(xSpec?.value)
   )
   const {
     positionReferenceDropdown,
@@ -125,6 +129,15 @@ export function TipPositionModal(
     wellDepth: wellDepthMm,
   })
 
+  // submerge/retract in well warning
+  const isInWell =
+    zValue != null && zValue !== ''
+      ? getIsTipInWell(Number(zValue), reference, wellDepthMm)
+      : false
+  const isSubmergeOrRetract =
+    MoveLiquidPrefixToAction[prefix] === 'submerge' ||
+    MoveLiquidPrefixToAction[prefix] === 'retract'
+
   // in this modal, pristinity hides the OUT_OF_BOUNDS error only.
   const [isPristine, setPristine] = useState<boolean>(true)
   const getMinMaxMmFromBottom = (
@@ -212,9 +225,9 @@ export function TipPositionModal(
 
   const handleDone = (): void => {
     if (!hasErrors) {
-      zSpec?.updateValue(zValue === null ? null : Number(zValue))
-      xSpec?.updateValue(xValue === null ? null : Number(xValue))
-      ySpec?.updateValue(yValue === null ? null : Number(yValue))
+      zSpec?.updateValue(Number(zValue))
+      xSpec?.updateValue(Number(xValue))
+      ySpec?.updateValue(Number(yValue))
       referenceSpec?.updateValue(reference)
       closeModal()
     }
@@ -226,7 +239,7 @@ export function TipPositionModal(
 
   const handleChange = (
     newValueRaw: string,
-    setValue: Dispatch<SetStateAction<string | null>>
+    setValue: Dispatch<SetStateAction<string>>
   ): void => {
     // if string, strip non-number characters from string and cast to number
     const newValue =
@@ -271,7 +284,9 @@ export function TipPositionModal(
       type="info"
       width="47rem"
       closeOnOutsideClick
-      title={t('shared:tip_position', { prefix: prefixMap[prefix] })}
+      title={t('shared:tip_position', {
+        prefix: MoveLiquidPrefixToAction[prefix],
+      })}
       onClose={handleCancel}
       footer={
         <Flex
@@ -297,10 +312,22 @@ export function TipPositionModal(
         {isXValueNearEdge || isYValueNearEdge || isZValueAtBottom ? (
           <Banner type="warning">
             <StyledText desktopStyle="bodyDefaultRegular">
-              {t('tip_position.warning')}
+              {t('tip_position.warning.close_to_edge')}
             </StyledText>
           </Banner>
         ) : null}
+        {isInWell && isSubmergeOrRetract ? (
+          <Banner type="warning">
+            <Flex flexDirection={DIRECTION_COLUMN}>
+              <StyledText desktopStyle="bodyDefaultSemiBold">
+                {t('tip_position.warning.submerge_retract_in_well.header')}
+              </StyledText>
+              <StyledText desktopStyle="bodyDefaultRegular">
+                {t('tip_position.warning.submerge_retract_in_well.subtext')}
+              </StyledText>
+            </Flex>
+          </Banner>
+        ) : null}
         <Flex gridGap={SPACING.spacing40}>
           <Flex
             flexDirection={DIRECTION_COLUMN}

protocol-designer/src/components/organisms/TipPositionModal/index.tsx

@@ -2,6 +2,7 @@ import floor from 'lodash/floor'
 import round from 'lodash/round'
 
 import {
+  getMmFromBottom,
   POSITION_REFERENCE_CENTER,
   POSITION_REFERENCE_TOP,
 } from '@opentrons/shared-data'
@@ -156,3 +157,15 @@ export const getIsZValueAtBottom = (
   }
   return round(parseFloat(zValue), 1) === round(minZValue, 1)
 }
+
+export const getIsTipInWell = (
+  z: number,
+  positionReference: PositionReference,
+  wellDepth: number | null
+): boolean => {
+  if (wellDepth == null) {
+    return false
+  }
+  const mmFromBottom = getMmFromBottom(z, positionReference, wellDepth)
+  return mmFromBottom != null && mmFromBottom <= wellDepth
+}

protocol-designer/src/components/organisms/TipPositionModal/utils.tsx

@@ -21,9 +21,9 @@ import {
   TipPositionModal,
   ZTipPositionModal,
 } from '../../../../../components/organisms'
+import { MoveLiquidPrefixToAction } from '../../../../../components/organisms/TipPositionModal/constants'
 import { getDefaultMmFromEdge } from '../../../../../components/organisms/TipPositionModal/utils'
 import { getIsDelayPositionField } from '../../../../../form-types'
-import { prefixMap } from '../../../../../resources/utils'
 import { selectors as stepFormSelectors } from '../../../../../step-forms'
 
 import type { PositionSpecs } from '../../../../../components/organisms'
@@ -159,12 +159,12 @@ export function PositionField(props: PositionFieldProps): JSX.Element {
       },
       x: {
         name: xName,
-        value: rawXValue != null ? Number(rawXValue) : null,
+        value: rawXValue != null ? Number(rawXValue) : 0,
         updateValue: xUpdateValue,
       },
       y: {
         name: yName,
-        value: rawYValue != null ? Number(rawYValue) : null,
+        value: rawYValue != null ? Number(rawYValue) : 0,
         updateValue: yUpdateValue,
       },
     }
@@ -206,7 +206,7 @@ export function PositionField(props: PositionFieldProps): JSX.Element {
           <StyledText desktopStyle="bodyDefaultRegular" color={COLORS.grey60}>
             {i18n.format(
               t('protocol_steps:tip_position', {
-                prefix: prefixMap[prefix],
+                prefix: MoveLiquidPrefixToAction[prefix],
               }),
               'capitalize'
             )}