From 5140c13696c2a3a1eb455bd1d94652e274a68344 Mon Sep 17 00:00:00 2001
From: Alex Krolick <alexkrolick@users.noreply.github.com>
Date: Tue, 16 Jul 2019 17:39:52 -0700
Subject: [PATCH] feat(media): create media object component (#1383)

* feat(media): create media object component

* feat(media): add menu elements

* chore(media): rename media.img to media.figure

* docs(media): add layout examples

* docs(media): add form elements to media object example

* docs(media): add titles to examples

* feat(media): add aria-label prop to media.menu

* style(media): change to arrow fns from function keyword

* style(media): use defaultProps for everything

* fix(media): adjust composition of body + figure content

* refactor(media): remove menu wrapper div, pass props to button

* fix(media): remove unneeded css attr

* refactor(media): scss shorthand declaration

* fix(media): ie11 proofing

* refactor(media): use flex shorthand

* fix(media): revert change to dropdownmenu, add dropdownProps instead
---
 scripts/styleguide.config.js                  |  13 ++
 src/components/media/Media.js                 |  35 +++++
 src/components/media/Media.md                 | 148 ++++++++++++++++++
 src/components/media/Media.scss               |  42 +++++
 src/components/media/MediaBody.js             |  19 +++
 src/components/media/MediaBody.md             |  30 ++++
 src/components/media/MediaFigure.js           |  28 ++++
 src/components/media/MediaFigure.md           |  28 ++++
 src/components/media/MediaMenu.js             |  41 +++++
 src/components/media/MediaMenu.md             |  30 ++++
 src/components/media/__tests__/Media-test.js  |  40 +++++
 .../media/__tests__/MediaFigure-test.js       |  12 ++
 .../media/__tests__/MediaMenu-test.js         |  18 +++
 .../__snapshots__/Media-test.js.snap          |  38 +++++
 src/components/media/index.js                 |   2 +
 15 files changed, 524 insertions(+)
 create mode 100644 src/components/media/Media.js
 create mode 100644 src/components/media/Media.md
 create mode 100644 src/components/media/Media.scss
 create mode 100644 src/components/media/MediaBody.js
 create mode 100644 src/components/media/MediaBody.md
 create mode 100644 src/components/media/MediaFigure.js
 create mode 100644 src/components/media/MediaFigure.md
 create mode 100644 src/components/media/MediaMenu.js
 create mode 100644 src/components/media/MediaMenu.md
 create mode 100644 src/components/media/__tests__/Media-test.js
 create mode 100644 src/components/media/__tests__/MediaFigure-test.js
 create mode 100644 src/components/media/__tests__/MediaMenu-test.js
 create mode 100644 src/components/media/__tests__/__snapshots__/Media-test.js.snap
 create mode 100644 src/components/media/index.js

diff --git a/scripts/styleguide.config.js b/scripts/styleguide.config.js
index c4886bd2f2..dbb2286537 100644
--- a/scripts/styleguide.config.js
+++ b/scripts/styleguide.config.js
@@ -103,6 +103,19 @@ const allSections = [
         description: 'Box UI Elements components implement the reusable building blocks of the Box Design Language',
         sectionDepth: 2,
         usageMode: 'expand',
+        sections: [
+            {
+                name: 'Media',
+                components: [
+                    '../src/components/media/Media.js',
+                    '../src/components/media/MediaFigure.js',
+                    '../src/components/media/MediaBody.js',
+                    '../src/components/media/MediaMenu.js',
+                ],
+                description: 'Implements the "media object" layout',
+                usageMode: 'expand',
+            },
+        ],
     },
     {
         name: 'Icons',
diff --git a/src/components/media/Media.js b/src/components/media/Media.js
new file mode 100644
index 0000000000..0a314a0e4a
--- /dev/null
+++ b/src/components/media/Media.js
@@ -0,0 +1,35 @@
+// @flow
+import * as React from 'react';
+import classnames from 'classnames';
+import MediaFigure from './MediaFigure';
+import MediaBody from './MediaBody';
+import MediaMenu from './MediaMenu';
+import './Media.scss';
+
+type Props = {
+    /** Component to use as outermost element, e.g., 'li' */
+    as: React.ElementType,
+    /** Child elements */
+    children: React.ChildrenArray<React.Element<typeof MediaFigure | typeof MediaBody | typeof MediaMenu>>,
+    /** Additional class names */
+    className?: string,
+};
+
+const Media = ({ as: Wrapper, children, className, ...rest }: Props) => (
+    <Wrapper className={classnames('bdl-Media', className)} {...rest}>
+        {children}
+    </Wrapper>
+);
+
+// Use this instead of default value because of param destructuring bug in Flow
+// that affects union types
+// https://github.com/facebook/flow/issues/5461
+Media.defaultProps = {
+    as: 'div',
+};
+
+Media.Body = MediaBody;
+Media.Menu = MediaMenu;
+Media.Figure = MediaFigure;
+
+export default Media;
diff --git a/src/components/media/Media.md b/src/components/media/Media.md
new file mode 100644
index 0000000000..a88e50fb19
--- /dev/null
+++ b/src/components/media/Media.md
@@ -0,0 +1,148 @@
+> **Note**
+>
+> `Media` is a compound component, the inner elements are not meant to be used outside of the Media container
+
+Implements the "media object" element
+
+```plaintext
+import Media from 'box-ui-elements/es/components/media'
+```
+
+```js
+const { MenuItem } = require('../menu');
+
+<Media style={{ width: 300 }}>
+  <Media.Figure>
+    <Avatar size="large" />
+  </Media.Figure>
+
+  <Media.Body>
+    <Media.Menu label="Options">
+      <MenuItem>Edit</MenuItem>
+      <MenuItem>Delete</MenuItem>
+    </Media.Menu>
+    <div>
+      <b>Yo Yo Ma</b> commented on this file
+    </div>
+    <div>
+      Please review the notes
+      <br />a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8
+      9 0 1 2 3 4 5 6 7 8 9
+    </div>
+  </Media.Body>
+</Media>;
+```
+
+```js
+const { MenuItem } = require('../menu');
+
+<>
+  <code>
+    <span style={{ color: 'green' }}>Media</span>{' '}
+    <span style={{ color: 'purple' }}>Media.Figure</span>{' '}
+    <span style={{ color: 'orange' }}>Media.Body</span>{' '}
+    <span style={{ color: 'red' }}>Media.Menu</span>
+  </code>
+  <br />
+  <br />
+  <Media style={{ width: 300, boxShadow: '0 0 2px 3px green', padding: 5 }}>
+    <Media.Figure style={{ boxShadow: '0 0 2px 3px purple' }}>
+      <Avatar size="large" />
+    </Media.Figure>
+
+    <Media.Body style={{ boxShadow: '0 0 2px 3px orange', padding: 3 }}>
+      <Media.Menu
+        style={{ boxShadow: '0 0 2px 3px red', margin: 3, padding: 3 }}
+      >
+        <MenuItem>Edit</MenuItem>
+        <MenuItem>Delete</MenuItem>
+      </Media.Menu>
+      <div>
+        <b>Yo Yo Ma</b> commented on this file
+      </div>
+      <div>
+        Please review the notes
+        <br />a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7
+        8 9 0 1 2 3 4 5 6 7 8 9
+      </div>
+    </Media.Body>
+  </Media>
+</>;
+```
+
+## Nesting Media Components
+
+```js
+const { MenuItem } = require('../menu');
+
+<Media style={{ width: 300 }}>
+  <Media.Figure>
+    <Avatar />
+  </Media.Figure>
+
+  <Media.Body>
+    <Media.Menu>
+      <MenuItem>Edit</MenuItem>
+      <MenuItem>Delete</MenuItem>
+    </Media.Menu>
+    <div>
+      <b>Yo Yo Ma</b> commented on this file
+    </div>
+    <div>This is a nested media object</div>
+    <ul style={{ margin: 0, padding: 0 }}>
+      <Media as="li" style={{ marginTop: 10 }}>
+        <Media.Figure>
+          <Avatar />
+        </Media.Figure>
+
+        <Media.Body>
+          <div>
+            <b>Bjork</b> replied
+          </div>
+          <div>I must agree!</div>
+          <Media as="li" style={{ marginTop: 10 }}>
+            <Media.Figure>
+              <Avatar />
+            </Media.Figure>
+
+            <Media.Body>
+              <div>
+                <b>Bono</b> replied
+              </div>
+              <div>Me too!</div>
+            </Media.Body>
+          </Media>
+        </Media.Body>
+      </Media>
+    </ul>
+  </Media.Body>
+</Media>;
+```
+
+## With Form Elements
+
+```js
+const { MenuItem } = require('../menu');
+
+<Media style={{ width: 300 }}>
+  <Media.Figure>
+    <Avatar size="large" />
+  </Media.Figure>
+
+  <Media.Body>
+    <Media.Menu>
+      <MenuItem>Edit</MenuItem>
+      <MenuItem>Delete</MenuItem>
+    </Media.Menu>
+    <div>
+      <b>W.A. Mozart</b> commented on this file
+    </div>
+    <div>Everyone get ready to perform the symphony tonight!</div>
+    <div>
+      <Button>Reply</Button>
+      <Button>Cancel</Button>
+      <TextArea label="Response" />
+    </div>
+  </Media.Body>
+</Media>;
+```
diff --git a/src/components/media/Media.scss b/src/components/media/Media.scss
new file mode 100644
index 0000000000..7e2b825458
--- /dev/null
+++ b/src/components/media/Media.scss
@@ -0,0 +1,42 @@
+@import '../../styles/variables';
+
+// the outermost element
+.bdl-Media {
+    align-items: flex-start;
+    display: flex;
+}
+
+// the media content, ie, an avatar
+.bdl-Media-figure {
+    align-self: flex-start;
+    flex: 0 0 auto;
+    justify-self: flex-start;
+    margin: 0;
+    padding: 0;
+}
+
+// the main content, e.g. title and message
+.bdl-Media-body {
+    flex: 1 1 100%;
+    margin-left: 10px;
+    // handle wrapping long words in text content without breaking
+    // float position of menu
+    overflow-wrap: break-word;
+    word-break: break-word; // CJK scripts
+    word-wrap: break-word; // old IE
+}
+
+// the "..." menu button, meant to be used inside Media-body
+.bdl-Media-menu {
+    // float is used to reflow content instead of pushing it to the left
+    float: right;
+
+    // overrides for .btn-plain's margin resets on focus states
+    &,
+    &:active,
+    &:hover,
+    &:focus {
+        margin-bottom: 5px;
+        margin-left: 10px;
+    }
+}
diff --git a/src/components/media/MediaBody.js b/src/components/media/MediaBody.js
new file mode 100644
index 0000000000..df5f70311f
--- /dev/null
+++ b/src/components/media/MediaBody.js
@@ -0,0 +1,19 @@
+// @flow
+import * as React from 'react';
+import classnames from 'classnames';
+import './Media.scss';
+
+type Props = {
+    /** Child elements */
+    children: React.Node,
+    /** Additional class names */
+    className?: string,
+};
+
+const MediaBody = ({ className, children, ...rest }: Props) => (
+    <div className={classnames('bdl-Media-body', className)} {...rest}>
+        {children}
+    </div>
+);
+
+export default MediaBody;
diff --git a/src/components/media/MediaBody.md b/src/components/media/MediaBody.md
new file mode 100644
index 0000000000..2a3dc1cce4
--- /dev/null
+++ b/src/components/media/MediaBody.md
@@ -0,0 +1,30 @@
+> **Note**
+>
+> `Media` is a compound component, the inner elements are not meant to be used outside of the Media container
+
+```js
+const { MenuItem } = require('../menu');
+
+<Media style={{ width: 300 }}>
+  <Media.Figure>
+    <Avatar size="large" />
+  </Media.Figure>
+
+  <Media.Body style={{ boxShadow: '0 0 2px 3px red' }}>
+    <Media.Menu>
+      <MenuItem>Edit</MenuItem>
+      <MenuItem>Delete</MenuItem>
+    </Media.Menu>
+    <div>
+      <b>Yo Yo Ma</b> commented on this file
+    </div>
+    <div>
+      Long strings without spaces wrap:
+      <br />
+      Thistextdoesnothaveanyspacesanditshouldbewrappedinsidethecontaineralignedwiththerightedge
+      <br />a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8
+      9 0 1 2 3 4 5 6 7 8 9
+    </div>
+  </Media.Body>
+</Media>;
+```
diff --git a/src/components/media/MediaFigure.js b/src/components/media/MediaFigure.js
new file mode 100644
index 0000000000..9c99c62680
--- /dev/null
+++ b/src/components/media/MediaFigure.js
@@ -0,0 +1,28 @@
+// @flow
+import * as React from 'react';
+import classnames from 'classnames';
+import './Media.scss';
+
+type Props = {
+    /** Component to use as outermost element, e.g., 'div' */
+    as: React.ElementType,
+    /** Child elements */
+    children: React.Node,
+    /** Additional class names */
+    className?: string,
+};
+
+const MediaFigure = ({ as: Wrapper, className, children, ...rest }: Props) => (
+    <Wrapper className={classnames('bdl-Media-figure', className)} {...rest}>
+        {children}
+    </Wrapper>
+);
+
+// Use this instead of default value because of param destructuring bug in Flow
+// that affects union types
+// https://github.com/facebook/flow/issues/5461
+MediaFigure.defaultProps = {
+    as: 'figure',
+};
+
+export default MediaFigure;
diff --git a/src/components/media/MediaFigure.md b/src/components/media/MediaFigure.md
new file mode 100644
index 0000000000..5df9c49bf1
--- /dev/null
+++ b/src/components/media/MediaFigure.md
@@ -0,0 +1,28 @@
+> **Note**
+>
+> `Media` is a compound component, the inner elements are not meant to be used outside of the Media container
+
+```js
+const { MenuItem } = require('../menu');
+
+<Media style={{ width: 300 }}>
+  <Media.Figure style={{ boxShadow: '0 0 2px 3px red' }}>
+    <Avatar size="large" />
+  </Media.Figure>
+
+  <Media.Body>
+    <Media.Menu>
+      <MenuItem>Edit</MenuItem>
+      <MenuItem>Delete</MenuItem>
+    </Media.Menu>
+    <div>
+      <b>Yo Yo Ma</b> commented on this file
+    </div>
+    <div>
+      Please review the notes
+      <br />a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8
+      9 0 1 2 3 4 5 6 7 8 9
+    </div>
+  </Media.Body>
+</Media>;
+```
diff --git a/src/components/media/MediaMenu.js b/src/components/media/MediaMenu.js
new file mode 100644
index 0000000000..009c9191d8
--- /dev/null
+++ b/src/components/media/MediaMenu.js
@@ -0,0 +1,41 @@
+// @flow
+import * as React from 'react';
+import classnames from 'classnames';
+import IconEllipsis from '../../icons/general/IconEllipsis';
+import PlainButton from '../plain-button';
+import DropdownMenu from '../dropdown-menu';
+import { Menu } from '../menu';
+import { bdlGray62 } from '../../styles/variables';
+import './Media.scss';
+
+type Props = {
+    /** Child elements */
+    children: React.Node,
+    /** Additional class names for the menu button */
+    className?: string,
+    /** Additional props for the DropdownMenu */
+    dropdownProps?: {},
+    /** is the dropdown menu button disabled */
+    isDisabled: boolean,
+};
+
+const MediaMenu = ({ className, children, isDisabled, dropdownProps, ...rest }: Props) => (
+    <DropdownMenu constrainToScrollParent isRightAligned {...dropdownProps}>
+        <PlainButton
+            isDisabled={isDisabled}
+            className={classnames('bdl-Media-menu', className)}
+            type="button"
+            {...rest}
+        >
+            <IconEllipsis color={bdlGray62} height={16} width={16} />
+        </PlainButton>
+        <Menu>{children}</Menu>
+    </DropdownMenu>
+);
+
+MediaMenu.defaultProps = {
+    dropdownProps: {},
+    isDisabled: false,
+};
+
+export default MediaMenu;
diff --git a/src/components/media/MediaMenu.md b/src/components/media/MediaMenu.md
new file mode 100644
index 0000000000..c278a447fa
--- /dev/null
+++ b/src/components/media/MediaMenu.md
@@ -0,0 +1,30 @@
+> **Note**
+>
+> `Media` is a compound component, the inner elements are not meant to be used outside of the Media container
+
+Using the `Media.Menu` component is optional for a Media component and should go inside `Media.Body` for optimal reflow of the content around the menu icon
+
+```js
+const { MenuItem } = require('../menu');
+
+<Media style={{ width: 300 }}>
+  <Media.Figure>
+    <Avatar size="large" />
+  </Media.Figure>
+
+  <Media.Body style={{ boxShadow: '0 0 2px 3px orange' }}>
+    <Media.Menu style={{ boxShadow: '0 0 2px 3px red' }}>
+      <MenuItem>Edit</MenuItem>
+      <MenuItem>Delete</MenuItem>
+    </Media.Menu>
+    <div>
+      <b>Yo Yo Ma</b> commented on this file
+    </div>
+    <div>
+      Please review the notes
+      <br />a b c d e f g h i j k l m n o p q r s t u v w x y z 0 1 2 3 4 5 6 7 8
+      9 0 1 2 3 4 5 6 7 8 9
+    </div>
+  </Media.Body>
+</Media>;
+```
diff --git a/src/components/media/__tests__/Media-test.js b/src/components/media/__tests__/Media-test.js
new file mode 100644
index 0000000000..a77212d1ed
--- /dev/null
+++ b/src/components/media/__tests__/Media-test.js
@@ -0,0 +1,40 @@
+import React from 'react';
+
+import Media from '../Media';
+
+jest.mock('../../../icons/general/IconEllipsis', () => () => <icon-ellipsis />);
+
+describe('components/Media', () => {
+    test('compound component', () => {
+        const title = (
+            <div>
+                <b>Yo Yo Ma</b> commented on this file
+            </div>
+        );
+        const content = <div>Please review the notes</div>;
+
+        const compoundComponent = (
+            <Media>
+                <Media.Figure>
+                    <img src="" alt="some img" />
+                </Media.Figure>
+
+                <Media.Body>
+                    <Media.Menu />
+                    {title}
+                    {content}
+                </Media.Body>
+            </Media>
+        );
+        const wrapper = mount(compoundComponent);
+
+        expect(wrapper.render()).toMatchSnapshot();
+    });
+
+    test('"as" prop changes Media root element', () => {
+        const wrapper = shallow(<Media />);
+        const wrapperAs = shallow(<Media as="li" />);
+        expect(wrapper.is('div')).toBe(true);
+        expect(wrapperAs.is('li')).toBe(true);
+    });
+});
diff --git a/src/components/media/__tests__/MediaFigure-test.js b/src/components/media/__tests__/MediaFigure-test.js
new file mode 100644
index 0000000000..8dbef9ce6f
--- /dev/null
+++ b/src/components/media/__tests__/MediaFigure-test.js
@@ -0,0 +1,12 @@
+import React from 'react';
+
+import MediaFigure from '../MediaFigure';
+
+describe('components/Media/MediaFigure', () => {
+    test('"as" prop changes root element', () => {
+        const wrapper = shallow(<MediaFigure />);
+        const wrapperAs = shallow(<MediaFigure as="div" />);
+        expect(wrapper.is('figure')).toBe(true);
+        expect(wrapperAs.is('div')).toBe(true);
+    });
+});
diff --git a/src/components/media/__tests__/MediaMenu-test.js b/src/components/media/__tests__/MediaMenu-test.js
new file mode 100644
index 0000000000..b9256cad3a
--- /dev/null
+++ b/src/components/media/__tests__/MediaMenu-test.js
@@ -0,0 +1,18 @@
+import React from 'react';
+
+import MediaMenu from '../MediaMenu';
+
+describe('components/Media/MediaMenu', () => {
+    test('props are spread onto button', () => {
+        const extraProps = {
+            'aria-label': 'label for menu',
+            'data-testid': 'a-menu',
+            'resin-target': 'my-menu',
+        };
+        const className = 'foo';
+        const wrapper = mount(<MediaMenu className={className} {...extraProps} />);
+
+        expect(wrapper.find('PlainButton').props()).toEqual(expect.objectContaining(extraProps));
+        expect(wrapper.find('PlainButton').prop('className')).toBe(`bdl-Media-menu ${className}`);
+    });
+});
diff --git a/src/components/media/__tests__/__snapshots__/Media-test.js.snap b/src/components/media/__tests__/__snapshots__/Media-test.js.snap
new file mode 100644
index 0000000000..a16b67565e
--- /dev/null
+++ b/src/components/media/__tests__/__snapshots__/Media-test.js.snap
@@ -0,0 +1,38 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`components/Media compound component 1`] = `
+<div
+  class="bdl-Media"
+>
+  <figure
+    class="bdl-Media-figure"
+  >
+    <img
+      alt="some img"
+      src=""
+    />
+  </figure>
+  <div
+    class="bdl-Media-body"
+  >
+    <button
+      aria-expanded="false"
+      aria-haspopup="true"
+      class="btn-plain bdl-Media-menu"
+      id="menubutton2"
+      type="button"
+    >
+      <icon-ellipsis />
+    </button>
+    <div>
+      <b>
+        Yo Yo Ma
+      </b>
+       commented on this file
+    </div>
+    <div>
+      Please review the notes
+    </div>
+  </div>
+</div>
+`;
diff --git a/src/components/media/index.js b/src/components/media/index.js
new file mode 100644
index 0000000000..7496b1abc0
--- /dev/null
+++ b/src/components/media/index.js
@@ -0,0 +1,2 @@
+// @flow
+export { default } from './Media';