[AvatarGroup] Introduce new component

docs/pages/api/avatar-group.js

@@ -0,0 +1,7 @@
+import React from 'react';
+import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs';
+import markdown from './avatar-group.md';
+
+export default function Page() {
+  return <MarkdownDocs markdown={markdown} />;
+}

docs/pages/api/avatar-group.md

@@ -0,0 +1,55 @@
+---
+filename: /packages/material-ui-lab/src/AvatarGroup/AvatarGroup.js
+---
+
+<!--- This documentation is automatically generated, do not try to edit it. -->
+
+# AvatarGroup API
+
+<p class="description">The API documentation of the AvatarGroup React component. Learn more about the props and the CSS customization points.</p>
+
+## Import
+
+```js
+import AvatarGroup from '@material-ui/lab/AvatarGroup';
+// or
+import { AvatarGroup } from '@material-ui/lab';
+```
+
+You can learn more about the difference by [reading this guide](/guides/minimizing-bundle-size/).
+
+
+
+## Props
+
+| Name | Type | Default | Description |
+|:-----|:-----|:--------|:------------|
+| <span class="prop-name">children</span> | <span class="prop-type">node</span> |  | The avatars to stack. |
+| <span class="prop-name">classes</span> | <span class="prop-type">object</span> |  | Override or extend the styles applied to the component. See [CSS API](#css) below for more details. |
+
+The `ref` is forwarded to the root element.
+
+Any other props supplied will be provided to the root element (native element).
+
+## CSS
+
+- Style sheet name: `MuiAvatarGroup`.
+- Style sheet details:
+
+| Rule name | Global class | Description |
+|:-----|:-------------|:------------|
+| <span class="prop-name">root</span> | <span class="prop-name">.MuiAvatarGroup-root</span> | Styles applied to the root element.
+| <span class="prop-name">avatar</span> | <span class="prop-name">.MuiAvatarGroup-avatar</span> | Styles applied to the avatar elements.
+
+You can override the style of the component thanks to one of these customization points:
+
+- With a rule name of the [`classes` object prop](/customization/components/#overriding-styles-with-classes).
+- With a [global class name](/customization/components/#overriding-styles-with-global-class-names).
+- With a theme and an [`overrides` property](/customization/globals/#css).
+
+If that's not sufficient, you can check the [implementation of the component](https://github.com/mui-org/material-ui/blob/master/packages/material-ui-lab/src/AvatarGroup/AvatarGroup.js) for more detail.
+
+## Demos
+
+- [Avatars](/components/avatars/)
+

docs/pages/api/badge.md

@@ -73,5 +73,6 @@ If that's not sufficient, you can check the [implementation of the component](ht
 
 ## Demos
 
+- [Avatars](/components/avatars/)
 - [Badges](/components/badges/)
 

docs/src/pages/components/avatars/BadgeAvatars.js

@@ -0,0 +1,16 @@
+import React from 'react';
+import Badge from '@material-ui/core/Badge';
+import Avatar from '@material-ui/core/Avatar';
+
+export default function BadgeAvatars() {
+  return (
+    <Badge
+      overlap="circle"
+      anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+      badgeContent={1}
+      color="error"
+    >
+      <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
+    </Badge>
+  );
+}

docs/src/pages/components/avatars/BadgeAvatars.tsx

@@ -0,0 +1,16 @@
+import React from 'react';
+import Badge from '@material-ui/core/Badge';
+import Avatar from '@material-ui/core/Avatar';
+
+export default function BadgeAvatars() {
+  return (
+    <Badge
+      overlap="circle"
+      anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+      badgeContent={1}
+      color="error"
+    >
+      <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
+    </Badge>
+  );
+}

docs/src/pages/components/avatars/GroupAvatars.js

@@ -0,0 +1,17 @@
+import React from 'react';
+import Avatar from '@material-ui/core/Avatar';
+import AvatarGroup from '@material-ui/lab/AvatarGroup';
+import Tooltip from '@material-ui/core/Tooltip';
+
+export default function GroupAvatars() {
+  return (
+    <AvatarGroup>
+      <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
+      <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
+      <Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />
+      <Tooltip title="Foo • Bar • Baz">
+        <Avatar>+3</Avatar>
+      </Tooltip>
+    </AvatarGroup>
+  );
+}

docs/src/pages/components/avatars/GroupAvatars.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import Avatar from '@material-ui/core/Avatar';
+import AvatarGroup from '@material-ui/lab/AvatarGroup';
+import Tooltip from '@material-ui/core/Tooltip';
+
+export default function GroupAvatars() {
+  return (
+    <AvatarGroup>
+      <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
+      <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
+      <Avatar alt="Cindy Baker" src="/static/images/avatar/3.jpg" />
+      <Tooltip title="Foo • Bar • Baz">
+        <Avatar>+3</Avatar>
+      </Tooltip>
+    </AvatarGroup>
+  );
+}

docs/src/pages/components/avatars/IconAvatars.js

@@ -14,7 +14,7 @@ const useStyles = makeStyles(theme => ({
     },
   },
   pink: {
-    color: '#fff',
+    color: theme.palette.getContrastText(pink[500]),
     backgroundColor: pink[500],
   },
   green: {

docs/src/pages/components/avatars/IconAvatars.tsx

@@ -15,7 +15,7 @@ const useStyles = makeStyles((theme: Theme) =>
       },
     },
     pink: {
-      color: '#fff',
+      color: theme.palette.getContrastText(pink[500]),
       backgroundColor: pink[500],
     },
     green: {

docs/src/pages/components/avatars/LetterAvatars.js

@@ -11,11 +11,11 @@ const useStyles = makeStyles(theme => ({
     },
   },
   orange: {
-    color: '#fff',
+    color: theme.palette.getContrastText(deepOrange[500]),
     backgroundColor: deepOrange[500],
   },
   purple: {
-    color: '#fff',
+    color: theme.palette.getContrastText(deepPurple[500]),
     backgroundColor: deepPurple[500],
   },
 }));

docs/src/pages/components/avatars/LetterAvatars.tsx

@@ -12,11 +12,11 @@ const useStyles = makeStyles((theme: Theme) =>
       },
     },
     orange: {
-      color: '#fff',
+      color: theme.palette.getContrastText(deepOrange[500]),
       backgroundColor: deepOrange[500],
     },
     purple: {
-      color: '#fff',
+      color: theme.palette.getContrastText(deepPurple[500]),
       backgroundColor: deepPurple[500],
     },
   }),

docs/src/pages/components/avatars/VariantAvatars.js

@@ -12,7 +12,7 @@ const useStyles = makeStyles(theme => ({
     },
   },
   square: {
-    color: '#fff',
+    color: theme.palette.getContrastText(deepOrange[500]),
     backgroundColor: deepOrange[500],
   },
   rounded: {

docs/src/pages/components/avatars/VariantAvatars.tsx

@@ -13,7 +13,7 @@ const useStyles = makeStyles((theme: Theme) =>
       },
     },
     square: {
-      color: '#fff',
+      color: theme.palette.getContrastText(deepOrange[500]),
       backgroundColor: deepOrange[500],
     },
     rounded: {

docs/src/pages/components/avatars/avatars.md

@@ -1,6 +1,6 @@
 ---
 title: Avatar React component
-components: Avatar
+components: Avatar, AvatarGroup, Badge
 ---
 
 # Avatar
@@ -40,3 +40,13 @@ The component fallbacks if there is an error loading the avatar image, in this o
 - a generic avatar icon
 
 {{"demo": "pages/components/avatars/FallbackAvatars.js"}}
+
+## With badge
+
+{{"demo": "pages/components/avatars/BadgeAvatars.js"}}
+
+## Grouped
+
+`AvatarGroup` is a wrapper around avatars designed to render a stacked collection of avatars.
+
+{{"demo": "pages/components/avatars/GroupAvatars.js"}}

docs/src/pages/components/badges/CustomizedBadges.js

@@ -69,7 +69,7 @@ export default function CustomizedBadges() {
           }}
           variant="dot"
         >
-          <Avatar alt="Stock avatar" src="/static/images/avatar/1.jpg" />
+          <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
         </StyledBadge2>
       </Box>
       <Box m={1}>
@@ -81,7 +81,7 @@ export default function CustomizedBadges() {
           }}
           badgeContent={<SmallAvatar alt="Stock avatar" src="/static/images/avatar/1.jpg" />}
         >
-          <Avatar alt="Stock avatar" src="/static/images/avatar/2.jpg" />
+          <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
         </Badge>
       </Box>
     </Box>

docs/src/pages/components/badges/CustomizedBadges.tsx

@@ -75,7 +75,7 @@ export default function CustomizedBadges() {
           }}
           variant="dot"
         >
