[Terra-Image] Adds support for Decorative Image (#3712)

* Added support for Decorative Image

* removes additional wrappers around image component

* linters updated

* typo corrections

* doc updates

---------

Co-authored-by: SM051274 <sm051274@cerner.net>

packages/terra-core-docs/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+* Added
+  * Added examples and accessibility guide for `terra-image`.
+
 ## 1.18.0 - (January 9, 2023)
 
 * Changed

packages/terra-core-docs/src/terra-dev-site/common/layout-helpers/Whitespace.jsx

@@ -0,0 +1,39 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import classNames from 'classnames';
+import classNamesBind from 'classnames/bind';
+import styles from './Whitespace.module.scss';
+
+const cx = classNamesBind.bind(styles);
+
+const propTypes = {
+  /**
+   * Sets the height of a newline spacer, equivalent to number of lines based on lineheight, not fontsize.
+   * One of `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, default is `1`.
+   */
+  newline: PropTypes.oneOf([1, 2, 3, 4, 5, 6, 7, 8]),
+};
+
+const defaultProps = {
+  newline: 1,
+};
+
+const Whitespace = ({
+  newline,
+  ...customProps
+}) => {
+  const WhitespaceClassNames = classNames(
+    cx(
+      'whitespace',
+      `newline-${newline}`,
+    ),
+    customProps.className,
+  );
+
+  return <div {...customProps} className={WhitespaceClassNames} aria-hidden="true" />;
+};
+
+Whitespace.propTypes = propTypes;
+Whitespace.defaultProps = defaultProps;
+
+export default Whitespace;

packages/terra-core-docs/src/terra-dev-site/common/layout-helpers/Whitespace.module.scss

@@ -0,0 +1,48 @@
+/* 
+ * SASS calculation 
+ * based on lineheight of 20px (1.42857) for fontsize of 14px (1rem)
+ */
+@mixin terra-newline-height ($number-of-lines) {
+  height: 1.4285714286em * $number-of-lines;
+}
+
+:local {
+  .whitespace {
+    display: block;
+    margin: 0;
+    min-height: 0;
+    padding: 0;
+  }
+
+  .newline-1 {
+    @include terra-newline-height(1);
+  }
+
+  .newline-2 {
+    @include terra-newline-height(2);
+  }
+
+  .newline-3 {
+    @include terra-newline-height(3);
+  }
+
+  .newline-4 {
+    @include terra-newline-height(4);
+  }
+
+  .newline-5 {
+    @include terra-newline-height(5);
+  }
+
+  .newline-6 {
+    @include terra-newline-height(6);
+  }
+
+  .newline-7 {
+    @include terra-newline-height(7);
+  }
+
+  .newline-8 {
+    @include terra-newline-height(8);
+  }
+}

packages/terra-core-docs/src/terra-dev-site/doc/image/About.1.doc.mdx

@@ -2,6 +2,8 @@ import { Badge } from 'terra-image/package.json?dev-site-package';
 
 import ImageDefault from './example/ImageDefault?dev-site-example';
 import ImageFit from './example/ImageFitTypes?dev-site-example';
+import DecorativeImage from './example/DecorativeImage?dev-site-example';
+import InformativeImage from './example/InformativeImage?dev-site-example';
 
 import ImagePropsTable from 'terra-image/src/Image?dev-site-props-table';
 
@@ -11,6 +13,36 @@ import ImagePropsTable from 'terra-image/src/Image?dev-site-props-table';
 
 The terra-image component provides styling for visual imagery.
 
+
+# Informative Image
+
+Informative images are images that graphically represent concepts and information on a page. images are known as informative when they convey a concept or information of image with a short phrase or sentence.
+
+Images must have text alternatives described through `alt` prop which will provide the information or function represented by them. This will ensure that images are accessible for people with various disabilities.
+
+Images may be infomative when they are:
+- Used to label other information
+- Used to supplement other information
+- Conveying succinct information
+- Conveying an impression or emotion
+- Conveying file format
+
+
+# Decorative Image
+
+Decorative images are images that don’t add information to the content of a page but instead support existing content or are used plainly for aesthetics. For example, it can be an image depicting adjacent text or to make the website more visually attractive.
+
+Decorative Image should be used only when the purpose of an image is to add visual interest to the page, rather than to convey information that is important to understanding the page.
+
+Images may be decorative when they are:
+- Visual styling such as borders, spacers, and corners.
+- Supplementary to link text to improve its appearance or increase the clickable area.
+- Illustrative of adjacent text but not contributing information (“eye-candy”).
+- Identified and described by surrounding text.
+
+
+Provide a null text alternative (alt="") when the only purpose of an image is to add visual decoration to the page.
+
 ## Getting Started
 
 - Install with [npmjs](https://www.npmjs.com):
@@ -42,6 +74,8 @@ import Image from 'terra-image';
 ## Examples
 <ImageDefault />
 <ImageFit />
+<DecorativeImage />
+<InformativeImage />
 
 ## Image Props
 <ImagePropsTable />

packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleDecorativeImage.jsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import classNamesBind from 'classnames/bind';
+import Card from 'terra-card';
+import Image from 'terra-image';
+import matterhornBackgroundImage from '../../../../common/images/creative-commons/Matterhorn,_March_2019_(01)_960x640.jpg';
+import styles from './common/A11yExamples.module.scss';
+
+const cx = classNamesBind.bind(styles);
+
+const A11yExampleDecorativeImage = () => (
+  <div className={cx('decorative-example')}>
+    <Image src={matterhornBackgroundImage} fit="cover" className={cx('background')} />
+    <div className={cx('foreground')}>
+      <Card className={cx('card')}>
+        <p className={cx('decorative-text-container')}>
+          <strong className={cx('title')}>Matterhorn</strong>
+          Standing at 4,478 meters (14,692ft), Matterhorn is the fifth highest peak in the Alps located on the border between Switzerland and Italy, in the Monte Rosa area of the western Pennine Alps, and overlooks the Swiss town of Zermatt.
+          <cite className={cx('cite')}>
+            <small>
+              {'Photo Credit: '}
+              <a href="https://commons.wikimedia.org/wiki/File:Matterhorn,_March_2019_(01).jpg">Liridon</a>
+              {', '}
+              <a href="https://creativecommons.org/licenses/by-sa/4.0">CC BY-SA 4.0</a>
+              , via Wikimedia Commons
+            </small>
+          </cite>
+        </p>
+      </Card>
+    </div>
+  </div>
+);
+
+export default A11yExampleDecorativeImage;

packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleInformative.jsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import classNamesBind from 'classnames/bind';
+import Card from 'terra-card';
+import Image from 'terra-image';
+import matterhornImage from '../../../common/images/creative-commons/Matterhorn,_March_2019_(01)_150x150.jpg';
+import styles from './common/A11yExamples.module.scss';
+
+const cx = classNamesBind.bind(styles);
+
+const matterhornAlternativeText = 'North-east face of the Matterhorn mountain peak and surrounding landscape covered in snow against a blue sky, located in the Swiss Apps near Zermatt, Switzerland';
+
+const A11yGuideInformativeImage = () => (
+  <Card className={cx('card')}>
+    <p className={cx('informative-example')}>
+      <Image src={matterhornImage} alt={matterhornAlternativeText} className={cx('image')} />
+      <strong className={cx('title')}>Matterhorn</strong>
+    </p>
+  </Card>
+);
+
+export default A11yGuideInformativeImage;

packages/terra-core-docs/src/terra-dev-site/doc/image/example/A11yExampleInformativeConcise.jsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import classNamesBind from 'classnames/bind';
+import Card from 'terra-card';
+import Image from 'terra-image';
+import matterhornImage from '../../../common/images/creative-commons/Matterhorn,_March_2019_(01)_150x150.jpg';
+import styles from './common/A11yExamples.module.scss';
+
+const cx = classNamesBind.bind(styles);
+
+const matterhornAlternativeText = 'Matterhorn mountain peak';
+
+export default () => (
+  <Card className={cx('card')}>
+    <p className={cx('informative-example')}>
+      <Image src={matterhornImage} alt={matterhornAlternativeText} className={cx('image')} />
+      <strong className={cx('title')}>Matterhorn</strong>
+      Standing at 4,478 meters (14,692ft), Matterhorn is the fifth highest peak in the Alps located on the border between Switzerland and Italy, in the Monte Rosa area of the western Pennine Alps, and overlooks the Swiss town of Zermatt.
+      <cite className={cx('cite')}>
+        <small>
+          {'Photo Credit: '}
+          <a href="https://commons.wikimedia.org/wiki/File:Matterhorn,_March_2019_(01).jpg">Liridon</a>
+          {', '}
+          <a href="https://creativecommons.org/licenses/by-sa/4.0">CC BY-SA 4.0</a>
+          , via Wikimedia Commons
+        </small>
+      </cite>
+    </p>
+  </Card>
+);

packages/terra-core-docs/src/terra-dev-site/doc/image/example/DecorativeImage.jsx

@@ -0,0 +1,18 @@
+import React from 'react';
+import Image from 'terra-image';
+import decorativeBar from '../assets/decorative-bar.png';
+import crocus from '../assets/crocus.jpg';
+
+const DecorativeImageBar = () => (
+  <div>
+    <h2>Image used as part of page design.</h2>
+    <p>This image is used as a border in the page design and has a purely decorative purpose.</p>
+    <Image src={decorativeBar} />
+    <h2>Image as part of a text link.</h2>
+    <p>This illustration of a crocus bulb is used to make the link easier to identify and to increase the clickable area but doesn’t add to the information already provided in the adjacent link text (of the same anchor). In this case, alt value for the image would be `null` / `empty`.</p>
+    <Image src={crocus} />
+    <a href="https://engineering.cerner.com/terra-ui/components/cerner-terra-core-docs/image/about#examples"><span>Crocus bulbs</span></a>
+  </div>
+);
+
+export default DecorativeImageBar;

packages/terra-core-docs/src/terra-dev-site/doc/image/example/InformativeImage.jsx

@@ -0,0 +1,15 @@
+import React from 'react';
+import Image from 'terra-image';
+import matterhornImage from '../../../common/images/creative-commons/Matterhorn,_March_2019_(01)_150x150.jpg';
+
+const matterhornAlternativeText = 'North-east face of the Matterhorn mountain peak and surrounding landscape covered in snow against a blue sky, located in the Swiss Apps near Zermatt, Switzerland';
+
+const InformativeImage = () => (
+  <div>
+    <h2>Information provided using Image.</h2>
+    <Image src={matterhornImage} alt={matterhornAlternativeText} />
+    <p><strong>Matterhorn</strong></p>
+  </div>
+);
+
+export default InformativeImage;

packages/terra-core-docs/src/terra-dev-site/doc/image/example/common/A11yExamples.module.scss

@@ -0,0 +1,72 @@
+:local {
+  .card {
+    width: 100%;
+  }
+
+  .informative-example {
+    font-size: 0.85rem;
+    margin-left: auto;
+    margin-right: auto;
+    max-width: 40rem;
+    padding: 0.25rem 1rem 0;
+    text-align: center;
+    width: 100%;
+  }
+
+  .image {
+    margin: 0 auto;
+  }
+
+  .title {
+    display: block;
+    font-size: 1.1em;
+    margin-bottom: 0.25em;
+    margin-top: 0.5em;
+  }
+
+  .cite {
+    display: block;
+    margin-top: 0.25em;
+  }
+
+  .decorative-example {
+    min-height: 240px;
+    position: relative;
+    width: 100%;
+
+    .background {
+      height: 240px;
+      width: 100%;
+    }
+
+    .foreground {
+      padding: 20px;
+      position: absolute;
+      top: 0;
+      width: 100%;
+    }
+
+    .card {
+      opacity: 0.85;
+    }
+  }
+
+  .decorative-text-container {
+    font-size: 0.85rem;
+    padding-left: 1rem;
+    padding-right: 1rem;
+    text-align: center;
+  }
+
+  @media screen and (min-width: 544px) {
+    .informative-example {
+      font-size: 1rem;
+    }
+
+    .decorative-text-container {
+      font-size: 1rem;
+      padding-left: 3rem;
+      padding-right: 3rem;
+    }  
+  }
+}

packages/terra-image/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 ## Unreleased
 
+* Added
+  * Added support for decorative images.
+
 ## 3.36.0 - (December 7, 2022)
 
 * Changed