Overlay

[emplums]

Pre-requisite for #1065, #1064, and #1072

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, and may include a backdrop that dims the rest of the screen for focus.

Overlays can streamline the interface by allowing extra options to be displayed as the person needs them. Overlays present a new context to the user, and facilitate the completion of individual tasks.

Keep overlays simple. Avoid creating a whole page inside an overlay. Overlays are better suited for single-column, focused experiences that should perfectly transition from small smartphones to the largest screens.

Overlays are often used for data manipulation. It's important to ensure its interactions are quick and effective. For example, a search field should appear focused when opening an overlay with selection options.

Overlays can be fully interacted with a keyboard. Keyboard navigation should be limited to the elements of the active overlay. Pressing Escape should dismiss the overlay. When an overlay is dismissed, focus should usually return to the element that opened it.

Overlays can be dismissed by pressing the browser's Back button. This is particularly useful in mobile devices.

The Overlay component & its subcomponents are meant to be used mostly internally to build other composite components.

Resources

Figma:
Prototype:

Screenshot

Components

Overlay

Behaviors

• useOnEscapePress @emplums
• useOnOutsideClick @emplums
• useReturnFocus @emplums
• useFocusTrap @T-Hugs
• useInitialFocus @emplums
• Wrapped in Portal
• useAnchoredPosition @T-Hugs

Props

name: type
type: "popover" | "dialog"
description:

note: I'm not sure if it makes sense to have this as a prop on the overlay component, or handle this as an abstracted separate component such as Popover and Dialog??

---

name: mobileVariant
type: "none" | "bottomSheet" | "fullScreen"
description: what the component should transform to on smaller screens

Open questions: what breakpoint should this be kicking in at?

---

name: width:
type: auto | 256px | 320px | 480px | 640px
default: auto

Note: I'm checking in with Vini on this one, I'm not sure how this would work with styled system, we might need to name these. Also not sure if he wants to allow custom widths. I also don't think the default should be auto.

---

name: height
type: auto | 480px | 640px
default: auto

Note: same as above

---

name: role
type: "dialog" | "alertdialog"
default: dialog

---

name: aria-labelledby
type: string
description: Use this attribute to label the dialog. The value of the aria-labelledby attribute will be the id of the element used to title the dialog.

---

name: aria-describedby
type: string
description: Use this attribute to describe the contents of the dialog.

Overlay.Header

Description

An overlay header is a generic component placed at the top of an overlay. It introduces the overlay content with title, description, and general actions.

Screenshot

Props

name: backButton
type: boolean??

Notes: needs more info

---

name: leadingVisual
type: ?
description: An optional visual to accompany the header. Only use a leading visual such as an octicon in an overlay header when it helps reinforcing the context or the object being manipulated. For example, an overlay that manipulates labels may include the tag icon. Only use a leading visual of objects when the overlay is manipulating them. Don't use octicons for generic actions such as plus or pencil.

Notes: needs more info

---

name: leadingVisualArea
type: 16 | 20
description: How much space is reserved for the leading visual. You may want to place a 16px octicon in a 20px area to align with a list of avatars.

Note: we may want to rename the types to small and large instead of using numbers here?

---

name: title
type: string | React.ReactElement
description: A text container defining the title of the overlay.

---

name: description
type: string
description: An optional description or message under the title. Avoid using it if the title already provides an explanation to the overlay. Don't be verbose. If on a confirmationDialog, use description as the main place for the dialog's message. A description may be used for accessibility/ screen readers only

---

name: closeButton
type: boolean
description: whether to include a close button that dismisses the overlay

---

name: searchField
type: ??
description: ??

needs more info

---

name: size
type: "medium" | "large"
default: medium
description: large is meant to be used for confirmation dialogs

---

name: divider
type: boolean
default: false
description: Whether to display a divider in the bottom of the overlay header.

Overlay.Footer

Variants

• Binary actions
• Single call-to-action
• Custom buttons

[emplums]

@vdepizzol am I missing any behaviors?

[emplums]

Note: we need to support the ability to render children of at the bottom of the markup, this would allow people to pass in tabs if they wanted to, this functionality needs to get passed down to the internal consuming components

[emplums]

Notes - should we accept an open prop or let the consumer handle all open state management and conditionally show/hide the component like so:

    <>
      <Button onClick={() => setIsOpen(true)}>
        open overlay
      </Button>
      {isOpen && <Overlay width="sm"> content!!</Overlay>}
    </>