feat: pass reason for closing to the emitted event

[JohnCampionJr]

Can we please get this? It's a pretty common use case at this point to not allow clicking outside the dialog to close it. I think @mgambill's suggestion is the best way to implement it with non-breaking API and no extra properties or anything needed.

What if we just pass information as part of the emit event then the user will have information to determine if they want to close or not. @adamwathan

api.close( reason ) // 'backdrop' | 'key' | 'trap' | 'other')

function onClose(e) {
   if (e.reason === 'backdrop') // update ref or not 
}

Originally posted by @mgambill in #1968 (comment)