Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Overlay #1084

Merged
merged 93 commits into from
Mar 30, 2021
Merged

Overlay #1084

merged 93 commits into from
Mar 30, 2021

Conversation

emplums
Copy link

@emplums emplums commented Feb 25, 2021

This PR adds the Overlay component 🎉

Closes #1061

Component description

An Overlay is a flexible floating surface, used to display transient content such as menus, selection options, dialogs, and more. Overlays use shadows to express elevation. The Overlay component handles all behaviors needed by overlay UIs as well as the common styles that all overlays should have. Overlay is the base component for many of our overlay-type components.

Behaviors

  • Rendering the overlay in a React Portal so that it always renders on top of other content on the page
  • Positioning the overlay according to passed in settings, using our context-aware positioning algorithms
  • Trapping focus (implemented in separate PR, will add to this component when it's ready, but this can ship as is for now)
  • Calling a user provided function when the user presses Escape
  • Calling a user provided function when the user clicks outside of the container
  • Focusing either an user provided element, or the first focusable element in the container when it is opened
  • Returning focus to an element when container is closed

Accessibility

Relevant items from #1117:

  • The element that serves as the dialog container has a role of dialog
  • All elements required to operate the dialog are descendants of the element that has role dialog.
  • The dialog container element has aria-modal set to true.
  • When a dialog opens, focus placement depends on the nature and size of the content.
    In all circumstances, focus moves to an element contained in the dialog.
    Unless a condition where doing otherwise is advisable, focus is initially set on the first focusable element.
  • Modal dialogs do not provide means for moving keyboard focus outside the dialog window without closing the dialog (Addressed in useFocusTrap which will be added to this component once it's done)
  • When a dialog closes, focus returns to the element that invoked the dialog unless either:
    • The invoking element no longer exists. Then, focus is set on another element that provides logical work flow.
    • The work flow design includes the following conditions that can occasionally make focusing a different element a more logical choice
  • Focus is trapped inside of the dialog
  • It is strongly recommended that the tab sequence of all dialogs include a visible element with role button that closes the dialog, such as a close icon or cancel button. (Will be addressed in follow up PR adding the Overlay.Header component)
  • Content under a modal dialog are inert, users cannot interact with content outside of an active dialog window (Addressed in useFocusTrap)

Addressed in documentation

  • Optionally, the aria-describedby property is set on the element with the dialog role to indicate which element or elements in the dialog contain content that describes the primary purpose or message of the dialog. Specifying descriptive elements enables screen readers to announce the description along with the dialog title and initially focused element when the dialog opens.
  • The dialog has either:
    • A value set for the aria-labelledby property that refers to a visible dialog title.
    • A label specified by aria-label.

Notes

  • I'm going to add Overlay.Header and Overlay.Footer in a separate PR
  • Mobile variations need more API thinking, and is not a priority for this quarter so skipping for now
  • Since the behaviors included in this PR are pretty simple, I opted not to write additional JS only behaviors to support them I actually did this first with the useOpenAndCloseFocus Hook, but when I was ready to make a PR it felt a little silly since it was basically just focusing an item passed in.

@vercel
Copy link

vercel bot commented Feb 25, 2021

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/primer/primer-components/DuivWJCwQCYcfsysR73vHvDq4Ku7
✅ Preview: https://primer-components-git-overlay-primer.vercel.app

@vercel vercel bot temporarily deployed to Preview February 25, 2021 17:52 Inactive
@vercel vercel bot temporarily deployed to Preview February 25, 2021 20:18 Inactive
@vercel vercel bot temporarily deployed to Preview February 25, 2021 20:21 Inactive
@vercel vercel bot temporarily deployed to Preview February 25, 2021 20:52 Inactive
@vercel vercel bot temporarily deployed to Preview February 25, 2021 21:26 Inactive
@changeset-bot
Copy link

changeset-bot bot commented Mar 3, 2021

⚠️ No Changeset found

Latest commit: c368635

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

@vercel vercel bot temporarily deployed to Preview March 18, 2021 22:19 Inactive
docs/content/Overlay.mdx Outdated Show resolved Hide resolved
docs/content/Overlay.mdx Outdated Show resolved Hide resolved
Co-authored-by: Inayaili León <[email protected]>
@vercel vercel bot temporarily deployed to Preview March 25, 2021 17:27 Inactive
Co-authored-by: Inayaili León <[email protected]>
* An `Overlay` is a flexible floating surface, used to display transient content such as menus,
* selection options, dialogs, and more. Overlays use shadows to express elevation. The `Overlay`
* component handles all behaviors needed by overlay UIs as well as the common styles that all overlays * should have.
* @param positionSettings Settings for calculating the anchored position.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prop docs below (e.g. ignoreClickRefs and anchorRef) are explicitly marked Optional/Required. Can we add that to positionSettings (and positionDeps, width, and height)?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suggested some changes on @T-Hugs PR #1132 to address this

@vercel vercel bot temporarily deployed to Preview March 25, 2021 17:31 Inactive
@smockle smockle mentioned this pull request Mar 29, 2021
7 tasks
src/hooks/useOverlay.tsx Outdated Show resolved Hide resolved
src/Overlay.tsx Outdated Show resolved Hide resolved
index.d.ts Outdated Show resolved Hide resolved
@vercel vercel bot temporarily deployed to Preview March 30, 2021 17:52 Inactive
@vercel vercel bot temporarily deployed to Preview March 30, 2021 18:33 Inactive
@emplums
Copy link
Author

emplums commented Mar 30, 2021

I think this is finally ready to go 🚀 I'll address the animation issues when I create the Popover component.

@vercel vercel bot temporarily deployed to Preview March 30, 2021 18:47 Inactive
@emplums
Copy link
Author

emplums commented Mar 30, 2021

skipping the changelog, let's do that when we are ready to make components publicly available.

Copy link
Contributor

@vdepizzol vdepizzol left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✨ ✨ ✨

@emplums emplums merged commit f970ada into main Mar 30, 2021
@emplums emplums deleted the overlay branch March 30, 2021 20:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Overlay
5 participants