feat(app) add third step to blowout (#18760)

* feat(app) add third step to blowout

Author: koji

app/src/assets/localization/en/quick_transfer.json

@@ -31,6 +31,7 @@
   "blow_out_into_trash_bin": "into trash bin",
   "blow_out_into_waste_chute": "into waste chute",
   "blow_out_source_well": "Source well",
+  "blow_out_speed": "Blowout speed (µL/second)",
   "blow_out_trash_bin": "Trash bin",
   "blow_out_waste_chute": "Waste chute",
   "blow_out": "Blowout",

app/src/organisms/ODD/QuickTransferFlow/Dispense/hooks/useDispenseSettingsConfig.ts

@@ -31,18 +31,21 @@ export function useDispenseSettingsConfig({
   const { makeSnackbar } = useToaster()
 
   const getBlowoutValueCopy = (): string | undefined => {
-    if (state.blowOut === 'dest_well') {
+    if (state.blowOutDispense?.location === 'dest_well') {
       return t('blow_out_into_destination_well')
-    } else if (state.blowOut === 'source_well') {
+    } else if (state.blowOutDispense?.location === 'source_well') {
       return t('blow_out_into_source_well')
     } else if (
-      state.blowOut != null &&
-      state.blowOut.cutoutFixtureId === TRASH_BIN_ADAPTER_FIXTURE
+      state.blowOutDispense?.location != null &&
+      state.blowOutDispense.location.cutoutFixtureId ===
+        TRASH_BIN_ADAPTER_FIXTURE
     ) {
       return t('blow_out_into_trash_bin')
     } else if (
-      state.blowOut != null &&
-      WASTE_CHUTE_FIXTURES.includes(state.blowOut.cutoutFixtureId)
+      state.blowOutDispense?.location != null &&
+      WASTE_CHUTE_FIXTURES.includes(
+        state.blowOutDispense.location.cutoutFixtureId
+      )
     ) {
       return t('blow_out_into_waste_chute')
     }

app/src/organisms/ODD/QuickTransferFlow/QuickTransferAdvancedSettings/BlowOut.tsx

@@ -1,34 +1,49 @@
-import { useState } from 'react'
+import { useRef, useState } from 'react'
 import { createPortal } from 'react-dom'
 import { useTranslation } from 'react-i18next'
 import isEqual from 'lodash/isEqual'
 
 import {
+  ALIGN_CENTER,
   COLORS,
   DIRECTION_COLUMN,
   Flex,
+  InputField,
   POSITION_FIXED,
   RadioButton,
   SPACING,
   StyledText,
 } from '@opentrons/components'
 import {
+  ETHANOL_LIQUID_CLASS_NAME,
   FLEX_SINGLE_SLOT_BY_CUTOUT_ID,
+  getAllLiquidClassDefs,
+  getFlexNameConversion,
+  getTipTypeFromTipRackDefinition,
+  GLYCEROL_LIQUID_CLASS_NAME,
+  linearInterpolate,
+  LOW_VOLUME_PIPETTES,
+  NONE_LIQUID_CLASS_NAME,
   TRASH_BIN_ADAPTER_FIXTURE,
   WASTE_CHUTE_FIXTURES,
+  WATER_LIQUID_CLASS_NAME,
 } from '@opentrons/shared-data'
+import { getTransferPlanAndReferenceVolumes } from '@opentrons/step-generation'
 
 import { getTopPortalEl } from '/app/App/portal'
+import { NumericalKeyboard } from '/app/atoms/SoftwareKeyboard'
 import { i18n } from '/app/i18n'
 import { ChildNavigation } from '/app/organisms/ODD/ChildNavigation'
 import { useTrackEventWithRobotSerial } from '/app/redux-resources/analytics'
 import { ANALYTICS_QUICK_TRANSFER_SETTING_SAVED } from '/app/redux/analytics'
 import { useNotifyDeckConfigurationQuery } from '/app/resources/deck_configuration'
 
 import { ACTIONS } from '../constants'
+import { getMaxUiFlowRate, getPipetteName } from '../utils'
+import { getExtractTiprackTypeFromURI } from '../utils/getExtractTiprackTypeFromURI'
 
 import type { Dispatch } from 'react'
-import type { DeckConfiguration } from '@opentrons/shared-data'
+import type { DeckConfiguration, SupportedTip } from '@opentrons/shared-data'
 import type {
   BlowOutLocation,
   FlowRateKind,
@@ -101,27 +116,31 @@ export function BlowOut(props: BlowOutProps): JSX.Element {
   const { trackEventWithRobotSerial } = useTrackEventWithRobotSerial()
   const deckConfig = useNotifyDeckConfigurationQuery().data ?? []
 
-  const [isBlowOutEnabled, setisBlowOutEnabled] = useState<boolean>(
-    state.blowOut != null
+  const keyboardRef = useRef(null)
+  const [isBlowOutEnabled, setIsBlowOutEnabled] = useState<boolean>(
+    state.blowOutDispense != null
   )
   const [currentStep, setCurrentStep] = useState<number>(1)
   const [blowOutLocation, setBlowOutLocation] = useState<
     BlowOutLocation | undefined
-  >(state.blowOut)
+  >(state.blowOutDispense?.location as BlowOutLocation | undefined)
+  const [speed, setSpeed] = useState<number | null>(
+    (state.blowOutDispense?.flowRate as number) ?? null
+  )
 
   const enableBlowOutDisplayItems = [
     {
       option: true,
       description: t('option_enabled'),
       onClick: () => {
-        setisBlowOutEnabled(true)
+        setIsBlowOutEnabled(true)
       },
     },
     {
       option: false,
       description: t('option_disabled'),
       onClick: () => {
-        setisBlowOutEnabled(false)
+        setIsBlowOutEnabled(false)
       },
     },
   ]
@@ -140,7 +159,10 @@ export function BlowOut(props: BlowOutProps): JSX.Element {
       if (!isBlowOutEnabled) {
         dispatch({
           type: ACTIONS.SET_BLOW_OUT,
-          location: undefined,
+          blowOutSettings: {
+            location: undefined,
+            flowRate: 0,
+          },
         })
         trackEventWithRobotSerial({
           name: ANALYTICS_QUICK_TRANSFER_SETTING_SAVED,
@@ -152,10 +174,17 @@ export function BlowOut(props: BlowOutProps): JSX.Element {
       } else {
         setCurrentStep(currentStep + 1)
       }
+    } else if (currentStep === 2) {
+      if (blowOutLocation != null) {
+        setCurrentStep(currentStep + 1)
+      }
     } else {
       dispatch({
         type: ACTIONS.SET_BLOW_OUT,
-        location: blowOutLocation,
+        blowOutSettings: {
+          location: blowOutLocation,
+          flowRate: speed ?? 1,
+        },
       })
       trackEventWithRobotSerial({
         name: ANALYTICS_QUICK_TRANSFER_SETTING_SAVED,
@@ -168,15 +197,121 @@ export function BlowOut(props: BlowOutProps): JSX.Element {
   }
 
   const saveOrContinueButtonText =
-    isBlowOutEnabled && currentStep < 2
+    isBlowOutEnabled && currentStep < 3
       ? t('shared:continue')
       : t('shared:save')
 
   let buttonIsDisabled = false
-  if (currentStep === 2) {
+  if (currentStep === 3) {
     buttonIsDisabled = blowOutLocation == null
   }
 
+  const pipetteName = getPipetteName(state.pipette)
+  const liquidSpecs = state.pipette.liquids
+  const tipType = getTipTypeFromTipRackDefinition(state.tipRack)
+  const flowRatesForSupportedTip: SupportedTip | undefined =
+    state.volume < 5 &&
+    `lowVolumeDefault` in liquidSpecs &&
+    LOW_VOLUME_PIPETTES.includes(pipetteName as string)
+      ? liquidSpecs.lowVolumeDefault.supportedTips[tipType]
+      : liquidSpecs.default.supportedTips[tipType]
+
+  const allLiquidClassDefs = getAllLiquidClassDefs()
+  const liquidClassMap = new Map<string, string>([
+    ['none', NONE_LIQUID_CLASS_NAME],
+    ['water', WATER_LIQUID_CLASS_NAME],
+    ['glycerol_50', GLYCEROL_LIQUID_CLASS_NAME],
+    ['ethanol_80', ETHANOL_LIQUID_CLASS_NAME],
+  ])
+
+  const selectedLiquidClass = liquidClassMap.get(
+    state.liquidClass?.liquidClassName ?? 'none'
+  )
+  const liquidClassDef =
+    allLiquidClassDefs[selectedLiquidClass ?? NONE_LIQUID_CLASS_NAME]
+  const convertedPipetteName =
+    state.pipette != null ? getFlexNameConversion(state.pipette) : null
+
+  const minFlowRate = 1
+  const { loadName: currentTiprackLoadName } = state.tipRack.parameters
+
+  const tipTypeSettings = liquidClassDef?.byPipette
+    ?.find(({ pipetteModel }) => convertedPipetteName === pipetteModel)
+    ?.byTipType.find(tipObject => {
+      const tiprackLoadName = tipObject.tiprack.split('/')[1]
+      return tiprackLoadName === currentTiprackLoadName
+    })
+
+  const correctionByVolume = tipTypeSettings?.singleDispense?.correctionByVolume
+  const retract = tipTypeSettings?.singleDispense?.retract
+
+  const referenceVolumesForByVolumeInterpolation = getTransferPlanAndReferenceVolumes(
+    {
+      pipetteSpecs: state.pipette,
+      volume: state.volume,
+      tiprackDefinition: state.tipRack,
+      path: state.path,
+      numDispenseWells: state.destinationWells.length,
+      aspirateAirGapByVolume:
+        (retract?.airGapByVolume as Array<[number, number]>) ?? null,
+      conditioningByVolume:
+        (correctionByVolume as Array<[number, number]>) ?? null,
+      disposalByVolume: null, // note always null because blowout is available only for single dispense
+    }
+  )
+
+  const [referenceVolumeFlowRate, referenceVolumeCorrection] = [
+    referenceVolumesForByVolumeInterpolation.referenceVolumes?.flowRate
+      .dispense,
+    referenceVolumesForByVolumeInterpolation.referenceVolumes?.correction
+      .dispense,
+  ]
+
+  const liquidClassValuesForPipette = liquidClassDef?.byPipette?.find(
+    ({ pipetteModel }) => convertedPipetteName === pipetteModel
+  )
+  const liquidClassValuesForTip = getExtractTiprackTypeFromURI(
+    liquidClassValuesForPipette,
+    currentTiprackLoadName
+  )
+
+  const correctionVolume =
+    referenceVolumeCorrection != null &&
+    (liquidClassValuesForTip?.singleDispense?.correctionByVolume?.length ?? 0) >
+      0
+      ? linearInterpolate(
+          referenceVolumeCorrection,
+          liquidClassValuesForTip?.singleDispense?.correctionByVolume as Array<
+            [number, number]
+          >
+        )
+      : 0
+
+  const maxFlowRate = getMaxUiFlowRate({
+    targetVolume: referenceVolumeFlowRate,
+    channels: state.pipette.channels,
+    tipLiquidSpecs: flowRatesForSupportedTip,
+    flowRateType: 'blowout',
+    correctionVolume: correctionVolume ?? 0,
+    shaftULperMM: state.pipette.shaftULperMM,
+  })
+
+  const speedError =
+    speed != null && (speed < minFlowRate || speed > maxFlowRate)
+      ? t(`value_out_of_range`, {
+          min: minFlowRate,
+          max: maxFlowRate,
+        })
+      : null
+
+  const handleFlowRateChange = (userInput: string): void => {
+    if (userInput === '') {
+      setSpeed(null)
+    }
+    const parsedFlowRate = parseInt(userInput)
+    setSpeed(!isNaN(parsedFlowRate) ? parsedFlowRate : null)
+  }
+
   return createPortal(
     <Flex position={POSITION_FIXED} backgroundColor={COLORS.white} width="100%">
       <ChildNavigation
@@ -244,6 +379,47 @@ export function BlowOut(props: BlowOutProps): JSX.Element {
           </Flex>
         </Flex>
       ) : null}
+      {currentStep === 3 ? (
+        <Flex
+          alignSelf={ALIGN_CENTER}
+          gridGap={SPACING.spacing48}
+          paddingX={SPACING.spacing40}
+          padding={`${SPACING.spacing16} ${SPACING.spacing40} ${SPACING.spacing40}`}
+          marginTop="7.75rem" // using margin rather than justify due to content moving with error message
+          alignItems={ALIGN_CENTER}
+          height="22rem"
+        >
+          <Flex
+            width="30.5rem"
+            height="100%"
+            gridGap={SPACING.spacing24}
+            flexDirection={DIRECTION_COLUMN}
+            marginTop={SPACING.spacing68}
+          >
+            <InputField
+              type="text"
+              value={String(speed ?? '')}
+              title={t('blow_out_speed')}
+              error={speedError}
+              readOnly
+            />
+          </Flex>
+          <Flex
+            paddingX={SPACING.spacing24}
+            height="21.25rem"
+            marginTop="7.75rem"
+            borderRadius="0"
+          >
+            <NumericalKeyboard
+              keyboardRef={keyboardRef}
+              initialValue={String(speed ?? '')}
+              onChange={e => {
+                handleFlowRateChange(e)
+              }}
+            />
+          </Flex>
+        </Flex>
+      ) : null}
     </Flex>,
     getTopPortalEl()
   )

app/src/organisms/ODD/QuickTransferFlow/QuickTransferAdvancedSettings/DisposalVolume.tsx

@@ -30,6 +30,7 @@ import { ANALYTICS_QUICK_TRANSFER_SETTING_SAVED } from '/app/redux/analytics'
 import { useNotifyDeckConfigurationQuery } from '/app/resources/deck_configuration'
 
 import { ACTIONS } from '../constants'
+import { getPipetteName } from '../utils'
 
 import type { Dispatch } from 'react'
 import type { SupportedTip } from '@opentrons/shared-data'
@@ -55,20 +56,22 @@ export function DisposalVolume(props: DisposalVolumeProps): JSX.Element {
   const [currentStep, setCurrentStep] = useState<number>(1)
   const [volume, setVolume] = useState<number | null>(null)
 
-  const getInitialBlowoutLocation = (blowOut: typeof state.blowOut): string => {
-    if (blowOut == null) {
+  const getInitialBlowoutLocation = (
+    blowOut: typeof state.blowOutDispense
+  ): string => {
+    if (blowOut?.location == null) {
       return ''
     }
-    if (typeof blowOut === 'string') {
-      return blowOut
+    if (typeof blowOut.location === 'string') {
+      return blowOut.location
     }
-    return `trashBin:${blowOut.cutoutId}`
+    return `trashBin:${blowOut.location.cutoutId}`
   }
 
   const [
     selectedBlowoutLocation,
     setSelectedBlowoutLocation,
-  ] = useState<string>(getInitialBlowoutLocation(state.blowOut))
+  ] = useState<string>(getInitialBlowoutLocation(state.blowOutDispense))
   const [flowRate, setFlowRate] = useState<number | null>(null)
   const deckConfig = useNotifyDeckConfigurationQuery().data ?? []
   const fixtureLocationOptions = deckConfig.filter(
@@ -106,15 +109,7 @@ export function DisposalVolume(props: DisposalVolumeProps): JSX.Element {
     },
   ]
 
-  let pipetteName = state.pipette.model
-  if (state.pipette.channels === 1) {
-    pipetteName = pipetteName + `_single_flex`
-  } else if (state.pipette.channels === 8) {
-    pipetteName = pipetteName + `_multi_flex`
-  } else {
-    pipetteName = pipetteName + `_96`
-  }
-
+  const pipetteName = getPipetteName(state.pipette)
   const liquidSpecs = state.pipette.liquids
   const tipType = getTipTypeFromTipRackDefinition(state.tipRack)
   const flowRatesForSupportedTip: SupportedTip | undefined =

app/src/organisms/ODD/QuickTransferFlow/QuickTransferAdvancedSettings/PipettePath.tsx

@@ -50,7 +50,7 @@ export function PipettePath(props: PipettePathProps): JSX.Element {
   const [currentStep, setCurrentStep] = useState<number>(1)
   const [blowOutLocation, setBlowOutLocation] = useState<
     BlowOutLocation | undefined
-  >(state.blowOut)
+  >(state.blowOutDispense?.location)
 
   const [disposalVolume, setDisposalVolume] = useState<number | undefined>(
     state?.disposalVolume