feat(list): Add List Group and List Group Subheader (#386)

Author: bonniezhou

package.json

@@ -31,11 +31,13 @@
           "card",
           "checkbox",
           "chips",
+          "drawer",
           "fab",
           "floating-label",
           "icon-button",
           "layout-grid",
           "line-ripple",
+          "list",
           "menu-surface",
           "ripple",
           "select",

packages/list/.npmignore

@@ -1,3 +1,7 @@
 index.js
-ListDivider.js
+ListGroup.js
+ListGroupSubheader.js
 ListItem.js
+ListItemGraphic.js
+ListItemMeta.js
+ListItemText.js

packages/list/ListGroup.js

@@ -0,0 +1,54 @@
+// The MIT License
+//
+// Copyright (c) 2018 Google, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import React from 'react';
+import PropTypes from 'prop-types';
+import classnames from 'classnames';
+
+const ListGroup = (props) => {
+  const {
+    tag: Tag,
+    className,
+    children,
+    ...otherProps
+  } = props;
+
+  return (
+    <Tag className={classnames('mdc-list-group', className)} {...otherProps}>
+      {children}
+    </Tag>
+  );
+};
+
+ListGroup.propTypes = {
+  className: PropTypes.string,
+  children: PropTypes.element,
+  tag: PropTypes.string,
+};
+
+ListGroup.defaultProps = {
+  className: '',
+  children: null,
+  tag: 'div',
+};
+
+export default ListGroup;

packages/list/ListGroupSubheader.js

@@ -0,0 +1,57 @@
+// The MIT License
+//
+// Copyright (c) 2018 Google, Inc.
+//
+// Permission is hereby granted, free of charge, to any person obtaining a copy
+// of this software and associated documentation files (the "Software"), to deal
+// in the Software without restriction, including without limitation the rights
+// to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+// copies of the Software, and to permit persons to whom the Software is
+// furnished to do so, subject to the following conditions:
+//
+// The above copyright notice and this permission notice shall be included in
+// all copies or substantial portions of the Software.
+//
+// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+// OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+// THE SOFTWARE.
+
+import React from 'react';
+import PropTypes from 'prop-types';
+import classnames from 'classnames';
+
+const ListGroupSubheader = (props) => {
+  const {
+    tag: Tag,
+    className,
+    children,
+    ...otherProps
+  } = props;
+
+  return (
+    <Tag className={classnames('mdc-list-group__subheader', className)} {...otherProps}>
+      {children}
+    </Tag>
+  );
+};
+
+ListGroupSubheader.propTypes = {
+  className: PropTypes.string,
+  children: PropTypes.oneOfType([
+    PropTypes.string,
+    PropTypes.element,
+  ]),
+  tag: PropTypes.string,
+};
+
+ListGroupSubheader.defaultProps = {
+  className: '',
+  children: '',
+  tag: 'h3',
+};
+
+export default ListGroupSubheader;

packages/list/README.md

@@ -28,7 +28,7 @@ import "@material/react-list/dist/list.css";
 
 ```js
 import React, {Component} from 'react';
-import List, {ListItem} from '@material/react-list';
+import List, {ListItem, ListItemText} from '@material/react-list';
 
 class MyApp extends Component {
   render() {
@@ -56,6 +56,9 @@ class MyApp extends Component {
 You can use the `twoLine` Boolean prop for `List` combined with the `secondaryText` prop for `ListItem` to style a list as a double line list.
 
 ```js
+import React, {Component} from 'react';
+import List, {ListItem, ListItemText} from '@material/react-list';
+
 class MyApp extends React.Component {
   render() {
     return (
@@ -87,7 +90,7 @@ You may add a leading visuals or trailing metadata to a list item using `ListIte
 
 ```js
 import React, {Component} from 'react';
-import List, {ListItem} from '@material/react-list';
+import List, {ListItem, ListItemGraphic, ListItemText, ListItemMeta} from '@material/react-list';
 
 class MyApp extends Component {
   render() {
@@ -105,6 +108,36 @@ class MyApp extends Component {
 }
 ```
 
+### List groups
+
+Multiple related lists can be grouped together using the `ListGroup` component. Optional subheaders can be added using `ListGroupSubheader`.
+
+> _NOTE_: You can override the element that the `ListGroup` or `ListGroupSubheader` renders by passing in a `tag` prop. By default, `ListGroup` renders a `div` and `ListGroupSubheader` renders an `h3`.
+
+```js
+import React, {Component} from 'react';
+import List, {ListItem, ListItemText, ListGroup, ListGroupSubheader} from '@material/react-list';
+
+class MyApp extends Component {
+  render() {
+    return (
+      <ListGroup>
+        <ListGroupSubheader tag='h2'>Folders</ListGroupSubheader>
+        <List>
+          <ListItem><ListItemText primaryText='Photos' /></ListItem>
+          ...
+        </List>
+        <ListGroupSubheader tag='h2'>Recent Files</ListGroupSubheader>
+        <List>
+          <ListItem><ListItemText primaryText='Vacation' /></ListItem>
+          ...
+        </List>
+      </ListGroup>
+    );
+  }
+}
+```
+
 ### Single Selection
 
 You can use the `singleSelection` Boolean prop for `List` to allow for selection of list items. You can also set the `selectedIndex` of the list programmatically.

packages/list/index.js

@@ -30,6 +30,8 @@ import ListItem from './ListItem';
 import ListItemGraphic from './ListItemGraphic';
 import ListItemText from './ListItemText';
 import ListItemMeta from './ListItemMeta';
+import ListGroup from './ListGroup';
+import ListGroupSubheader from './ListGroupSubheader';
 
 const ARIA_ORIENTATION = 'aria-orientation';
 const VERTICAL = 'vertical';
@@ -334,4 +336,4 @@ List.defaultProps = {
 
 /* eslint-enable quote-props */
 
-export {ListItem, ListItemGraphic, ListItemText, ListItemMeta};
+export {ListItem, ListItemGraphic, ListItemText, ListItemMeta, ListGroup, ListGroupSubheader};

test/screenshot/golden.json

@@ -8,7 +8,7 @@
   "icon-button": "5ffb1f7fbd06d2c0533f6ba8d4d9ea170cec1a248a61de1cc1bb626cb58ebcd2",
   "layout-grid": "fe40f7a34853bc2a1d9a836e812599d4d47b5b26b839a8eaed7f98ea91946790",
   "line-ripple": "56b136db2dc7e09260849447e6bde9b55a837af332a05d9f52506ab1c95e2e57",
-  "list": "2d98c951d42a2e724d57083159aebdc34848bbd3fa2c264c8595ea0982cc1a99",
+  "list": "3a7f7334d1a3f883122e4b410ea1b23b7601754aa44ff46ee24d31aeb808632d",
   "material-icon": "442b39fb22d2c7a74efb23ca098429b471501ce21df8662327bbf9871fe0bcb0",
   "menu-surface": "f5face1a24fe166e86e8a3dc35ea85b2d4431469a3d06bf6fc1a30fbdc175aff",
   "notched-outline": "7770dd381c27608a1f43b6f83da92507fe53963f5e4409bd73184b86275538fe",

test/screenshot/list/index.js

@@ -3,11 +3,14 @@ import './index.scss';
 import '../../../packages/list/index.scss';
 
 import MaterialIcon from '../../../packages/material-icon';
-import List from '../../../packages/list/index';
-import {ListItem} from '../../../packages/list/index';
-import ListItemGraphic from '../../../packages/list/ListItemGraphic';
-import ListItemText from '../../../packages/list/ListItemText';
-import ListItemMeta from '../../../packages/list/ListItemMeta';
+import List, {
+  ListItem,
+  ListItemGraphic,
+  ListItemText,
+  ListItemMeta,
+  ListGroup,
+  ListGroupSubheader,
+} from '../../../packages/list/index';
 
 class SelectionListTest extends React.Component {
   state = {
@@ -41,21 +44,34 @@ const renderListItem = (primaryText, secondaryText) => {
 const ListScreenshotTest = () => {
   return (
     <div>
-      <h2>Two-line Selection List</h2>
+      <h2>Two-line selection list</h2>
       <SelectionListTest twoLine>
-        {renderListItem('hello', 'world')}
-        {renderListItem('hello', 'world')}
-        {renderListItem('hello', 'world')}
-        {renderListItem('hello', 'world')}
+        {renderListItem('List item', 'Secondary text')}
+        {renderListItem('List item', 'Secondary text')}
+        {renderListItem('List item', 'Secondary text')}
       </SelectionListTest>
 
-      <h2>One-line List</h2>
+      <h2>One-line list</h2>
       <List>
-        {renderListItem('hello')}
-        {renderListItem('hello')}
-        {renderListItem('hello')}
-        {renderListItem('hello')}
+        {renderListItem('List item')}
+        {renderListItem('List item')}
+        {renderListItem('List item')}
       </List>
+
+      <h2>List group</h2>
+      <ListGroup>
+        <ListGroupSubheader>Folders</ListGroupSubheader>
+        <List>
+          {renderListItem('Photos')}
+          {renderListItem('Recipes')}
+          {renderListItem('Work')}
+        </List>
+        <ListGroupSubheader>Recent Files</ListGroupSubheader>
+        <List>
+          {renderListItem('Vacation itinerary')}
+          {renderListItem('Kitchen remodel')}
+        </List>
+      </ListGroup>
     </div>
   );
 };

test/unit/list/ListGroup.test.js

@@ -0,0 +1,26 @@
+import React from 'react';
+import {assert} from 'chai';
+import {shallow} from 'enzyme';
+import {ListGroup} from '../../../packages/list';
+
+suite('ListGroup');
+
+test('className adds classes', () => {
+  const wrapper = shallow(<ListGroup className='test-class-name' />);
+  assert.isTrue(wrapper.hasClass('test-class-name'));
+});
+
+test('has mdc-list-group class', () => {
+  const wrapper = shallow(<ListGroup />);
+  assert.isTrue(wrapper.hasClass('mdc-list-group'));
+});
+
+test('renders children', () => {
+  const wrapper = shallow(<ListGroup><div className='child-list'/></ListGroup>);
+  assert.exists(wrapper.find('.child-list'));
+});
+
+test('renders with given tag', () => {
+  const wrapper = shallow(<ListGroup tag='span' />);
+  assert.exists(wrapper.find('span'));
+});

test/unit/list/ListGroupSubheader.test.js

@@ -0,0 +1,26 @@
+import React from 'react';
+import {assert} from 'chai';
+import {shallow} from 'enzyme';
+import {ListGroupSubheader} from '../../../packages/list';
+
+suite('ListGroupSubheader');
+
+test('className adds classes', () => {
+  const wrapper = shallow(<ListGroupSubheader className='test-class-name' />);
+  assert.isTrue(wrapper.hasClass('test-class-name'));
+});
+
+test('has mdc-list-group__subheader class', () => {
+  const wrapper = shallow(<ListGroupSubheader />);
+  assert.isTrue(wrapper.hasClass('mdc-list-group__subheader'));
+});
+
+test('renders children', () => {
+  const wrapper = shallow(<ListGroupSubheader><div className='child-list'/></ListGroupSubheader>);
+  assert.exists(wrapper.find('.child-list'));
+});
+
+test('renders with given tag', () => {
+  const wrapper = shallow(<ListGroupSubheader tag='span' />);
+  assert.exists(wrapper.find('span'));
+});