-          <Avatar alt="Stock avatar" src="/static/images/avatar/1.jpg" />
+          <Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />
         </StyledBadge2>
       </Box>
       <Box m={1}>
@@ -87,7 +87,7 @@ export default function CustomizedBadges() {
           }}
           badgeContent={<SmallAvatar alt="Stock avatar" src="/static/images/avatar/1.jpg" />}
         >
-          <Avatar alt="Stock avatar" src="/static/images/avatar/2.jpg" />
+          <Avatar alt="Travis Howard" src="/static/images/avatar/2.jpg" />
         </Badge>
       </Box>
     </Box>

packages/material-ui-lab/src/AvatarGroup/AvatarGroup.d.ts

@@ -0,0 +1,14 @@
+import * as React from 'react';
+import { StandardProps } from '@material-ui/core';
+
+export interface AvatarGroupProps
+  extends StandardProps<React.HTMLAttributes<HTMLDivElement>, AvatarGroupClassKey> {
+  /**
+   * The avatars to stack.
+   */
+  children: React.ReactNode;
+}
+
+export type AvatarGroupClassKey = 'root' | 'avatar';
+
+export default function AvatarGroup(props: AvatarGroupProps): JSX.Element | null;

packages/material-ui-lab/src/AvatarGroup/AvatarGroup.js

