DialogRefactor.md

Dialog Components Refactor

The purpose of this document is to help define the components that comprise Instructure UI's dialog components. Dialog components typically render outside the context of the application and are the primary focal point when rendered.

This represents a refactor as specified by Jen Stern.

Building Blocks

These are the low-level components needed for dialogs.

Portal

Portal allows content to be declared inline but render to document.body outside the render tree.

Features

• Render outside current tree

document.body
+-------------------------+
| App                     |
| +---------------------+ |
| | div                 | |
| | +-----------------+ | |
| | | h1              | | |
| | | +-------------+ | | |
| | | | Hello World | | | |
| | | +-------------+ | | |
| | | Portal          | | |
| | | +-------------+ | | |
| | | | Foo Bar     | | | |
| | | +-------------+ | | |
| | +-----------------+ | |
| +---------------------+ |
| "Foo Bar"               |
+-------------------------+

Overlay

Overay is a utility component that renders it's content with an optional mask (grayed out background) behind it's content.

Features

• Transitions (optional)
• Background mask (optional)
• Click outside to close (optional)
• Click × to close (optional)
• Press Esc to close (optional)
• Trap focus (optional)
• Trap Tab press (optional)

Portal
+---------------+
| Transition    |
| +-----------+ |
| | {content} | |
| +-----------+ |
+---------------+

Position

Position is a utility component that renders a target element with it's content positioned adjacent.

Features

• Position content adjacent to a target

span
+---------------+
| {target}      |
| Overlay       |
| +-----------+ |
| | {content} | |
| +-----------+ |
+---------------+

Popover

Popover is a utility component that render's it's content in relation to a trigger.

Features

• Click outside to close
• Styled content

Position
+---------------+
| {trigger}     |
| ContextBox    |
| +-----------+ |
| | {content} | |
| +-----------+ |
+---------------+

Dialogs

These are a variety of dialog components.

Modal

Dialog that occupies the entire app.

Features

• Transitions
• Background mask
• Dismissable
• Click outside to close
• Click × to close
• Press Esc to close
• Trap focus
• Trap Tab press
• Styled content (header/footer)
• Size variant

Overlay
+-------------+
| Header    × |
| { content } |
| Footer      |
+-------------+

Tray

Dialog that attaches to one side of the screen.

Features

• Transitions
• Dismissable
• Click × to close
• Styled content
• Position variant

Overlay
+---------------+
| { content } × |
+---------------+

Alert

Dialog that provides feedback (e.g., success, failure).

Features

• Dismissable
• Click × to close
• Styled content

Container
+---------------+
| { content } × |
+---------------+

Tooltip

Popover that provides further information related to other content (e.g., valid password format).

Features

• Styled content

Popover
+-------------+
| { trigger } |
| { content } |
+-------------+

PopoverMenu

PopverMenu is a Popover that renders it's children as Menu items.

Features

• Click outside to close
• Press Esc to close
• Trap focus

Popover
+------------------+
| { trigger }      |
| Menu             |
| +--------------+ |
| | { children } | |
| +--------------+ |
+------------------+

PopoverDialog

PopoverDialog is a Popover that traps focus and is dismissable.

Features

• Dismissable
• Click outside to close
• Press Esc to close
• Trap focus
• Trap Tab press

Popover
+---------------+
| { trigger } × |
| { children }  |
+---------------+

A couple suggested changes here: PopoverMenu should do TAB or ESC to close and Alert is dismissable/click outside to close as an option (it can also render inline).

Also note that Modal, Tray, PopoverDialog, Popover and PopoverMenu should provide a focus() method that would focus the "default focusable element" if open and Modal, Tray, PopoverDialog and Popover should provide a defaultFocusableElement prop that would let you specify what that element should be (it should default to the close button). PopoverMenu should always focus the first MenuItem.