From 6a345aabaecef2caaff74d3ddb2e9a503537896b Mon Sep 17 00:00:00 2001
From: Josh Black <josh@josh.black>
Date: Tue, 15 Mar 2022 15:02:15 -0500
Subject: [PATCH] refactor(popover): update popover usage and implementation
 (#10952)

* refactor(popover): update popover usage and implementation

* test(react): update public api snapshot

* docs(react): remove light prop from storybook

Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>
---
 .../__snapshots__/PublicAPI-test.js.snap      |  3 -
 .../react/src/components/Popover/index.js     | 13 ++--
 .../src/components/Popover/next/Popover.mdx   | 78 +++++++++++++++++--
 .../Popover/next/Popover.stories.js           |  9 +--
 .../src/components/Popover/next/story.scss    |  4 +-
 .../scss/components/popover/_popover.scss     |  8 --
 6 files changed, 81 insertions(+), 34 deletions(-)

diff --git a/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap b/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap
index c1a99c4d6b5a..25482eeb51b9 100644
--- a/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap
+++ b/packages/react/__tests__/__snapshots__/PublicAPI-test.js.snap
@@ -8669,9 +8669,6 @@ Map {
       "highContrast": Object {
         "type": "bool",
       },
-      "light": Object {
-        "type": "bool",
-      },
       "open": Object {
         "isRequired": true,
         "type": "bool",
diff --git a/packages/react/src/components/Popover/index.js b/packages/react/src/components/Popover/index.js
index 30a3b988027d..6e5726d9f580 100644
--- a/packages/react/src/components/Popover/index.js
+++ b/packages/react/src/components/Popover/index.js
@@ -19,7 +19,6 @@ const Popover = React.forwardRef(function Popover(props, ref) {
     children,
     dropShadow = true,
     highContrast = false,
-    light = false,
     open,
     ...rest
   } = props;
@@ -29,7 +28,6 @@ const Popover = React.forwardRef(function Popover(props, ref) {
     [`${prefix}--popover--caret`]: caret,
     [`${prefix}--popover--drop-shadow`]: dropShadow,
     [`${prefix}--popover--high-contrast`]: highContrast,
-    [`${prefix}--popover--light`]: light,
     [`${prefix}--popover--open`]: open,
     [`${prefix}--popover--${align}`]: true,
     [customClassName]: !!customClassName,
@@ -42,6 +40,12 @@ const Popover = React.forwardRef(function Popover(props, ref) {
   );
 });
 
+// Note: this displayName is temporarily set so that Storybook ArgTable
+// correctly displays the name of this component
+if (__DEV__) {
+  Popover.displayName = 'Popover';
+}
+
 Popover.propTypes = {
   /**
    * Specify how the popover should align with the trigger element
@@ -96,11 +100,6 @@ Popover.propTypes = {
    */
   highContrast: PropTypes.bool,
 
-  /**
-   * Render the component using the light variant
-   */
-  light: PropTypes.bool,
-
   /**
    * Specify whether the component is currently open or closed
    */
diff --git a/packages/react/src/components/Popover/next/Popover.mdx b/packages/react/src/components/Popover/next/Popover.mdx
index 5cee9fc3c53f..558e96b54e48 100644
--- a/packages/react/src/components/Popover/next/Popover.mdx
+++ b/packages/react/src/components/Popover/next/Popover.mdx
@@ -1,8 +1,11 @@
-import { Preview, Props, Story } from '@storybook/addon-docs/blocks';
+import { ArgsTable, Canvas, Story } from '@storybook/addon-docs/blocks';
 
-# [Unstable] Popover
+# Popover
 
 [Source code](https://github.com/carbon-design-system/carbon/tree/main/packages/react/src/components/Popover)
+&nbsp;|&nbsp;
+[Usage guidelines](https://www.carbondesignsystem.com/components/popover/usage)
+&nbsp;|&nbsp;
 
 <!-- START doctoc generated TOC please keep comment here to allow auto update -->
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
@@ -17,14 +20,77 @@ import { Preview, Props, Story } from '@storybook/addon-docs/blocks';
 
 ## Overview
 
-**Note: this component is currently experimental and does not follow semver.**
+`Popover` is a primitive component used to build custom components which render
+over other elements on the page. For example, `Popover` is used to build
+our popover components in Carbon.
 
-The Popover component is used to build layers that appear on top of the current
-surface.
+The `Popover` component accepts two items as `children`: a trigger element and
+a `PopoverContent` component which contains the content to be rendered inside of the
+`Popover`.
+
+```jsx
+import { Popover, PopoverContent } from '@carbon/react';
+import React from 'react';
+
+function CustomComponent() {
+  const [open, setOpen] = React.useState(false);
+
+  return (
+    <Popover open={open}>
+      <button
+        type="button"
+        onClick={() => {
+          setOpen(!open);
+        }}>
+        Toggle
+      </button>
+      <PopoverContent>
+        The content that is revealed by interacting with the Toggle button
+      </PopoverContent>
+    </Popover>
+  );
+}
+```
+
+## Visibility
+
+The `open` prop allows you to control the visibility of the `Popover`. This is
+often tracked in state and is toggled based on the trigger render inside of the
+`Popover`. A trigger must be an interactive element and in most cases it will be
+a `<button>`.
+
+## Alignment
+
+The `align` prop allows you to specify where your content should be placed
+relative to the popover. For example, if you provide `align="top"` to the
+`Popover` component then the popover will render above your component.
+Similarly, if you provide `align="bottom"` then the popover will render below
+your component.
+
+You can also configure the placement of the caret, if it is enabled, by choosing
+between `left` and `right` or `bottom` and `top`, depending on where your
+popover is being rendered.
+
+If you are using `align="top"`, then you can choose between `align="top-left"`
+and `align="top-right"`. These options will place the caret closer to the left
+or right edges of the popover.
+
+If you are using `align="left"` or `align="right"`, you can use `top` or
+`bottom` to control this alignment.
+
+## Appearance
+
+The `Popover` component has several props which you can use to customize its
+appearance, including:
+
+- `caret`: to conditionally display a `caret` or render the popover directly
+beside the trigger element
+- `dropShadow`: to display a drop shadow on the popover content
+- `highContrast`: to display a high contrast variant of the popover
 
 ## Component API
 
-<Props />
+<ArgsTable />
 
 ## Feedback
 
diff --git a/packages/react/src/components/Popover/next/Popover.stories.js b/packages/react/src/components/Popover/next/Popover.stories.js
index 454365dca0d5..d7262fc4c1bd 100644
--- a/packages/react/src/components/Popover/next/Popover.stories.js
+++ b/packages/react/src/components/Popover/next/Popover.stories.js
@@ -50,14 +50,13 @@ export default {
 };
 
 const PlaygroundStory = (props) => {
-  const { align, caret, dropShadow, highContrast, light, open } = props;
+  const { align, caret, dropShadow, highContrast, open } = props;
   return (
     <Popover
       align={align}
       caret={caret}
       dropShadow={dropShadow}
       highContrast={highContrast}
-      light={light}
       open={open}>
       <div className="playground-trigger">
         <Checkbox16 />
@@ -115,12 +114,6 @@ Playground.argTypes = {
     },
     defaultValue: false,
   },
-  light: {
-    control: {
-      type: 'boolean',
-    },
-    defaultValue: false,
-  },
   open: {
     control: {
       type: 'boolean',
diff --git a/packages/react/src/components/Popover/next/story.scss b/packages/react/src/components/Popover/next/story.scss
index 7c21423b0f4a..7e8092acf482 100644
--- a/packages/react/src/components/Popover/next/story.scss
+++ b/packages/react/src/components/Popover/next/story.scss
@@ -84,12 +84,12 @@
 }
 
 .popover-title {
-  @include type.type-style('productive-heading-01');
+  @include type.type-style('heading-compact-01');
   margin-bottom: spacing.$spacing-01;
 }
 
 .popover-details {
-  @include type.type-style('body-short-01');
+  @include type.type-style('body-compact-01');
 }
 
 .popover-story {
diff --git a/packages/styles/scss/components/popover/_popover.scss b/packages/styles/scss/components/popover/_popover.scss
index 5f37e0f80617..ece94416077c 100644
--- a/packages/styles/scss/components/popover/_popover.scss
+++ b/packages/styles/scss/components/popover/_popover.scss
@@ -79,14 +79,6 @@ $popover-caret-height: custom-property.get-var(
 
   /// Modifiers
 
-  // Light modifier
-  .#{$prefix}--popover--light .#{$prefix}--popover-content {
-    @include custom-property.declaration(
-      'popover-background-color',
-      theme.$layer-02
-    );
-  }
-
   // High contrast modifier
   .#{$prefix}--popover--high-contrast .#{$prefix}--popover {
     @include custom-property.declaration(