NEW! [EuiAvatarGroup]

[cchaos]

Spec Doc (internal):

https://docs.google.com/document/d/1BNiL-__nHCZnbfE7pZfpmrZSkjbxLQWz_KdGafUiWsw/edit#

EUI should provide a way to quickly display small to large lists of avatars. This list will take an array of EuiAvatars, stack them visually (overlapping left to right) and maxing out at a recommended number while displaying a "+5" at the end. EUI should provide a view all list when clicking the group, which consumers can override, providing that they adhere to the guidelines which would state that the behavior should go to managing the list.

For full details please see the spec doc.

[cchaos]

Discussion point 1:

Should we support both an array of items as Avatar objects and children?

Last response from @constancecchen copied over from doc:

It adds complexity because if it's possible to mix and match items and s, we now need to account for both when calculating maxCount:

So let's say someone does this:

<EuiAvatarGroup items={[ ...4 items ]} maxCount={5} />
  <EuiAvatar />
  <EuiAvatar />
  <EuiAvatar />
  <div className="customWrapper"><EuiAvatar /></div> // because why not
</EuiAvatarGroup>

We would want to find the length of both items and children, and in the case of children, possibly check for child.type to ensure it's an EuiAvatar before incrementing it as a count - and then to make it even more potentially horrible, what happens if a consumer wraps an EuiAvatar child in something else? Do we need to recursively iterate through each child's children until we find an EuiAvatar before we can count it as well?

FWIW the latter (wrappers) is a real complexity that is now coming up in EuiContextMenu - wrapping an expected EuiContextMenuItem child (in, e.g. an EuiCopy or EuiTooltip) stops it from being considered the correct child type and introduces unexpected bugs. This is not strictly related to the 'combination' issue but is worth thinking about as well in terms of how we want to deal with wildcard JSX.

[cchaos]

My opinion in general around components who are "lists of things" is that if they rely purely on nested order for styling, then we shouldn't need to require the items as a prop. That allowing simple parent/child relationships to visually style the items is the easiest form of consuming we can provide. Example:

<ParentComponent>
  <ChildComponent />
  <ChildComponent />
  <ChildComponent />
</ParentComponent>

.parentComponent > .childComponent {
  // style the child
}

Where it certainly gets more complicated is things like:

A. Passing parent level props through to the children

In this case, we'd determine if those props can only be supplied by the parent (like dynamically created by the component itself) or if we can allow the same props to be applied directly to the children by the consumer. In the case of the latter, I'd opt for this flexibility to pass both items and children.

B. Requiring strictly only certain types children components

