Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: adding avatar network to design system react #409

Merged
merged 3 commits into from
Feb 5, 2025
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
@@ -0,0 +1,146 @@
import type { Meta, StoryObj } from '@storybook/react';
import React from 'react';

import { AvatarNetwork } from './AvatarNetwork';
import { AvatarNetworkSize } from '.';
import README from './README.mdx';

const meta: Meta<typeof AvatarNetwork> = {
title: 'React Components/AvatarNetwork',
component: AvatarNetwork,
parameters: {
docs: {
page: README,
},
},
argTypes: {
name: {
control: 'text',
description:
'Required name of the network. Used as alt text for image and first letter is used as fallback if no fallbackText provided',
},
src: {
control: 'text',
description:
'Optional URL for the network image. When provided, displays the image instead of fallback text',
},
imageProps: {
control: 'object',
description:
'Optional prop to pass to the underlying img element. Useful for overriding the default alt text',
},
size: {
control: 'select',
options: Object.keys(AvatarNetworkSize),
mapping: AvatarNetworkSize,
description:
'Optional prop to control the size of the avatar. Defaults to AvatarNetworkSize.Md',
},
fallbackText: {
control: 'text',
description:
'Optional text to display when no image is provided. If not provided, first letter of name will be used',
},
fallbackTextProps: {
control: 'object',
description:
'Optional props to be passed to the Text component when rendering fallback text. Only used when src is not provided',
},
className: {
control: 'text',
description:
'Optional additional CSS classes to be applied to the component',
},
},
};

export default meta;
type Story = StoryObj<typeof AvatarNetwork>;

export const Default: Story = {
args: {
src: 'https://cryptologos.cc/logos/ethereum-eth-logo.png',
name: 'Ethereum',
fallbackText: 'ETH',
},
};

export const Src: Story = {
render: () => (
<div className="flex gap-2">
<AvatarNetwork
name="Ethereum"
fallbackText="ETH"
src="https://cryptologos.cc/logos/ethereum-eth-logo.png"
/>
<AvatarNetwork
name="Avalanche"
fallbackText="AVA"
src="https://cryptologos.cc/logos/avalanche-avax-logo.png"
/>
<AvatarNetwork
name="Polygon"
fallbackText="POL"
src="https://cryptologos.cc/logos/polygon-matic-logo.png"
/>
</div>
),
};

export const Name: Story = {
render: () => (
<div className="flex gap-2">
<AvatarNetwork
name="Ethereum"
src="https://cryptologos.cc/logos/ethereum-eth-logo.png"
/>
<AvatarNetwork
name="Avalanche"
src="https://cryptologos.cc/logos/avalanche-avax-logo.png"
/>
<AvatarNetwork name="Polygon" />
</div>
),
};

export const FallbackText: Story = {
render: () => (
<div className="flex gap-2">
<AvatarNetwork name="Ethereum" fallbackText="ETH" />
<AvatarNetwork name="Avalanche" fallbackText="AVA" />
<AvatarNetwork name="Polygon" fallbackText="POL" />
</div>
),
};

export const Size: Story = {
render: () => (
<div className="flex gap-2 items-center">
<AvatarNetwork
name="Ethereum"
fallbackText="E"
size={AvatarNetworkSize.Xs}
/>
<AvatarNetwork
name="Ethereum"
fallbackText="ETH"
size={AvatarNetworkSize.Sm}
/>
<AvatarNetwork
name="Ethereum"
fallbackText="ETH"
size={AvatarNetworkSize.Md}
/>
<AvatarNetwork
name="Ethereum"
fallbackText="ETH"
size={AvatarNetworkSize.Lg}
/>
<AvatarNetwork
name="Ethereum"
fallbackText="ETH"
size={AvatarNetworkSize.Xl}
/>
</div>
),
};
Original file line number Diff line number Diff line change
@@ -0,0 +1,217 @@
import { render, screen } from '@testing-library/react';
import React from 'react';

