added avatar token component (#15466)

* added avatar token component

* added avatar token component story

* added avatar token readme to story

* added avatar token readme to story

* added halo effect

* added test to avatar token component

* fixed alt name

* added test for blur

* added test for aria hidden element

* fixed fallback issue

* updated halo id in README

* added changes to avatar token stories

* updated stories and README in storybook

* fixed indentation in stories

* changed component name structure

* updated css for avatar halo image

* updated README for Avatar Base Component

* added className to avatar Token

* Updates to docs and styles

* fixed tests for Avatar Token

* added color to the props

* fixed table props issue

* updated avatar token Readme

* updated args in avatar token stories

Co-authored-by: georgewrmarshall <george.marshall@consensys.net>

ui/components/component-library/avatar-token/README.mdx

@@ -0,0 +1,67 @@
+import { Story, Canvas, ArgsTable } from '@storybook/addon-docs';
+
+import { AvatarToken } from './avatar-token';
+
+# AvatarToken
+
+The `AvatarToken` is a component responsible for display of the image of a given token
+
+<Canvas>
+  <Story id="ui-components-component-library-avatar-token-avatar-token-stories-js--default-story" />
+</Canvas>
+
+## Props
+
+The `AvatarToken` accepts all props below as well as all [Box](/docs/ui-components-ui-box-box-stories-js--default-story#props) component props
+
+<ArgsTable of={AvatarToken} />
+
+### Size
+
+Use the `size` prop to set the size of the `AvatarToken`.
+
+Possible sizes include:
+
+- `xs` 16px
+- `sm` 24px
+- `md` 32px
+- `lg` 40px
+- `xl` 48px
+
+Defaults to `md`
+
+<Canvas>
+  <Story id="ui-components-component-library-avatar-token-avatar-token-stories-js--size" />
+</Canvas>
+
+### Token Name
+
+Use the ` tokenName` prop to set the initial letter of the `AvatarToken`. This will be used as the fallback display if no image url is passed to the `tokenImageUrl` prop.
+
+<Canvas>
+  <Story id="ui-components-component-library-avatar-token-avatar-token-stories-js--token-name" />
+</Canvas>
+
+### Token Image Url
+
+Use the `tokenImageUrl` prop to set the image to be rendered of the `AvatarToken`.
+
+<Canvas>
+  <Story id="ui-components-component-library-avatar-token-avatar-token-stories-js--token-image-url" />
+</Canvas>
+
+### Show Halo
+
+If we want to display the component with halo effect. Only works if an image url is supplied to `tokenImageUrl`
+
+<Canvas>
+  <Story id="ui-components-component-library-avatar-token-avatar-token-stories-js--show-halo" />
+</Canvas>
+
+### Color, Background Color And Border Color
+
+Use the `color`, `backgroundColor` and `borderColor` props to set the text color, background-color and border-color of the `AvatarToken`.
+
+<Canvas>
+  <Story id="ui-components-component-library-avatar-token-avatar-token-stories-js--color-background-color-and-border-color" />
+</Canvas>

ui/components/component-library/avatar-token/avatar-token.js

@@ -0,0 +1,121 @@
+import React, { useState, useEffect } from 'react';
+import classnames from 'classnames';
+import PropTypes from 'prop-types';
+import Box from '../../ui/box/box';
+import { BaseAvatar } from '../base-avatar';
+
+import {
+  COLORS,
+  SIZES,
+  DISPLAY,
+  ALIGN_ITEMS,
+  JUSTIFY_CONTENT,
+} from '../../../helpers/constants/design-system';
+
+export const AvatarToken = ({
+  size = SIZES.MD,
+  tokenName,
+  tokenImageUrl,
+  showHalo,
+  color = COLORS.TEXT_DEFAULT,
+  backgroundColor = COLORS.BACKGROUND_ALTERNATIVE,
+  borderColor = COLORS.TRANSPARENT,
+  className,
+  ...props
+}) => {
+  const [showFallback, setShowFallback] = useState(false);
+
+  useEffect(() => {
+    setShowFallback(!tokenImageUrl);
+  }, [tokenImageUrl]);
+
+  const handleOnError = () => {
+    setShowFallback(true);
+  };
+
+  const fallbackString = tokenName && tokenName[0] ? tokenName[0] : '?';
+
+  return (
+    <BaseAvatar
+      size={size}
+      display={DISPLAY.FLEX}
+      alignItems={ALIGN_ITEMS.CENTER}
+      justifyContent={JUSTIFY_CONTENT.CENTER}
+      className={classnames(
+        'avatar-token',
+        showHalo && 'avatar-token--with-halo',
+        className,
+      )}
+      {...{ backgroundColor, borderColor, color, ...props }}
+    >
+      {showFallback ? (
+        fallbackString
+      ) : (
+        <>
+          {showHalo && (
+            <img
+              src={tokenImageUrl}
+              className={showHalo ? 'avatar-token__token-image--blurred' : ''}
+              aria-hidden="true"
+            />
+          )}
+          <img
+            className={
+              showHalo
+                ? 'avatar-token__token-image--size-reduced'
+                : 'avatar-token__token-image'
+            }
+            onError={handleOnError}
+            src={tokenImageUrl}
+            alt={tokenName || 'token avatar'}
+          />
+        </>
+      )}
+    </BaseAvatar>
+  );
+};
+
+AvatarToken.propTypes = {
+  /**
+   * The tokenName accepts the string to render the first letter of the AvatarToken. This will be used as the fallback display if no image url is passed to the tokenImageUrl
+   */
+  tokenName: PropTypes.string,
+  /**
+   * The tokenImageUrl accepts the string of the image to be rendered
+   */
+  tokenImageUrl: PropTypes.string,
+  /**
+   * The showHalo accepts a boolean prop to render the image with halo effect
+   */
+  showHalo: PropTypes.bool,
+  /**
+   * The size of the AvatarToken.
+   * Possible values could be 'SIZES.XS', 'SIZES.SM', 'SIZES.MD', 'SIZES.LG', 'SIZES.XL'
+   * Defaults to SIZES.MD
+   */
+  size: PropTypes.oneOf(Object.values(SIZES)),
+  /**
+   * The background color of the AvatarToken
+   * Defaults to COLORS.BACKGROUND_ALTERNATIVE
+   */
+  backgroundColor: Box.propTypes.backgroundColor,
+  /**
+   * The background color of the AvatarToken
+   * Defaults to COLORS.BORDER_DEFAULT
+   */
+  borderColor: Box.propTypes.borderColor,
+  /**
+   * The color of the text inside the AvatarToken
+   * Defaults to COLORS.TEXT_DEFAULT
+   */
+  color: Box.propTypes.color,
+  /**
+   * Additional classNames to be added to the AvatarToken
+   */
+  className: PropTypes.string,
+  /**
+   * AvatarToken also accepts all Box props including but not limited to
+   * className, as(change root element of HTML element) and margin props
+   */
+  ...Box.propTypes,
+};

ui/components/component-library/avatar-token/avatar-token.scss

@@ -0,0 +1,23 @@
+.avatar-token {
+  &--with-halo {
+    position: relative;
+  }
+
+  &__token-image {
+    width: 100%;
+
+    &--blurred {
+      filter: blur(20px);
+    }
+
+    &--size-reduced {
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      transform: translate(-50%, -50%);
+      width: 62.5%;
+      height: 62.5%;
+      border-radius: 50%;
+    }
+  }
+}

ui/components/component-library/avatar-token/avatar-token.stories.js

@@ -0,0 +1,124 @@
+import React from 'react';
+import {
+  COLORS,
+  SIZES,
+  DISPLAY,
+  ALIGN_ITEMS,
+  TEXT_COLORS,
+  BACKGROUND_COLORS,
+  BORDER_COLORS,
+} from '../../../helpers/constants/design-system';
+
+import Box from '../../ui/box/box';
+
+import README from './README.mdx';
+import { AvatarToken } from './avatar-token';
+
+export default {
+  title: 'Components/ComponentLibrary/AvatarToken',
+  id: __filename,
+  component: AvatarToken,
+  parameters: {
+    docs: {
+      page: README,
+    },
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: Object.values(SIZES),
+    },
+    color: {
+      options: Object.values(TEXT_COLORS),
+      control: 'select',
+    },
+    backgroundColor: {
+      options: Object.values(BACKGROUND_COLORS),
+      control: 'select',
+    },
+    borderColor: {
+      options: Object.values(BORDER_COLORS),
+      control: 'select',
+    },
+    tokenName: {
+      control: 'text',
+    },
+    tokenImageUrl: {
+      control: 'text',
+    },
+    showHalo: {
+      control: 'boolean',
+    },
+  },
+  args: {
+    tokenName: 'ast',
+    tokenImageUrl: './AST.png',
+    size: SIZES.MD,
+    showHalo: false,
+  },
+};
+
+const Template = (args) => {
+  return <AvatarToken {...args} />;
+};
+
+export const DefaultStory = Template.bind({});
+DefaultStory.storyName = 'Default';
+
+export const Size = (args) => (
+  <Box display={DISPLAY.FLEX} alignItems={ALIGN_ITEMS.BASELINE} gap={1}>
+    <AvatarToken {...args} size={SIZES.XS} />
+    <AvatarToken {...args} size={SIZES.SM} />
+    <AvatarToken {...args} size={SIZES.MD} />
+    <AvatarToken {...args} size={SIZES.LG} />
+    <AvatarToken {...args} size={SIZES.XL} />
+  </Box>
+);
+
+export const tokenName = Template.bind({});
+tokenName.args = {
+  tokenImageUrl: '',
+};
+
+export const tokenImageUrl = Template.bind({});
+
+export const showHalo = Template.bind({});
+showHalo.args = {
+  showHalo: true,
+};
+
+export const ColorBackgroundColorAndBorderColor = (args) => (
+  <Box display={DISPLAY.FLEX} gap={1}>
+    <AvatarToken
+      {...args}
+      backgroundColor={COLORS.KOVAN}
+      borderColor={COLORS.KOVAN}
+      tokenName="K"
+      color={COLORS.PRIMARY_INVERSE} // TODO: This will have to be added to the BaseAvatar component as a prop so we can change the color of the text and to the base avatar
+    />
+    <AvatarToken
+      {...args}
+      backgroundColor={COLORS.RINKEBY}
+      borderColor={COLORS.RINKEBY}
+      tokenName="R"
+      color={COLORS.PRIMARY_INVERSE} // TODO: This will have to be added to the BaseAvatar component as a prop so we can change the color of the text and to the base avatar
+    />
+    <AvatarToken
+      {...args}
+      backgroundColor={COLORS.GOERLI}
+      borderColor={COLORS.GOERLI}
+      tokenName="G"
+      color={COLORS.PRIMARY_INVERSE} // TODO: This will have to be added to the BaseAvatar component as a prop so we can change the color of the text and to the base avatar
+    />
+    <AvatarToken
+      {...args}
+      backgroundColor={COLORS.ROPSTEN}
+      borderColor={COLORS.ROPSTEN}
+      tokenName="R"
+      color={COLORS.PRIMARY_INVERSE} // TODO: This will have to be added to the BaseAvatar component as a prop so we can change the color of the text and to the base avatar
+    />
+  </Box>
+);
+ColorBackgroundColorAndBorderColor.args = {
+  tokenImageUrl: '',
+};

ui/components/component-library/avatar-token/avatar-token.test.js

@@ -0,0 +1,50 @@
+/* eslint-disable jest/require-top-level-describe */
+import { render, screen } from '@testing-library/react';
+import React from 'react';
+
+import { AvatarToken } from './avatar-token';
+
+describe('AvatarToken', () => {
+  const args = {
+    tokenName: 'ast',
+    tokenImageUrl: './AST.png',
+    showHalo: false,
+  };
+
+  it('should render correctly', () => {
+    const { getByTestId } = render(<AvatarToken data-testid="avatar-token" />);
+    expect(getByTestId('avatar-token')).toBeDefined();
+  });
+
+  it('should render image Avatar', () => {
+    render(<AvatarToken {...args} data-testid="avatar-token" />);
+    const image = screen.getByRole('img');
+    expect(image).toBeDefined();
+    expect(image).toHaveAttribute('src', args.tokenImageUrl);
+  });
+
+  it('should render the first letter of the tokenName prop if no tokenImageUrl is provided', () => {
+    const { getByText } = render(
+      <AvatarToken {...args} data-testid="avatar-token" tokenImageUrl="" />,
+    );
+    expect(getByText('a')).toBeDefined();
+  });
+
+  it('should render halo effect if showHalo is true and image url is there', () => {
+    render(<AvatarToken {...args} data-testid="avatar-token" showHalo />);
+    const image = screen.getAllByRole('img', { hidden: true });
+    expect(image[1]).toHaveClass('avatar-token__token-image--size-reduced');
+  });
+
+  it('should render text showHalo is true and no image url is provided', () => {
+    const { getByText } = render(
+      <AvatarToken
+        {...args}
+        tokenImageUrl=""
+        data-testid="avatar-token"
+        showHalo
+      />,
+    );
+    expect(getByText('a')).toBeDefined();
+  });
+});

ui/components/component-library/avatar-token/index.js

@@ -0,0 +1 @@
+export { AvatarToken } from './avatar-token';

ui/components/component-library/base-avatar/README.mdx

@@ -44,10 +44,10 @@ The `BaseAvatar` component can contain images, icons or text
   <Story id="ui-components-component-library-base-avatar-base-avatar-stories-js--children" />
 </Canvas>
 
-### Background and border color
+### Color, Background Color And Border Color
 
-Use the `backgroundColor` and `borderColor` prop to set the background and border colors of the avatar
+Use the `color`, `backgroundColor` and `borderColor` props to set the text color, background-color and border-color of the s of the `BaseAvatar`.
 
 <Canvas>
-  <Story id="ui-components-component-library-base-avatar-base-avatar-stories-js--background-and-border-color" />
+  <Story id="ui-components-component-library-base-avatar-base-avatar-stories-js--color-background-color-and-border-color" />
 </Canvas>

ui/components/component-library/base-avatar/base-avatar.js

@@ -1,6 +1,7 @@
 import React from 'react';
 import PropTypes from 'prop-types';
 import classnames from 'classnames';
+
 import Box from '../../ui/box/box';
 import { COLORS, SIZES } from '../../../helpers/constants/design-system';
 
@@ -9,11 +10,17 @@ export const BaseAvatar = ({
   children,
   backgroundColor = COLORS.BACKGROUND_ALTERNATIVE,
   borderColor = COLORS.BORDER_DEFAULT,
+  color = COLORS.TEXT_DEFAULT,
+  className,
   ...props
 }) => (
   <Box
-    className={classnames('base-avatar', `base-avatar--size-${size}`)}
-    {...{ backgroundColor, borderColor, ...props }}
+    className={classnames(
+      'base-avatar',
+      `base-avatar--size-${size}`,
+      className,
+    )}
+    {...{ backgroundColor, borderColor, color, ...props }}
   >
     {children}
   </Box>
@@ -22,7 +29,8 @@ export const BaseAvatar = ({
 BaseAvatar.propTypes = {
   /**
    * The size of the BaseAvatar.
-   * Possible values could be 'xs', 'sm', 'md', 'lg', 'xl',
+   * Possible values could be 'SIZES.XS', 'SIZES.SM', 'SIZES.MD', 'SIZES.LG', 'SIZES.XL'
+   * Defaults to SIZES.MD
    */
   size: PropTypes.oneOf(Object.values(SIZES)),
   /**
@@ -31,14 +39,26 @@ BaseAvatar.propTypes = {
   children: PropTypes.node,
   /**
    * The background color of the BaseAvatar
+   * Defaults to COLORS.BACKGROUND_ALTERNATIVE
    */
   backgroundColor: Box.propTypes.backgroundColor,
   /**
    * The background color of the BaseAvatar
+   * Defaults to COLORS.BORDER_DEFAULT
    */
   borderColor: Box.propTypes.borderColor,
   /**
-   * BaseAvatar accepts all the props from Box
+   * The color of the text inside the BaseAvatar
+   * Defaults to COLORS.TEXT_DEFAULT
+   */
+  color: Box.propTypes.color,
+  /**
+   * Additional classNames to be added to the AvatarToken
+   */
+  className: PropTypes.string,
+  /**
+   * BaseAvatar also accepts all Box props including but not limited to
+   * className, as(change root element of HTML element) and margin props
    */
   ...Box.propTypes,
 };

ui/components/component-library/base-avatar/base-avatar.scss

@@ -28,4 +28,5 @@
   display: flex;
   align-items: center;
   justify-content: center;
+  text-transform: uppercase;
 }

ui/components/component-library/base-avatar/base-avatar.stories.js

@@ -4,8 +4,11 @@ import {
   COLORS,
   DISPLAY,
   SIZES,
+  TEXT_COLORS,
+  BACKGROUND_COLORS,
+  BORDER_COLORS,
 } from '../../../helpers/constants/design-system';
-import { ValidBackgroundColors, ValidBorderColors } from '../../ui/box';
+
 import Box from '../../ui/box/box';
 
 import README from './README.mdx';
@@ -42,12 +45,16 @@ export default {
       control: 'select',
       options: Object.values(SIZES),
     },
+    color: {
+      options: Object.values(TEXT_COLORS),
+      control: 'select',
+    },
     backgroundColor: {
-      options: ValidBackgroundColors,
+      options: Object.values(BACKGROUND_COLORS),
       control: 'select',
     },
     borderColor: {
-      options: ValidBorderColors,
+      options: Object.values(BORDER_COLORS),
       control: 'select',
     },
     display: {
@@ -79,6 +86,7 @@ export default {
   },
   args: {
     size: SIZES.MD,
+    color: COLORS.TEXT_DEFAULT,
     backgroundColor: COLORS.BACKGROUND_ALTERNATIVE,
     borderColor: COLORS.BORDER_DEFAULT,
   },
@@ -90,11 +98,11 @@ DefaultStory.storyName = 'Default';
 
 export const Size = (args) => (
   <Box display={DISPLAY.FLEX} alignItems={ALIGN_ITEMS.BASELINE} gap={1}>
-    <BaseAvatar {...args} marginBottom={2} size={SIZES.XS} />
-    <BaseAvatar {...args} marginBottom={2} size={SIZES.SM} />
-    <BaseAvatar {...args} marginBottom={2} size={SIZES.MD} />
-    <BaseAvatar {...args} marginBottom={2} size={SIZES.LG} />
-    <BaseAvatar {...args} marginBottom={2} size={SIZES.XL} />
+    <BaseAvatar {...args} size={SIZES.XS} />
+    <BaseAvatar {...args} size={SIZES.SM} />
+    <BaseAvatar {...args} size={SIZES.MD} />
+    <BaseAvatar {...args} size={SIZES.LG} />
+    <BaseAvatar {...args} size={SIZES.XL} />
   </Box>
 );
 
@@ -123,13 +131,14 @@ export const Children = (args) => (
   </Box>
 );
 
-export const BackgroundAndBorderColor = (args) => (
+export const ColorBackgroundColorAndBorderColor = (args) => (
   <Box display={DISPLAY.FLEX} gap={1}>
     <BaseAvatar {...args}>B</BaseAvatar>
     <BaseAvatar
       {...args}
       backgroundColor={COLORS.KOVAN}
       borderColor={COLORS.KOVAN}
+      color={COLORS.PRIMARY_INVERSE} // TO DO: Update once test network colors have been added to design tokens
     >
       K
     </BaseAvatar>
@@ -144,6 +153,7 @@ export const BackgroundAndBorderColor = (args) => (
       {...args}
       backgroundColor={COLORS.GOERLI}
       borderColor={COLORS.GOERLI}
+      color={COLORS.PRIMARY_INVERSE} // TO DO: Update once test network colors have been added to design tokens
     >
       G
     </BaseAvatar>
@@ -151,6 +161,7 @@ export const BackgroundAndBorderColor = (args) => (
       {...args}
       backgroundColor={COLORS.ROPSTEN}
       borderColor={COLORS.ROPSTEN}
+      color={COLORS.PRIMARY_INVERSE} // TO DO: Update once test network colors have been added to design tokens
     >
       R
     </BaseAvatar>

ui/components/component-library/component-library-components.scss

@@ -1,3 +1,4 @@
 /** Please import your files in alphabetical order **/
+@import 'avatar-token/avatar-token';
 @import 'base-avatar/base-avatar';
 @import 'base-icon/base-icon';