[TrapFocus] Add documentation

docs/pages/api-docs/unstable-trap-focus.md

@@ -37,3 +37,7 @@ Utility component that locks focus inside the component.
 The component cannot hold a ref.
 
 
+## Demos
+
+- [Trap Focus](/components/trap-focus/)
+

docs/pages/components/trap-focus.js

@@ -0,0 +1,20 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import { prepareMarkdown } from 'docs/src/modules/utils/parseMarkdown';
+
+const pageFilename = 'components/trap-focus';
+const requireDemo = require.context('docs/src/pages/components/trap-focus', false, /\.(js|tsx)$/);
+const requireRaw = require.context(
+  '!raw-loader!../../src/pages/components/trap-focus',
+  false,
+  /\.(js|md|tsx)$/,
+);
+
+export default function Page({ demos, docs }) {
+  return <MarkdownDocs demos={demos} docs={docs} requireDemo={requireDemo} />;
+}
+
+Page.getInitialProps = () => {
+  const { demos, docs } = prepareMarkdown({ pageFilename, requireRaw });
+  return { demos, docs };
+};

docs/src/pages.js

@@ -124,6 +124,7 @@ const pages = [
           { pathname: '/components/speed-dial' },
           { pathname: '/components/timeline' },
           { pathname: '/components/toggle-button' },
+          { pathname: '/components/trap-focus' },
           { pathname: '/components/tree-view' },
         ],
       },

docs/src/pages/components/trap-focus/BasicTrapFocus.js

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
+
+export default function BasicTrapFocus() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open
+      </button>
+      <br />
+      {open && (
+        <TrapFocus open isEnabled={() => true} getDoc={() => document}>
+          <div tabIndex={-1}>
+            <h3>Quick form</h3>
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}

docs/src/pages/components/trap-focus/BasicTrapFocus.tsx

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
+
+export default function BasicTrapFocus() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open
+      </button>
+      <br />
+      {open && (
+        <TrapFocus open isEnabled={() => true} getDoc={() => document}>
+          <div tabIndex={-1}>
+            <h3>Quick form</h3>
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}

docs/src/pages/components/trap-focus/DisableEnforceFocus.js

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
+
+export default function DisableEnforceFocus() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open
+      </button>
+      <br />
+      {open && (
+        <TrapFocus
+          disableEnforceFocus
+          open
+          isEnabled={() => true}
+          getDoc={() => document}
+        >
+          <div tabIndex={-1}>
+            <h3>Quick form</h3>
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}

docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
+
+export default function DisableEnforceFocus() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open
+      </button>
+      <br />
+      {open && (
+        <TrapFocus
+          disableEnforceFocus
+          open
+          isEnabled={() => true}
+          getDoc={() => document}
+        >
+          <div tabIndex={-1}>
+            <h3>Quick form</h3>
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}

docs/src/pages/components/trap-focus/LazyTrapFocus.js

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
+
+export default function LazyTrapFocus() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open
+      </button>
+      <br />
+      {open && (
+        <TrapFocus
+          open
+          isEnabled={() => true}
+          getDoc={() => document}
+          disableAutoFocus
+        >
+          <div tabIndex={-1}>
+            <h3>Quick form</h3>
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}

docs/src/pages/components/trap-focus/LazyTrapFocus.tsx

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
+
+export default function LazyTrapFocus() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open
+      </button>
+      <br />
+      {open && (
+        <TrapFocus
+          open
+          isEnabled={() => true}
+          getDoc={() => document}
+          disableAutoFocus
+        >
+          <div tabIndex={-1}>
+            <h3>Quick form</h3>
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}

docs/src/pages/components/trap-focus/PortalTrapFocus.js

@@ -0,0 +1,39 @@
+import React from 'react';
+import Portal from '@material-ui/core/Portal';
+import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
+
+export default function PortalTrapFocus() {
+  const [open, setOpen] = React.useState(false);
+  const [container, setContainer] = React.useState(null);
+
+  return (
+    <div>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open
+      </button>
+      <br />
+      {open && (
+        <TrapFocus open isEnabled={() => true} getDoc={() => document}>
+          <div tabIndex={-1}>
+            <h3>Quick form</h3>
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <Portal container={container}>
+              <label>
+                Last name: <input type="text" />
+              </label>
+              <br />
+            </Portal>
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+
+      <div ref={setContainer} />
+    </div>
+  );
+}

docs/src/pages/components/trap-focus/PortalTrapFocus.tsx

@@ -0,0 +1,38 @@
+import React from 'react';
+import Portal from '@material-ui/core/Portal';
+import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
+
+export default function PortalTrapFocus() {
+  const [open, setOpen] = React.useState(false);
+  const [container, setContainer] = React.useState<HTMLElement | null>(null);
+
+  return (
+    <div>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open
+      </button>
+      <br />
+      {open && (
+        <TrapFocus open isEnabled={() => true} getDoc={() => document}>
+          <div tabIndex={-1}>
+            <h3>Quick form</h3>
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <Portal container={container}>
+              <label>
+                Last name: <input type="text" />
+              </label>
+              <br />
+            </Portal>
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+      <div ref={setContainer} />
+    </div>
+  );
+}

docs/src/pages/components/trap-focus/trap-focus.md

@@ -0,0 +1,45 @@
+---
+title: Trap Focus React component
+components: Unstable_TrapFocus
+---
+
+# Trap Focus
+
+<p class="description">Trap focus within a DOM node.</p>
+
+> ⚠️ The component is experimental and unstable.
+
+`TrapFocus` is a component that manages focus for its descendants.
+This is useful when implementing overlays such as modal dialogs, which should not allow focus to escape while open.
+
+When `open={true}` the trap is enabled, and pressing <kbd>Tab</kbd> or <kbd>Shift</kbd>+<kbd>Tab</kbd> will rotate focus within the inner focusable elements of the component.
+
+- 📦 [1.5 kB gzipped](https://material-ui.com/size-snapshot).
+- ⚛️ Support portals
+
+## Example
+
+{{"demo": "pages/components/trap-focus/BasicTrapFocus.js"}}
+
+## Disable enforce focus
+
+Clicks within the focus trap behave normally; but clicks outside the focus trap are blocked.
+
+You can disable this behavior with the `disableEnforceFocus` prop.
+
+{{"demo": "pages/components/trap-focus/DisableEnforceFocus.js"}}
+
+## Lazy activation
+
+By default, the component moves the focus to its descendants as soon as it opens: `open={true}`.
+
+You can disable this behavior and make it lazy with the `disableAutoFocus` prop.
+When auto focus is disabled, as in the demo below, the component only traps the focus once it gets focused.
+
+{{"demo": "pages/components/trap-focus/LazyTrapFocus.js"}}
+
+## Portal
+
+The following demo uses the [`Portal`](/components/portal/) component to render a subset of the trap focus children into a new "subtree" outside of the current DOM hierarchy, so that they no longer form part of the focus loop.
+
+{{"demo": "pages/components/trap-focus/PortalTrapFocus.js"}}

packages/material-ui/src/Unstable_TrapFocus/Unstable_TrapFocus.d.ts

@@ -45,6 +45,10 @@ export interface TrapFocusProps {
 
 /**
  * Utility component that locks focus inside the component.
+ * Demos:
+ *
+ * - [Trap Focus](https://material-ui.com/components/trap-focus/)
+ *
  * API:
  *
  * - [Unstable_TrapFocus API](https://material-ui.com/api/unstable-trap-focus/)