Consolidate and simplify the modal API

[connor-baer]

Addresses DS-162.

Purpose

Circuit UI Web currently exports a number of modal-related components. Not all of these should be publicly exposed.

• Modal — This component wraps react-modal to apply custom styles and add tracking. It is not accessible when used by itself and thus should be removed from the exports.
• ModalWrapper, ModalHeader, ModalFooter — These are thin wrappers around the card components. Since the card and modal styles have diverged, these should be turned into standalone styled components. The motivation behind exporting these components separately was to ensure that they are only included in the bundle when used. The performance benefit is negligible though. The resulting API is less than ideal: it requires users to know about these components and to use them in a particular order. This goes against Circuit UI’s principle to help users fall into the pit of success. I propose to make these components internal-only and integrate them into the Modal component.
• ModalContext, ModalProvider, ModalConsumer — Of these, only the ModalProvider should be exposed, the others should remain implementation details/be wrapped in better APIs (e.g. useModal). The ModalProvider keeps track of the open modals (we need to add support for multiple, stacked modals), prevents scrolling of the page when a modal is open, sets the app element and renders it, and takes care of any other global logic.
• useModal — This hook should be the only API to render modals going forward. It hooks into the ModalContext and returns methods to open and close a modal. The current API is fine.

Approach and changes

• Removed the exports of the Modal, ModalWrapper, ModalHeader, ModalFooter, ModalContext, and ModalConsumer components
• Added a useStack hook to support multiple, stacked modals (this can be reused by the NotificationToast component)
• Added a factory function to generate useModal hooks to render different types of modals (such as the upcoming NotificationModal Add notification modal #994)
• Moved global side-effects from the Modal to the ModalProvider so they are applied consistently and only once

Definition of done

• Development completed
• Reviewers assigned
• Unit and integration tests
• Meets minimum browser support
• Meets accessibility requirements

[changeset-bot]

🦋 Changeset detected

Latest commit: 00e30a1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@sumup/circuit-ui	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/sumup/oss-circuit-ui/A1qRoirkF8aN3CbD6CTNqg6Vy7CS
✅ Preview: https://oss-circuit-ui-git-feature-ds-162modal-sumup.vercel.app

[robinmetral]

Wow! 🤩

Just added a few initial comments as I went through the code. It looks good generally, I like that this will be streamlining how we use modals and ensure accessibility 🙌

[codecov]

Codecov Report

Merging #949 (00e30a1) into next (bd23429) will increase coverage by 0.13%.
The diff coverage is 94.17%.

@@            Coverage Diff             @@
##             next     #949      +/-   ##
==========================================
+ Coverage   90.68%   90.81%   +0.13%     
==========================================
  Files         162      160       -2     
  Lines        2610     2647      +37     
  Branches      749      766      +17     
==========================================
+ Hits         2367     2404      +37     
  Misses        218      218              
  Partials       25       25              

Impacted Files	Coverage Δ
...ackages/circuit-ui/components/Carousel/Carousel.js	100.00% <ø> (ø)
...ckages/circuit-ui/components/Checkbox/Checkbox.tsx	100.00% <ø> (ø)
packages/circuit-ui/components/Modal/useModal.ts	0.00% <0.00%> (ø)
packages/circuit-ui/components/Popover/Popover.tsx	93.33% <ø> (ø)
.../circuit-ui/components/RadioButton/RadioButton.tsx	100.00% <ø> (ø)
packages/circuit-ui/components/Select/Select.tsx	97.91% <ø> (ø)
...ckages/circuit-ui/components/Selector/Selector.tsx	100.00% <ø> (ø)
packages/circuit-ui/components/Sidebar/Sidebar.js	100.00% <ø> (ø)
...nents/Sidebar/components/Aggregator/Aggregator.tsx	100.00% <ø> (ø)
...i/components/Sidebar/components/NavItem/NavItem.js	100.00% <ø> (ø)
... and 15 more

[robinmetral]

Amazing! Just a few tiny comments 🙂

[robinmetral]

Love it this way! And it's such an incredible improvement ❤️

I'm super sorry about the merge conflicts, and happy to handle them if you'd like.