[RFC] feat(Accessibility): Add focus trap zone

docs/src/examples/components/Portal/Types/PortalExample.shorthand.tsx

@@ -18,6 +18,7 @@ class PortalExamplePortal extends React.Component {
     return (
       <div>
         <Portal
+          trapFocus={true}
           content={
             <div
               style={{

docs/src/examples/components/Portal/Types/PortalExampleFocusTrapped.shorthand.tsx

@@ -0,0 +1,52 @@
+import React from 'react'
+import { Button, Header, Portal } from '@stardust-ui/react'
+
+class PortalExampleFocusTrapped extends React.Component {
+  state = { open: false }
+
+  openPortal = () => {
+    this.setState({ open: true })
+  }
+
+  closePortal = () => {
+    this.setState({ open: false })
+  }
+
+  render() {
+    const { open } = this.state
+    const btnContent = open ? 'Close Portal' : 'Open Portal'
+
+    return (
+      <div>
+        <Button content={btnContent} onClick={this.openPortal} />
+        <Portal
+          trapFocus={true}
+          focusTrapZoneProps={{
+            isClickableOutsideFocusTrap: false,
+          }}
+          open={open}
+          content={
+            <div
+              style={{
+                background: '#ddd',
+                position: 'fixed',
+                left: '40%',
+                top: '45%',
+                zIndex: 1000,
+                padding: '10px',
+              }}
+            >
+              <Header>This is a portal with focus trap!</Header>
+              <p tabIndex={0}>Portals have tons of great callback functions to hook into.</p>
+              <p tabIndex={0}>To close, simply click the close button or click away</p>
+              <Button size="small" content="Do nothing" />
+              <Button size="small" content="Close popup" onClick={this.closePortal} />
+            </div>
+          }
+        />
+      </div>
+    )
+  }
+}
+
+export default PortalExampleFocusTrapped

docs/src/examples/components/Portal/Types/PortalExampleFocusTrapped.tsx

@@ -0,0 +1,51 @@
+import React from 'react'
+import { Button, Header, Portal } from '@stardust-ui/react'
+
+class PortalExamplePortal extends React.Component {
+  state = { open: false }
+
+  openPortal = () => {
+    this.setState({ open: true })
+  }
+
+  closePortal = () => {
+    this.setState({ open: false })
+  }
+
+  render() {
+    const { open } = this.state
+    const btnContent = open ? 'Close Portal' : 'Open Portal'
+
+    return (
+      <div>
+        <Button content={btnContent} onClick={this.openPortal} />
+        <Portal
+          open={open}
+          trapFocus={true}
+          focusTrapZoneProps={{
+            isClickableOutsideFocusTrap: false,
+          }}
+        >
+          <div
+            style={{
+              background: '#ddd',
+              position: 'fixed',
+              left: '40%',
+              top: '45%',
+              zIndex: 1000,
+              padding: '10px',
+            }}
+          >
+            <Header>This is a portal with focus trap!</Header>
+            <p tabIndex={0}>Portals have tons of great callback functions to hook into.</p>
+            <p tabIndex={0}>To close, simply click the close button or click away</p>
+            <Button size="small" content="Do nothing" />
+            <Button size="small" content="Close popup" onClick={this.closePortal} />
+          </div>
+        </Portal>
+      </div>
+    )
+  }
+}
+
+export default PortalExamplePortal

docs/src/examples/components/Portal/Types/index.tsx

@@ -15,6 +15,11 @@ const PortalTypesExamples = () => (
       description="A controlled portal."
       examplePath="components/Portal/Types/PortalExampleControlled"
     />
+    <ComponentExample
+      title="With Focus Trap"
+      description="A portal with a focus trap."
+      examplePath="components/Portal/Types/PortalExampleFocusTrapped"
+    />
   </ExampleSection>
 )
 

src/components/Portal/Portal.tsx

@@ -12,6 +12,7 @@ import {
 import { ItemShorthand, ReactChildren } from '../../../types/utils'
 import Ref from '../Ref'
 import PortalInner from './PortalInner'
+import { FocusTrapZone, IFocusTrapZoneProps } from '../../lib/accessibility/FocusZone'
 
 type ReactMouseEvent = React.MouseEvent<HTMLElement>
 
@@ -23,7 +24,8 @@ export interface IPortalProps {
   onUnmount?: (props: IPortalProps) => void
   open?: boolean
   trigger?: JSX.Element
-  triggerRef?: (node: HTMLElement) => void
+  trapFocus?: boolean
+  focusTrapZoneProps?: IFocusTrapZoneProps
 }
 
 export interface IPortalState {
@@ -75,15 +77,23 @@ class Portal extends AutoControlledComponent<IPortalProps, IPortalState> {
      * @param {JSX.Element} node - Referred node.
      */
     triggerRef: PropTypes.func,
+
+    /** Controls whether or not focus trap should be applied */
+    trapFocus: PropTypes.bool,
+
+    /** FocusTrapZone props */
+    focusTrapZoneProps: PropTypes.object,
   }
 
   public static handledProps = [
     'children',
     'content',
     'defaultOpen',
+    'focusTrapZoneProps',
     'onMount',
     'onUnmount',
     'open',
+    'trapFocus',
     'trigger',
     'triggerRef',
   ]
@@ -98,14 +108,19 @@ class Portal extends AutoControlledComponent<IPortalProps, IPortalState> {
   }
 
   private renderPortal(): JSX.Element | undefined {
-    const { children, content } = this.props
+    const { children, content, trapFocus, focusTrapZoneProps } = this.props
     const { open } = this.state
+    const contentToRender = childrenExist(children) ? children : content
 
     return (
       open && (
         <Ref innerRef={this.handlePortalRef}>
           <PortalInner onMount={this.handleMount} onUnmount={this.handleUnmount}>
-            {childrenExist(children) ? children : content}
+            {trapFocus ? (
+              <FocusTrapZone {...focusTrapZoneProps}>{contentToRender}</FocusTrapZone>
+            ) : (
+              contentToRender
+            )}
           </PortalInner>
         </Ref>
       )