Document Overlay Component Family

.storybook/Story.scss

@@ -133,6 +133,12 @@
 }
 
 .mockOverlay {
+  position: absolute;
+  width: 100%;
+  height: 100%;
+  top: 0;
+  left: 0;
+
   .overlay--mask {
     opacity: 0.7;
   }
@@ -167,6 +173,21 @@
   align-items: center;
   align-content: center;
   padding: 64px;
+  position: relative;
+
+}
+
+.overlay--example {
+  .overlay--mask {
+    opacity: 0.7;
+    visibility: hidden;
+  }
+
+  &.show-overlay {
+    .overlay--mask {
+      visibility: visible;
+    }
+  }
 }
 
 .story--form-example {

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 #### 0.0.17 [Unreleassed]
 
+- [#178](https://github.com/influxdata/clockface/pull/178): Add markdown documentation for `Overlay` component family
 - [#170](https://github.com/influxdata/clockface/pull/170): Introduce and document `Table` component family
 - [#169](https://github.com/influxdata/clockface/pull/169): Introduce `DatePicker` and `DateRangePicker` components
 - [#166](https://github.com/influxdata/clockface/pull/166): Add markdown documentation for `ClickOutside`, `DapperScrollbars`, `DraggableResizer`, and `WaitingText`

src/Components/Overlay/ConfirmationOverlay.md

@@ -0,0 +1,19 @@
+# Confirmation Overlay
+
+This examples contains every element in the `Overlay` family and demonstrates a common use case: asking for permission before performing a dangerous action.
+
+### Usage
+```tsx
+import {Overlay} from '@influxdata/clockface'
+```
+All components in the `Overlay` family can be accessed from the single class import
+
+### Example
+<!-- STORY -->
+
+
+<!-- STORY HIDE START -->
+
+<!-- STORY HIDE END -->
+
+<!-- PROPS -->

src/Components/Overlay/Overlay.md

@@ -0,0 +1,75 @@
+# Overlay
+
+Overlays (also known as Modals) are a way to focus the user on a specific task without causing them to lose context by rendering a new page or view. They can help lessen the impact of a workflow with many steps by focusing the user on each step rather than hitting them with all the steps at once. Overlays are also useful as a quick way to get confirmation from the user before executing a dangerous action.
+
+### Usage
+```tsx
+import {Overlay} from '@influxdata/clockface'
+```
+All components in the `Overlay` family can be accessed from the single class import
+```tsx
+<Overlay visible={true}>
+  <Overlay.Container maxWidth={600}>
+    <Overlay.Header />
+    <Overlay.Body>
+      // Contents go here
+    </Overlay.Body>
+    <Overlay.Footer>
+      // Action buttons go here
+    </Overlay.Footer>
+  </Overlay.Container>
+</Overlay>
+```
+
+### Example
+<!-- STORY -->
+
+### Managing State
+
+An overlay requires a stateful wrapper in order to work properly. At the very least you need a single state key, and handlers for showing/hiding the overlay:
+
+```tsx
+interface State {
+  isOverlayVisible: boolean
+}
+```
+```tsx
+this.state = {
+  isOverlayVisible: false,
+}
+```
+```tsx
+private handleShowOverlay = (): void => {
+  this.setState({isOverlayVisible: true})
+}
+```
+```tsx
+private handleHideOverlay = (): void => {
+  this.setState({isOverlayVisible: false})
+}
+```
+
+In this case you would pass `isOverlayVisible` into the `visible` prop of your `Overlay`.
+
+### Customization
+
+One of the key components rendered by `Overlay` is the "mask" which obscures contents below the overlay. `Overlay` has a render prop called `renderMaskElement` which is designed to receive a component of type `<Overlay.Mask />` but you could pass in whatever you want so long as the CSS includes the same positioning rules. The mask has a specific gradient by default but you can choose your own gradient using the `Gradients` data type:
+
+```tsx
+import {Overlay, Gradients} from '@influxdata/clockface'
+```
+```tsx
+<Overlay renderMaskElement={<Overlay.Mask gradient={Gradients.GundamPilot} />}>
+  // Container goes here
+</Overlay>
+```
+
+### Gotchas
+
+In order for the overlay to appear on top of other UI components it makes use of CSS fixed positioning and a high z-index. If you are having trouble with an overlay check out the positioning and z-index styles of the component wrapping the overlay.
+
+<!-- STORY HIDE START -->
+
+<!-- STORY HIDE END -->
+
+<!-- PROPS -->

src/Components/Overlay/Overlay.scss

@@ -21,6 +21,10 @@ $overlay--transition-distance: 72px;
   left: 0;
 }
 
+%overlay-children {
+  width: 100%;
+}
+
 .overlay--mask {
   z-index: 0;
   @extend %overlay-styles;
@@ -62,12 +66,14 @@ $overlay--transition-distance: 72px;
 }
 
 .overlay--container {
+  @extend %overlay-children;
   margin: $overlay--container-padding auto;
   @include gradient-v($g3-castle, $g2-kevlar);
   border-radius: $cf-radius;
 }
 
 .overlay--header {
+  @extend %overlay-children;
   height: $overlay--header-height;
   display: flex;
   padding: 0 $overlay--gutter;
@@ -121,6 +127,7 @@ $overlay--transition-distance: 72px;
 }
 
 .overlay--body {
+  @extend %overlay-children;
   padding: $overlay--gutter;
   padding-top: 0;
   color: $g13-mist;
@@ -131,6 +138,7 @@ $overlay--transition-distance: 72px;
 }
 
 .overlay--footer {
+  @extend %overlay-children;
   padding: $overlay--gutter;
   padding-top: 0;
 }