Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
10.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.
import {describe, it, expect} from 'vitest';
import {render, screen} from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import {AvatarGroup} from './AvatarGroup';
import {AvatarGroupOverflow} from './AvatarGroupOverflow';
import {Avatar, AvatarStatusDot} from '../Avatar';
import {HoverCard} from '../HoverCard';
import {Tooltip} from '../Tooltip';

describe('AvatarGroup', () => {
  it('renders all avatar children', () => {
    render(
      <AvatarGroup>
        <Avatar name="Alice" />
        <Avatar name="Bob" />
        <Avatar name="Charlie" />
      </AvatarGroup>,
    );

    expect(screen.getByLabelText('Alice')).toBeInTheDocument();
    expect(screen.getByLabelText('Bob')).toBeInTheDocument();
    expect(screen.getByLabelText('Charlie')).toBeInTheDocument();
  });

  it('composes a labelled status into a grouped avatar accessible name (WCAG 4.1.2)', () => {
    render(
      <AvatarGroup>
        <Avatar
          name="Alice"
          status={<AvatarStatusDot variant="success" label="Online" />}
        />
        <Avatar name="Bob" />
      </AvatarGroup>,
    );

    expect(screen.getByLabelText('Alice, Online')).toBeInTheDocument();
    expect(screen.getByLabelText('Bob')).toBeInTheDocument();
  });

  it('renders with role="group" and default aria-label', () => {
    render(
      <AvatarGroup>
        <Avatar name="Alice" />
      </AvatarGroup>,
    );

    expect(screen.getByRole('group')).toHaveAttribute('aria-label', 'Avatars');
  });

  it('accepts a custom aria-label', () => {
    render(
      <AvatarGroup aria-label="Team members">
        <Avatar name="Alice" />
      </AvatarGroup>,
    );

    expect(screen.getByRole('group')).toHaveAttribute(
      'aria-label',
      'Team members',
    );
  });

  it('applies data-testid', () => {
    render(
      <AvatarGroup data-testid="avatar-group">
        <Avatar name="Alice" />
      </AvatarGroup>,
    );

    expect(screen.getByTestId('avatar-group')).toBeInTheDocument();
  });

  it('reflects size on the group', () => {
    render(
      <AvatarGroup size="lg">
        <Avatar name="Alice" />
      </AvatarGroup>,
    );

    const group = screen.getByRole('group');
    expect(group.className).toContain('astryx-avatar-group');
    expect(group).toHaveAttribute('data-size', 'lg');
  });

  it('renders empty group when no children', () => {
    render(<AvatarGroup data-testid="empty">{[]}</AvatarGroup>);

    expect(screen.getByTestId('empty')).toBeInTheDocument();
    expect(screen.queryByRole('img')).not.toBeInTheDocument();
  });
});

describe('AvatarGroup — roving focus + keyboard hint', () => {
  it('is a single tab stop over interactive avatars (one tabindex=0, rest -1)', () => {
    render(
      <AvatarGroup>
        <Avatar name="Alice" href="/alice" />
        <Avatar name="Bob" href="/bob" />
        <Avatar name="Charlie" href="/charlie" />
      </AvatarGroup>,
    );

    const alice = screen.getByRole('link', {name: 'Alice'});
    const bob = screen.getByRole('link', {name: 'Bob'});
    const charlie = screen.getByRole('link', {name: 'Charlie'});

    expect(alice).toHaveAttribute('tabindex', '0');
    expect(bob).toHaveAttribute('tabindex', '-1');
    expect(charlie).toHaveAttribute('tabindex', '-1');
  });

  it('roves focus with ArrowRight/ArrowLeft across interactive avatars', async () => {
    const user = userEvent.setup();
    render(
      <AvatarGroup>
        <Avatar name="Alice" href="/alice" />
        <Avatar name="Bob" onClick={() => {}} />
        <Avatar name="Charlie" href="/charlie" />
      </AvatarGroup>,
    );

    const alice = screen.getByRole('link', {name: 'Alice'});
    const bob = screen.getByRole('button', {name: 'Bob'});
    const charlie = screen.getByRole('link', {name: 'Charlie'});

    alice.focus();
    expect(alice).toHaveFocus();

    await user.keyboard('{ArrowRight}');
    expect(bob).toHaveFocus();
    expect(bob).toHaveAttribute('tabindex', '0');
    expect(alice).toHaveAttribute('tabindex', '-1');

    await user.keyboard('{ArrowRight}');
    expect(charlie).toHaveFocus();

    await user.keyboard('{ArrowLeft}');
    expect(bob).toHaveFocus();
  });

  it('includes the overflow button as the last roving item', async () => {
    const user = userEvent.setup();
    render(
      <AvatarGroup>
        <Avatar name="Alice" href="/alice" />
        <AvatarGroupOverflow count={3} onClick={() => {}} />
      </AvatarGroup>,
    );

    const alice = screen.getByRole('link', {name: 'Alice'});
    const overflow = screen.getByRole('button', {name: '3 more'});
    expect(overflow).toHaveAttribute('data-avatar-item');

    alice.focus();
    await user.keyboard('{ArrowRight}');
    expect(overflow).toHaveFocus();
  });

  it('does NOT rove over a non-avatar button in a status slot', async () => {
    const user = userEvent.setup();
    render(
      <AvatarGroup>
        <Avatar
          name="Alice"
          href="/alice"
          status={<button type="button">badge</button>}
        />
        <Avatar name="Bob" href="/bob" />
      </AvatarGroup>,
    );

    const alice = screen.getByRole('link', {name: 'Alice'});
    const bob = screen.getByRole('link', {name: 'Bob'});
    const statusButton = screen.getByRole('button', {name: 'badge'});

    // The status button carries no data-avatar-item marker.
    expect(statusButton).not.toHaveAttribute('data-avatar-item');

    alice.focus();
    await user.keyboard('{ArrowRight}');
    // Arrow moves to the next avatar, skipping the nested status button.
    expect(bob).toHaveFocus();
    expect(statusButton).not.toHaveFocus();
  });

  it('attaches an aria-describedby keyboard hint when interactive children exist', () => {
    render(
      <AvatarGroup>
        <Avatar name="Alice" href="/alice" />
        <Avatar name="Bob" href="/bob" />
      </AvatarGroup>,
    );

    const group = screen.getByRole('group');
    const describedBy = group.getAttribute('aria-describedby');
    expect(describedBy).toBeTruthy();
    const hint = document.getElementById(describedBy!);
    expect(hint).not.toBeNull();
    expect(hint).toHaveTextContent('Use arrow keys to move between avatars');
  });

  it('a purely static group has no tab stop and no keyboard hint', () => {
    render(
      <AvatarGroup>
        <Avatar name="Alice" data-testid="alice" />
        <Avatar name="Bob" data-testid="bob" />
      </AvatarGroup>,
    );

    const group = screen.getByRole('group');
    expect(group).not.toHaveAttribute('aria-describedby');
    // Static avatars are not focusable — no roving tabindex stamped.
    expect(screen.getByTestId('alice')).not.toHaveAttribute('tabindex');
    expect(screen.getByTestId('bob')).not.toHaveAttribute('tabindex');
  });
});

