@patternfly/react-core 5.1.1-prerelease.2 → 5.1.1-prerelease.4

package/helpers/package.json

@@ -1 +1 @@
-{"name":"@patternfly/react-core-helpers","main":"../dist/js/helpers/index.js","module":"../dist/esm/helpers/index.js","typings":"../dist/esm/helpers/index.d.ts","version":"5.1.1-prerelease.1","private":true}
+{"name":"@patternfly/react-core-helpers","main":"../dist/js/helpers/index.js","module":"../dist/esm/helpers/index.js","typings":"../dist/esm/helpers/index.d.ts","version":"5.1.1-prerelease.3","private":true}

package/layouts/package.json

@@ -1 +1 @@
-{"name":"@patternfly/react-core-layouts","main":"../dist/js/layouts/index.js","module":"../dist/esm/layouts/index.js","typings":"../dist/esm/layouts/index.d.ts","version":"5.1.1-prerelease.1","private":true}
+{"name":"@patternfly/react-core-layouts","main":"../dist/js/layouts/index.js","module":"../dist/esm/layouts/index.js","typings":"../dist/esm/layouts/index.d.ts","version":"5.1.1-prerelease.3","private":true}

package/next/package.json

@@ -1 +1 @@
-{"name":"@patternfly/react-core-next","main":"../dist/js/next/index.js","module":"../dist/esm/next/index.js","typings":"../dist/esm/next/index.d.ts","version":"5.1.1-prerelease.1","private":true}
+{"name":"@patternfly/react-core-next","main":"../dist/js/next/index.js","module":"../dist/esm/next/index.js","typings":"../dist/esm/next/index.d.ts","version":"5.1.1-prerelease.3","private":true}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patternfly/react-core",
-  "version": "5.1.1-prerelease.2",
+  "version": "5.1.1-prerelease.4",
   "description": "This library provides a set of common React components for use with the PatternFly reference implementation.",
   "main": "dist/js/index.js",
   "module": "dist/esm/index.js",
@@ -70,5 +70,5 @@
     "react": "^17 || ^18",
     "react-dom": "^17 || ^18"
   },
-  "gitHead": "52cbf11e7e407d70d674a160da7f432d197c5f57"
+  "gitHead": "12ac5fc7a5280fd5f3fc1ad9bb6134ca028f2ed9"
 }

package/src/components/Drawer/DrawerPanelContent.tsx

@@ -4,6 +4,22 @@ import { css } from '@patternfly/react-styles';
 import { DrawerColorVariant, DrawerContext } from './Drawer';
 import { formatBreakpointMods } from '../../helpers/util';
 import { GenerateId } from '../../helpers/GenerateId/GenerateId';
+import { FocusTrap } from '../../helpers/FocusTrap/FocusTrap';
+
+export interface DrawerPanelFocusTrapObject {
+  /** Enables a focus trap on the drawer panel content. This will also automatically
+   * handle focus management when the panel expands and when it collapses. Do not pass
+   * this prop if the isStatic prop on the drawer component is true.
+   */
+  enabled?: boolean;
+  /** The element to focus when the drawer panel content expands. By default the
+   * first focusable element will receive focus. If there are no focusable elements, the
+   * panel itself will receive focus.
+   */
+  elementToFocusOnExpand?: HTMLElement | SVGElement | string;
+  /** One or more id's to use for the drawer panel content's accessible label. */
+  'aria-labelledby'?: string;
+}
 
 export interface DrawerPanelContentProps extends React.HTMLProps<HTMLDivElement> {
   /** Additional classes added to the drawer. */
@@ -37,6 +53,8 @@ export interface DrawerPanelContentProps extends React.HTMLProps<HTMLDivElement>
   };
   /** Color variant of the background of the drawer panel */
   colorVariant?: DrawerColorVariant | 'light-200' | 'no-background' | 'default';
+  /** Adds and customizes a focus trap on the drawer panel content. */
+  focusTrap?: DrawerPanelFocusTrapObject;
 }
 let isResizing: boolean = null;
 let newSize: number = 0;
@@ -55,6 +73,7 @@ export const DrawerPanelContent: React.FunctionComponent<DrawerPanelContentProps
   resizeAriaLabel = 'Resize',
   widths,
   colorVariant = DrawerColorVariant.default,
