feat(components): RichContent component for server HTML

PageBuilder CMS, like many CMSes, will provide raw HTML as a server
response. Added a `RichContent` component to handle this common use
case.

 - It uses the `dangerouslySetInnerHTML` API, rendering a string of
   HTML supplied as a prop.
 - If the outer system replaces the raw HTML with progressively
   enhanced functionality, such as a tree of live `ReactElements`,
   `RichContent` accepts `ReactElements` as children. Children will
   override the `sanitizedRawHtml` prop.

feat(RichContent): Add configurability to wrapper tag

 - Added two props to configure the "parent element" that React requires
 to `dangerouslySetInnerHTML`:
    - `wrapperTag` to specify the tag name as a string
    - `wrapperProps` to pass an object of props to that tag
 - Updated docs, stories, and tests to reflect this change

feat:retract children API for later

Author: zetlen

package-lock.json

@@ -0,0 +1,31 @@
+import { createElement, Component } from 'react';
+import { object, string } from 'prop-types';
+
+export default class RichContent extends Component {
+    static propTypes = {
+        sanitizedRawHtml: string.isRequired,
+        wrapperTag: string,
+        wrapperProps: object
+    };
+
+    static defaultProps = {
+        wrapperTag: 'span',
+        wrapperProps: {
+            className: 'peregrine-raw-html'
+        }
+    };
+
+    render() {
+        // JSX tags must be in PascalCase
+        const WrapperTag = this.props.wrapperTag;
+
+        return (
+            <WrapperTag
+                {...this.props.wrapperProps}
+                dangerouslySetInnerHTML={{
+                    __html: this.props.sanitizedRawHtml
+                }}
+            />
+        );
+    }
+}

src/Content/RichContent.js

@@ -0,0 +1,73 @@
+# RichContent
+
+The `RichContent` component is a utility component for rendering visual content
+delivered by an external data provider. It can render raw HTML supplied as
+a string.
+
+CMS and catalog systems often store HTML content in the server-side database,
+and deliver that content in API responses as a raw string. PWA Studio provides
+the `RichContent` component to easily embed content for this common
+situation.
+
+## Usage
+
+```jsx
+import React from 'react';
+import { RichContent } from '@magento/peregrine';
+
+class ItemDescription extends React.Component {
+    render() {
+        const { data } = this.props;
+        return (
+            <div className="desc-container">
+                <h3>Description</h3>
+                <RichContent sanitizedRawHtml={data.long_description} />
+            </div>
+        );
+    }
+}
+```
+
+## Props
+
+| Prop Name          | Required? |                                         Description |
+| ------------------ | :-------: | --------------------------------------------------: |
+| `sanitizedRawHtml` |    ✅      | A string of raw HTML to display. Ignored if `children` are also passed and are not null.
+| `wrapperTag`       |           | Optional HTML tag to use as a custom wrapper element. Default `span.`.
+| `wrapperProps`     |           | Optional object to be passed as props to the `wrapperTag`. Default `{ className: "peregrine-raw-html" }`.
+
+## Notes
+
+- The `RichContent` component will wrap `sanitizedRawHtml` content with a parent
+  element for compatibility with React. The default wrapper tag is a `span` with
+  a default classname:
+
+  ```html
+  <RichContent
+      sanitizedRawHtml="<h2>Header</h2><p>body text</p>" />
+
+  <!-- emits this HTML: -->
+  <span class="peregrine-raw-html">
+    <h2>Header</h2><p>body text</p>
+  </span>
+  ```
+
+  Use the `wrapperTag` string prop and `wrapperProps` object prop to customize
+  the  parent tag:
+
+  ```html
+  <RichContent
+      sanitizedRawHtml="<h2>Header</h2><p>body text</p>"
+      wrapperTag="section"
+      wrapperProps={{ className: "product-description loading" }}
+  />
+
+  <!-- emits this HTML: -->
+  <section class="product-description loading">
+    <h2>Header</h2><p>body text</p>
+  </section>
+  ```
+
+- ⚠️⚠️ **`RichContent` does *not* sanitize its input in any way. It is the
+  responsibility of the data provider to ensure that the HTML is safe,
+  contains no script tags and no escaping issues.**

src/Content/__docs__/RichContent.md

@@ -0,0 +1,18 @@
+import { createElement } from 'react';
+import { storiesOf } from '@storybook/react';
+import { withReadme } from 'storybook-readme';
+import { RichContent } from '..';
+import docs from '../__docs__/RichContent.md';
+
+storiesOf('RichContent', module)
+    .addDecorator(withReadme(docs))
+    .add('Raw HTML', () => (
+        <RichContent sanitizedRawHtml="<p><em>HTML fallback content</em></p><img src='https://placebeard.it/420/320'/>" />
+    ))
+    .add('Raw HTML with custom wrapper tag', () => (
+        <RichContent
+            sanitizedRawHtml="<p><em>HTML fallback content</em></p><img src='https://placebeard.it/320/240'/>"
+            wrapperTag="article"
+            wrapperProps={{ style: { background: 'whitesmoke' } }}
+        />
+    ));

src/Content/__stories__/RichContent.js

@@ -0,0 +1,27 @@
+import { createElement } from 'react';
+import { RichContent } from '..';
+import { configure, mount } from 'enzyme';
+import Adapter from 'enzyme-adapter-react-16';
+
+configure({ adapter: new Adapter() });
+
+test('Renders raw HTML in a wrapper element', () => {
+    const wrapper = mount(
+        <RichContent sanitizedRawHtml="<h1 id='o-no'>Raw!!!</h1>" />
+    );
+    expect(wrapper.html()).toEqual(
+        '<span class="peregrine-raw-html"><h1 id="o-no">Raw!!!</h1></span>'
+    );
+});
+
+test('Takes DOM properties for a custom wrapper element', () => {
+    const wrapper = mount(
+        <RichContent
+            sanitizedRawHtml="<h1 id='o-no'>Raw!!!</h1>"
+            wrapperTag="article"
+        />
+    );
+    expect(wrapper.html()).toEqual(
+        '<article class="peregrine-raw-html"><h1 id="o-no">Raw!!!</h1></article>'
+    );
+});

src/Content/__tests__/RichContent.test.js

@@ -0,0 +1 @@
+export { default as RichContent } from './RichContent';