[terra-icon] accessibility upgrade

packages/terra-core-docs/src/terra-dev-site/doc/icon/Icon.1.doc.mdx

@@ -7,6 +7,8 @@ import IconBasePropsTable from 'terra-icon/src/IconBase?dev-site-props-table';
 # Terra Icon
 
 The terra-icon component is used to visually represent a literal or symbolic object intended to initiate an action, communicate a status, or navigate the workflow.
+Icons can be `meaningful` where they used to convey a semantic meaning or `decorative` where they are are simply used for aesthetic purposes.
+See [Usage](#usage) for more information.
 
 ## Getting Started
 
@@ -19,20 +21,35 @@ The terra-icon component is used to visually represent a literal or symbolic obj
 This component requires the following peer dependencies be installed in your app for the component to properly function.
 
 | Peer Dependency | Version |
-|-|-|
-| react | ^16.8.5 |
-| react-dom | ^16.8.5 |
-| react-intl | ^2.8.0 |
+|-----------------|---------|
+| react           | ^16.8.5 |
+| react-dom       | ^16.8.5 |
+| react-intl      | ^2.8.0  |
 
 <!-- AUTO-GENERATED-CONTENT:END -->
 
 ## Usage
+
+### Meaningful Icons
 Each Icon can be imported individually.
 
 ```jsx
 import IconAdd from 'terra-icon/lib/icon/IconAdd';
 import IconEdit from 'terra-icon/lib/icon/IconEdit';
 
+<div>
+  <IconAdd a11yLabel="add item"/>
+  <IconEdit a11yLabel="edit item"/>
+</div>
+```
+
+By default, the icons imported are `meaningful` which means that they are intended to convey meaning and thus, the `a11yLabel` prop is required for screenreaders. 
+If icons are intended for aesthetic purposes, then `decorative` icons and be imported as follows:
+
+```jsx
+import IconAddDecorative from 'terra-icon/lib/icon/decorative/IconAdd';
+import IconEditDecorative from 'terra-icon/lib/icon/decoartive/IconEdit';
+
 <div>
   <IconAdd />
   <IconEdit />

packages/terra-core-docs/src/terra-dev-site/test/icon/IconAccessibleLabel.test.jsx

@@ -0,0 +1,19 @@
+import React from 'react';
+import IconAlert from 'terra-icon/lib/icon/IconAlert';
+import IconAlertDecorative from 'terra-icon/lib/icon/decorative/IconAlert';
+
+const IconAccessibleLabel = () => (
+  <div>
+    <h3>Meaningful icon</h3>
+    <div>
+      <IconAlert a11yLabel="alert icon"/>
+    </div>
+
+    <h3>Decorative icon</h3>
+    <div>
+      <IconAlertDecorative a11yLabel="alert icon"/>
+    </div>
+  </div>
+);
+
+export default IconAccessibleLabel;

packages/terra-core-docs/src/terra-dev-site/test/icon/IconAll.module.scss

@@ -1,8 +1,8 @@
 :local {
   .icon {
     height: 40px;
-    margin: 5px;
     width: 40px;
+    margin: 5px;
   }
 
   .icon-inverse {

packages/terra-core-docs/src/terra-dev-site/test/icon/IconBidi.test.jsx

@@ -6,19 +6,19 @@ const IconBidi = () => (
   <div dir="rtl">
     <h3>Icon where isBidi is false by default</h3>
     <h4>Default</h4>
-    <IconDeviceCheck />
+    <IconDeviceCheck a11yLabel="device check icon"/>
     <h4>Set isBidi true</h4>
-    <IconDeviceCheck isBidi />
+    <IconDeviceCheck a11yLabel="device check icon" isBidi />
     <h4>Set isBidi false</h4>
-    <IconDeviceCheck isBidi={false} />
+    <IconDeviceCheck a11yLabel="device check icon" isBidi={false} />
 
     <h3>Icon where isBidi is true by default</h3>
     <h4>Default</h4>
-    <IconComment />
+    <IconComment a11yLabel="comment icon"/>
     <h4>Set isBidi true</h4>
-    <IconComment isBidi />
+    <IconComment a11yLabel="comment icon" isBidi />
     <h4>Set isBidi false</h4>
-    <IconComment isBidi={false} />
+    <IconComment a11yLabel="comment icon" isBidi={false} />
   </div>
 );
 

packages/terra-core-docs/src/terra-dev-site/test/icon/IconDefault.test.jsx

@@ -4,7 +4,7 @@ import IconAdd from 'terra-icon/lib/icon/IconAdd';
 const IconDefault = () => (
   <div>
     <h3>Default Icon</h3>
-    <IconAdd id="icon-default" />
+    <IconAdd id="icon-default" a11yLabel="add icon"/>
   </div>
 );
 

packages/terra-core-docs/src/terra-dev-site/test/icon/IconHeightWidth.test.jsx

@@ -9,19 +9,19 @@ const cx = classNames.bind(styles);
 const IconHeightWidth = () => (
   <div>
     <h3>Default</h3>
-    <IconAlert />
+    <IconAlert a11yLabel="alert icon"/>
     <h3>Height and Width are 50px</h3>
-    <IconAlert id="icon-height-50-width-50" height="50" width="50" />
+    <IconAlert a11yLabel="alert icon" id="icon-height-50-width-50" height="50" width="50" />
     <h3>Height and Width are 5em</h3>
-    <IconAlert id="icon-height-5em-width-5em" height="5em" width="5em" />
+    <IconAlert a11yLabel="alert icon" id="icon-height-5em-width-5em" height="5em" width="5em" />
     <h3>Container font size is 5em</h3>
     <div className={cx('icon-wrapper')}>
-      <IconAlert />
+      <IconAlert a11yLabel="alert icon"/>
     </div>
     <h3>Height of 5em</h3>
-    <IconAlert id="icon-height-5em" height="5em" />
+    <IconAlert a11yLabel="alert icon" id="icon-height-5em" height="5em" />
     <h3>Width of 5em</h3>
-    <IconAlert id="icon-width-5em" width="5em" />
+    <IconAlert a11yLabel="alert icon" id="icon-width-5em" width="5em" />
   </div>
 );
 

packages/terra-icon/CHANGELOG.md

@@ -1,6 +1,8 @@
 # Changelog
 
 ## Unreleased
+  * Breaking changes
+    * Updated terra-icon to meet accessibility standards.
 
 ## 3.46.1 - (January 4, 2022)
 

packages/terra-icon/package.json

@@ -40,18 +40,24 @@
   "scripts": {
     "compilescripts": "npm run compilescripts:clean && npm run compilescripts:build",
     "compilescripts:clean": "rm -rf scripts/lib",
+    "create-decorative-dir": "mkdir -p src/icon/decorative && cp -r src/icon/*.jsx src/icon/decorative/",
     "compilescripts:build": "babel --root-mode upward scripts/src --out-dir scripts/lib --copy-files",
     "migrate-csv": "node scripts/lib/migrate-csv/index.js",
     "migrate-svg": "node scripts/lib/migrate-svg/index.js",
     "generate-json": "node scripts/lib/generate-json/index.js",
-    "generate-icon": "node scripts/lib/generate-icon/index.js",
+    "generate-all-icons": "npm run generate-meaningful-icons && npm run generate-decorative-icons",
+    "generate-meaningful-icons": "npm run compilescripts && node scripts/lib/generate-icon/index.js",
+    "generate-decorative-icons": "npm run create-decorative-dir && npm run replace-decorative-baseclass && npm run replace-decorative-import && npm run replace-decorative-displayname",
     "generate-example": "node scripts/lib/generate-example/index.js",
-    "migrate-cerner-one-icons": "npm run compilescripts && npm run migrate-csv && npm run migrate-svg && npm run generate-json && npm run generate-icon && npm run generate-example",
+    "migrate-cerner-one-icons": "npm run compilescripts && npm run migrate-csv && npm run migrate-svg && npm run generate-json && npm run generate-all-icons && npm run generate-example",
     "compile": "babel --root-mode upward src --out-dir lib --copy-files",
     "lint": "npm run lint:js && npm run lint:scss",
     "lint:js": "eslint --ext .js,.jsx . --ignore-path ../../.eslintignore",
     "lint:scss": "stylelint src/**/*.scss",
     "precompile": "rm -rf lib",
+    "replace-decorative-baseclass": "find src/icon/decorative -type f -exec perl -i -pe's|IconBase|IconBaseDec|g' {} +",
+    "replace-decorative-import": "find src/icon/decorative -type f -exec perl -i -pe's|\\Q../\\E|../../|g' {} +",
+    "replace-decorative-displayname": "find src/icon/decorative -type f -exec perl -i -pe's/(SvgIcon\\.displayName = \")(\\w[\\w\\d]+)(\";)/\\1\\2Dec\\3/g' {} +",
     "test": "npm run lint && npm run jest && npm run wdio",
     "jest": "jest --config ../../jest.config.js",
     "wdio-default": "cd ../.. && terra wdio",

packages/terra-icon/scripts/src/README.md

@@ -1,10 +1,26 @@
 # Update all SVG icons
 
-```
-npm run migrate-cerner-one-icons
-```
-* npm run compilescripts
-* npm run migrate-csv
-* npm run migrate-svg
-* npm run generate-icon
-* npm run generate-example
+### Step 1. Initate scripts
+
+    npm run compilescripts
+
+### Step 2. (Optional) Migrate icons from a csv file
+You can skip this step if you're not updating the svg files in `packages/terra-icon/src/svg`.
+
+    npm run migrate-csv
+    npm run migrate-svg
+
+### Step 3. Generate icons based
+This will generate icons based on the files in `packages/terra-icon/src/svg`, whether they are newly migrated or pre-existing. 
+
+    npm run generate-all-icons
+
+Meaningful icons will be generated in `packages/terra-icon/src/icon`, directly in the folder. 
+Decorative icons will be generated in `packages/terra-icon/src/icon/decorative`.
+
+
+### Alternative run all steps command
+
+Alternatively, if you need to run steps 1, 2 and 3, then you can execute them all with a single command:
+
+    npm run migrate-cerner-one-icons

packages/terra-icon/scripts/src/generate-icon/parseSvg.js

@@ -8,7 +8,7 @@ import Icon from './Icon';
 const parseSvg = filepath => new Promise((resolve) => {
   const source = fs.readFileSync(filepath, 'utf-8');
   const { name } = path.parse(filepath);
-
+  
   const { document } = new JSDOM(source).window;
   const icon = new Icon(name, document.querySelector('svg'));
 

packages/terra-icon/scripts/src/generate-icon/template.txt

@@ -6,7 +6,7 @@ const SvgIcon = (customProps) => {
   const attributes = Object.assign({}, customProps);
 
   return (
-    <IconBase {...attributes}>
+    <IconBase {...attributes} >
       <%= icon.children %>
     </IconBase>
   );

packages/terra-icon/scripts/src/generate-icon/themeIconWithTooltipTemplate.txt

@@ -5,12 +5,11 @@ import { FormattedMessage } from 'react-intl';
 
 const SvgIcon = (customProps) => {
   const attributes = Object.assign({}, customProps);
-
   return (
     <FormattedMessage id="Terra.icon.<%= icon.name %>.title">
       {iconTitle => (
         <span aria-label={iconTitle} title={iconTitle}>
-            <IconBase {...attributes}>
+            <IconBase {...attributes} >
                 <%= icon.children %>
             </IconBase>
         </span>

packages/terra-icon/src/IconBase.jsx

@@ -9,6 +9,10 @@ import styles from './Icon.module.scss';
 const cx = classNamesBind.bind(styles);
 
 const propTypes = {
+  /**
+  * String that labels the current element. 
+  */
+  a11yLabel: PropTypes.string.isRequired,
   /**
    * Should the svg mirror when dir="rtl".
    */
@@ -29,11 +33,6 @@ const propTypes = {
    * Width of SVG.
    */
   width: PropTypes.string,
-  /**
-   * String that labels the current element. If 'aria-label' is present,
-   * role is set to 'img' and aria-hidden is removed.
-   */
-  ariaLabel: PropTypes.string,
   /**
    * Focusable attribute. IE 10/11 are focusable without this attribute.
    */
@@ -46,17 +45,20 @@ const defaultProps = {
   children: null,
   height: '1em',
   width: '1em',
-  ariaLabel: null,
   focusable: 'false',
 };
 
+// Returns a SVG representing the icon. Is utilized as: <Iconbase  {..props} ><svg children></IconBase>
+// Note: while an img is the ideal recommended approach by accessibility guidelines, 
+// IconBase returns a svg so that non-static icons can be themable by using the CSS color property. 
+
 const IconBase = ({
+  a11yLabel,
   isBidi,
   isSpin,
   children,
   height,
   width,
-  ariaLabel,
   focusable,
   ...customProps
 }) => {
@@ -73,20 +75,14 @@ const IconBase = ({
     attributes.className,
   );
 
-  // aria-label is present, remove aria-hidden, set role to img
-  if (ariaLabel) {
-    attributes['aria-label'] = ariaLabel;
-    attributes.role = 'img';
-    attributes['aria-hidden'] = null;
-  } else {
-    attributes['aria-hidden'] = 'true';
-  }
-
   attributes.height = height;
   attributes.width = width;
   attributes.focusable = focusable;
+
+  const svgA11yLabel = React.createElement('title', {}, a11yLabel);
+  const svgChildren = new Array(svgA11yLabel).concat(children);
 
-  return <svg {...attributes} className={classes}>{children}</svg>;
+  return <svg {...attributes} className={classes}>{svgChildren}</svg>;
 };
 
 IconBase.propTypes = propTypes;