import { TextColor } from '..';
import { AvatarNetwork } from './AvatarNetwork';
import { AvatarNetworkSize } from '.';

describe('AvatarNetwork', () => {
it('renders image when src is provided', () => {
render(
<AvatarNetwork src="test-image.jpg" name="Ethereum" fallbackText="Eth" />,
);

const img = screen.getByRole('img');
expect(img).toBeInTheDocument();
expect(img).toHaveAttribute('src', 'test-image.jpg');
expect(img).toHaveAttribute('alt', 'Ethereum');
});

it('renders fallbackText when src is not provided', () => {
render(<AvatarNetwork name="Ethereum" fallbackText="Eth" />);
expect(screen.getByText('Eth')).toBeInTheDocument();
});

it('applies fallbackTextProps to Text component', () => {
render(
<AvatarNetwork
name="Ethereum"
fallbackText="Eth"
fallbackTextProps={{
color: TextColor.TextAlternative,
className: 'test-class',
'data-testid': 'fallback-text',
}}
/>,
);

const text = screen.getByTestId('fallback-text');
expect(text).toHaveClass('text-alternative', 'test-class');
});

it('applies custom className to root element', () => {
render(
<AvatarNetwork
name="Ethereum"
fallbackText="Eth"
className="custom-class"
data-testid="avatar"
/>,
);

const avatar = screen.getByTestId('avatar');
expect(avatar).toHaveClass('custom-class');
});

it('passes through additional image props when src is provided', () => {
render(
<AvatarNetwork
src="test-image.jpg"
name="Ethereum"
fallbackText="Eth"
imageProps={{
loading: 'lazy',
}}
/>,
);

screen.debug();

const img = screen.getByRole('img');
expect(img).toHaveAttribute('loading', 'lazy');
});

it('applies size classes correctly', () => {
const { rerender } = render(
<AvatarNetwork
name="Ethereum"
fallbackText="Eth"
size={AvatarNetworkSize.Xs}
data-testid="avatar"
/>,
);

let avatar = screen.getByTestId('avatar');
expect(avatar).toHaveClass('h-4 w-4');

rerender(
<AvatarNetwork
name="Ethereum"
fallbackText="Eth"
size={AvatarNetworkSize.Sm}
data-testid="avatar"
/>,
);
avatar = screen.getByTestId('avatar');
expect(avatar).toHaveClass('h-6 w-6');

rerender(
<AvatarNetwork
name="Ethereum"
fallbackText="Eth"
size={AvatarNetworkSize.Md}
data-testid="avatar"
/>,
);
avatar = screen.getByTestId('avatar');
expect(avatar).toHaveClass('h-8 w-8');

rerender(
<AvatarNetwork
name="Ethereum"
fallbackText="Eth"
size={AvatarNetworkSize.Lg}
data-testid="avatar"
/>,
);
avatar = screen.getByTestId('avatar');
expect(avatar).toHaveClass('h-10 w-10');

rerender(
<AvatarNetwork
name="Ethereum"
fallbackText="Eth"
size={AvatarNetworkSize.Xl}
data-testid="avatar"
/>,
);
avatar = screen.getByTestId('avatar');
expect(avatar).toHaveClass('h-12 w-12');
});

it('uses medium size by default', () => {
render(<AvatarNetwork name="Ethereum" data-testid="avatar" />);
const avatar = screen.getByTestId('avatar');
expect(avatar).toHaveClass('h-8 w-8');
});

it('uses name as alt text when fallbackText is not provided', () => {
render(<AvatarNetwork src="test-image.jpg" name="Ethereum" />);

const img = screen.getByRole('img');
expect(img).toHaveAttribute('alt', 'Ethereum');
});

it('uses first letter of name as fallback text when fallbackText is not provided', () => {
render(<AvatarNetwork name="Ethereum" />);
expect(screen.getByText('E')).toBeInTheDocument();
});

it('prioritizes fallbackText over name for both alt text and fallback display', () => {
const { rerender } = render(
<AvatarNetwork
src="test-image.jpg"
name="Ethereum"
fallbackText="ETH"
imageProps={{ alt: 'ETH' }}
/>,
);

let img = screen.getByRole('img');
expect(img).toHaveAttribute('alt', 'ETH');

rerender(<AvatarNetwork name="Ethereum" fallbackText="ETH" />);

expect(screen.getByText('ETH')).toBeInTheDocument();
});
});

