styling-hooks(popovers): Add z-index styling hook for Popovers (#4594)

Author: Alexis Córdova

ui/components/popovers/RELEASENOTES.md

@@ -30,6 +30,7 @@
 
 - Added light and dark Brand variants, including new selectors `.slds-popover_brand, .slds-popover_brand-dark, .slds-popover_brand-top, .slds-popover_brand-left, .slds-popover_brand-bottom, .slds-popover_brand-right`
 - Added new Prompt branded variants
+- Enabled styling hooks for popovers. See popovers' styling hooks overview table for a full listing of the currently available hooks.
 
 ## 2.13.1
 

ui/components/popovers/docs.mdx

@@ -13,6 +13,7 @@ import * as FeatureExamples from './feature/example';
 import * as PreviewPanelExamples from './panels/example';
 import * as PromptExamples from './prompt/example';
 import { getDisplayElementById } from '../../shared/helpers';
+import StylingHooksTable from '../../../shared/components/StylingHooksTable';
 
 <div className="doc lead">
   A popover is a non-modal dialog. The component should be paired with a
@@ -333,3 +334,13 @@ Panel Popovers can be shown on mouse hover but for keyboard or screen reader use
 <CodeView demoStyles="height: 250px;">
   {getDisplayElementById(PromptExamples.examples, 'brand-without-footer')}
 </CodeView>
+
+## Styling Hooks Overview
+
+<Blockquote header="A Note About z-index">
+  <p>By default, Popovers use the <code>$z-index-dialog</code> (<a href="/design-tokens/#category-z-index">value of 6000</a>) token. This allows the Popover to appear above the element that triggered it, and in the vast majority of cases should work well out of the box. However, depending on where the Popover code lives when it's triggered, layout issues could arise.</p>
+
+  <p>For this particular use case, the <code>--slds-c-popover-zindex</code> <a href="/platforms/lightning/styling-hooks/">Styling Hook</a> allows developers to change the z-index value. <strong>Please note</strong>: when this value is changed, the responsibility is on the developer to maintain the CSS stacking order.</p>
+</Blockquote>
+
+<StylingHooksTable name="popovers" type="component" />

ui/dependencies/_popover.scss

@@ -41,7 +41,7 @@
   border-radius: $border-radius-medium;
   width: $size-medium;
   min-height: ($nubbin-size-default * 2);
-  z-index: $z-index-dialog;
+  z-index: var(--slds-c-popover-position-zindex, $z-index-dialog);
   background-color: $color;
   display: inline-block;