Improve FocusTrap behaviour (#1432)

* refactor `VisuallyHidden` to `Hidden` component

This new component will also make sure that it is visually hidden to
sighted users. However, it contains a few more features that are going
to be useful in other places as well. These features include:

1. Make visually hidden to sighted users (default)
2. Hide from assistive technology via `features={Features.Hidden}`
   (will add `display: none;`)
3. Hide from assistive technology but make the element focusable via
   `features={Features.Focusable}` (will add `aria-hidden="true"`)

* add `useEvent` hook

This will behave the same (roughly) as the new to be released `useEvent`
hook in React 18.X

This hook allows you to have a stable function that can "see" the latest
data it is using. We already had this concept using:

```js
let handleX = useLatestValue(() => {
  // ...
})
```

But this returned a stable ref so you had to call `handleX.current()`.
This new hook is a bit nicer to work with but doesn't change much in the
end.

* add `useTabDirection` hook

This keeps track of the direction people are tabbing in. This returns a
ref so no re-renders happen because of this hook.

* add `useWatch` hook

This is similar to the `useEffect` hook, but only executes if values are
_actually_ changing... 😒

* add `microTask` util

* refactor `useFocusTrap` hook to `FocusTrap` component

Using a component directly allows us to simplify the focus trap logic
itself. Instead of intercepting the <kbd>Tab</kbd> keydown event and
figuring out the correct element to focus, we will now add 2 "guard"
buttons (hence why we require a component now). These buttons will
receive focus and if they do, redirect the focus to the first/last
element inside the focus trap.

The sweet part is that all the tabs in between those buttons will now be
handled natively by the browser. No need to find the first non disabled,
non hidden with correct tabIndex element!

* refactor the `Dialog` component to use the `FocusTrap` component

Also added a hidden button so that we know the correct "main" tree of
the application. Before this we were assuming the previous active
element which will still be correct in most cases but we don't have
access to that anymore since the logic is encapsulated inside the
FocusTrap component.

* ensure `<Portal />` properly cleans up

We make sure that the Portal is cleaning up its `element` properly.
We also make sure to call the `target.appendChild(element)`
conditionally because I ran into a super annoying bug where a focused
element got blurred because I believe that this re-mounts the element
instead of 'moving' it or just ignoring it, if it already is in the
correct spot.

* refactor: use `useEvent` instead of `useLatestValue`

Not really necessary, just cleaner.

* update changelog

Author: RobinMalfait

CHANGELOG.md

@@ -11,13 +11,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Ensure `DialogPanel` exposes its ref ([#1404](https://github.com/tailwindlabs/headlessui/pull/1404))
 - Ignore `Escape` when event got prevented in `Dialog` component ([#1424](https://github.com/tailwindlabs/headlessui/pull/1424))
+- Improve `FocusTrap` behaviour ([#1432](https://github.com/tailwindlabs/headlessui/pull/1432))
 
 ## [Unreleased - @headlessui/react]
 
 ### Fixed
 
 - Fix closing of `Popover.Panel` in React 18 ([#1409](https://github.com/tailwindlabs/headlessui/pull/1409))
 - Ignore `Escape` when event got prevented in `Dialog` component ([#1424](https://github.com/tailwindlabs/headlessui/pull/1424))
+- Improve `FocusTrap` behaviour ([#1432](https://github.com/tailwindlabs/headlessui/pull/1432))
 
 ## [@headlessui/react@1.6.1] - 2022-05-03
 

packages/@headlessui-react/src/components/combobox/combobox.tsx

@@ -36,7 +36,7 @@ import { useResolveButtonType } from '../../hooks/use-resolve-button-type'
 import { useLatestValue } from '../../hooks/use-latest-value'
 import { useTreeWalker } from '../../hooks/use-tree-walker'
 import { sortByDomNode } from '../../utils/focus-management'
-import { VisuallyHidden } from '../../internal/visually-hidden'
+import { Hidden, Features as HiddenFeatures } from '../../internal/hidden'
 import { objectToFormEntries } from '../../utils/form'
 
 enum ComboboxStates {
@@ -565,7 +565,8 @@ let ComboboxRoot = forwardRefWithAs(function Combobox<
             {name != null &&
               value != null &&
               objectToFormEntries({ [name]: value }).map(([name, value]) => (
-                <VisuallyHidden
+                <Hidden
+                  features={HiddenFeatures.Hidden}
                   {...compact({
                     key: name,
                     as: 'input',

packages/@headlessui-react/src/components/dialog/dialog.tsx

@@ -25,7 +25,7 @@ import { useSyncRefs } from '../../hooks/use-sync-refs'
 import { Keys } from '../keyboard'
 import { isDisabledReactIssue7711 } from '../../utils/bugs'
 import { useId } from '../../hooks/use-id'
-import { useFocusTrap, Features as FocusTrapFeatures } from '../../hooks/use-focus-trap'
+import { FocusTrap } from '../../components/focus-trap/focus-trap'
 import { useInertOthers } from '../../hooks/use-inert-others'
 import { Portal } from '../../components/portal/portal'
 import { ForcePortalRoot } from '../../internal/portal-force-root'
@@ -37,6 +37,7 @@ import { useOutsideClick, Features as OutsideClickFeatures } from '../../hooks/u
 import { getOwnerDocument } from '../../utils/owner'
 import { useOwnerDocument } from '../../hooks/use-owner'
 import { useEventListener } from '../../hooks/use-event-listener'
+import { Hidden, Features as HiddenFeatures } from '../../internal/hidden'
 
 enum DialogStates {
   Open,
@@ -137,6 +138,9 @@ let DialogRoot = forwardRefWithAs(function Dialog<
   let internalDialogRef = useRef<HTMLDivElement | null>(null)
   let dialogRef = useSyncRefs(internalDialogRef, ref)
 
+  // Reference to a node in the "main" tree, not in the portalled Dialog tree.
+  let mainTreeNode = useRef<HTMLDivElement | null>(null)
+
   let ownerDocument = useOwnerDocument(internalDialogRef)
 
   // Validations
@@ -196,26 +200,17 @@ let DialogRoot = forwardRefWithAs(function Dialog<
   // in between. We only care abou whether you are the top most one or not.
   let position = !hasNestedDialogs ? 'leaf' : 'parent'
 
-  let previousElement = useFocusTrap(
-    internalDialogRef,
-    enabled
-      ? match(position, {
-          parent: FocusTrapFeatures.RestoreFocus,
-          leaf: FocusTrapFeatures.All & ~FocusTrapFeatures.FocusLock,
-        })
-      : FocusTrapFeatures.None,
-    { initialFocus, containers }
-  )
+  // Ensure other elements can't be interacted with
   useInertOthers(internalDialogRef, hasNestedDialogs ? enabled : false)
 
-  // Handle outside click
+  // Close Dialog on outside click
   useOutsideClick(
     () => {
       // Third party roots
       let rootContainers = Array.from(ownerDocument?.querySelectorAll('body > *') ?? []).filter(
         (container) => {
           if (!(container instanceof HTMLElement)) return false // Skip non-HTMLElements
-          if (container.contains(previousElement.current)) return false // Skip if it is the main app
+          if (container.contains(mainTreeNode.current)) return false // Skip if it is the main app
           if (state.panelRef.current && container.contains(state.panelRef.current)) return false
           return true // Keep
         }
@@ -345,21 +340,35 @@ let DialogRoot = forwardRefWithAs(function Dialog<
             <Portal.Group target={internalDialogRef}>
               <ForcePortalRoot force={false}>
                 <DescriptionProvider slot={slot} name="Dialog.Description">
-                  {render({
-                    ourProps,
-                    theirProps,
-                    slot,
-                    defaultTag: DEFAULT_DIALOG_TAG,
-                    features: DialogRenderFeatures,
-                    visible: dialogState === DialogStates.Open,
-                    name: 'Dialog',
-                  })}
+                  <FocusTrap
+                    initialFocus={initialFocus}
+                    containers={containers}
+                    features={
+                      enabled
+                        ? match(position, {
+                            parent: FocusTrap.features.RestoreFocus,
+                            leaf: FocusTrap.features.All & ~FocusTrap.features.FocusLock,
+                          })
+                        : FocusTrap.features.None
+                    }
+                  >
+                    {render({
+                      ourProps,
+                      theirProps,
+                      slot,
+                      defaultTag: DEFAULT_DIALOG_TAG,
+                      features: DialogRenderFeatures,
+                      visible: dialogState === DialogStates.Open,
+                      name: 'Dialog',
+                    })}
+                  </FocusTrap>
                 </DescriptionProvider>
               </ForcePortalRoot>
             </Portal.Group>
           </DialogContext.Provider>
         </Portal>
       </ForcePortalRoot>
+      <Hidden features={HiddenFeatures.Hidden} ref={mainTreeNode} />
     </StackProvider>
   )
 })