chore(panels): backport #4654 to 232-summer-21 (#4667)

Author: Dottenpixel

ui/components/menus/docs.mdx

@@ -281,7 +281,7 @@ For an overflow of action items, use the overflow menu with actions styling by a
 
 <Example title="Menu with Action Overflow">
   <CodeView demoStyles="height: 150px;">
-    <ActionOverflow />
+    <ActionOverflow isOpen />
   </CodeView>
 </Example>
 

ui/components/menus/dropdown/example.jsx

@@ -311,28 +311,32 @@ export const IconRight = props => (
   </Trigger>
 );
 
-export const ActionOverflow = ({ size, position }) => {
-  const positionClassNames = classNames({
-    'slds-dropdown_left': position === 'left',
-    'slds-dropdown_right': position === 'right',
-    'slds-dropdown_bottom': position === 'bottom'
-  });
+export const ActionOverflow = ({ isOpen, size, position }) => {
+  const menuClassNames = classNames(
+    {
+      'slds-dropdown_left': position === 'left',
+      'slds-dropdown_right': position === 'right',
+      'slds-dropdown_bottom': position === 'bottom'
+    },
+    'slds-dropdown_actions'
+  );
 
   return (
     <Trigger
-      isOpen
+      isOpen={isOpen}
       triggerIcon={
         <ButtonIcon
           className="slds-button_icon-border-filled"
           symbol="down"
           assistiveText="Show More"
           aria-haspopup="true"
+          aria-expanded={isOpen ? 'true' : 'false'}
           title="Show More"
           size={size}
         />
       }
     >
-      <Menu className={classNames(positionClassNames, 'slds-dropdown_actions')}>
+      <Menu className={menuClassNames}>
         <MenuList ariaLabel="Show More">
           <MenuItem tabIndex="0">Action One</MenuItem>
           <MenuItem>Action Two</MenuItem>
@@ -344,6 +348,7 @@ export const ActionOverflow = ({ size, position }) => {
 };
 
 ActionOverflow.propTypes = {
+  isOpen: PropTypes.bool,
   position: PropTypes.string,
   size: PropTypes.string
 };
@@ -484,7 +489,7 @@ export let examples = [
   {
     id: 'action-overflow',
     label: 'Overflow menu with actions',
-    element: <ActionOverflow />
+    element: <ActionOverflow isOpen />
   },
   {
     id: 'notifications-menu',

ui/components/panels/__tests__/__snapshots__/snapshot.spec.js.snap

@@ -729,6 +729,7 @@ exports[`render Panel component renders Base Panel with secondary actions 1`] =
         className="slds-dropdown-trigger slds-dropdown-trigger_click slds-is-open"
       >
         <button
+          aria-expanded="true"
           aria-haspopup="true"
           className="slds-button slds-button_icon slds-button_icon-small slds-button_icon-border-filled"
           onClick={[Function]}

ui/components/panels/base/example.jsx

@@ -36,7 +36,7 @@ export let examples = [
         title="Panel Header"
         docked="left"
         invoke="toggle"
-        headerActions={<ActionOverflow size="small" position="right" />}
+        headerActions={<ActionOverflow position="right" size="small" isOpen />}
       >
         A panel body accepts any layout or component
       </Panel>
@@ -62,7 +62,7 @@ export let examples = [
         title="Panel Header"
         docked="left"
         invoke="drill-in"
-        headerActions={<ActionOverflow size="small" position="right" />}
+        headerActions={<ActionOverflow size="small" position="right" isOpen />}
       >
         A panel body accepts any layout or component
       </Panel>

ui/components/panels/docs.mdx

@@ -51,6 +51,14 @@ The panel should take up 100% of the height of its parent container. In most cas
   </p>
 </Blockquote>
 
+### Accessibility
+
+When managing the visibility of the panel, there are a few essential accessibility elements to make sure are in place:
+
+- When the panel is not visible, set its `aria-hidden` attribute to `true`, and when visible, set `aria-hidden` to `false`.
+- If the panel's visibility is triggered by an element, the triggering element must be focusable with `aria-controls` set to the unique ID of the panel and `aria-expanded` set to either `true` or `false` depending on the visibility of the panel.
+- When toggling a panel open, place the user's focus inside the first focusable element within the panel that isn't the close button. If the close button is the only focusable element, place focus there. Return focus to the triggering element when the panel closes.
+
 ## Base
 
 <Example title="Panel base">
@@ -114,6 +122,12 @@ To center the header title, add the class `slds-panel__header_align-center` to t
 
 Secondary actions provide a compact way to offer additional actions without the need for a dedicated action toolbar. Actions in the menu apply to the entire component.
 
+<Blockquote type="a11y" header="Accessibility Requirement">
+  <p>
+    Secondary actions use the <a href="/components/menus/#Accessibility">menu component</a>. All of the <a href="/components/menus/#Accessibility">accessibility guidelines</a> for the menu component are pertinent within the context of secondary actions.
+  </p>
+</Blockquote>
+
 <CodeView
   demoStyles={getDemoStylesById(Base.examples, 'with-secondary-actions')}
 >
@@ -244,7 +258,7 @@ Filtering lists or reports can be done by using a Filtering expressions inside o
     Make sure to use assistive text to improve the clarity of what you might be
     editing, for example, add{' '}
     <code>
-      <span className="slds-assistive-text">Edit filter:</span>
+      &lt;span className="slds-assistive-text"&gt;Edit filter:&lt;/span&gt;
     </code>{' '}
     to the button element inside each filterable object.
   </p>