[Docs] Adding more acccessibility-focused notes and examples (elastic…

…#3714) * making more a11y callouts in docs * Apply suggestions from code review Co-authored-by: gchaps <[email protected]> * prettier update Co-authored-by: gchaps <[email protected]>
anishagg17 · Jul 20, 2020 · c7666f5 · c7666f5
1 parent 0a9cb7a
commit c7666f5
Show file tree

Hide file tree

Showing 16 changed files with 126 additions and 47 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -22,7 +22,6 @@ export default () => {
 
   return (
     <EuiPopover
-      ownFocus
       button={button}
       isOpen={isPopoverOpen}
       closePopover={closePopover}