From c7666f54c403a90569eb1b18b68801259d92fe14 Mon Sep 17 00:00:00 2001
From: Michail Yasonik <michail.yasonik@elastic.co>
Date: Wed, 15 Jul 2020 13:22:48 -0400
Subject: [PATCH] [Docs] Adding more acccessibility-focused notes and examples
 (#3714)

* making more a11y callouts in docs

* Apply suggestions from code review

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>

* prettier update

Co-authored-by: gchaps <33642766+gchaps@users.noreply.github.com>
---
 src-docs/src/views/flyout/flyout.js           |  1 +
 src-docs/src/views/flyout/flyout_banner.js    |  5 +-
 .../src/views/flyout/flyout_complicated.js    |  1 +
 src-docs/src/views/flyout/flyout_example.js   | 59 +++++++++++------
 src-docs/src/views/flyout/flyout_large.js     |  1 +
 src-docs/src/views/flyout/flyout_max_width.js |  1 +
 src-docs/src/views/flyout/flyout_small.js     |  1 -
 src-docs/src/views/modal/modal_example.js     |  2 +-
 src-docs/src/views/popover/popover.js         |  1 +
 src-docs/src/views/popover/popover_block.js   |  1 +
 .../src/views/popover/popover_container.js    |  1 +
 src-docs/src/views/popover/popover_example.js | 65 ++++++++++++-------
 src-docs/src/views/popover/popover_fixed.js   |  1 +
 .../popover/popover_htmlelement_anchor.js     |  1 +
 src-docs/src/views/popover/trap_focus.js      |  1 -
 .../src/views/tool_tip/tool_tip_example.js    | 31 +++++++++
 16 files changed, 126 insertions(+), 47 deletions(-)

diff --git a/src-docs/src/views/flyout/flyout.js b/src-docs/src/views/flyout/flyout.js
index e2190c51a85..ff9fd049086 100644
--- a/src-docs/src/views/flyout/flyout.js
+++ b/src-docs/src/views/flyout/flyout.js
@@ -30,6 +30,7 @@ export default () => {
   if (isFlyoutVisible) {
     flyout = (
       <EuiFlyout
+        ownFocus
         onClose={() => setIsFlyoutVisible(false)}
         aria-labelledby="flyoutTitle">
         <EuiFlyoutHeader hasBorder>
diff --git a/src-docs/src/views/flyout/flyout_banner.js b/src-docs/src/views/flyout/flyout_banner.js
index 8b4be85cc2e..a787f4631be 100644
--- a/src-docs/src/views/flyout/flyout_banner.js
+++ b/src-docs/src/views/flyout/flyout_banner.js
@@ -44,7 +44,10 @@ export default () => {
 
   if (isFlyoutVisible) {
     flyout = (
-      <EuiFlyout onClose={closeFlyout} aria-labelledby="flyoutWithBannerTitle">
+      <EuiFlyout
+        ownFocus
+        onClose={closeFlyout}
+        aria-labelledby="flyoutWithBannerTitle">
         <EuiFlyoutHeader hasBorder>
           <EuiTitle size="m">
             <h2 id="flyoutWithBannerTitle">A flyout with a banner</h2>
diff --git a/src-docs/src/views/flyout/flyout_complicated.js b/src-docs/src/views/flyout/flyout_complicated.js
index d5e8aab5703..cce6ee80904 100644
--- a/src-docs/src/views/flyout/flyout_complicated.js
+++ b/src-docs/src/views/flyout/flyout_complicated.js
@@ -178,6 +178,7 @@ export default () => {
   if (isFlyoutVisible) {
     flyout = (
       <EuiFlyout
+        ownFocus
         onClose={closeFlyout}
         hideCloseButton
         aria-labelledby="flyoutComplicatedTitle">
diff --git a/src-docs/src/views/flyout/flyout_example.js b/src-docs/src/views/flyout/flyout_example.js
index f94c6cbb0a5..e341fe23d79 100644
--- a/src-docs/src/views/flyout/flyout_example.js
+++ b/src-docs/src/views/flyout/flyout_example.js
@@ -37,7 +37,7 @@ import FlyoutWithBanner from './flyout_banner';
 const flyoutWithBannerSource = require('!!raw-loader!./flyout_banner');
 const flyoutWithBannerHtml = renderToHtml(FlyoutWithBanner);
 
-const flyOutSnippet = `<EuiFlyout onClose={closeFlyout}>
+const flyOutSnippet = `<EuiFlyout ownFocus onClose={closeFlyout}>
   <EuiFlyoutHeader hasBorder aria-labelledby={flyoutHeadingId}>
     <EuiTitle>
       <h2 id={flyoutHeadingId}><!-- Defaults to medium size. Change the heading level based on your context. --></h2>
@@ -49,7 +49,7 @@ const flyOutSnippet = `<EuiFlyout onClose={closeFlyout}>
 </EuiFlyout>
 `;
 
-const flyoutComplicatedSnippet = `<EuiFlyout onClose={closeFlyout}>
+const flyoutComplicatedSnippet = `<EuiFlyout ownFocus onClose={closeFlyout}>
   <EuiFlyoutHeader hasBorder aria-labelledby={flyoutHeadingId}>
     <EuiTitle>
       <h2 id={flyoutHeadingId}><!-- Defaults to medium size. Change the heading level based on your context. --></h2>
@@ -67,7 +67,7 @@ const flyoutComplicatedSnippet = `<EuiFlyout onClose={closeFlyout}>
 </EuiFlyout>
 `;
 
-const flyoutSmallSnippet = `<EuiFlyout size="s" ownFocus onClose={closeFlyout}>
+const flyoutSmallSnippet = `<EuiFlyout size="s" onClose={closeFlyout}>
   <EuiFlyoutHeader hasBorder aria-labelledby={flyoutHeadingId}>
     <EuiTitle>
       <h2 id={flyoutHeadingId}><!-- Defaults to medium size. Change the heading level based on your context. --></h2>
@@ -79,7 +79,7 @@ const flyoutSmallSnippet = `<EuiFlyout size="s" ownFocus onClose={closeFlyout}>
 </EuiFlyout>
 `;
 
-const flyoutMaxWidthSnippet = `<EuiFlyout maxWidth={448} onClose={closeFlyout}>
+const flyoutMaxWidthSnippet = `<EuiFlyout ownFocus maxWidth={448} onClose={closeFlyout}>
   <EuiFlyoutHeader hasBorder aria-labelledby={flyoutHeadingId}>
     <EuiTitle>
       <h2 id={flyoutHeadingId}><!-- Defaults to medium size. Change the heading level based on your context. --></h2>
@@ -91,7 +91,7 @@ const flyoutMaxWidthSnippet = `<EuiFlyout maxWidth={448} onClose={closeFlyout}>
 </EuiFlyout>
 `;
 
-const flyoutLargeSnippet = `<EuiFlyout size="l" onClose={closeFlyout}>
+const flyoutLargeSnippet = `<EuiFlyout ownFocus size="l" onClose={closeFlyout}>
   <EuiFlyoutHeader hasBorder aria-labelledby={flyoutHeadingId}>
     <EuiTitle>
       <h2 id={flyoutHeadingId}><!-- Defaults to medium size. Change the heading level based on your context. --></h2>
@@ -103,7 +103,7 @@ const flyoutLargeSnippet = `<EuiFlyout size="l" onClose={closeFlyout}>
 </EuiFlyout>
 `;
 
-const flyoutWithBannerSnippet = `<EuiFlyout onClose={closeFlyout}>
+const flyoutWithBannerSnippet = `<EuiFlyout ownFocus onClose={closeFlyout}>
   <EuiFlyoutHeader hasBorder aria-labelledby={flyoutHeadingId}>
     <EuiTitle>
       <h2 id={flyoutHeadingId}><!-- Defaults to medium size. Change the heading level based on your context. --></h2>
@@ -130,19 +130,24 @@ export const FlyoutExample = {
         },
       ],
       text: (
-        <div>
+        <>
           <p>
             <strong>EuiFlyout</strong> is a fixed position panel that pops in
             from the right side of the screen. It should be used any time you
             need to perform quick, individual actions to a larger page or list.
           </p>
 
-          <p>
-            For accessibility, use{' '}
-            <EuiCode>{'aria-labelledby={headingId}'}</EuiCode> to announce the
-            flyout to screen readers when the user opens it.
-          </p>
-        </div>
+          <EuiCallOut
+            iconType="accessibility"
+            title={
+              <>
+                Use <EuiCode>{'aria-labelledby={headingId}'}</EuiCode> and{' '}
+                <EuiCode>ownFocus</EuiCode> to announce the flyout to screen
+                readers when the user opens it.
+              </>
+            }
+          />
+        </>
       ),
       props: { EuiFlyout, EuiFlyoutHeader, EuiFlyoutBody },
       snippet: flyOutSnippet,
@@ -195,7 +200,7 @@ export const FlyoutExample = {
       demo: <FlyoutWithBanner />,
     },
     {
-      title: 'Small flyout, ownFocus',
+      title: 'Small flyout, without ownFocus',
       source: [
         {
           type: GuideSectionTypes.JS,
@@ -207,12 +212,26 @@ export const FlyoutExample = {
         },
       ],
       text: (
-        <p>
-          In this example, we set <EuiCode>size</EuiCode> to{' '}
-          <EuiCode>s</EuiCode> and apply the <EuiCode>ownFocus</EuiCode> prop.
-          The latter not only traps the focus of our flyout, but also adds
-          background overlay to reinforce your boundaries.
-        </p>
+        <>
+          <p>
+            In this example, we set <EuiCode>size</EuiCode> to{' '}
+            <EuiCode>s</EuiCode> and remove the <EuiCode>ownFocus</EuiCode>{' '}
+            prop. The latter not only removes the focus trap around the flyout,
+            but also removes the background overlay that reinforces your
+            boundaries.
+          </p>
+          <EuiCallOut
+            iconType="accessibility"
+            color="warning"
+            title={
+              <>
+                Removing <EuiCode>ownFocus</EuiCode> makes it difficult for
+                keyboard-only and screen reader users to navigate to and from
+                your flyout.
+              </>
+            }
+          />
+        </>
       ),
       snippet: flyoutSmallSnippet,
       demo: <FlyoutSmall />,
diff --git a/src-docs/src/views/flyout/flyout_large.js b/src-docs/src/views/flyout/flyout_large.js
index f1c2ce02929..45c16ed6a87 100644
--- a/src-docs/src/views/flyout/flyout_large.js
+++ b/src-docs/src/views/flyout/flyout_large.js
@@ -20,6 +20,7 @@ export default () => {
   if (isFlyoutVisible) {
     flyout = (
       <EuiFlyout
+        ownFocus
         onClose={closeFlyout}
         size="l"
         aria-labelledby="flyoutLargeTitle">
diff --git a/src-docs/src/views/flyout/flyout_max_width.js b/src-docs/src/views/flyout/flyout_max_width.js
index 5fafe0c0fe9..d781bb615de 100644
--- a/src-docs/src/views/flyout/flyout_max_width.js
+++ b/src-docs/src/views/flyout/flyout_max_width.js
@@ -47,6 +47,7 @@ export default () => {
 
     flyout = (
       <EuiFlyout
+        ownFocus
         onClose={closeFlyout}
         aria-labelledby="flyoutMaxWidthTitle"
         size={flyoutSize}
diff --git a/src-docs/src/views/flyout/flyout_small.js b/src-docs/src/views/flyout/flyout_small.js
index 8e6d0a988b4..3986deeef90 100644
--- a/src-docs/src/views/flyout/flyout_small.js
+++ b/src-docs/src/views/flyout/flyout_small.js
@@ -20,7 +20,6 @@ export default () => {
   if (isFlyoutVisible) {
     flyout = (
       <EuiFlyout
-        ownFocus
         onClose={closeFlyout}
         size="s"
         aria-labelledby="flyoutSmallTitle">
diff --git a/src-docs/src/views/modal/modal_example.js b/src-docs/src/views/modal/modal_example.js
index 8c08fb43de5..d601a9de739 100644
--- a/src-docs/src/views/modal/modal_example.js
+++ b/src-docs/src/views/modal/modal_example.js
@@ -77,7 +77,7 @@ export const ModalExample = {
         <p>
           Use a modal to temporarily interrupt a user’s current task and block
           interactions to the content below it. Be sure to read the full{' '}
-          <Link to="/guidelines/modals">modal usage guidelines</Link>.
+          <Link to="/layout/modal/guidelines">modal usage guidelines</Link>.
         </p>
       ),
       props: { EuiModal, EuiOverlayMask },
diff --git a/src-docs/src/views/popover/popover.js b/src-docs/src/views/popover/popover.js
index b1412892282..8798fedd8f7 100644
--- a/src-docs/src/views/popover/popover.js
+++ b/src-docs/src/views/popover/popover.js
@@ -16,6 +16,7 @@ export default () => {
 
   return (
     <EuiPopover
+      ownFocus
       button={button}
       isOpen={isPopoverOpen}
       closePopover={closePopover}>
diff --git a/src-docs/src/views/popover/popover_block.js b/src-docs/src/views/popover/popover_block.js
index 327486d094a..6462d4295e0 100644
--- a/src-docs/src/views/popover/popover_block.js
+++ b/src-docs/src/views/popover/popover_block.js
@@ -16,6 +16,7 @@ export default () => {
 
   return (
     <EuiPopover
+      ownFocus
       button={button}
       isOpen={isPopoverOpen}
       closePopover={closePopover}
diff --git a/src-docs/src/views/popover/popover_container.js b/src-docs/src/views/popover/popover_container.js
index 03e5aaffafe..21f14628ccb 100644
--- a/src-docs/src/views/popover/popover_container.js
+++ b/src-docs/src/views/popover/popover_container.js
@@ -29,6 +29,7 @@ export default () => {
   return (
     <EuiPanel panelRef={setPanelRef}>
       <EuiPopover
+        ownFocus
         button={button}
         isOpen={isPopoverOpen}
         closePopover={closePopover}
diff --git a/src-docs/src/views/popover/popover_example.js b/src-docs/src/views/popover/popover_example.js
index 7ed4a09f063..1211336be6c 100644
--- a/src-docs/src/views/popover/popover_example.js
+++ b/src-docs/src/views/popover/popover_example.js
@@ -10,6 +10,7 @@ import {
   EuiPopover,
   EuiPopoverTitle,
   EuiPopoverFooter,
+  EuiCallOut,
 } from '../../../../src/components';
 
 import Popover from './popover';
@@ -57,6 +58,7 @@ const inputPopoverSource = require('!!raw-loader!./input_popover');
 const inputPopoverHtml = renderToHtml(PopoverBlock);
 
 const popOverSnippet = `<EuiPopover
+  ownFocus
   button={button}
   isOpen={isPopoverOpen}
   closePopover={closePopover}>
@@ -65,13 +67,13 @@ const popOverSnippet = `<EuiPopover
 
 const trapFocusSnippet = `<EuiPopover
   button={button}
-  ownFocus
   isOpen={isPopoverOpen}
   closePopover={closePopover}>
   <!-- Popover content -->
 </EuiPopover>`;
 
 const popoverAnchorSnippet = `<EuiPopover
+  ownFocus
   button={button}
   isOpen={isPopoverOpen}
   closePopover={closePopover}
@@ -80,6 +82,7 @@ const popoverAnchorSnippet = `<EuiPopover
 </EuiPopover>`;
 
 const popoverWithTitleSnippet = `<EuiPopover
+  ownFocus
   button={button}
   isOpen={isPopoverOpen}
   closePopover={closePopover}>
@@ -99,6 +102,7 @@ const popoverPanelClassNameSnippet = `<EuiPopover
 </EuiPopover>`;
 
 const popoverWithTitlePaddingSnippet = `<EuiPopover
+  ownFocus
   button={button}
   isOpen={isPopoverOpen}
   closePopover={closePopover}
@@ -108,6 +112,7 @@ const popoverWithTitlePaddingSnippet = `<EuiPopover
 </EuiPopover>`;
 
 const popoverContainerSnippet = `<EuiPopover
+  ownFocus
   button={button}
   isOpen={isPopoverOpen}
   closePopover={closePopover}
@@ -116,6 +121,7 @@ const popoverContainerSnippet = `<EuiPopover
 </EuiPopover>`;
 
 const popoverFixedSnippet = `<EuiPopover
+  ownFocus
   button={button}
   isOpen={isPopoverOpen}
   closePopover={closePopover}
@@ -124,6 +130,7 @@ const popoverFixedSnippet = `<EuiPopover
 </EuiPopover>`;
 
 const popoverBlockSnippet = `<EuiPopover
+  ownFocus
   button={button}
   isOpen={isPopoverOpen}
   closePopover={closePopover}
@@ -162,28 +169,6 @@ export const PopoverExample = {
       snippet: popOverSnippet,
       demo: <Popover />,
     },
-    {
-      title: 'Trap focus',
-      source: [
-        {
-          type: GuideSectionTypes.JS,
-          code: trapFocusSource,
-        },
-        {
-          type: GuideSectionTypes.HTML,
-          code: trapFocusHtml,
-        },
-      ],
-      text: (
-        <p>
-          If the popover should be responsible for trapping the focus within
-          itself (as opposed to a child component), then you should set{' '}
-          <EuiCode>ownFocus</EuiCode>.
-        </p>
-      ),
-      snippet: trapFocusSnippet,
-      demo: <TrapFocus />,
-    },
     {
       title: 'Anchor position',
       source: [
@@ -435,5 +420,39 @@ export const PopoverExample = {
       snippet: inputPopoverSnippet,
       demo: <InputPopover />,
     },
+    {
+      title: 'Removing the focus focus',
+      source: [
+        {
+          type: GuideSectionTypes.JS,
+          code: trapFocusSource,
+        },
+        {
+          type: GuideSectionTypes.HTML,
+          code: trapFocusHtml,
+        },
+      ],
+      text: (
+        <>
+          <p>
+            If the popover cannot trap focus within itself, then you can remove{' '}
+            <EuiCode>ownFocus</EuiCode>.
+          </p>
+          <EuiCallOut
+            iconType="accessibility"
+            color="warning"
+            title={
+              <>
+                Removing <EuiCode>ownFocus</EuiCode> makes it difficult for
+                keyboard-only and screen reader users to navigate to and from
+                your popover.
+              </>
+            }
+          />
+        </>
+      ),
+      snippet: trapFocusSnippet,
+      demo: <TrapFocus />,
+    },
   ],
 };
diff --git a/src-docs/src/views/popover/popover_fixed.js b/src-docs/src/views/popover/popover_fixed.js
index e94932679dd..6fa4e9e482a 100644
--- a/src-docs/src/views/popover/popover_fixed.js
+++ b/src-docs/src/views/popover/popover_fixed.js
@@ -27,6 +27,7 @@ export default () => {
       <EuiButton onClick={toggleExample}>Toggle Example</EuiButton>
       {isExampleShown && (
         <EuiPopover
+          ownFocus
           button={button}
           isOpen={isPopoverOpen}
           closePopover={closePopover}
diff --git a/src-docs/src/views/popover/popover_htmlelement_anchor.js b/src-docs/src/views/popover/popover_htmlelement_anchor.js
index 05715e05c20..be40eedb9a3 100644
--- a/src-docs/src/views/popover/popover_htmlelement_anchor.js
+++ b/src-docs/src/views/popover/popover_htmlelement_anchor.js
@@ -18,6 +18,7 @@ const PopoverApp = props => {
 
   return (
     <EuiWrappingPopover
+      ownFocus
       button={props.anchor}
       isOpen={isPopoverOpen}
       closePopover={closePopover}>
diff --git a/src-docs/src/views/popover/trap_focus.js b/src-docs/src/views/popover/trap_focus.js
index 73d8688cfc1..5f1a8db035f 100644
--- a/src-docs/src/views/popover/trap_focus.js
+++ b/src-docs/src/views/popover/trap_focus.js
@@ -22,7 +22,6 @@ export default () => {
 
   return (
     <EuiPopover
-      ownFocus
       button={button}
       isOpen={isPopoverOpen}
       closePopover={closePopover}
diff --git a/src-docs/src/views/tool_tip/tool_tip_example.js b/src-docs/src/views/tool_tip/tool_tip_example.js
index 76e563047cc..84770f3da15 100644
--- a/src-docs/src/views/tool_tip/tool_tip_example.js
+++ b/src-docs/src/views/tool_tip/tool_tip_example.js
@@ -1,4 +1,5 @@
 import React, { Fragment } from 'react';
+import { Link } from 'react-router-dom';
 
 import { renderToHtml } from '../../services';
 
@@ -86,6 +87,36 @@ export const ToolTipExample = {
       </EuiText>
 
       <EuiSpacer size="l" />
+
+      <EuiCallOut
+        iconType="accessibility"
+        color="warning"
+        title={
+          <>
+            Anchoring a tooltip to a non-interactive element makes it difficult
+            for keyboard-only and screen reader users to read.
+          </>
+        }
+      />
+
+      <EuiSpacer size="l" />
+
+      <EuiCallOut
+        iconType="accessibility"
+        color="warning"
+        title={
+          <>
+            Putting anything other than plain text in a tooltip is lost on
+            screen readers. Consider switching to{' '}
+            <Link href="/layout/popover">
+              <strong>EuiPopover</strong>
+            </Link>{' '}
+            if you need more content inside a tooltip.
+          </>
+        }
+      />
+
+      <EuiSpacer size="l" />
     </Fragment>
   ),
   sections: [