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>

Author: joshblack

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",

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

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)
+ | 
+[Usage guidelines](https://www.carbondesignsystem.com/components/popover/usage)
+ | 
 
 <!-- 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
 

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',

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 {

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(