Terra-core: [terra-avatar] Enhancements

[yuderekyu]

Feature Request

• Split avatar into three variants: Person, Facility, and Multiple (name pending).
• Make other changes that will be listed in the tech design below.

[yuderekyu]

Avatar Tech Design

terra-avatar will be split into three sub-packages: avatar, location, and multi-user (names pending) and be exported similar to this. They shall share themeable variables and common utils for determining color.

Enhancements

Color Support

• Support 10 color variants.
• Add color prop
  
  
  
  • Defaults to auto. Consumers can override this by passing neutral for a theme specific base color, or one of 10 color variants: one, two,, three, four, five, six, seven, eight, nine, ten.
  
  
• Create shared color utils, utilized when color="auto". This will hash the alt prop to determine a color from the color variants. Sample hash function.

Other

• alt prop shall be required.
• add isDeceased prop to avatar. If set, styles change.
• Extract box-shadow to an :after selector. Addresses https://github.com/cerner/terra-core/issues/1845.
• Support single initials for a user avatar.
• Spread custom props onto inner span. This allows an outer component to set aria-hidden on avatar.
• Default size in em's - avatar shall scale based on its container's font-size.

Removals

• Remove support for three initials from user avatar.
• Remove ariaLabel prop. Instead, use alt prop to set the aria-label attribute.
  

  Code Samples

Avatar

import React from 'react';
import { Avatar } from 'terra-avatar/lib/Avatar';

const AvatarUser = () => (
  <Avatar alt="John Doe" initials="JD" />
);

export default AvatarUser;

Facility

import React from 'react';
import { Location } from 'terra-avatar/lib/Avatar';

const AvatarLocation = () => (
  <Location alt="Cerneeeer" />
);

export default AvatarLocation;

MultiUser

import React from 'react';
import { MultiUser } from 'terra-avatar/lib/Avatar';

const AvatarMultiUser = () => (
  <MultiUser alt="Squad" />
);

export default AvatarMultiUser;

Avatar Props

| Prop Name | Type | Is Required | Default Value | Description |
|-|-|-|-|-|
|alt | string | required | none | The text content that specifies the alternative text for the image. Also sets the aria-label for accessibility.
| color |PropTypes.oneOf([, 'auto', 'neutral', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten']) | optional | 'auto' | Sets the background color. Defaults to 'auto'.
| hashValue | string | optional | none | Value used for the hash function. If not provided, hash function utilizes alt |
| image |string | optional | none | The image to display. |
| initials |string | optional | none | One or Two letters to display. |
| isAriaHidden | boolean | optional | false | Whether to hide avatar from accessibility API |
| isDeceased | boolean | optional | false | Whether the person is deceased. |
| size |string | optional | none | Sets the size of the avatar. Overrides the default size. |

Location Props

| Prop Name | Type | Is Required | Default Value | Description |
|-|-|-|-|-|
|alt | string | required | none | The text content that specifies the alternative text for the image. Also sets the aria-label for accessibility. |
| color |PropTypes.oneOf([, 'auto', 'neutral', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten']) | optional | 'auto' | Sets the background color. Defaults to 'auto'.
| hashValue | string | optional | none | Value used for the hash function. If not provided, hash function utilizes alt |
| image |string | optional | none | The image to display. If no image is provided, fallback to facility icon. |
| isAriaHidden | boolean | optional | false | Whether to hide avatar from accessibility API |
| size |string | optional | none | Sets the size of the avatar. Overrides the default size. |

MultiUser Props

| Prop Name | Type | Is Required | Default Value | Description |
|-|-|-|-|-|
|alt | string | required | none | The text content that specifies the alternative text for the image. Also sets the aria-label for accessibility.
| color |PropTypes.oneOf([, 'auto', 'neutral', 'one', 'two', 'three', 'four', 'five', 'six', 'seven', 'eight', 'nine', 'ten']) | optional | 'auto' | Sets the background color. Defaults to 'auto'.
| hashValue | string | optional | none | Value used for the hash function. If not provided, hash function utilizes alt |
| isAriaHidden | boolean | optional | false | Whether to hide avatar from accessibility API |
| size |string | optional | none | Sets the size of the avatar. Overrides the default size. |

[mjhenkes]

Could we just name AvatarUser as Avatar as the default?

Could we add a first class prop for aria hidden instead of spreading props?

We need to determine if alt and the string we should hash could be separate. i.e. is there a case where you want the color determined by an id, but a screen reader to say something different.

We need to add a deceased variant.

[yuderekyu]

Updated to avatar. Added isDeceased prop to avatar.

@mjhenkes we could potentially create a prop for the hash to use, but default to using alt

[bjankord]

+1 on tech design.

We need to determine if alt and the string we should hash could be separate.

I lean towards use alt unless a hash is provided via some prop. Not too concerned with the name of this prop.

[yuderekyu]

Update

• add first class isAriaHidden prop instead of spreading custom props on inner span. This will put the onus on consumers to know when to toggle this for accessibility
• add hashValue prop. If provided, the hash function will use hashValue instead of alt

[mjhenkes]

+1 Make sure is deceased takes precedence over any other color settings.

[benbcai]

1. Would MultiUser also need an image prop?
2. If no image is provided for Avatar, would it have a fallback icon like it does for Location?

[yuderekyu]

@benbcai

1. MultiUser will only render an icon
2. Yes, the existing icon fallback logic will be applied to Avatar

[benbcai]

+1 on tech design.

[yuderekyu]

Update - making isAriaHidden default to false

[yuderekyu]

Anyone have an opinion on refactoring the MultiUser variant to SharedUser?

[bjankord]

shareduser sounds better to me compared to multiuser

[yuderekyu]

I have also changed Location to Facility, because location is a reserved word in js

[yuderekyu]

Changed height and width props to size. When avatar is resized, the initials will also scale correctly.

https://github.com/cerner/terra-core/pull/2061#discussion_r235048195