[Framework/Accessibility] Add kuiScreenReaderOnly class (#13133)

* [Framework/Accessibility] Add kuiScreenReaderOnly class

* fix typo

* use GuideLink

* add screen_reader react component and tests

* export KuiScreenReaderOnly

* --wip-- [skip ci]

* fix lint rule

* remove obsolete snapshots

ui_framework/components/accessibility/__snapshots__/screen_reader.test.js.snap

@@ -0,0 +1,17 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`KuiScreenReaderOnly adds an accessibility class to a child element and combines other classNames (foo, bar) given as props on the child 1`] = `
+<p
+  class="kuiScreenReaderOnly foo bar"
+>
+  This paragraph is not visibile to sighted users but will be read by screenreaders.
+</p>
+`;
+
+exports[`KuiScreenReaderOnly adds an accessibility class to a child element when used with no props 1`] = `
+<p
+  class="kuiScreenReaderOnly"
+>
+  This paragraph is not visibile to sighted users but will be read by screenreaders.
+</p>
+`;

ui_framework/components/accessibility/_index.scss

@@ -0,0 +1 @@
+@import "./_screen_reader";

ui_framework/components/accessibility/_screen_reader.scss

@@ -0,0 +1,8 @@
+.kuiScreenReaderOnly {
+  position: absolute;
+  left: -10000px;
+  top: auto;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+}

ui_framework/components/accessibility/index.js

@@ -1 +1,2 @@
 export { KuiKeyboardAccessible } from './keyboard_accessible';
+export { KuiScreenReaderOnly } from './screen_reader';

ui_framework/components/accessibility/screen_reader.js

@@ -0,0 +1,20 @@
+import {
+  cloneElement,
+  PropTypes,
+} from 'react';
+import classNames from 'classnames';
+
+
+export const KuiScreenReaderOnly = ({ children }) => {
+  const classes = classNames('kuiScreenReaderOnly', children.props.className);
+
+  const props = Object.assign({}, children.props, {
+    className: classes
+  });
+
+  return cloneElement(children, props);
+};
+
+KuiScreenReaderOnly.propTypes = {
+  children: PropTypes.node
+};

ui_framework/components/accessibility/screen_reader.test.js

@@ -0,0 +1,35 @@
+import React from 'react';
+import { render } from 'enzyme';
+
+import { KuiScreenReaderOnly } from './screen_reader';
+
+describe('KuiScreenReaderOnly', () => {
+  describe('adds an accessibility class to a child element', () => {
+    test('when used with no props', () => {
+      const $paragraph = render(
+        <KuiScreenReaderOnly>
+          <p>
+            This paragraph is not visibile to sighted users but will be read by
+            screenreaders.
+          </p>
+        </KuiScreenReaderOnly>
+      );
+
+      expect($paragraph)
+        .toMatchSnapshot();
+    });
+    test('and combines other classNames (foo, bar) given as props on the child', () => {
+      const $paragraph = render(
+        <KuiScreenReaderOnly>
+          <p className='foo bar'>
+            This paragraph is not visibile to sighted users but will be read by
+            screenreaders.
+          </p>
+        </KuiScreenReaderOnly>
+      );
+
+      expect($paragraph)
+        .toMatchSnapshot();
+    });
+  });
+});

ui_framework/components/index.js

@@ -2,6 +2,7 @@ export { KuiActionItem } from './action_item';
 
 export {
   KuiKeyboardAccessible,
+  KuiScreenReaderOnly,
 } from './accessibility';
 
 export {

ui_framework/components/index.scss

@@ -19,6 +19,7 @@
 @import "common_styles";
 
 // Components
+@import "accessibility/index";
 @import "action_item/index";
 @import "badge/index";
 @import "bar/index";

ui_framework/dist/ui_framework.css

@@ -76,6 +76,14 @@ main {
   display: block;
   /* 1 */ }
 
+.kuiScreenReaderOnly {
+  position: absolute;
+  left: -10000px;
+  top: auto;
+  width: 1px;
+  height: 1px;
+  overflow: hidden; }
+
 .kuiActionItem {
   display: -webkit-box;
   display: -webkit-flex;

ui_framework/doc_site/src/views/accessibility/accessibility_example.js

@@ -5,16 +5,22 @@ import { renderToHtml } from '../../services';
 import {
   GuideCode,
   GuideDemo,
+  GuideLink,
   GuidePage,
   GuideSection,
   GuideSectionTypes,
   GuideText,
 } from '../../components';
 
 import KeyboardAccessible from './keyboard_accessible';
+import ScreenReaderOnly from './screen_reader';
+
 const keyboardAccessibleSource = require('!!raw!./keyboard_accessible');
 const keyboardAccessibleHtml = renderToHtml(KeyboardAccessible);
 
+const screenReaderOnlyHtml = renderToHtml(ScreenReaderOnly);
+const screenReaderOnlySource = require('!!raw!./screen_reader');
+
 export default props => (
   <GuidePage title={props.route.name}>
     <GuideSection
@@ -37,5 +43,35 @@ export default props => (
         <KeyboardAccessible />
       </GuideDemo>
     </GuideSection>
+
+    <GuideSection
+      title="ScreenReaderOnly"
+      source={[{
+        type: GuideSectionTypes.JS,
+        code: screenReaderOnlySource,
+      }, {
+        type: GuideSectionTypes.HTML,
+        code: screenReaderOnlyHtml,
+      }]}
+    >
+      <GuideText>
+        This class can be useful to add accessibility to older designs that are
+        still in use, but it shouldn't be a permanent solution. See <GuideLink
+          href='http://webaim.org/techniques/css/invisiblecontent/'
+        >
+          http://webaim.org/techniques/css/invisiblecontent/
+        {
+          // eslint-disable-next-line react/jsx-closing-tag-location
+        }</GuideLink> for more information.
+      </GuideText>
+
+      <GuideText>
+        Use a screenreader to verify that there is a second paragraph in this example:
+      </GuideText>
+
+      <GuideDemo>
+        <ScreenReaderOnly />
+      </GuideDemo>
+    </GuideSection>
   </GuidePage>
 );

ui_framework/doc_site/src/views/accessibility/screen_reader.js

@@ -0,0 +1,23 @@
+import React from 'react';
+
+import {
+  KuiScreenReaderOnly,
+} from '../../../../components';
+
+
+export default () => (
+  <div>
+    <p>
+      This is the first paragraph. It is visible to all.
+    </p>
+    <KuiScreenReaderOnly>
+      <p>
+        This is the second paragraph. It is hidden for sighted users but visible to screen readers.
+      </p>
+    </KuiScreenReaderOnly>
+    <p>
+      This is the third paragraph. It is visible to all.
+    </p>
+  </div>
+);
+