+  focusTrap,
   ...props
 }: DrawerPanelContentProps) => {
   const panel = React.useRef<HTMLDivElement>();
@@ -64,6 +83,8 @@ export const DrawerPanelContent: React.FunctionComponent<DrawerPanelContentProps
     React.useContext(DrawerContext);
   const hidden = isStatic ? false : !isExpanded;
   const [isExpandedInternal, setIsExpandedInternal] = React.useState(!hidden);
+  const [isFocusTrapActive, setIsFocusTrapActive] = React.useState(false);
+  const previouslyFocusedElement = React.useRef(null);
   let currWidth: number = 0;
   let panelRect: DOMRect;
   let right: number;
@@ -71,6 +92,13 @@ export const DrawerPanelContent: React.FunctionComponent<DrawerPanelContentProps
   let bottom: number;
   let setInitialVals: boolean = true;
 
+  if (isStatic && focusTrap?.enabled) {
+    // eslint-disable-next-line no-console
+    console.warn(
+      `DrawerPanelContent: The focusTrap.enabled prop cannot be true if the Drawer's isStatic prop is true. This will cause a permanent focus trap.`
+    );
+  }
+
   React.useEffect(() => {
     if (!isStatic && isExpanded) {
       setIsExpandedInternal(isExpanded);
@@ -246,64 +274,101 @@ export const DrawerPanelContent: React.FunctionComponent<DrawerPanelContentProps
   if (maxSize) {
     boundaryCssVars['--pf-v5-c-drawer__panel--md--FlexBasis--max'] = maxSize;
   }
+
+  const isValidFocusTrap = focusTrap?.enabled && !isStatic;
+  const Component = isValidFocusTrap ? FocusTrap : 'div';
+
   return (
     <GenerateId prefix="pf-drawer-panel-">
-      {(panelId) => (
-        <div
-          id={id || panelId}
-          className={css(
-            styles.drawerPanel,
-            isResizable && styles.modifiers.resizable,
-            hasNoBorder && styles.modifiers.noBorder,
-            formatBreakpointMods(widths, styles),
-            colorVariant === DrawerColorVariant.light200 && styles.modifiers.light_200,
-            colorVariant === DrawerColorVariant.noBackground && styles.modifiers.noBackground,
-            className
-          )}
-          ref={panel}
-          onTransitionEnd={(ev) => {
-            if ((ev.target as HTMLElement) === panel.current) {
-              if (!hidden && ev.nativeEvent.propertyName === 'transform') {
-                onExpand(ev);
+      {(panelId) => {
+        const focusTrapProps = {
+          tabIndex: -1,
+          'aria-modal': true,
+          role: 'dialog',
+          active: isFocusTrapActive,
+          'aria-labelledby': focusTrap?.['aria-labelledby'] || id || panelId,
+          focusTrapOptions: {
+            fallbackFocus: () => panel.current,
+            onActivate: () => {
+              if (previouslyFocusedElement.current !== document.activeElement) {
+                previouslyFocusedElement.current = document.activeElement;
+              }
+            },
+            onDeactivate: () => {
+              previouslyFocusedElement.current &&
+                previouslyFocusedElement.current.focus &&
+                previouslyFocusedElement.current.focus();
+            },
+            clickOutsideDeactivates: true,
+            returnFocusOnDeactivate: false,
+            // FocusTrap's initialFocus can accept false as a value to prevent initial focus.
+            // We want to prevent this in case false is ever passed in.
+            initialFocus: focusTrap?.elementToFocusOnExpand || undefined,
+            escapeDeactivates: false
+          }
+        };
+
+        return (
+          <Component
+            {...(isValidFocusTrap && focusTrapProps)}
+            id={id || panelId}
+            className={css(
+              styles.drawerPanel,
+              isResizable && styles.modifiers.resizable,
+              hasNoBorder && styles.modifiers.noBorder,
+              formatBreakpointMods(widths, styles),
+              colorVariant === DrawerColorVariant.light200 && styles.modifiers.light_200,
+              colorVariant === DrawerColorVariant.noBackground && styles.modifiers.noBackground,
+              className
+            )}
+            onTransitionEnd={(ev) => {
+              if ((ev.target as HTMLElement) === panel.current) {
+                if (!hidden && ev.nativeEvent.propertyName === 'transform') {
+                  onExpand(ev);
+                }
+                setIsExpandedInternal(!hidden);
+                if (isValidFocusTrap && ev.nativeEvent.propertyName === 'transform') {
+                  setIsFocusTrapActive((prevIsFocusTrapActive) => !prevIsFocusTrapActive);
+                }
               }
-              setIsExpandedInternal(!hidden);
-            }
-          }}
-          hidden={hidden}
-          {...((defaultSize || minSize || maxSize) && {
-            style: boundaryCssVars as React.CSSProperties
-          })}
-          {...props}
-        >
-          {isExpandedInternal && (
-            <React.Fragment>
-              {isResizable && (
-                <React.Fragment>
-                  <div
-                    className={css(styles.drawerSplitter, position !== 'bottom' && styles.modifiers.vertical)}
-                    role="separator"
-                    tabIndex={0}
-                    aria-orientation={position === 'bottom' ? 'horizontal' : 'vertical'}
-                    aria-label={resizeAriaLabel}
-                    aria-valuenow={separatorValue}
-                    aria-valuemin={0}
-                    aria-valuemax={100}
-                    aria-controls={id || panelId}
-                    onMouseDown={handleMousedown}
-                    onKeyDown={handleKeys}
-                    onTouchStart={handleTouchStart}
-                    ref={splitterRef}
-                  >
-                    <div className={css(styles.drawerSplitterHandle)} aria-hidden></div>
-                  </div>
-                  <div className={css(styles.drawerPanelMain)}>{children}</div>
-                </React.Fragment>
-              )}
-              {!isResizable && children}
-            </React.Fragment>
-          )}
-        </div>
-      )}
+            }}
+            hidden={hidden}
+            {...((defaultSize || minSize || maxSize) && {
+              style: boundaryCssVars as React.CSSProperties
+            })}
+            {...props}
+            ref={panel}
+          >
+            {isExpandedInternal && (
+              <React.Fragment>
+                {isResizable && (
+                  <React.Fragment>
+                    <div
+                      className={css(styles.drawerSplitter, position !== 'bottom' && styles.modifiers.vertical)}
+                      role="separator"
+                      tabIndex={0}
+                      aria-orientation={position === 'bottom' ? 'horizontal' : 'vertical'}
+                      aria-label={resizeAriaLabel}
+                      aria-valuenow={separatorValue}
+                      aria-valuemin={0}
+                      aria-valuemax={100}
+                      aria-controls={id || panelId}
+                      onMouseDown={handleMousedown}
+                      onKeyDown={handleKeys}
+                      onTouchStart={handleTouchStart}
+                      ref={splitterRef}
+                    >
+                      <div className={css(styles.drawerSplitterHandle)} aria-hidden></div>
+                    </div>
+                    <div className={css(styles.drawerPanelMain)}>{children}</div>
+                  </React.Fragment>
+                )}
+                {!isResizable && children}
+              </React.Fragment>
+            )}
+          </Component>
+        );
+      }}
     </GenerateId>
   );
 };

package/src/components/Drawer/__tests__/DrawerPanelContent.test.tsx

@@ -0,0 +1,89 @@
+import React from 'react';
+import { render, screen } from '@testing-library/react';
+import { DrawerPanelContent } from '../DrawerPanelContent';
+import { Drawer } from '../Drawer';
+
+test('Does not render with aria-labelledby by default', () => {
+  render(
+    <Drawer isExpanded>
+      <DrawerPanelContent>Drawer panel content</DrawerPanelContent>
+    </Drawer>
+  );
+
+  expect(screen.getByText('Drawer panel content')).not.toHaveAccessibleName();
+});
+
+test('Renders with aria-labelledby when focusTrap.enabled is true', () => {
+  render(
+    <Drawer isExpanded>
+      <DrawerPanelContent focusTrap={{ enabled: true }}>Drawer panel content</DrawerPanelContent>
+    </Drawer>
+  );
+
+  expect(screen.getByText('Drawer panel content')).toHaveAccessibleName('Drawer panel content');
+});
+
+test('Renders with aria-labelledby when id is passed in', () => {
+  render(
+    <Drawer isExpanded>
+      <DrawerPanelContent id="drawer-panel-content" focusTrap={{ enabled: true }}>
+        Drawer panel content
+      </DrawerPanelContent>
+    </Drawer>
+  );
+
+  expect(screen.getByText('Drawer panel content')).toHaveAccessibleName('Drawer panel content');
+});
+
+test('Renders with custom aria-labelledby', () => {
+  render(
+    <Drawer isExpanded>
+      <DrawerPanelContent focusTrap={{ enabled: true, 'aria-labelledby': 'drawer-panel-title' }}>
+        <span id="drawer-panel-title">Title</span>
+        <span>Drawer panel content</span>
+      </DrawerPanelContent>
+    </Drawer>
+  );
+
+  expect(screen.getByText('Drawer panel content').parentElement).toHaveAccessibleName('Title');
+});
+
+test('Does not render with aria-modal="true" by default', () => {
+  render(
+    <Drawer isExpanded>
+      <DrawerPanelContent>Drawer panel content</DrawerPanelContent>
+    </Drawer>
+  );
+
+  expect(screen.getByText('Drawer panel content')).not.toHaveAttribute('aria-modal');
+});
+
+test('Renders with aria-modal="true" when focusTrap.enabled is true', () => {
+  render(
+    <Drawer isExpanded>
+      <DrawerPanelContent focusTrap={{ enabled: true }}>Drawer panel content</DrawerPanelContent>
+    </Drawer>
+  );
+
+  expect(screen.getByText('Drawer panel content')).toHaveAttribute('aria-modal', 'true');
+});
+
+test('Does not render with role="dialog" by default', () => {
+  render(
+    <Drawer isExpanded>
+      <DrawerPanelContent>Drawer panel content</DrawerPanelContent>
+    </Drawer>
+  );
+
+  expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+});
+
+test('Renders with role="dialog" when focusTrap.enabled is true', () => {
+  render(
+    <Drawer isExpanded>
+      <DrawerPanelContent focusTrap={{ enabled: true }}>Drawer panel content</DrawerPanelContent>
+    </Drawer>
+  );
+
+  expect(screen.getByRole('dialog')).toBeInTheDocument();
+});

package/src/components/Drawer/examples/Drawer.md

@@ -13,6 +13,7 @@ propComponents:
     DrawerActions,
     DrawerCloseButton,
     DrawerColorVariant,
+    DrawerPanelFocusTrapObject
   ]
 section: components
 ---
@@ -22,56 +23,67 @@ section: components
 ### Basic
 
 ```ts file="./DrawerBasic.tsx"
+
 ```
 
 ### Panel on right
 
 ```ts file="./DrawerPanelRight.tsx"
+
 ```
 
 ### Panel on left
 
 ```ts file="./DrawerPanelLeft.tsx"
+
 ```
 
 ### Panel on bottom
 
 ```ts file="./DrawerPanelBottom.tsx"
+
 ```
 
 ### Basic inline
 
 ```ts file="./DrawerBasicInline.tsx"
+
 ```
 
 ### Inline panel on right
 
 ```ts file="./DrawerInlinePanelRight.tsx"
+
 ```
 
 ### Inline panel on left
 
 ```ts file="./DrawerInlinePanelLeft.tsx"
+
 ```
 
 ### Stacked content body elements
 
 ```ts file="./DrawerStackedContentBodyElements.tsx"
+
 ```
 
 ### Modified content padding
 
 ```ts file="DrawerModifiedContentPadding.tsx"
+
 ```
 
 ### Modified panel padding
 
 ```ts file="DrawerModifiedPanelPadding.tsx"
+
 ```
 
 ### Additional section above drawer content
 
 ```ts file="DrawerAdditionalSectionAboveContent.tsx"
+
 ```
 
 ### Static drawer
@@ -79,34 +91,53 @@ section: components
 **Note:** For mobile viewports, all drawer variants behave the same way. At the `md` breakpoint, or where `.pf-m-static{-on-[lg, xl, 2xl]}` is applied, the `static drawer` variant’s `close button` is automatically hidden because the drawer panel doesn’t close by design.
 
 ```ts file="DrawerStatic.tsx"
+
 ```
 
 ### Breakpoint
 
 ```ts file="DrawerBreakpoint.tsx"
+
 ```
 
 ### Resizable on right
 
 ```ts file="DrawerResizableOnRight.tsx"
+
 ```
 
 ### Resizable on left
 
 ```ts file="DrawerResizableOnLeft.tsx"
+
 ```
 
 ### Resizable on bottom
 
 ```ts file="DrawerResizableOnBottom.tsx"
+
 ```
 
 ### Resizable on inline
 
 ```ts file="DrawerResizableOnInline.tsx"
+
 ```
 
 ### Panel with secondary background
 
 ```ts file="DrawerSecondaryBackground.tsx"
+
+```
+
+### With focus trap
+
+When a [focus trap](/accessibility/product-development-guide#trapping-focus) is enabled on an element, a user will only be able to interact with the contents of that element until the focus trap is closed or deactivated.
+
+To enable and customize a focus trap on a drawer panel, apply the `focusTrap` property to the `<DrawerPanelContent>` component. Enabling a focus trap with `focusTrap.enabled` will also automatically place focus on the first focusable element when the drawer panel expands, and return focus to the previously focused element when it collapses.
+
+To customize which element receives focus when the drawer panel expands, use the `focusTrap.elementToFocusOnExpand` property.
+
+```ts file="./DrawerFocusTrap.tsx"
+
 ```

package/src/components/Drawer/examples/DrawerFocusTrap.tsx

@@ -0,0 +1,58 @@
+import React from 'react';
+import {
+  Drawer,
+  DrawerPanelContent,
+  DrawerContent,
+  DrawerContentBody,
+  DrawerHead,
+  DrawerActions,
+  DrawerCloseButton,
+  Button
+} from '@patternfly/react-core';
+
+export const DrawerFocusTrap: React.FunctionComponent = () => {
+  const [isExpanded, setIsExpanded] = React.useState(false);
+
+  const onClick = () => {
+    setIsExpanded(!isExpanded);
+  };
+
+  const onCloseClick = () => {
+    setIsExpanded(false);
+  };
+
+  // An onKeyDown property must be passed to the Drawer component to handle closing
+  // the drawer panel and deactivating the focus trap via the Escape key.
+  const onEscape = (event: React.KeyboardEvent) => {
+    if (event.key === 'Escape') {
+      setIsExpanded(false);
+    }
+  };
+
+  const panelContent = (
+    <DrawerPanelContent focusTrap={{ enabled: true }}>
+      <DrawerHead>
+        <span>drawer-panel</span>
+        <DrawerActions>
+          <DrawerCloseButton onClick={onCloseClick} />
+        </DrawerActions>
+      </DrawerHead>
+    </DrawerPanelContent>
+  );
+
+  const drawerContent =
+    'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Phasellus pretium est a porttitor vehicula. Quisque vel commodo urna. Morbi mattis rutrum ante, id vehicula ex accumsan ut. Morbi viverra, eros vel porttitor facilisis, eros purus aliquet erat,nec lobortis felis elit pulvinar sem. Vivamus vulputate, risus eget commodo eleifend, eros nibh porta quam, vitae lacinia leo libero at magna. Maecenas aliquam sagittis orci, et posuere nisi ultrices sit amet. Aliquam ex odio, malesuada sed posuere quis, pellentesque at mauris. Phasellus venenatis massa ex, eget pulvinar libero auctor pretium. Aliquam erat volutpat. Duis euismod justo in quam ullamcorper, in commodo massa vulputate.';
+
+  return (
+    <React.Fragment>
+      <Button aria-expanded={isExpanded} onClick={onClick}>
+        Toggle drawer with focus trap
+      </Button>
+      <Drawer onKeyDown={onEscape} isExpanded={isExpanded}>
+        <DrawerContent panelContent={panelContent}>
+          <DrawerContentBody>{drawerContent}</DrawerContentBody>
+        </DrawerContent>
+      </Drawer>
+    </React.Fragment>
+  );
+};