diff --git a/site/docs/components/overlay/accessibility.mdx b/site/docs/components/overlay/accessibility.mdx new file mode 100644 index 00000000000..1e00faafd42 --- /dev/null +++ b/site/docs/components/overlay/accessibility.mdx @@ -0,0 +1,41 @@ +--- +# Leave the frontmatter as is +title: + $ref: ./#/title +layout: DetailComponent +sidebar: + exclude: true +data: + $ref: ./#/data +--- + +### Best practices + +### Keyboard interactions + + + + +- If focus is on close button, Tab moves focus through focusable content elements in the overlay. +- If focus is on the last element in the overlay content, Tab wraps focus to the close button. Focus does not leave the overlay. + + + + +- If focus is on close button, this action moves focus to last focusable content element in the overlay. + +- If focus is on the first element in the overlay content, this action wraps focus to the close button. Focus does not leave the overlay. + + + + +- If focus is on close button, this action closes the overlay. Focus returns to trigger element. +- This action closes the overlay if a content element is configured to close the overlay when activated. + + + + +- If focus is in the overlay content, Escape closes the overlay and returns focus to trigger element. + + + diff --git a/site/docs/components/overlay/examples.mdx b/site/docs/components/overlay/examples.mdx new file mode 100644 index 00000000000..226b5e28a23 --- /dev/null +++ b/site/docs/components/overlay/examples.mdx @@ -0,0 +1,61 @@ +--- +# Leave the frontmatter as is +title: + $ref: ./#/title +layout: DetailComponent +sidebar: + exclude: true +data: + $ref: ./#/data +--- + + + + +### Default + +The basic overlay component allows the user to expose and interact with supplemental information. The overlay remains persistent until the user dismisses it. + +You can configure the `placement` of an overlay to the top, bottom, left or right in relation to a UI element. + + + + + +### Placement right + +Use `placement=”right”` to display overlay content to the right of the trigger element. + + + + + +### Placement bottom + +Use `placement=”bottom”` to display overlay content to the bottom of the trigger element. + + + + + +### Placement left + +Use `placement=”left”` to display overlay content to the left of the trigger element. + + + + + +### Long content + +When overlay content extends beyond the set height, the content defaults to scroll. The close button remains sticky and accessible at all times. + + + + + +### With actions + +With actions, users can decide if interacting with content in the overlay should close the overlay. This example shows how activating the **Export** button triggers the export function, closes the overlay, and returns focus to the trigger element. + + diff --git a/site/docs/components/overlay/index.mdx b/site/docs/components/overlay/index.mdx new file mode 100644 index 00000000000..a41c546866b --- /dev/null +++ b/site/docs/components/overlay/index.mdx @@ -0,0 +1,27 @@ +--- +title: Overlay +data: + description: "`Overlay` reveals supplementary content when the user clicks a UI trigger element. It remains active and open until the user dismisses it. It can contain interactive and focusable elements, such as buttons and links, in addition to text elements." + + # Fill in the info from the content template's "Metadata" table below. + # To omit optional items, comment them out with # + sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/tree/main/packages/lab/src/overlay" + package: + name: "@salt-ds/lab" + alsoKnownAs: ["Dialog", "Modal"] + relatedComponents: [ + # Add a { name: "...", relationship: "..." } block for each + # related component here (separated by commas). + # Permitted values for relationship are: "similarTo" or + # "contains". + { name: "Button", relationship: "contains" }, + { name: "Dialog", relationship: "similarTo" }, + { name: "Tooltip", relationship: "similarTo" }, + ] + # stickerSheet: "https://figma.com/..." + +# Leave this as is +layout: DetailComponent +--- + +{/* This area stays blank */} diff --git a/site/docs/components/overlay/usage.mdx b/site/docs/components/overlay/usage.mdx new file mode 100644 index 00000000000..950b3ce21ea --- /dev/null +++ b/site/docs/components/overlay/usage.mdx @@ -0,0 +1,42 @@ +--- +# Leave the frontmatter as is +title: + $ref: ./#/title +layout: DetailComponent +sidebar: + exclude: true +data: + $ref: ./#/data +--- + +### Using the component + +Interaction with the content in an overlay is typically constrained, as richer interactions/workflows should occur within a separate UI mechanism (such as a new page, `Dialog` or `Drawer`). + +#### When to use + +- To expose interactive and essential elements within a tooltip to carry out in-context tasks. +- For filter or dropdown panels that overlay content. +- When acknowledgement on overlay content is needed. An overlay only dismissess after user interaction. + +#### When not to use + +- To notify and present critical information that requires immediate action from the user. Instead, use [`Dialog`](../dialog). +- To provide a non-focusable and informative hint. Instead, use [`Tooltip`](../tooltip). + +### Import + +{/* Update the text and code snippet below as needed: */} + +To import `Overlay` from the lab Salt package, use: + +```js +import { Overlay} from "@salt-ds/lab"; +``` + +### Props + +{/* Update packageName and componentName below as needed */} +{/* packageName is optional and defaults to "core" if omitted */} + +