From 070deb19409ddf634b5140a656759d056ffda74d Mon Sep 17 00:00:00 2001
From: Olivier Tassinari <olivier.tassinari@gmail.com>
Date: Tue, 4 Aug 2020 00:05:59 +0200
Subject: [PATCH 1/6] [TrapFocus] Add documentation

---
 docs/pages/api-docs/unstable-trap-focus.md    |  4 ++
 docs/pages/components/trap-focus.js           | 20 ++++++++
 docs/src/pages.js                             |  1 +
 .../components/trap-focus/BasicTrapFocus.js   | 26 ++++++++++
 .../components/trap-focus/BasicTrapFocus.tsx  | 26 ++++++++++
 .../trap-focus/DisableEnforceFocus.js         | 31 ++++++++++++
 .../trap-focus/DisableEnforceFocus.tsx        | 31 ++++++++++++
 .../trap-focus/DisableRestoreFocus.js         | 31 ++++++++++++
 .../trap-focus/DisableRestoreFocus.tsx        | 31 ++++++++++++
 .../components/trap-focus/LazyTrapFocus.js    | 31 ++++++++++++
 .../components/trap-focus/LazyTrapFocus.tsx   | 31 ++++++++++++
 .../components/trap-focus/PortalTrapFocus.js  | 33 ++++++++++++
 .../components/trap-focus/PortalTrapFocus.tsx | 32 ++++++++++++
 .../pages/components/trap-focus/trap-focus.md | 50 +++++++++++++++++++
 .../Unstable_TrapFocus.d.ts                   |  4 ++
 15 files changed, 382 insertions(+)
 create mode 100644 docs/pages/components/trap-focus.js
 create mode 100644 docs/src/pages/components/trap-focus/BasicTrapFocus.js
 create mode 100644 docs/src/pages/components/trap-focus/BasicTrapFocus.tsx
 create mode 100644 docs/src/pages/components/trap-focus/DisableEnforceFocus.js
 create mode 100644 docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx
 create mode 100644 docs/src/pages/components/trap-focus/DisableRestoreFocus.js
 create mode 100644 docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx
 create mode 100644 docs/src/pages/components/trap-focus/LazyTrapFocus.js
 create mode 100644 docs/src/pages/components/trap-focus/LazyTrapFocus.tsx
 create mode 100644 docs/src/pages/components/trap-focus/PortalTrapFocus.js
 create mode 100644 docs/src/pages/components/trap-focus/PortalTrapFocus.tsx
 create mode 100644 docs/src/pages/components/trap-focus/trap-focus.md

diff --git a/docs/pages/api-docs/unstable-trap-focus.md b/docs/pages/api-docs/unstable-trap-focus.md
index 095e8bd63429b3..d1622bd14f40e3 100644
--- a/docs/pages/api-docs/unstable-trap-focus.md
+++ b/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/)
+
diff --git a/docs/pages/components/trap-focus.js b/docs/pages/components/trap-focus.js
new file mode 100644
index 00000000000000..f26ed07bbadda2
--- /dev/null
+++ b/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 };
+};
diff --git a/docs/src/pages.js b/docs/src/pages.js
index aa9f3c94278f81..bdf0d1533c6060 100644
--- a/docs/src/pages.js
+++ b/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' },
         ],
       },
