fix(ui-dialog,ui-a11y-utils): fix focus getting stuck in some cases if something is removed from the middle of the focus stack

The issue occured in the following conditions:
1.A non-keyboard focusable element is added to the top of the stack,e.g. an Overlay with just text
2.The keyboard focusable element is removed from the stack just below it.
In this caset the focus region stayesd the now removed element getting the focus stuck

Fixes INSTUI-4685

Author: matyasf

cypress/component/Focusable.cy.tsx

@@ -21,7 +21,7 @@
  * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  * SOFTWARE.
  */
-import React from 'react'
+
 import { Focusable } from '@instructure/ui'
 
 import '../support/component'

cypress/component/Tray.cy.tsx

@@ -22,7 +22,8 @@
  * SOFTWARE.
  */
 
-import { Tray } from '@instructure/ui'
+import { Button, Overlay, Text, Tray, View } from '@instructure/ui'
+import React from 'react'
 
 import '../support/component'
 import 'cypress-real-events'
@@ -66,4 +67,79 @@ describe('<Tray />', () => {
     cy.get('@tray').realPress('Escape')
     cy.wrap(onDismiss).should('have.been.called')
   })
+
+  it.only('should handle focus properly in complex cases', async () => {
+    const Example = () => {
+      const [showTray, setShowTray] = React.useState(false)
+      const [showOverlay, setShowOverlay] = React.useState(false)
+
+      const handleTrayButtonClick = () => {
+        setShowOverlay(true)
+        // hide the Tray after the Overlay is rendered.
+        // This means it's not on the top of the FocusRegion stack
+        setTimeout(() => {
+          setShowTray(false)
+        }, 30)
+      }
+
+      return (
+        <View textAlign="center">
+          <View as="div" maxWidth="600px" margin="0 auto">
+            <Text as="p" size="large">
+              Click the button below to open a tray. Then click the button
+              inside the tray to trigger an overlay that will automatically
+              close after a short time.
+            </Text>
+            <Button
+              color="primary"
+              size="large"
+              id="open_tray_button"
+              onClick={() => setShowTray(true)}
+            >
+              Open Tray
+            </Button>
+            <Button id="test1_button">test 1</Button>
+            <Button id="test2_button">test 2</Button>
+          </View>
+
+          <Tray label="Sample Tray" open={showTray} placement="end">
+            <Text as="p">
+              This is the Tray. Click the button below to show an overlay and
+              automatically close this tray after a short time.
+            </Text>
+            <Button
+              color="success"
+              id="close_tray_button"
+              onClick={handleTrayButtonClick}
+            >
+              Close after a short time
+            </Button>
+            <Button onClick={() => setShowTray(false)}>Cancel</Button>
+            <Button>test</Button>
+          </Tray>
+
+          <Overlay open={showOverlay} transition="fade" label="Loading overlay">
+            <Text size="large" color="success">
+              This is the overlay.
+            </Text>
+          </Overlay>
+        </View>
+      )
+    }
+
+    cy.mount(<Example />)
+
+    cy.get('#open_tray_button').click()
+    // Wait 500ms so the Tray CSS animation can finish
+    cy.wait(500)
+    // Click the close_tray_button. This should run the state changes in its handler
+    cy.get('#close_tray_button').click()
+    // Wait 500ms so the Tray CSS animation can finish
+    cy.wait(500)
+    cy.focused().should('have.attr', 'id', 'open_tray_button')
+    cy.realPress('Tab')
+    cy.focused().should('have.attr', 'id', 'test1_button')
+    cy.realPress('Tab')
+    cy.focused().should('have.attr', 'id', 'test2_button')
+  })
 })

packages/ui-a11y-utils/src/FocusRegion.ts

@@ -67,13 +67,15 @@ class FocusRegion {
       shouldCloseOnEscape: true,
       isTooltip: false
     }
+    this._id = uid()
+    // eslint-disable-next-line no-param-reassign
+    options.regionId = this._id
     this._contextElement = element
     this._screenReaderFocusRegion = new ScreenReaderFocusRegion(
       element,
       options
     )
     this._keyboardFocusRegion = new KeyboardFocusRegion(element, options)
-    this._id = uid()
   }
 
   updateElement(element: Element | Node, options?: FocusRegionOptions) {
@@ -211,17 +213,15 @@ class FocusRegion {
   }
 
   deactivate({ keyboard = true }: { keyboard?: boolean } = {}) {
-    if (this._active) {
-      this._listeners.forEach((listener) => {
-        listener.remove()
-      })
-      this._listeners = []
-      if (keyboard) {
-        this._keyboardFocusRegion.deactivate()
-      }
-      this._screenReaderFocusRegion.deactivate()
-      this._active = false
+    this._listeners.forEach((listener) => {
+      listener.remove()
+    })
+    this._listeners = []
+    if (keyboard) {
+      this._keyboardFocusRegion.deactivate()
     }
+    this._screenReaderFocusRegion.deactivate()
+    this._active = false
   }
 
   focus() {

packages/ui-a11y-utils/src/FocusRegionOptions.ts

@@ -86,4 +86,8 @@ export type FocusRegionOptions = {
    * Whether or not the element is a Tooltip
    */
   isTooltip?: boolean
+  /**
+   * The ID of the `FocusRegion` this belongs to. Used only for debugging.
+   */
+  regionId?: string
 }

packages/ui-dialog/src/Dialog/props.ts

@@ -136,7 +136,11 @@ const propTypes: PropValidators<PropKeys> = {
   /**
    * Whether or not the element is a Tooltip
    */
-  isTooltip: PropTypes.bool
+  isTooltip: PropTypes.bool,
+  /**
+   * The ID of the `FocusRegion` this belongs to. Used only for debugging.
+   */
+  regionId: PropTypes.string
 }
 
 const allowedProps: AllowedPropKeys = [