describe('text display and alt text logic', () => {
it('uses first letter of name when fallbackText is not provided', () => {
render(<AvatarNetwork name="Ethereum" />);
expect(screen.getByText('E')).toBeInTheDocument();
});

it('uses fallbackText for display when provided', () => {
render(<AvatarNetwork name="Ethereum" fallbackText="ETH" />);
expect(screen.getByText('ETH')).toBeInTheDocument();
});

it('uses name for alt text when src is provided', () => {
render(<AvatarNetwork name="Ethereum" src="test.jpg" />);
const img = screen.getByRole('img');
expect(img).toHaveAttribute('alt', 'Ethereum');
});

it('uses name for alt text even when fallbackText is provided', () => {
render(<AvatarNetwork name="Ethereum" fallbackText="ETH" src="test.jpg" />);
const img = screen.getByRole('img');
expect(img).toHaveAttribute('alt', 'Ethereum');
});

it('allows alt text override through imageProps', () => {
render(
<AvatarNetwork
name="Ethereum"
src="test.jpg"
imageProps={{ alt: 'Custom Alt' }}
/>,
);
const img = screen.getByRole('img');
expect(img).toHaveAttribute('alt', 'Custom Alt');
});

it('uses empty string for display text when name is not provided', () => {
// @ts-expect-error testing invalid props
render(<AvatarNetwork data-testid="avatar" />);
const base = screen.getByTestId('avatar');
expect(base.querySelector('span')).toHaveTextContent('');
});

it('uses default "Network logo" for alt text when name is not provided', () => {
// @ts-expect-error testing invalid props
render(<AvatarNetwork src="test.jpg" />);
const img = screen.getByRole('img');
expect(img).toHaveAttribute('alt', 'Network logo');
});
});
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
import React from 'react';

import { AvatarBase, AvatarBaseShape, AvatarBaseSize } from '../avatar-base';
import type { AvatarNetworkProps } from './AvatarNetwork.types';

export const AvatarNetwork = React.forwardRef<
HTMLDivElement,
AvatarNetworkProps
>(
(
{
src,
name,
fallbackText,
fallbackTextProps,
className,
size = AvatarBaseSize.Md,
imageProps,
...props
},
ref,
) => {
const displayText = fallbackText || (name ? name[0] : '');
const altText = name || 'Network logo'; // TBC: Add localization for default text
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice


return (
<AvatarBase
ref={ref}
shape={AvatarBaseShape.Square}
size={size}
className={className}
fallbackText={displayText}
fallbackTextProps={fallbackTextProps}
{...props}
>
{src && (
<img
src={src}
alt={altText}
className="w-full h-full object-cover"
{...imageProps}
/>
)}
</AvatarBase>
);
},
);

AvatarNetwork.displayName = 'AvatarNetwork';
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
import type { ComponentProps } from 'react';

import type { TextProps } from '../text';
import { AvatarNetworkSize } from '.';

export type AvatarNetworkProps = Omit<
ComponentProps<'img'>,
'children' | 'size'
> & {
/**
* Required name of the network
* Used as alt text for image and first letter is used as fallback if no fallbackText provided
*/
name: string;
/**
* Optional URL for the network image
* When provided, displays the image instead of fallback text
*/
src?: string;
/**
* Optional prop to pass to the underlying img element
* Useful for overriding the default alt text which is the network name
*/
imageProps?: ComponentProps<'img'>;
/**
* Optional prop to control the size of the avatar
* @default AvatarNetworkSize.Md
*/
size?: AvatarNetworkSize;
/**
* Optional text to display when no image is provided
* If not provided, first letter of name will be used
*/
fallbackText?: string;
/**
* Optional props to be passed to the Text component when rendering fallback text
* Only used when src is not provided
*/
fallbackTextProps?: Partial<
React.HTMLAttributes<HTMLSpanElement> & TextProps
>;
/**
* Optional additional CSS classes to be applied to the component
*/
className?: string;
};
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
import { Controls, Canvas } from '@storybook/blocks';