diff --git a/docs/src/pages/components/trap-focus/BasicTrapFocus.js b/docs/src/pages/components/trap-focus/BasicTrapFocus.js
new file mode 100644
index 00000000000000..127d8d326f3cc0
--- /dev/null
+++ b/docs/src/pages/components/trap-focus/BasicTrapFocus.js
@@ -0,0 +1,26 @@
+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>
+            <input aria-label="First name" placeholder="First name" />
+            <input aria-label="Last name" placeholder="Last name" />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/trap-focus/BasicTrapFocus.tsx b/docs/src/pages/components/trap-focus/BasicTrapFocus.tsx
new file mode 100644
index 00000000000000..127d8d326f3cc0
--- /dev/null
+++ b/docs/src/pages/components/trap-focus/BasicTrapFocus.tsx
@@ -0,0 +1,26 @@
+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>
+            <input aria-label="First name" placeholder="First name" />
+            <input aria-label="Last name" placeholder="Last name" />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/trap-focus/DisableEnforceFocus.js b/docs/src/pages/components/trap-focus/DisableEnforceFocus.js
new file mode 100644
index 00000000000000..8c94a48a8a318d
--- /dev/null
+++ b/docs/src/pages/components/trap-focus/DisableEnforceFocus.js
@@ -0,0 +1,31 @@
+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>
+            <input aria-label="First name" placeholder="First name" />
+            <input aria-label="Last name" placeholder="Last name" />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx b/docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx
new file mode 100644
index 00000000000000..8c94a48a8a318d
--- /dev/null
+++ b/docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx
@@ -0,0 +1,31 @@
+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>
+            <input aria-label="First name" placeholder="First name" />
+            <input aria-label="Last name" placeholder="Last name" />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/trap-focus/DisableRestoreFocus.js b/docs/src/pages/components/trap-focus/DisableRestoreFocus.js
new file mode 100644
index 00000000000000..ab5806f314f07d
--- /dev/null
+++ b/docs/src/pages/components/trap-focus/DisableRestoreFocus.js
@@ -0,0 +1,31 @@
+import * as React from 'react';
+import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
+
+export default function DisableRestoreFocus() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open
+      </button>
+      <br />
+      {open && (
+        <TrapFocus
+          disableRestoreFocus
+          open
+          isEnabled={() => true}
+          getDoc={() => document}
+        >
+          <div tabIndex={-1}>
+            <h3>Quick form</h3>
+            <input aria-label="First name" placeholder="First name" />
+            <input aria-label="Last name" placeholder="Last name" />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx b/docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx
new file mode 100644
index 00000000000000..ab5806f314f07d
--- /dev/null
+++ b/docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx
@@ -0,0 +1,31 @@
+import * as React from 'react';
+import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
+
+export default function DisableRestoreFocus() {
+  const [open, setOpen] = React.useState(false);
+  return (
+    <div>
+      <button type="button" onClick={() => setOpen(true)}>
+        Open
+      </button>
+      <br />
+      {open && (
+        <TrapFocus
+          disableRestoreFocus
+          open
+          isEnabled={() => true}
+          getDoc={() => document}
+        >
+          <div tabIndex={-1}>
+            <h3>Quick form</h3>
+            <input aria-label="First name" placeholder="First name" />
+            <input aria-label="Last name" placeholder="Last name" />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/trap-focus/LazyTrapFocus.js b/docs/src/pages/components/trap-focus/LazyTrapFocus.js
new file mode 100644
index 00000000000000..44be0a2418cb37
--- /dev/null
+++ b/docs/src/pages/components/trap-focus/LazyTrapFocus.js
@@ -0,0 +1,31 @@
+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>
+            <input aria-label="First name" placeholder="First name" />
+            <input aria-label="Last name" placeholder="Last name" />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/trap-focus/LazyTrapFocus.tsx b/docs/src/pages/components/trap-focus/LazyTrapFocus.tsx
new file mode 100644
index 00000000000000..44be0a2418cb37
--- /dev/null
+++ b/docs/src/pages/components/trap-focus/LazyTrapFocus.tsx
@@ -0,0 +1,31 @@
+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>
+            <input aria-label="First name" placeholder="First name" />
+            <input aria-label="Last name" placeholder="Last name" />
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/trap-focus/PortalTrapFocus.js b/docs/src/pages/components/trap-focus/PortalTrapFocus.js
new file mode 100644
index 00000000000000..910d39b1c61ad7
--- /dev/null
+++ b/docs/src/pages/components/trap-focus/PortalTrapFocus.js
@@ -0,0 +1,33 @@
+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>
+            <input aria-label="First name" placeholder="First name" />
+            <Portal container={container}>
+              <input aria-label="Last name" placeholder="Last name" />
+            </Portal>
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+
+      <div ref={setContainer} />
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/trap-focus/PortalTrapFocus.tsx b/docs/src/pages/components/trap-focus/PortalTrapFocus.tsx
new file mode 100644
index 00000000000000..7394e5e6556295
--- /dev/null
+++ b/docs/src/pages/components/trap-focus/PortalTrapFocus.tsx
@@ -0,0 +1,32 @@
+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>
+            <input aria-label="First name" placeholder="First name" />
+            <Portal container={container}>
+              <input aria-label="Last name" placeholder="Last name" />
+            </Portal>
+            <button type="button" onClick={() => setOpen(false)}>
+              Close
+            </button>
+          </div>
+        </TrapFocus>
+      )}
+      <div ref={setContainer} />
+    </div>
+  );
+}
diff --git a/docs/src/pages/components/trap-focus/trap-focus.md b/docs/src/pages/components/trap-focus/trap-focus.md
new file mode 100644
index 00000000000000..da78eb083a92c6
--- /dev/null
+++ b/docs/src/pages/components/trap-focus/trap-focus.md
@@ -0,0 +1,50 @@
+---
+title: Trap Focus React component
+components: Unstable_TrapFocus
+---
+
+# Trap Focus
+
+<p class="description">Trap focus within a DOM node.</p>
+
+`TrapFocus` is a utility component that manage focus for its descendants.
+This is useful when implementing overlays like modal dialogs, which should not allow focus to escape them while open.
+
+When `open={true}` the trap enables, pressing <kbd>Tab</kbd> or <kbd>Shift+Tab</kbd> will circle 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 the behavior with the `disableEnforceFocus` prop.
+
+{{"demo": "pages/components/trap-focus/DisableEnforceFocus.js"}}
+
+## Disable restore focus
+
+The component restores the focus back to the previously focused element when it deactivates, for example, back to a button which opened a dialog.
+
+You can disable this behavior with the `disableRestoreFocus` prop.
+
+{{"demo": "pages/components/trap-focus/DisableRestoreFocus.js"}}
+
+## Lazy activation
+
+By default, the component moves the focus to its descendants as soon as it opens, `open={true}`.
+
+You can disale this behavior, and make it lazy, with the `disableAutoFocus` prop.
+
+{{"demo": "pages/components/trap-focus/LazyTrapFocus.js"}}
+
+## Portal
+
+The following demo uses [`Portal`](/components/portal/) to render a part of the trap focus into a new "subtree" outside of current DOM hierarchy.
+
+{{"demo": "pages/components/trap-focus/PortalTrapFocus.js"}}
diff --git a/packages/material-ui/src/Unstable_TrapFocus/Unstable_TrapFocus.d.ts b/packages/material-ui/src/Unstable_TrapFocus/Unstable_TrapFocus.d.ts
index 4b5c65287cafa6..be232c4777cf90 100644
--- a/packages/material-ui/src/Unstable_TrapFocus/Unstable_TrapFocus.d.ts
+++ b/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/)

From f19b53b817651e8d40a8a8d4be200452a605b361 Mon Sep 17 00:00:00 2001
From: Olivier Tassinari <olivier.tassinari@gmail.com>
Date: Thu, 6 Aug 2020 12:24:04 +0200
Subject: [PATCH 2/6] Matt code review

Co-authored-by: Matt <github@nospam.33m.co>
---
 docs/src/pages/components/trap-focus/trap-focus.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/docs/src/pages/components/trap-focus/trap-focus.md b/docs/src/pages/components/trap-focus/trap-focus.md
index da78eb083a92c6..22ce9fbe596885 100644
--- a/docs/src/pages/components/trap-focus/trap-focus.md
+++ b/docs/src/pages/components/trap-focus/trap-focus.md
@@ -7,10 +7,10 @@ components: Unstable_TrapFocus
 
 <p class="description">Trap focus within a DOM node.</p>
 
-`TrapFocus` is a utility component that manage focus for its descendants.
-This is useful when implementing overlays like modal dialogs, which should not allow focus to escape them while open.
+`TrapFocus` is a utility component that manages focus for its descendants.
+This is useful when implementing overlays like modal dialogs, which should not allow focus to escape while open.
 
-When `open={true}` the trap enables, pressing <kbd>Tab</kbd> or <kbd>Shift+Tab</kbd> will circle focus within the inner focusable elements of the component.
+When `open={true}` the trap is enabled, and pressing <kbd>Tab</kbd> or <kbd>Shift+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
@@ -29,7 +29,7 @@ You can disable the behavior with the `disableEnforceFocus` prop.
 
 ## Disable restore focus
 
-The component restores the focus back to the previously focused element when it deactivates, for example, back to a button which opened a dialog.
+The component restores the focus back to the previously focused element when it deactivates, for example back to the button which opened a dialog.
 
 You can disable this behavior with the `disableRestoreFocus` prop.
 
@@ -37,14 +37,14 @@ You can disable this behavior with the `disableRestoreFocus` prop.
 
 ## Lazy activation
 
-By default, the component moves the focus to its descendants as soon as it opens, `open={true}`.
+By default, the component moves the focus to its descendants as soon as it opens: `open={true}`.
 
-You can disale this behavior, and make it lazy, with the `disableAutoFocus` prop.
+You can disable this behavior and make it lazy with the `disableAutoFocus` prop.
 
 {{"demo": "pages/components/trap-focus/LazyTrapFocus.js"}}
 
 ## Portal
 
-The following demo uses [`Portal`](/components/portal/) to render a part of the trap focus into a new "subtree" outside of current DOM hierarchy.
+The following demo uses [`Portal`](/components/portal/) to render a part of the trap focus into a new "subtree" outside of the current DOM hierarchy.
 
 {{"demo": "pages/components/trap-focus/PortalTrapFocus.js"}}

From 4229f34862e195e08c6cb182f0d717496308be14 Mon Sep 17 00:00:00 2001
From: Olivier Tassinari <olivier.tassinari@gmail.com>
Date: Thu, 6 Aug 2020 19:54:21 +0200
Subject: [PATCH 3/6] Matt code review 2

Co-authored-by: Matt <github@nospam.33m.co>
---
 docs/src/pages/components/trap-focus/trap-focus.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/src/pages/components/trap-focus/trap-focus.md b/docs/src/pages/components/trap-focus/trap-focus.md
index 22ce9fbe596885..fad9d8dcaebfbd 100644
--- a/docs/src/pages/components/trap-focus/trap-focus.md
+++ b/docs/src/pages/components/trap-focus/trap-focus.md
@@ -8,7 +8,7 @@ components: Unstable_TrapFocus
 <p class="description">Trap focus within a DOM node.</p>
 
 `TrapFocus` is a utility component that manages focus for its descendants.
-This is useful when implementing overlays like modal dialogs, which should not allow focus to escape while open.
+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+Tab</kbd> will rotate focus within the inner focusable elements of the component.
 
@@ -23,7 +23,7 @@ When `open={true}` the trap is enabled, and pressing <kbd>Tab</kbd> or <kbd>Shif
 
 Clicks within the focus trap behave normally; but clicks outside the focus trap are blocked.
 
-You can disable the behavior with the `disableEnforceFocus` prop.
+You can disable this behavior with the `disableEnforceFocus` prop.
 
 {{"demo": "pages/components/trap-focus/DisableEnforceFocus.js"}}
 
@@ -45,6 +45,6 @@ You can disable this behavior and make it lazy with the `disableAutoFocus` prop.
 
 ## Portal
 
-The following demo uses [`Portal`](/components/portal/) to render a part of the trap focus into a new "subtree" outside of the current DOM hierarchy.
+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"}}

From f74375fe523daa94e3a7676904a67b6db061a9e0 Mon Sep 17 00:00:00 2001
From: Olivier Tassinari <olivier.tassinari@gmail.com>
Date: Thu, 6 Aug 2020 19:59:32 +0200
Subject: [PATCH 4/6] lower case aria

---
 docs/src/pages/components/trap-focus/BasicTrapFocus.js       | 4 ++--
 docs/src/pages/components/trap-focus/BasicTrapFocus.tsx      | 4 ++--
 docs/src/pages/components/trap-focus/DisableEnforceFocus.js  | 4 ++--
 docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx | 4 ++--
 docs/src/pages/components/trap-focus/DisableRestoreFocus.js  | 4 ++--
 docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx | 4 ++--
 docs/src/pages/components/trap-focus/LazyTrapFocus.js        | 4 ++--
 docs/src/pages/components/trap-focus/LazyTrapFocus.tsx       | 4 ++--
 docs/src/pages/components/trap-focus/PortalTrapFocus.js      | 4 ++--
 docs/src/pages/components/trap-focus/PortalTrapFocus.tsx     | 4 ++--
 10 files changed, 20 insertions(+), 20 deletions(-)

diff --git a/docs/src/pages/components/trap-focus/BasicTrapFocus.js b/docs/src/pages/components/trap-focus/BasicTrapFocus.js
index 127d8d326f3cc0..25147089d02dad 100644
--- a/docs/src/pages/components/trap-focus/BasicTrapFocus.js
+++ b/docs/src/pages/components/trap-focus/BasicTrapFocus.js
@@ -13,8 +13,8 @@ export default function BasicTrapFocus() {
         <TrapFocus open isEnabled={() => true} getDoc={() => document}>
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="First name" placeholder="First name" />
-            <input aria-label="Last name" placeholder="Last name" />
+            <input aria-label="first name" placeholder="First name" />
+            <input aria-label="last name" placeholder="Last name" />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/BasicTrapFocus.tsx b/docs/src/pages/components/trap-focus/BasicTrapFocus.tsx
index 127d8d326f3cc0..25147089d02dad 100644
--- a/docs/src/pages/components/trap-focus/BasicTrapFocus.tsx
+++ b/docs/src/pages/components/trap-focus/BasicTrapFocus.tsx
@@ -13,8 +13,8 @@ export default function BasicTrapFocus() {
         <TrapFocus open isEnabled={() => true} getDoc={() => document}>
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="First name" placeholder="First name" />
-            <input aria-label="Last name" placeholder="Last name" />
+            <input aria-label="first name" placeholder="First name" />
+            <input aria-label="last name" placeholder="Last name" />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/DisableEnforceFocus.js b/docs/src/pages/components/trap-focus/DisableEnforceFocus.js
index 8c94a48a8a318d..daae758760c840 100644
--- a/docs/src/pages/components/trap-focus/DisableEnforceFocus.js
+++ b/docs/src/pages/components/trap-focus/DisableEnforceFocus.js
@@ -18,8 +18,8 @@ export default function DisableEnforceFocus() {
         >
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="First name" placeholder="First name" />
-            <input aria-label="Last name" placeholder="Last name" />
+            <input aria-label="first name" placeholder="First name" />
+            <input aria-label="last name" placeholder="Last name" />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx b/docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx
index 8c94a48a8a318d..daae758760c840 100644
--- a/docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx
+++ b/docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx
@@ -18,8 +18,8 @@ export default function DisableEnforceFocus() {
         >
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="First name" placeholder="First name" />
-            <input aria-label="Last name" placeholder="Last name" />
+            <input aria-label="first name" placeholder="First name" />
+            <input aria-label="last name" placeholder="Last name" />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/DisableRestoreFocus.js b/docs/src/pages/components/trap-focus/DisableRestoreFocus.js
index ab5806f314f07d..c0d286b8c51dd4 100644
--- a/docs/src/pages/components/trap-focus/DisableRestoreFocus.js
+++ b/docs/src/pages/components/trap-focus/DisableRestoreFocus.js
@@ -18,8 +18,8 @@ export default function DisableRestoreFocus() {
         >
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="First name" placeholder="First name" />
-            <input aria-label="Last name" placeholder="Last name" />
+            <input aria-label="first name" placeholder="First name" />
+            <input aria-label="last name" placeholder="Last name" />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx b/docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx
index ab5806f314f07d..c0d286b8c51dd4 100644
--- a/docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx
+++ b/docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx
@@ -18,8 +18,8 @@ export default function DisableRestoreFocus() {
         >
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="First name" placeholder="First name" />
-            <input aria-label="Last name" placeholder="Last name" />
+            <input aria-label="first name" placeholder="First name" />
+            <input aria-label="last name" placeholder="Last name" />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/LazyTrapFocus.js b/docs/src/pages/components/trap-focus/LazyTrapFocus.js
index 44be0a2418cb37..1858a850f19369 100644
--- a/docs/src/pages/components/trap-focus/LazyTrapFocus.js
+++ b/docs/src/pages/components/trap-focus/LazyTrapFocus.js
@@ -18,8 +18,8 @@ export default function LazyTrapFocus() {
         >
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="First name" placeholder="First name" />
-            <input aria-label="Last name" placeholder="Last name" />
+            <input aria-label="first name" placeholder="First name" />
+            <input aria-label="last name" placeholder="Last name" />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/LazyTrapFocus.tsx b/docs/src/pages/components/trap-focus/LazyTrapFocus.tsx
index 44be0a2418cb37..1858a850f19369 100644
--- a/docs/src/pages/components/trap-focus/LazyTrapFocus.tsx
+++ b/docs/src/pages/components/trap-focus/LazyTrapFocus.tsx
@@ -18,8 +18,8 @@ export default function LazyTrapFocus() {
         >
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="First name" placeholder="First name" />
-            <input aria-label="Last name" placeholder="Last name" />
+            <input aria-label="first name" placeholder="First name" />
+            <input aria-label="last name" placeholder="Last name" />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/PortalTrapFocus.js b/docs/src/pages/components/trap-focus/PortalTrapFocus.js
index 910d39b1c61ad7..f8efd5424d9496 100644
--- a/docs/src/pages/components/trap-focus/PortalTrapFocus.js
+++ b/docs/src/pages/components/trap-focus/PortalTrapFocus.js
@@ -16,9 +16,9 @@ export default function PortalTrapFocus() {
         <TrapFocus open isEnabled={() => true} getDoc={() => document}>
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="First name" placeholder="First name" />
+            <input aria-label="first name" placeholder="First name" />
             <Portal container={container}>
-              <input aria-label="Last name" placeholder="Last name" />
+              <input aria-label="last name" placeholder="Last name" />
             </Portal>
             <button type="button" onClick={() => setOpen(false)}>
               Close
diff --git a/docs/src/pages/components/trap-focus/PortalTrapFocus.tsx b/docs/src/pages/components/trap-focus/PortalTrapFocus.tsx
index 7394e5e6556295..9eafee9356a7e9 100644
--- a/docs/src/pages/components/trap-focus/PortalTrapFocus.tsx
+++ b/docs/src/pages/components/trap-focus/PortalTrapFocus.tsx
@@ -16,9 +16,9 @@ export default function PortalTrapFocus() {
         <TrapFocus open isEnabled={() => true} getDoc={() => document}>
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="First name" placeholder="First name" />
+            <input aria-label="first name" placeholder="First name" />
             <Portal container={container}>
-              <input aria-label="Last name" placeholder="Last name" />
+              <input aria-label="last name" placeholder="Last name" />
             </Portal>
             <button type="button" onClick={() => setOpen(false)}>
               Close

From c6db23d7dfaa34a0cf7004d23123ca0547be2d7a Mon Sep 17 00:00:00 2001
From: Olivier Tassinari <olivier.tassinari@gmail.com>
Date: Thu, 6 Aug 2020 20:02:25 +0200
Subject: [PATCH 5/6] sebastian's review

---
 docs/src/pages/components/trap-focus/trap-focus.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/src/pages/components/trap-focus/trap-focus.md b/docs/src/pages/components/trap-focus/trap-focus.md
index fad9d8dcaebfbd..1a935928c4ce3c 100644
--- a/docs/src/pages/components/trap-focus/trap-focus.md
+++ b/docs/src/pages/components/trap-focus/trap-focus.md
@@ -7,6 +7,8 @@ components: Unstable_TrapFocus
 
 <p class="description">Trap focus within a DOM node.</p>
 
+> ⚠️ The component is experimental and unstable.
+
 `TrapFocus` is a utility 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.
 

From 646f0a54964efbb05f784ce5bb39963a7dd16486 Mon Sep 17 00:00:00 2001
From: Olivier Tassinari <olivier.tassinari@gmail.com>
Date: Fri, 7 Aug 2020 17:22:50 +0200
Subject: [PATCH 6/6] sebastian's review

---
 .../components/trap-focus/BasicTrapFocus.js   | 10 ++++--
 .../components/trap-focus/BasicTrapFocus.tsx  | 10 ++++--
 .../trap-focus/DisableEnforceFocus.js         | 10 ++++--
 .../trap-focus/DisableEnforceFocus.tsx        | 10 ++++--
 .../trap-focus/DisableRestoreFocus.js         | 31 -------------------
 .../trap-focus/DisableRestoreFocus.tsx        | 31 -------------------
 .../components/trap-focus/LazyTrapFocus.js    | 10 ++++--
 .../components/trap-focus/LazyTrapFocus.tsx   | 10 ++++--
 .../components/trap-focus/PortalTrapFocus.js  | 10 ++++--
 .../components/trap-focus/PortalTrapFocus.tsx | 10 ++++--
 .../pages/components/trap-focus/trap-focus.md | 13 ++------
 11 files changed, 67 insertions(+), 88 deletions(-)
 delete mode 100644 docs/src/pages/components/trap-focus/DisableRestoreFocus.js
 delete mode 100644 docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx

diff --git a/docs/src/pages/components/trap-focus/BasicTrapFocus.js b/docs/src/pages/components/trap-focus/BasicTrapFocus.js
index 25147089d02dad..706c7cd40acb7f 100644
--- a/docs/src/pages/components/trap-focus/BasicTrapFocus.js
+++ b/docs/src/pages/components/trap-focus/BasicTrapFocus.js
@@ -13,8 +13,14 @@ export default function BasicTrapFocus() {
         <TrapFocus open isEnabled={() => true} getDoc={() => document}>
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="first name" placeholder="First name" />
-            <input aria-label="last name" placeholder="Last name" />
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/BasicTrapFocus.tsx b/docs/src/pages/components/trap-focus/BasicTrapFocus.tsx
index 25147089d02dad..706c7cd40acb7f 100644
--- a/docs/src/pages/components/trap-focus/BasicTrapFocus.tsx
+++ b/docs/src/pages/components/trap-focus/BasicTrapFocus.tsx
@@ -13,8 +13,14 @@ export default function BasicTrapFocus() {
         <TrapFocus open isEnabled={() => true} getDoc={() => document}>
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="first name" placeholder="First name" />
-            <input aria-label="last name" placeholder="Last name" />
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/DisableEnforceFocus.js b/docs/src/pages/components/trap-focus/DisableEnforceFocus.js
index daae758760c840..0284eb245f51d4 100644
--- a/docs/src/pages/components/trap-focus/DisableEnforceFocus.js
+++ b/docs/src/pages/components/trap-focus/DisableEnforceFocus.js
@@ -18,8 +18,14 @@ export default function DisableEnforceFocus() {
         >
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="first name" placeholder="First name" />
-            <input aria-label="last name" placeholder="Last name" />
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx b/docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx
index daae758760c840..0284eb245f51d4 100644
--- a/docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx
+++ b/docs/src/pages/components/trap-focus/DisableEnforceFocus.tsx
@@ -18,8 +18,14 @@ export default function DisableEnforceFocus() {
         >
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="first name" placeholder="First name" />
-            <input aria-label="last name" placeholder="Last name" />
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/DisableRestoreFocus.js b/docs/src/pages/components/trap-focus/DisableRestoreFocus.js
deleted file mode 100644
index c0d286b8c51dd4..00000000000000
--- a/docs/src/pages/components/trap-focus/DisableRestoreFocus.js
+++ /dev/null
@@ -1,31 +0,0 @@
-import * as React from 'react';
-import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
-
-export default function DisableRestoreFocus() {
-  const [open, setOpen] = React.useState(false);
-  return (
-    <div>
-      <button type="button" onClick={() => setOpen(true)}>
-        Open
-      </button>
-      <br />
-      {open && (
-        <TrapFocus
-          disableRestoreFocus
-          open
-          isEnabled={() => true}
-          getDoc={() => document}
-        >
-          <div tabIndex={-1}>
-            <h3>Quick form</h3>
-            <input aria-label="first name" placeholder="First name" />
-            <input aria-label="last name" placeholder="Last name" />
-            <button type="button" onClick={() => setOpen(false)}>
-              Close
-            </button>
-          </div>
-        </TrapFocus>
-      )}
-    </div>
-  );
-}
diff --git a/docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx b/docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx
deleted file mode 100644
index c0d286b8c51dd4..00000000000000
--- a/docs/src/pages/components/trap-focus/DisableRestoreFocus.tsx
+++ /dev/null
@@ -1,31 +0,0 @@
-import * as React from 'react';
-import TrapFocus from '@material-ui/core/Unstable_TrapFocus';
-
-export default function DisableRestoreFocus() {
-  const [open, setOpen] = React.useState(false);
-  return (
-    <div>
-      <button type="button" onClick={() => setOpen(true)}>
-        Open
-      </button>
-      <br />
-      {open && (
-        <TrapFocus
-          disableRestoreFocus
-          open
-          isEnabled={() => true}
-          getDoc={() => document}
-        >
-          <div tabIndex={-1}>
-            <h3>Quick form</h3>
-            <input aria-label="first name" placeholder="First name" />
-            <input aria-label="last name" placeholder="Last name" />
-            <button type="button" onClick={() => setOpen(false)}>
-              Close
-            </button>
-          </div>
-        </TrapFocus>
-      )}
-    </div>
-  );
-}
diff --git a/docs/src/pages/components/trap-focus/LazyTrapFocus.js b/docs/src/pages/components/trap-focus/LazyTrapFocus.js
index 1858a850f19369..2c1cc3a324f31a 100644
--- a/docs/src/pages/components/trap-focus/LazyTrapFocus.js
+++ b/docs/src/pages/components/trap-focus/LazyTrapFocus.js
@@ -18,8 +18,14 @@ export default function LazyTrapFocus() {
         >
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="first name" placeholder="First name" />
-            <input aria-label="last name" placeholder="Last name" />
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/LazyTrapFocus.tsx b/docs/src/pages/components/trap-focus/LazyTrapFocus.tsx
index 1858a850f19369..2c1cc3a324f31a 100644
--- a/docs/src/pages/components/trap-focus/LazyTrapFocus.tsx
+++ b/docs/src/pages/components/trap-focus/LazyTrapFocus.tsx
@@ -18,8 +18,14 @@ export default function LazyTrapFocus() {
         >
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="first name" placeholder="First name" />
-            <input aria-label="last name" placeholder="Last name" />
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
+            <label>
+              Last name: <input type="text" />
+            </label>
+            <br />
             <button type="button" onClick={() => setOpen(false)}>
               Close
             </button>
diff --git a/docs/src/pages/components/trap-focus/PortalTrapFocus.js b/docs/src/pages/components/trap-focus/PortalTrapFocus.js
index f8efd5424d9496..bb33586bd46583 100644
--- a/docs/src/pages/components/trap-focus/PortalTrapFocus.js
+++ b/docs/src/pages/components/trap-focus/PortalTrapFocus.js
@@ -16,9 +16,15 @@ export default function PortalTrapFocus() {
         <TrapFocus open isEnabled={() => true} getDoc={() => document}>
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="first name" placeholder="First name" />
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
             <Portal container={container}>
-              <input aria-label="last name" placeholder="Last name" />
+              <label>
+                Last name: <input type="text" />
+              </label>
+              <br />
             </Portal>
             <button type="button" onClick={() => setOpen(false)}>
               Close
diff --git a/docs/src/pages/components/trap-focus/PortalTrapFocus.tsx b/docs/src/pages/components/trap-focus/PortalTrapFocus.tsx
index 9eafee9356a7e9..39100661ecb54f 100644
--- a/docs/src/pages/components/trap-focus/PortalTrapFocus.tsx
+++ b/docs/src/pages/components/trap-focus/PortalTrapFocus.tsx
@@ -16,9 +16,15 @@ export default function PortalTrapFocus() {
         <TrapFocus open isEnabled={() => true} getDoc={() => document}>
           <div tabIndex={-1}>
             <h3>Quick form</h3>
-            <input aria-label="first name" placeholder="First name" />
+            <label>
+              First name: <input type="text" />
+            </label>
+            <br />
             <Portal container={container}>
-              <input aria-label="last name" placeholder="Last name" />
+              <label>
+                Last name: <input type="text" />
+              </label>
+              <br />
             </Portal>
             <button type="button" onClick={() => setOpen(false)}>
               Close
diff --git a/docs/src/pages/components/trap-focus/trap-focus.md b/docs/src/pages/components/trap-focus/trap-focus.md
index 1a935928c4ce3c..7f164687eb9645 100644
--- a/docs/src/pages/components/trap-focus/trap-focus.md
+++ b/docs/src/pages/components/trap-focus/trap-focus.md
@@ -9,10 +9,10 @@ components: Unstable_TrapFocus
 
 > ⚠️ The component is experimental and unstable.
 
-`TrapFocus` is a utility component that manages focus for its descendants.
+`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+Tab</kbd> will rotate focus within the inner focusable elements of the component.
+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
@@ -29,19 +29,12 @@ You can disable this behavior with the `disableEnforceFocus` prop.
 
 {{"demo": "pages/components/trap-focus/DisableEnforceFocus.js"}}
 
-## Disable restore focus
-
-The component restores the focus back to the previously focused element when it deactivates, for example back to the button which opened a dialog.
-
-You can disable this behavior with the `disableRestoreFocus` prop.
-
-{{"demo": "pages/components/trap-focus/DisableRestoreFocus.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"}}