@@ -0,0 +1,72 @@
+import React from 'react';
+import PropTypes from 'prop-types';
+import { isFragment } from 'react-is';
+import clsx from 'clsx';
+import { withStyles } from '@material-ui/core/styles';
+
+export const styles = theme => ({
+  /* Styles applied to the root element. */
+  root: {
+    display: 'flex',
+  },
+  /* Styles applied to the avatar elements. */
+  avatar: {
+    border: `2px solid ${theme.palette.background.default}`,
+    marginLeft: -8,
+  },
+});
+
+const AvatarGroup = React.forwardRef(function AvatarGroup(props, ref) {
+  const { children: childrenProp, classes, className, ...other } = props;
+
+  const children = React.Children.toArray(childrenProp).filter(child => {
+    if (process.env.NODE_ENV !== 'production') {
+      if (isFragment(child)) {
+        console.error(
+          [
+            "Material-UI: the AvatarGroup component doesn't accept a Fragment as a child.",
+            'Consider providing an array instead.',
+          ].join('\n'),
+        );
+      }
+    }
+
+    return React.isValidElement(child);
+  });
+
+  return (
+    <div className={clsx(classes.root, className)} ref={ref} {...other}>
+      {children.map((child, index) => {
+        return React.cloneElement(child, {
+          className: clsx(child.props.className, classes.avatar),
+          style: {
+            zIndex: children.length - index,
+            ...child.props.style,
+          },
+        });
+      })}
+    </div>
+  );
+});
+
+AvatarGroup.propTypes = {
+  // ----------------------------- Warning --------------------------------
+  // | These PropTypes are generated from the TypeScript type definitions |
+  // |     To update them edit the d.ts file and run "yarn proptypes"     |
+  // ----------------------------------------------------------------------
+  /**
+   * The avatars to stack.
+   */
+  children: PropTypes.node,
+  /**
+   * Override or extend the styles applied to the component.
+   * See [CSS API](#css) below for more details.
+   */
+  classes: PropTypes.object,
+  /**
+   * @ignore
+   */
+  className: PropTypes.string,
+};
+
+export default withStyles(styles, { name: 'MuiAvatarGroup' })(AvatarGroup);

packages/material-ui-lab/src/AvatarGroup/AvatarGroup.test.js

@@ -0,0 +1,26 @@
+import React from 'react';
+import { createMount, getClasses } from '@material-ui/core/test-utils';
+import describeConformance from '@material-ui/core/test-utils/describeConformance';
+import AvatarGroup from './AvatarGroup';
+
+describe('<AvatarGroup />', () => {
+  let mount;
+  let classes;
+
+  before(() => {
+    mount = createMount({ strict: true });
+    classes = getClasses(<AvatarGroup />);
+  });
+
+  after(() => {
+    mount.cleanUp();
+  });
+
+  describeConformance(<AvatarGroup />, () => ({
+    classes,
+    inheritComponent: 'div',
+    mount,
+    refInstanceof: window.HTMLDivElement,
+    skip: ['componentProp'],
+  }));
+});

packages/material-ui-lab/src/AvatarGroup/index.d.ts

@@ -0,0 +1,2 @@
+export { default } from './AvatarGroup';
+export * from './AvatarGroup';

packages/material-ui-lab/src/AvatarGroup/index.js

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

packages/material-ui-lab/src/index.d.ts

@@ -1,6 +1,9 @@
 export { default as Autocomplete } from './Autocomplete';
 export * from './Autocomplete';
 
+export { default as AvatarGroup } from './AvatarGroup';
+export * from './AvatarGroup';
+
 export { default as Rating } from './Rating';
 export * from './Rating';