In this case we may want to consider a more strict parent/child relationship of components like we do for EuiSplitPanel. (I don't know what the official term for this pattern is).

eui/src/components/panel/split_panel/split_panel.tsx

Lines 101 to 104 in 7aa5510

	export const EuiSplitPanel = {
	Outer: _EuiSplitPanelOuter,
	Inner: _EuiSplitPanelInner,
	};

C. Supporting wrapping component, like tooltips, on children

This one is tougher and honestly is more of a problem with EuiTooltip that we're having to workaround versus just fixing EuiTooltip to accept a target node, or extend most commonly wrapped elements (like buttons) to accept tooltip props directly.

D. Parent props limit/count items dynamically

This is the most pertinent in EuiAvatarGroup's case, and my general take is that if some parent prop adds extra functionality based on the items, that isn't a required functionality of the component, then that functionality can be omitted if the consumer doesn't follow the pattern necessary to add that functionality.

---

Proposed scenario in how the component would handle items vs children:

Based on the example given by @constancecchen:

<EuiAvatarGroup items={[ { name: "name 1" }, { name: "name 2" } ... x10 ]} maxCount={5} />
  <EuiAvatar name="name 11" />
  <EuiAvatar name="name 12"  />
  <EuiAvatar name="name 13" />
  <div className="customWrapper"><EuiAvatar name="name 14" /></div> // wrapped by anything
</EuiAvatarGroup>

I would expect it to render as:

1. The max count would do it's thing and the last "avatar" being just the extra count
2. The direct children, because they're targeted via parent/child selectors, would be able to get the same style treatment, but they just wouldn't be accounted for in the count
3. The wrapped child, would not

Is this what consumers would expect?

Maybe not, maybe they didn't realize the person who wrote their side of it was also passing in items when they added children. But I would sure hope they notice something odd and investigate.

So then what does this help if it breaks the display and added functionality?

This is all about scale and ease of writing UI code. Let's say I'm using the avatar group in a context where I know I'll only have 3 or less avatars, or it's just a very manual implementation (not dynamic). I'd much rather write:

<EuiAvatarGroup />
  <EuiAvatar name="name 1" />
  <EuiAvatar name="name 2" />
  <EuiAvatar name="name 3" />
</EuiAvatarGroup>

than:

<EuiAvatarGroup 
  items={[ 
    { name: "name 1" }, 
    { name: "name 2" }, 
    { name: "name 3" },
  ]}
/>

Especially if I already have an avatar component that I'm using to render individual avatars as a service.

[cee-chen]

My 2c is that it would be much simpler and less unexpected to prefer the following rendering flow:

1. Only render items if it exists
2. Otherwise render children if items doesn't exist
3. Essentially, use one or the other API but don't mix and match both.

FWIW EuiContextMenu works this exact way currently. The above behavior also supports the latter example for a short static amount of avatars.

[cchaos]

I'm ok with that approach so long as it doesn't make the TS too complicated. And by complicated, less on the authoring side, but as a consumer who might be extending the props. We've had issues with this or that types of props in Kibana. I'll have to hunt down the example if you want to see one.

[cee-chen]

While we could opt for an ExclusiveUnion type of either items or children, we could also simply opt to not do so if it causes problems and just document in the props that items will supersede children.

[cchaos]

Yeah, I'd almost lean into console.warn() and prop comments versus hard-coded type exclusions.

[cchaos]

Discussion point 2

Interaction ideas

Codesandbox with ideas from @miukimiu: https://codesandbox.io/s/avatar-list-9y33vm?file=/demo.tsx

Concerns to consider:

1. The interaction needs to be subtle enough to not distract, but also visible enough to know that clicking the whole group will perform a single action.
2. We shouldn't add any animations that grow the bounding container because we can't be sure about placement in context.

cc @1Copenut for ideas

[1Copenut]

Looking through the animation ideas, I lean toward the third one, with the tooltip on hover. I'd ask that if we go this direction, we also trigger the tooltip on focus, so keyboard and screen readers can access the information. I'd also like to have an interaction on the +4 bubble at the end. It could say "and four more items" or something like that in the tooltip.

[cchaos]

Ack, sorry, got my codesandbox links mixed up. We actually don't want tooltips on the individual avatars because it's misleading what the interaction of clicking will do which is to actually pull up the entire list. I've updated the description above with the correct link but here it is as well: https://codesandbox.io/s/avatar-list-9y33vm?file=/demo.tsx

[cchaos]

Discussion point 3

Should the overlap order of the first be on top or bottom of the pile?

At first I thought it would be nice to highlight the individual avatars of the the final count avatar. However, as we consider more interaction options, I'm thinking the opposite. That the final count is probably best to be the most pronounced since the main interaction on the group will be to see the whole list including those that were in the beginning of the pile.

A. Original concept: First Avatar on top

B. Alternate concept: Count Avatar on top

But this would also mean if there are less items than the max count, the last avatar is on top.

[cee-chen]

1 vote for B here! (I think the last/3rd screenshot is fine as well personally, to my non-designer eyes)

[1Copenut]

I vote for B as well. This means we can just use a negative left margin to overlap the list items, and maintain a standard visual to HTML source order.

[ryankeairns]

Short of prioritizing it, it seems there was some consensus on the design - both for UI and API. That being:

• an API where items supersedes children; avoid more complex mixing
• use the 3rd animation option where a drop shadow is added; doesn't outgrow bounding container; interaction associated to entire group
• use alternative B for overlapping; most recent on top

With that, we can close this discussion and consider it for future development. cc:/ @JasonStoltz