Overlay documentation

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
+
+<KeyboardControls>
+<KeyboardControl keyOrCombos="Tab">
+
+- 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. 
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Shift + Tab">
+
+- 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. 
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Enter / Space">
+
+- 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. 
+
+</KeyboardControl>
+<KeyboardControl keyOrCombos="Escape">
+
+- If focus is in the overlay content, Escape closes the overlay and returns focus to trigger element. 
+
+</KeyboardControl>
+</KeyboardControls>

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
+---
+
+<LivePreviewControls>
+<LivePreview componentName="overlay" exampleName="Default">
+
+### 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.  
+
+</LivePreview>
+
+<LivePreview componentName="overlay" exampleName="OverlayRight" >
+
+### Placement right
+
+Use `placement=”right”` to display overlay content to the right of the trigger element.
+
+</LivePreview>
+
+<LivePreview componentName="overlay" exampleName="OverlayBottom" >
+
+### Placement bottom
+
+Use `placement=”bottom”` to display overlay content to the bottom of the trigger element.
+
+</LivePreview>
+
+<LivePreview componentName="overlay" exampleName="OverlayLeft" >
+
+### Placement left
+
+Use `placement=”left”` to display overlay content to the left of the trigger element.
+
+</LivePreview>
+
+<LivePreview componentName="overlay" exampleName="LongContent" >
+
+### 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.  
+
+</LivePreview>
+
+<LivePreview componentName="overlay" exampleName="WithActions" >
+
+### 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. 
+
+</LivePreview>

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 */}

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 */}
+
+<PropsTable packageName="lab" componentName="Overlay" />