describe('AvatarGroup — overlap', () => {
  // jsdom cannot lay the row out, so these check the declarations that make
  // it overlap: every item takes the negative overlap margin, and the group's
  // start padding gives the first item that space back.
  const overlapMargin = (el: HTMLElement) =>
    getComputedStyle(el).getPropertyValue('margin-inline-start');

  it('overlaps every avatar, including the first', () => {
    render(
      <AvatarGroup>
        <Avatar name="Alice" data-testid="alice" />
        <Avatar name="Bob" data-testid="bob" />
        <AvatarGroupOverflow count={2} data-testid="overflow" />
      </AvatarGroup>,
    );

    for (const id of ['alice', 'bob', 'overflow']) {
      expect(overlapMargin(screen.getByTestId(id))).toBe(
        'var(--_avatar-group-overlap)',
      );
    }
    const group = screen.getByRole('group');
    expect(
      getComputedStyle(group).getPropertyValue('padding-inline-start'),
    ).toBe('calc(-1 * var(--_avatar-group-overlap))');
    // md = 36px; the overlap is a quarter of that, negated.
    expect(group.getAttribute('style')).toContain('-9px');
  });

  it('keeps the overlap when avatars are wrapped in a HoverCard or Tooltip', () => {
    // Both wrap their trigger in a `display: contents` element, so each avatar
    // is the first child of its own wrapper. A `:not(:first-child)` rule
    // would never match.
    render(
      <AvatarGroup>
        <HoverCard content="Alice's card">
          <Avatar name="Alice" data-testid="alice" />
        </HoverCard>
        <HoverCard content="Bob's card">
          <Avatar name="Bob" data-testid="bob" />
        </HoverCard>
        <Tooltip content="Charlie">
          <Avatar name="Charlie" data-testid="charlie" />
        </Tooltip>
      </AvatarGroup>,
    );

    for (const id of ['alice', 'bob', 'charlie']) {
      const avatar = screen.getByTestId(id);
      expect(avatar.parentElement).not.toBe(screen.getByRole('group'));
      expect(overlapMargin(avatar)).toBe('var(--_avatar-group-overlap)');
    }
  });

  it('adds no start padding to an empty group', () => {
    render(<AvatarGroup data-testid="empty">{[]}</AvatarGroup>);

    expect(
      getComputedStyle(screen.getByTestId('empty')).getPropertyValue(
        'padding-inline-start',
      ),
    ).toMatch(/^0(px)?$/);
  });
});

describe('AvatarGroup — size cascade', () => {
  it("the group's size overrides a child's own size prop", () => {
    render(
      <AvatarGroup size="lg">
        <Avatar name="Alice" size="xsm" data-testid="alice" />
      </AvatarGroup>,
    );

    expect(screen.getByTestId('alice')).toHaveAttribute('data-size', 'lg');
  });

  it("the group's default size also overrides a child's own size prop", () => {
    // Known open finding: the group always publishes a size on its context, so
    // a group that never set one still imposes md on children that did set one.
    // Pinned here so the behaviour cannot change without a deliberate edit.
    render(
      <AvatarGroup>
        <Avatar name="Alice" size="xl" data-testid="alice" />
      </AvatarGroup>,
    );

    expect(screen.getByTestId('alice')).toHaveAttribute('data-size', 'md');
  });

  it("outside a group the avatar's own size applies", () => {
    render(<Avatar name="Alice" size="xl" data-testid="alice" />);

    expect(screen.getByTestId('alice')).toHaveAttribute('data-size', 'xl');
  });
});