diff --git a/src/data/nav-items.yaml b/src/data/nav-items.yaml index 3bba32cd1df..b7a6c9df90b 100644 --- a/src/data/nav-items.yaml +++ b/src/data/nav-items.yaml @@ -146,6 +146,8 @@ path: /components/overflow-menu/usage/ - title: Pagination path: /components/pagination/usage/ + - title: Popover + path: /components/popover/usage/ - title: Progress indicator path: /components/progress-indicator/usage/ - title: Radio button diff --git a/src/pages/components/popover/images/popover-style-1.png b/src/pages/components/popover/images/popover-style-1.png new file mode 100644 index 00000000000..0cf68bafd41 Binary files /dev/null and b/src/pages/components/popover/images/popover-style-1.png differ diff --git a/src/pages/components/popover/images/popover-style-2.png b/src/pages/components/popover/images/popover-style-2.png new file mode 100644 index 00000000000..358c73a5015 Binary files /dev/null and b/src/pages/components/popover/images/popover-style-2.png differ diff --git a/src/pages/components/popover/images/popover-style-3.png b/src/pages/components/popover/images/popover-style-3.png new file mode 100644 index 00000000000..66fa8a31821 Binary files /dev/null and b/src/pages/components/popover/images/popover-style-3.png differ diff --git a/src/pages/components/popover/images/popover-style-4.png b/src/pages/components/popover/images/popover-style-4.png new file mode 100644 index 00000000000..3b0a07c003c Binary files /dev/null and b/src/pages/components/popover/images/popover-style-4.png differ diff --git a/src/pages/components/popover/images/popover-style-5.png b/src/pages/components/popover/images/popover-style-5.png new file mode 100644 index 00000000000..cae7013a228 Binary files /dev/null and b/src/pages/components/popover/images/popover-style-5.png differ diff --git a/src/pages/components/popover/images/popover-style-6.png b/src/pages/components/popover/images/popover-style-6.png new file mode 100644 index 00000000000..7adf71703c5 Binary files /dev/null and b/src/pages/components/popover/images/popover-style-6.png differ diff --git a/src/pages/components/popover/images/popover-usage-1.png b/src/pages/components/popover/images/popover-usage-1.png new file mode 100644 index 00000000000..622fce256e1 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-1.png differ diff --git a/src/pages/components/popover/images/popover-usage-10.png b/src/pages/components/popover/images/popover-usage-10.png new file mode 100644 index 00000000000..750b187db92 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-10.png differ diff --git a/src/pages/components/popover/images/popover-usage-11.png b/src/pages/components/popover/images/popover-usage-11.png new file mode 100644 index 00000000000..d86e949a6a9 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-11.png differ diff --git a/src/pages/components/popover/images/popover-usage-12-do.png b/src/pages/components/popover/images/popover-usage-12-do.png new file mode 100644 index 00000000000..ff252015130 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-12-do.png differ diff --git a/src/pages/components/popover/images/popover-usage-12-dont.png b/src/pages/components/popover/images/popover-usage-12-dont.png new file mode 100644 index 00000000000..5e3e8f288ef Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-12-dont.png differ diff --git a/src/pages/components/popover/images/popover-usage-12.png b/src/pages/components/popover/images/popover-usage-12.png new file mode 100644 index 00000000000..750b187db92 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-12.png differ diff --git a/src/pages/components/popover/images/popover-usage-13.png b/src/pages/components/popover/images/popover-usage-13.png new file mode 100644 index 00000000000..d51ed2160c8 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-13.png differ diff --git a/src/pages/components/popover/images/popover-usage-14.png b/src/pages/components/popover/images/popover-usage-14.png new file mode 100644 index 00000000000..b933779b804 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-14.png differ diff --git a/src/pages/components/popover/images/popover-usage-15-do.png b/src/pages/components/popover/images/popover-usage-15-do.png new file mode 100644 index 00000000000..3c1b339860d Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-15-do.png differ diff --git a/src/pages/components/popover/images/popover-usage-15-dont.png b/src/pages/components/popover/images/popover-usage-15-dont.png new file mode 100644 index 00000000000..bbb3ab313b4 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-15-dont.png differ diff --git a/src/pages/components/popover/images/popover-usage-15.png b/src/pages/components/popover/images/popover-usage-15.png new file mode 100644 index 00000000000..d51ed2160c8 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-15.png differ diff --git a/src/pages/components/popover/images/popover-usage-16.png b/src/pages/components/popover/images/popover-usage-16.png new file mode 100644 index 00000000000..f7975422cca Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-16.png differ diff --git a/src/pages/components/popover/images/popover-usage-17.png b/src/pages/components/popover/images/popover-usage-17.png new file mode 100644 index 00000000000..0cf68bafd41 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-17.png differ diff --git a/src/pages/components/popover/images/popover-usage-18.png b/src/pages/components/popover/images/popover-usage-18.png new file mode 100644 index 00000000000..0f756f8a96f Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-18.png differ diff --git a/src/pages/components/popover/images/popover-usage-2.png b/src/pages/components/popover/images/popover-usage-2.png new file mode 100644 index 00000000000..9362cfe10eb Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-2.png differ diff --git a/src/pages/components/popover/images/popover-usage-3.png b/src/pages/components/popover/images/popover-usage-3.png new file mode 100644 index 00000000000..ddeca85beb4 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-3.png differ diff --git a/src/pages/components/popover/images/popover-usage-4-do.png b/src/pages/components/popover/images/popover-usage-4-do.png new file mode 100644 index 00000000000..4472b17fc4c Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-4-do.png differ diff --git a/src/pages/components/popover/images/popover-usage-4-dont.png b/src/pages/components/popover/images/popover-usage-4-dont.png new file mode 100644 index 00000000000..3e51a08765b Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-4-dont.png differ diff --git a/src/pages/components/popover/images/popover-usage-5.png b/src/pages/components/popover/images/popover-usage-5.png new file mode 100644 index 00000000000..95bd2261de5 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-5.png differ diff --git a/src/pages/components/popover/images/popover-usage-6.png b/src/pages/components/popover/images/popover-usage-6.png new file mode 100644 index 00000000000..ecf4089ccc7 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-6.png differ diff --git a/src/pages/components/popover/images/popover-usage-7.png b/src/pages/components/popover/images/popover-usage-7.png new file mode 100644 index 00000000000..e114cd96866 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-7.png differ diff --git a/src/pages/components/popover/images/popover-usage-8-do.png b/src/pages/components/popover/images/popover-usage-8-do.png new file mode 100644 index 00000000000..f4d2e3976ff Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-8-do.png differ diff --git a/src/pages/components/popover/images/popover-usage-8-dont.png b/src/pages/components/popover/images/popover-usage-8-dont.png new file mode 100644 index 00000000000..455a72ddd68 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-8-dont.png differ diff --git a/src/pages/components/popover/images/popover-usage-8.png b/src/pages/components/popover/images/popover-usage-8.png new file mode 100644 index 00000000000..ecf4089ccc7 Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-8.png differ diff --git a/src/pages/components/popover/images/popover-usage-9.png b/src/pages/components/popover/images/popover-usage-9.png new file mode 100644 index 00000000000..aaf237baafe Binary files /dev/null and b/src/pages/components/popover/images/popover-usage-9.png differ diff --git a/src/pages/components/popover/style.mdx b/src/pages/components/popover/style.mdx new file mode 100644 index 00000000000..f28a6b722a4 --- /dev/null +++ b/src/pages/components/popover/style.mdx @@ -0,0 +1,56 @@ +--- +title: Popover +description: + A popover is a layer that pops up over all other elements on a page. +tabs: ['Usage', 'Style'] +--- + +## Color + +| Element | Property | Color token | +| --------- | ---------------- | --------------------- | +| Container | background-color | `$layer-01` | +| | background-color | `$layer-02` | +| | background-color | `$background-inverse` | + + + + +![Popover container colors.](images/popover-style-1.png) + + + + +## Structure + +The width and height of a popover container can vary depending on the amount of +content within it. We recommend to not exceed a popover width size of four +columns. + +| Element | Property | px / rem | Spacing token | +| --------- | ------------- | -------- | ------------- | +| Container | max-width | 352 / 22 | – | +| | padding | 16 / 1 | `$spacing-05` | +| Caret tip | height, width | 8 / .5 | – | +| | margin-top | 4 / .25 | `$spacing-02` | + +
+ +![Structure and spacing measurements for a popover container.](images/popover-style-3.png) + +
+ + + Structure and spacing measurements a popover container. | px / rem + + +
+ +![Structure and spacing measurements between a popover container and trigger button.](images/popover-style-4.png) + +
+ + + Structure and spacing measurements between a popover container and trigger + button. | px / rem + diff --git a/src/pages/components/popover/usage.mdx b/src/pages/components/popover/usage.mdx new file mode 100644 index 00000000000..979cc6abaa8 --- /dev/null +++ b/src/pages/components/popover/usage.mdx @@ -0,0 +1,416 @@ +--- +title: Popover +description: + A popover is a layer that pops up over all other elements on a page. +tabs: ['Usage', 'Style'] +--- + + + +A popover is a layer that pops up over all other elements on a page. + + + + + +Overview +Live demo +Variants +Formatting +Content +Behaviors +Modifiers +Related +References +Feedback + + + +## Overview + +A popover is a layer that appears above all other content on the page. Only one +popover can appear at a time and can contain varying text and interactive +elements. Popovers are used as a base layer in some of our components like +tooltips, overflow menus, and dropdown menus. + +#### When to use + +- Use when placing interactive elements, like links, buttons, or rich media to + make the component more accessible. Disclosures that contain interactive + elements use popovers as a base container layer to achieve this accessibility + standard. For further guidance on how to display content within a popover, see + the disclosure pattern. +- Use when you need to display additional details for specific elements on a + page. If your popover exceeds four columns in width, use a modal instead. + +## Live demo + +## Variants + +By default, a popovers structure is made up of a container with no additional +tip. Depending on the usecase, caret tips or tab tips can be added to the +container to help show the relationship between the popover and where it was +triggered from. + +| Variant | Purpose | +| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [No tip](no-tip) | Popovers without a tip are typically used when the trigger button has a visually defined down state. | +| [Caret tip](#caret-tip) | Popovers with a caret tip should be used to help show the relationship between the popover and where it was triggered from. A caret tip is typically used when the trigger button does not have a visually defined down state and for icon buttons. | +| [Tab tip](#tab-tip) | Popovers can have a tab tip when the popover is connected to a toolbar or header area. | + + + + +![Popover variants](images/popover-usage-1.png) + + + + +## Formatting + +### Anatomy + + + + +![Popover anatomy](images/popover-usage-2.png) + + + + +1. **UI trigger button:** An interactive element that triggers the popover to + open on click, hover, or focus. +2. **Tip:** An indicator that is added to a popover container to help show the + relationship between the popover and where it was triggered from. +3. **Content area:** An area to place text and interactive elements. +4. **Container:** An area to place text and interactive elements. + +### Sizing + +#### Container + +The width and height of a popover container can vary depending on the amount of +content placed within it. We recommend to not exceed a popover width size of +four columns. + + + + +![Popover container size](images/popover-usage-3.png) + + + + + + + +![Do keep width between one to four columns.](images/popover-usage-4-do.png) + + + + +![Don't exceed width of four columns.](images/popover-usage-4-dont.png) + + + + +#### Trigger button + +A popover is controlled by a trigger button. By default, we use an icon button +to trigger a popover to open. However, as long as the trigger button is +interactive it can visually change its shape and size depending on the usecase. + +The trigger button can open the popover on click, hover, or focus depending on +what it is being used for. For more information about trigger buttons, see the +disclosure pattern. + +## Content + +### Main elements + +Heading, body, and footer content can vary based on your usecase. To see +examples of content used in popovers, visit the disclosure pattern. + +### Further guidance + +For further content guidance, see Carbon's +[content guidelines]([https://www.carbondesignsystem.com/guidelines/content/overview/]). + +## No tip + +Popovers without a tip can be used for a wide variety of different usecases. No +tip popovers are typically used when the trigger button has a visually defined +down state. + +### Placement + +Popover directions by default are set to auto. Upon opening, popovers can detect +the edges of the browser to properly be placed in view so the container does not +get cutoff. Alternatively, popovers can also specify distinct directions. +Direction options vary depending on the popover variant. + +When a popover does not have a tip, the trigger button should be flush to the +side of the popover. The popover can open from the **left**, **right**, +**bottom**, or **top** of the trigger button. + + + + +![No tip popover top and bottom directions with left and right alignments.](images/popover-usage-5.png) + + + + + + + +![No tip popover left and right directions with top and bottom alignments.](images/popover-usage-6.png) + + + + +### Alignment + +The trigger button should be placed 4px away from the popover container and +should always be the same distance away from the popover container regardless of +what size button is being used. + + + + +![No tip popover container and trigger button spacing.](images/popover-usage-7.png) + + + + + + + +![Do flush align the popover edge with the trigger button.](images/popover-usage-8-do.png) + + + + +![Don't arbitrarily place the popover near the trigger button.](images/popover-usage-8-dont.png) + + + + +## Caret tip + +A caret tip should be added to a popover to help show the relationship between +the popover and where it was triggered from. A caret tip is typically used when +the trigger button does not have a visually defined down state and for icon +buttons. + +### Placement + +The popover can open from the **left**, **right**, **bottom**, or **top** of the +trigger button. When using a caret tip, the trigger button and caret tip should +be vertically center with eachother. + +### Alignment + +The container of the popover may be aligned to **start**, **center**, or **end** +to keep the container from bleeding off the page or covering important +information. + + + + +![Caret tip popover top and bottom directions with left, center, and right alignments.](images/popover-usage-9.png) + + + + + + + +![Caret tip popover left and right directions with top, center, and bottom alignments.](images/popover-usage-10.png) + + + + +Similarly with no tip popovers, a trigger button paired with a caret tip popover +should be placed 4px away from the popover container. + + + + +![Caret tip popover container and trigger button spacing.](images/popover-usage-11.png) + + + + + + + +![Do align the caret tip center with the trigger button.](images/popover-usage-12-do.png) + + + + +![Don't misalign the caret tip with the trigger button.](images/popover-usage-12-dont.png) + + + + +## Tab tip + +Popovers can have a tab tip when the popover is connected to a toolbar or header +area where the trigger button sits within. + +### Placement + +Tab tip popovers nest within another layer on a page. The tab tip can appear on +the **left** and **right** of the container and the edges should be flush with +the layer edges it sits within. + + + + +![Tab tip popover bottom directions with left and right alignments.](images/popover-usage-13.png) + + + + +### Alignment + +Popovers with a tab tip have 0px space between the trigger button and the +container because they are connected to eachother. + + + + +![Tab tip popover container and trigger button spacing.](images/popover-usage-14.png) + + + + + + + +![Do top align the tab tip with the layer behind it.](images/popover-usage-15-do.png) + + + + +![Don't misalign the tab tip with the layer behind it.](images/popover-usage-15-dont.png) + + + + +## Behaviors + +### Interactions + +#### Mouse + +Users trigger a popover to open and close by clicking or hovering on the trigger +button depending on the usecase. + +Click: Open the popover by clicking on the trigger button. Close the popover by +clicking on the trigger button again, or anywhere outside of the open popover +container. + +Hover: Open the popover by hovering over the trigger button. Close the popover +by hovering off of the popover or clicking anywhere outside of the open popover +container. + + + + +![Popover close click target area.](images/popover-usage-16.png) + + + + +#### Keyboard + +Focus: When the popover control has focus `Enter` or `Space` activates the +popover control and toggles the visibility of the popover content. + +#### Screen readers + +VoiceOver: Users can trigger a button to open a popover by pressing `Enter` or +`Space` while the button has focus. + +JAWS: Users can trigger a button to open a popover by pressing `Enter` or +`Space` while the button has focus. + +NVDA: Users can trigger a button to open a popover by pressing `Enter` or +`Space` while the button has focus. + +## Modifiers + +#### Colors + +Popovers come in three different container colors—`$layer-01`, `$layer-02`, and +`$background-inverse`. + + + + +![Popover container colors.](images/popover-usage-17.png) + + + + +#### Corners + +A popover container has rounded corners by default and the corner radius is set +to 2px. Use straight corners when the popover structure contains a tab tip and +is connected to a toolbar or header to keep clean lines between the popover and +the layer underneath. + + + + +![Popover container corner options.](images/popover-usage-18.png) + + + + +## Related + +#### Form components + +Form components that have menus, like dropdowns, use popovers as a base layer. + +#### Disclosures + +Disclosures use popovers as a base layer. Disclosures are comprised of a popover +container, text, and interactive elements. For further guidance, see Carbon's +disclosure pattern. + +#### Overflow menus + +Overflow menus use popovers as a base layer. When the overflow menu icon button +is triggered, the menu opens and uses a tab tip popover as its base. For further +guidance, see Carbon's +[overflow menu](https://www.carbondesignsystem.com/components/overflow-menu/usage/). + +#### Toggletips + +TBD guidance. + +#### Tooltips + +Tooltips use popovers as a base layer. Tooltips are comprised of a trigger +button, popover container and text. For further guidance, see Carbon's +[tooltip](https://www.carbondesignsystem.com/components/tooltip/usage/). + +## References + +Popup,[Component research](https://open-ui.org/components/popup.research#popup), +(OpenUI) + +Disclosure, +[W3C WAI-ARIA practices]([https://www.w3.org/TR/wai-aria-practices-1.1/#disclosure), +(W3C Working Group Note) + +## Feedback + +Help us improve this component by providing feedback, asking questions, and +leaving any other comments on +[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).