[PR feedback] Docs & Comments & Updates styles for EuiScreenReaderOnly

cee-chen#2

* [Docs] Updated Accessiblity Utility pages with more nuances about EuiScreenReaderOnly

* Remove `euiScreenReaderOnly` mixin from checkbox and radio styles in favor of always having the input

* Commented Sass

* [EuiLink] Position relative if `target=_blank` for positioning screen reader text

src-docs/src/views/accessibility/accessibility_example.js

@@ -1,7 +1,5 @@
 import React from 'react';
 
-import { renderToHtml } from '../../services';
-
 import { GuideSectionTypes } from '../../components';
 
 import {
@@ -10,32 +8,25 @@ import {
   EuiLink,
   EuiSkipLink,
   EuiScreenReaderOnly,
+  EuiSpacer,
 } from '../../../../src/components';
 
 import ScreenReaderOnly from './screen_reader';
+import ScreenReaderFocus from './screen_reader_focus';
+import ScreenReaderButton from './screen_reader_button';
 import SkipLink from './skip_link';
 
-const screenReaderOnlyHtml = renderToHtml(ScreenReaderOnly);
 const screenReaderOnlySource = require('!!raw-loader!./screen_reader');
-const screenReaderOnlySnippet = [
-  `<EuiScreenReaderOnly>
-  <!-- visually hidden content -->
-</EuiScreenReaderOnly>
-`,
-  `<EuiScreenReaderOnly showOnFocus>
-  <!-- visually hidden content, displayed on focus -->
-</EuiScreenReaderOnly>
-`,
-];
+const screenReaderFocusSource = require('!!raw-loader!./screen_reader_focus');
+const screenReaderButtonSource = require('!!raw-loader!./screen_reader_button');
 
-const skipLinkHtml = renderToHtml(SkipLink);
 const skipLinkSource = require('!!raw-loader!./skip_link');
 const skipLinkSnippet = [
-  `<EuiSkipLink destinationId="myAnchorId">
+  `<EuiSkipLink destinationId={myAnchorId}>
   Skip to content
 </EuiSkipLink>
 `,
-  `<EuiSkipLink destinationId="myAnchorId" position="fixed">
+  `<EuiSkipLink destinationId={myAnchorId} position="fixed">
   Skip to main content
 </EuiSkipLink>
 `,
@@ -51,19 +42,15 @@ export const AccessibilityExample = {
           type: GuideSectionTypes.JS,
           code: screenReaderOnlySource,
         },
-        {
-          type: GuideSectionTypes.HTML,
-          code: screenReaderOnlyHtml,
-        },
       ],
       text: (
-        <div>
+        <>
           <p>
-            Use the <strong>EuiScreenReaderOnly</strong> component to visually
-            hide elements while still allowing them to be read by screen
-            readers. In certain cases, you may want to use the{' '}
-            <EuiCode>showOnFocus</EuiCode> prop to display screen reader-only
-            content when in focus.
+            Using <strong>EuiScreenReaderOnly</strong> hides the wrapped element
+            from the page, but keeps it accessible for screen readers to provide
+            more context. It should be used primarily to mask{' '}
+            <strong>text</strong> and requires the child to be a single React
+            element for cloning.
           </p>
           <EuiCallOut
             color="warning"
@@ -75,40 +62,119 @@ export const AccessibilityExample = {
               provides functionality or interactivity) is important enough to
               provide to screen reader users, it should probably be made
               available to all users.&quot;{' '}
-              <EuiLink
-                href="http://webaim.org/techniques/css/invisiblecontent/"
-                external
-              >
+              <EuiLink href="http://webaim.org/techniques/css/invisiblecontent/">
                 Learn more about invisible content
               </EuiLink>
             </p>
           </EuiCallOut>
-        </div>
+          <EuiSpacer />
+          <p>
+            <em>
+              Using a screen reader, verify that there is a second paragraph.
+            </em>
+          </p>
+        </>
       ),
       props: {
         EuiScreenReaderOnly,
       },
-      snippet: screenReaderOnlySnippet,
+      snippet: `<EuiScreenReaderOnly>
+  <!-- visually hidden content -->
+</EuiScreenReaderOnly>`,
       demo: <ScreenReaderOnly />,
     },
     {
-      title: 'Skip link',
       source: [
         {
           type: GuideSectionTypes.JS,
-          code: skipLinkSource,
+          code: screenReaderButtonSource,
+        },
+      ],
+      text: (
+        <>
+          <h3>Within a button</h3>
+          <p>
+            If the screen reader content is <strong>contained within</strong> a
+            focusable element, you should consider adding{' '}
+            <EuiCode language="scss">{'position: relative;'}</EuiCode> to the
+            focusable element. This will fix any screen reader focus rings to
+            stay within the bounds of the focusable element.
+          </p>
+          <p>
+            <em>
+              Using a screen reader, tab through the following example with your
+              keyboard to verify the focus outline and screen reader text.
+            </em>
+          </p>
+        </>
+      ),
+      props: {
+        EuiScreenReaderOnly,
+      },
+      snippet: `<button style={{ position: 'relative' }}>
+  Button text
+  <EuiScreenReaderOnly>
+    <!-- visually hidden content -->
+  </EuiScreenReaderOnly>
+</button>`,
+      demo: <ScreenReaderButton />,
+    },
+    {
+      source: [
+        {
+          type: GuideSectionTypes.JS,
+          code: screenReaderFocusSource,
         },
+      ],
+      text: (
+        <>
+          <h3>Showing on focus</h3>
+          <p>
+            If the wrapped element <strong>is focusable</strong>, you must use
+            the <EuiCode>showOnFocus</EuiCode> prop to visibly show the element
+            to all users when focused.
+          </p>
+          <p>
+            <em>
+              Tab through the following example with your keyboard to verify the
+              element is visible on focus.
+            </em>
+          </p>
+        </>
+      ),
+      props: {
+        EuiScreenReaderOnly,
+      },
+      snippet: `<EuiScreenReaderOnly showOnFocus>
+  <!-- visually hidden content, displayed on focus -->
+</EuiScreenReaderOnly>`,
+      demo: <ScreenReaderFocus />,
+    },
+    {
+      title: 'Skip link',
+      source: [
         {
-          type: GuideSectionTypes.HTML,
-          code: skipLinkHtml,
+          type: GuideSectionTypes.JS,
+          code: skipLinkSource,
         },
       ],
       text: (
-        <p>
-          The <strong>EuiSkipLink</strong> component allows users to bypass
-          navigation, or ornamental elements, and quickly reach the main content
-          of the page.
-        </p>
+        <>
+          <p>
+            The <strong>EuiSkipLink</strong> component allows users to bypass
+            navigation, or ornamental elements, and quickly reach the main
+            content of the page. It requires a <EuiCode>destinationId</EuiCode>{' '}
+            which should match the <EuiCode>id</EuiCode> of your main content.
+            You can also change the <EuiCode>position</EuiCode> to{' '}
+            <EuiCode>fixed</EuiCode>.
+          </p>
+          <p>
+            <em>
+              Tab through the following section to verify the{' '}
+              <strong>Skip to content</strong> button is visible on focus.
+            </em>
+          </p>
+        </>
       ),
       props: { EuiSkipLink },
       snippet: skipLinkSnippet,

src-docs/src/views/accessibility/screen_reader.tsx

@@ -1,51 +1,16 @@
 import React from 'react';
 
-import { EuiScreenReaderOnly } from '../../../../src/components/accessibility/screen_reader';
-import { EuiCallOut } from '../../../../src/components/call_out';
-import { EuiText } from '../../../../src/components/text';
-import { EuiTitle } from '../../../../src/components/title';
-import { EuiLink } from '../../../../src/components/link';
+import { EuiScreenReaderOnly, EuiText } from '../../../../src/components';
 
 export default () => (
-  <div>
-    <EuiText>
-      <EuiTitle size="xxs">
-        <h3>Visually hide content</h3>
-      </EuiTitle>
+  <EuiText>
+    <p>This is the first paragraph. It is visible to all.</p>
+    <EuiScreenReaderOnly>
       <p>
-        <em>
-          Use a screenreader to verify that there is a second paragraph in this
-          example:
-        </em>
+        This is the second paragraph. It is hidden for sighted users but visible
+        to screen readers.
       </p>
-      <p>This is the first paragraph. It is visible to all.</p>
-      <EuiScreenReaderOnly>
-        <p>
-          This is the second paragraph. It is hidden for sighted users but
-          visible to screen readers.
-        </p>
-      </EuiScreenReaderOnly>
-      <p>This is the third paragraph. It is visible to all.</p>
-      <EuiTitle size="xxs">
-        <h4>Show on focus</h4>
-      </EuiTitle>
-      <p>
-        <em>
-          Tab through this section with your keyboard to display a &lsquo;Skip
-          navigation&rsquo; link:
-        </em>
-      </p>
-      <p>
-        This link is visible to all on focus:{' '}
-        <EuiScreenReaderOnly showOnFocus>
-          <EuiLink href="#">Skip navigation</EuiLink>
-        </EuiScreenReaderOnly>
-      </p>
-      <EuiCallOut
-        size="s"
-        title="For a fully styled &lsquo;Skip to main content&rsquo; solution, see the EuiSkipLink component in the next section."
-        iconType="iInCircle"
-      />
-    </EuiText>
-  </div>
+    </EuiScreenReaderOnly>
+    <p>This is the third paragraph. It is visible to all.</p>
+  </EuiText>
 );

src-docs/src/views/accessibility/screen_reader_button.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+
+import {
+  EuiScreenReaderOnly,
+  EuiText,
+  EuiLink,
+} from '../../../../src/components';
+
+export default () => (
+  <EuiText>
+    <p>
+      Without relative position:{' '}
+      <EuiLink href="#/utilities/accessibility">
+        Link text{' '}
+        <EuiScreenReaderOnly>
+          <span>has screen reader text</span>
+        </EuiScreenReaderOnly>
+      </EuiLink>
+    </p>
+    <p>
+      With releative position:{' '}
+      <EuiLink
+        style={{ position: 'relative' }}
+        href="#/utilities/accessibility"
+      >
+        Link text{' '}
+        <EuiScreenReaderOnly>
+          <span>has screen reader text</span>
+        </EuiScreenReaderOnly>
+      </EuiLink>
+    </p>
+  </EuiText>
+);

src-docs/src/views/accessibility/screen_reader_focus.tsx

@@ -0,0 +1,18 @@
+import React from 'react';
+
+import {
+  EuiScreenReaderOnly,
+  EuiText,
+  EuiLink,
+} from '../../../../src/components';
+
+export default () => (
+  <EuiText>
+    <p>
+      This link is visible to all on focus:{' '}
+      <EuiScreenReaderOnly showOnFocus>
+        <EuiLink href="#/utilities/accessibility">Link text</EuiLink>
+      </EuiScreenReaderOnly>
+    </p>
+  </EuiText>
+);

src-docs/src/views/accessibility/skip_link.js → src-docs/src/views/accessibility/skip_link.tsx

@@ -3,7 +3,6 @@ import React, { useState } from 'react';
 import {
   EuiSkipLink,
   EuiCallOut,
-  EuiText,
   EuiSpacer,
   EuiSwitch,
 } from '../../../../src/components';
@@ -13,25 +12,6 @@ export default () => {
 
   return (
     <>
-      <EuiText>
-        {isFixed ? (
-          <p>
-            <em>
-              Tab through this section and a fixed{' '}
-              <strong>Skip to main content </strong> link will appear atop this
-              page.
-            </em>
-          </p>
-        ) : (
-          <p>
-            <em>
-              Tab through this section and a <strong>Skip to content</strong>{' '}
-              link will appear below.
-            </em>
-          </p>
-        )}
-      </EuiText>
-      <EuiSpacer />
       <EuiSwitch
         label="Fix link to top of screen"
         checked={isFixed}