[WNMGDS-2555] Add isOpen to Drawer and Dialog to fix focus-management issue

[pwolfert]

Summary

What I think has been happening is that React removes the Dialog and Drawer from the DOM before the browser has a chance to fully execute its close cycle and transfer focus to the element that had focus before the <dialog> underlying was opened. By always having the Dialog or Drawer (internally NativeDialog) rendered by its parent element and passing an isOpen prop to control its state, the browser is able to successfully transfer focus back to the right place after the dialog is closed.

For temporary backwards compatibility during a deprecation period, you can still conditionally render the dialog, and it will behave as it did before, but it will warn you that you need a isOpen prop. This is slated to go out in v9, so we'll fully deprecate the old behavior in v10.

I was curious if other React libraries conditionally rendered or used a boolean prop for toggling state. What I found was that Carbon, Ant, Forma 36, Helsinki, Polaris, and Primer use a boolean prop instead of conditionally rendering the modal to show and hide it. Gestalt uses conditional rendering, but their focus doesn't automatically return to the triggering button. The react-aria library uses modal trigger components like we were originally thinking we'd have to do (kind of an ugly solution to all this that would require more work for teams). All that to say, we're not weird for adopting this pattern.

• Added isOpen prop to Dialog and Drawer

How to test

Use yarn storybook:react to reproduce the original problem, which only happens in React. If you open a dialog or drawer and then close it, focus won't move back to the button that opened it.

How to migrate code

Previously applications would need to conditionally render dialogs and drawers like this:

const [isOpen, setIsOpen] = useState(false);
return (
  <>
    <Button onClick={() => setIsOpen(true)}>Open dialog</Button>
    {isOpen && <Dialog />}
  </>
);

With the new API, you always render the dialog or drawer, but the condition (a boolean) goes in the isOpen prop like this:

const [isOpen, setIsOpen] = useState(false);
return (
  <>
    <Button onClick={() => setIsOpen(true)}>Open dialog</Button>
    <Dialog isOpen={isOpen} />
  </>
);

Please note that if you had code effects that ran when the dialog rendered, you'll need to address any possible assumptions that rendering the dialog is the same as the dialog being open. For instance, if you previously called an external API to fetch information whenever your dialog was first rendered, you might see that API call happening when the page loads instead of waiting until the dialog is open. In those cases, you probably want to start looking at the isOpen prop before deciding to call your API.

Checklist

• Prefixed the PR title with the Jira ticket number as [WNMGDS-####] Title or [NO-TICKET] if this is unticketed work.
• Selected appropriate Type (only one) label for this PR, if it is a breaking change, label should only be Type: Breaking
• Selected appropriate Impacts, multiple can be selected.
• Selected appropriate release milestone

If this is a change to code:

• Created or updated unit tests to cover any new or modified code
• If necessary, updated unit-test snapshots (yarn test:unit:update) and browser-test snapshots (yarn test:browser:update)

[pwolfert]

Making the state dependent on the value of isOpen instead of following when it's mounted and unmounted, it meant that it was no longer as simple as a use effect and cleanup. Because I no longer had direct access to the y value created in the top of the use effect in a closure, I had to start tracking that state separately. I didn't love that, so you'll notice that I ended up moving this all into a separate module and used a reducer, which I ended up trying to model as a finite state machine. It might be a little more code than is needed, but I feel more confident in it being a finite state machine, especially since I've been able to leverage TypeScript to help make sure my logic is correct.

[pwolfert]

This OPEN action requires a starting point of ClosedState and an ending point of OpenState.

[pwolfert]

Because some of this state comes from the DOM, it didn't lend itself as well to modeling as a finite state machine. I didn't want to duplicate that state and make it way more verbose. Don't @ me. Or do, because this is a review.

[pwolfert]

@zarahzachz, the tests are finally passing. This is ready for real review.