import * as AvatarNetworkStories from './AvatarNetwork.stories';

# AvatarNetwork

Avatar reserved for representing networks

```tsx
import { AvatarNetwork } from '@metamask/design-system-react';

<AvatarNetwork
name="Ethereum Network"
src="path/to/ethereum-logo.png"
fallbackText="ETH"
/>;
```

<Canvas of={AvatarNetworkStories.Default} />

## Props

### Name (required)

The `name` prop is required and serves two purposes:

- Used as alt text for the network image (unless overridden by `imageProps.alt`)
- First letter is used as fallback display text when `fallbackText` is not provided

<Canvas of={AvatarNetworkStories.Name} />

### Src (image source)

The `src` prop is optional and specifies the URL of the network's logo image.

<Canvas of={AvatarNetworkStories.Src} />

> Note: The `imageProps` prop allows you to customize the img element when `src` is provided. All standard HTML img attributes are supported and will be passed to the underlying img element when `src` is provided. This is useful for overriding the default alt text (which is the network name) when the AvatarNetwork is used as an accompaniment to an image.
```tsx
<AvatarNetwork
name="Ethereum"
src="path/to/ethereum-logo.png"
fallbackText="ETH"
imageProps={{ alt: 'Ethereum Logo', loading: 'lazy' }}
/>
```

### Fallback Text

The `fallbackText` prop is optional and is used for display text when no image is provided. If not provided, the first letter of `name` will be used.

<Canvas of={AvatarNetworkStories.FallbackText} />

> Note: The `fallbackTextProps` prop allows you to customize the Text component used for the fallback display
```tsx
<AvatarNetwork
name="Ethereum"
fallbackText="ETH"
fallbackTextProps={{ color: TextColor.PrimaryDefault }}
/>
```

### Size

AvatarNetwork supports five sizes:

- `AvatarNetworkSize.Xs` (16px)
- `AvatarNetworkSize.Sm` (24px)
- `AvatarNetworkSize.Md` (32px) - default
- `AvatarNetworkSize.Lg` (40px)
- `AvatarNetworkSize.Xl` (48px)

The fallback text uses TextVariant.BodySm for all sizes to maintain consistency.

<Canvas of={AvatarNetworkStories.Size} />

### Class Name

Use the `className` prop to add custom CSS classes to the component. These classes will be merged with the component's default
classes using `twMerge`, allowing you to:

- Add new styles that don't exist in the default component
- Override the component's default styles when needed

Example:

```tsx
// Adding new styles
<AvatarNetwork
name="Ethereum"
src="path/to/ethereum-logo.png"
fallbackText="ETH"
className="my-4 mx-2"
/>
```

## Component API

<Controls of={AvatarNetworkStories.Default} />

## References

[MetaMask Design System Guides](https://www.notion.so/MetaMask-Design-System-Guides-Design-f86ecc914d6b4eb6873a122b83c12940)
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
export { AvatarNetwork } from './AvatarNetwork';
export type { AvatarNetworkProps } from './AvatarNetwork.types';
export { AvatarBaseSize as AvatarNetworkSize } from '../avatar-base';
3 changes: 3 additions & 0 deletions packages/design-system-react/src/components/index.ts
Original file line number Diff line number Diff line change
@@ -38,3 +38,6 @@ export type { ButtonIconProps } from './button-icon';

export { AvatarBase, AvatarBaseSize } from './avatar-base';
export type { AvatarBaseProps } from './avatar-base';

export { AvatarNetwork, AvatarNetworkSize } from './avatar-network';
export type { AvatarNetworkProps } from './avatar-network';