@transferwise/components 46.103.0 → 46.104.0

package/src/listItem/AvatarLayout/ListItemAvatarLayout.spec.tsx

@@ -0,0 +1,59 @@
+import { mockMatchMedia, render, screen } from '../../test-utils';
+import { ListItem, type ListItemProps } from '../ListItem';
+
+mockMatchMedia();
+
+const avatars = [
+  { imgSrc: 'avatar1.jpg', profileName: 'User 1' },
+  { imgSrc: 'avatar2.jpg', profileName: 'User 2' },
+];
+
+const renderWithMedia = (media: ListItemProps['media']) =>
+  render(<ListItem title="Test Title" media={media} />);
+
+describe('ListItem.AvatarLayout', () => {
+  it('applies custom className alongside default class', () => {
+    renderWithMedia(
+      <ListItem.AvatarLayout
+        className="custom-class"
+        role="group"
+        aria-label="Custom avatar group"
+        avatars={avatars}
+      />,
+    );
+
+    expect(screen.getByRole('group', { name: 'Custom avatar group' })).toHaveClass('custom-class');
+  });
+
+  it('renders both avatars', () => {
+    renderWithMedia(<ListItem.AvatarLayout avatars={avatars} />);
+
+    const images = screen.getAllByRole('presentation');
+    expect(images).toHaveLength(avatars.length);
+    expect(images[0]).toHaveAttribute('src', avatars[0].imgSrc);
+    expect(images[1]).toHaveAttribute('src', avatars[1].imgSrc);
+  });
+
+  it('renders with single avatar', () => {
+    renderWithMedia(<ListItem.AvatarLayout avatars={[avatars[0]]} />);
+    expect(screen.getByRole('presentation')).toHaveAttribute('src', avatars[0].imgSrc);
+  });
+
+  it('handles empty avatars array', () => {
+    renderWithMedia(<ListItem.AvatarLayout avatars={[]} />);
+    expect(screen.queryByRole('img')).not.toBeInTheDocument();
+  });
+
+  it('supports accessibility props', () => {
+    renderWithMedia(<ListItem.AvatarLayout aria-label="User avatars" avatars={avatars} />);
+    expect(screen.getByLabelText('User avatars')).toBeInTheDocument();
+  });
+
+  it('passes through role', () => {
+    renderWithMedia(
+      <ListItem.AvatarLayout role="group" aria-label="Avatar group" avatars={avatars} />,
+    );
+
+    expect(screen.getByRole('group', { name: 'Avatar group' })).toBeInTheDocument();
+  });
+});

package/src/listItem/AvatarLayout/ListItemAvatarLayout.story.tsx

@@ -0,0 +1,124 @@
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+import { Flag } from '@wise/art';
+import { lorem10 } from '../../test-utils';
+import { ListItem } from '../ListItem';
+import List from '../../list';
+import {
+  SB_LIST_ITEM_ADDITIONAL_INFO as INFO,
+  SB_LIST_ITEM_CONTROLS as CONTROLS,
+} from '../_stories/subcomponents';
+import { disableControls } from '../_stories/helpers';
+import type { ListItemAvatarLayoutProps } from './ListItemAvatarLayout';
+
+export default {
+  component: ListItem.AvatarLayout,
+  title: 'Content/ListItem/ListItem.AvatarLayout',
+  parameters: {
+    docs: {
+      toc: true,
+    },
+  },
+  args: {
+    avatars: [{ asset: <Flag code="gb" /> }, { asset: <Flag code="eur" /> }],
+    orientation: 'horizontal',
+    size: 48,
+  },
+  argTypes: {
+    avatars: {
+      description: 'Array of avatar objects with asset and optional styling properties',
+      table: {
+        type: { summary: 'SingleAvatarType[]' },
+      },
+    },
+    orientation: {
+      control: 'inline-radio',
+      options: ['horizontal', 'diagonal'],
+      description: 'Layout orientation for multiple avatars',
+    },
+    size: {
+      control: 'select',
+      options: [32, 40, 48, 56, 72],
+      description: 'Size of the avatar layout',
+    },
+  },
+} satisfies Meta<ListItemAvatarLayoutProps>;
+
+type Story = StoryObj<ListItemAvatarLayoutProps>;
+
+export const Playground: Story = {
+  tags: ['!autodocs'],
+  render: (args: ListItemAvatarLayoutProps) => {
+    return (
+      <List>
+        <ListItem
+          title="Transfer from GBP to EUR"
+          subtitle="Currency exchange"
+          media={<ListItem.AvatarLayout {...args} />}
+          control={CONTROLS.iconButton}
+          additionalInfo={INFO.nonInteractive}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * AvatarLayout supports two orientations: horizontal (default) and diagonal. <br />
+ * Please refer to the [design documentation](https://wise.design/components/avatar#double) for more details.
+ */
+export const Orientations: Story = {
+  argTypes: disableControls()(['orientation']),
+  render: (args) => {
+    return (
+      <List>
+        <ListItem
+          title="Horizontal orientation"
+          subtitle={lorem10}
+          media={<ListItem.AvatarLayout {...args} orientation="horizontal" />}
+          control={CONTROLS.iconButton}
+        />
+
+        <ListItem
+          title="Diagonal orientation"
+          subtitle={lorem10}
+          media={<ListItem.AvatarLayout {...args} orientation="diagonal" />}
+          control={CONTROLS.iconButton}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * AvatarLayout supports various sizes to fit different list item contexts.
+ */
+export const Sizes: Story = {
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: 'hidden',
+      },
+    },
+  },
+  argTypes: disableControls()(['size', 'orientation']),
+  render: (args) => {
+    const sizes = [32, 40, 48, 56, 72] as const;
+    const orientations = ['horizontal', 'diagonal'] as const;
+
+    return (
+      <List>
+        {orientations.map((orientation) =>
+          sizes.map((size) => (
+            <ListItem
+              key={`${orientation}-${size}`}
+              title={`Size ${size}`}
+              subtitle={lorem10}
+              media={<ListItem.AvatarLayout {...args} size={size} orientation={orientation} />}
+              control={CONTROLS.iconButton}
+            />
+          )),
+        )}
+      </List>
+    );
+  },
+};

package/src/listItem/AvatarLayout/ListItemAvatarLayout.tsx

@@ -0,0 +1,27 @@
+import AvatarLayoutComp, { type AvatarLayoutProps } from '../../avatarLayout';
+import { clsx } from 'clsx';
+import { useListItemMedia } from '../useListItemMedia';
+
+type SizeProp = { size?: 32 | 40 | 48 | 56 | 72 };
+
+export type ListItemAvatarLayoutProps = Omit<AvatarLayoutProps, 'size' | 'interactive'> & SizeProp;
+
+/**
+ * This component allows for rendering 2 avatars. It's a thin wrapper around the
+ * [AvatarLayout component](https://storybook.wise.design/?path=/docs/content-avatarlayout--docs), but offers only
+ * a subset of its sizes, and disallows interactive mode, in line with the ListItem's constraints. <br />
+ * <br />
+ * Please refer to the [Design documentation](https://wise.design/components/list-item#avatar) for details.
+ */
+export const AvatarLayout = ({ className, size = 48, ...props }: ListItemAvatarLayoutProps) => {
+  useListItemMedia(size);
+
+  return (
+    <AvatarLayoutComp
+      {...props}
+      size={size}
+      className={clsx('wds-list-item-media-avatar-layout', className)}
+    />
+  );
+};
+AvatarLayout.displayName = 'ListItem.AvatarLayout';

package/src/listItem/AvatarLayout/index.ts

@@ -0,0 +1,2 @@
+export type { ListItemAvatarLayoutProps } from './ListItemAvatarLayout';
+export { AvatarLayout } from './ListItemAvatarLayout';

package/src/listItem/AvatarView/ListItemAvatarView.spec.tsx

@@ -0,0 +1,75 @@
+import { mockMatchMedia, render, screen } from '../../test-utils';
+import { ListItem, type ListItemProps } from '../ListItem';
+
+mockMatchMedia();
+
+const baseProps = {
+  title: 'Test Title',
+};
+
+const avatarProps = {
+  imgSrc: 'avatar.jpg',
+  profileName: 'User Avatar',
+};
+
+const renderWithMedia = (media: ListItemProps['media']) =>
+  render(<ListItem title={baseProps.title} media={media} />);
+
+describe('ListItem.AvatarView', () => {
+  it('applies custom className alongside default class', () => {
+    const { container } = renderWithMedia(
+      <ListItem.AvatarView
+        className="custom-class"
+        imgSrc={avatarProps.imgSrc}
+        profileName={avatarProps.profileName}
+      />,
+    );
+
+    expect(container.querySelector('.custom-class')).toBeInTheDocument();
+  });
+
+  it('renders avatar with correct image src', () => {
+    renderWithMedia(
+      <ListItem.AvatarView imgSrc={avatarProps.imgSrc} profileName={avatarProps.profileName} />,
+    );
+
+    expect(screen.getByRole('presentation')).toHaveAttribute('src', avatarProps.imgSrc);
+  });
+
+  it('renders without image when no imgSrc provided', () => {
+    renderWithMedia(<ListItem.AvatarView profileName={avatarProps.profileName} />);
+    expect(screen.queryByRole('img')).not.toBeInTheDocument();
+  });
+
+  it('supports accessibility props', () => {
+    renderWithMedia(
+      <ListItem.AvatarView
+        imgSrc={avatarProps.imgSrc}
+        profileName={avatarProps.profileName}
+        aria-label="Profile picture"
+      />,
+    );
+
+    expect(screen.getByLabelText('Profile picture')).toBeInTheDocument();
+  });
+
+  it('passes through role attribute', () => {
+    renderWithMedia(
+      <ListItem.AvatarView
+        imgSrc={avatarProps.imgSrc}
+        profileName={avatarProps.profileName}
+        role="button"
+        aria-label="Profile button"
+      />,
+    );
+
+    expect(screen.getByRole('button', { name: 'Profile button' })).toBeInTheDocument();
+  });
+
+  it('renders initials when no image provided', () => {
+    const johnDoeProfile = 'John Doe';
+    renderWithMedia(<ListItem.AvatarView profileName={johnDoeProfile} />);
+
+    expect(screen.getByText('JD')).toBeInTheDocument();
+  });
+});

package/src/listItem/AvatarView/ListItemAvatarView.story.tsx

@@ -0,0 +1,339 @@
+import { Meta, StoryObj } from '@storybook/react-webpack5';
+import { Leaf, Taxi } from '@transferwise/icons';
+import { lorem10 } from '../../test-utils';
+import { ProfileType } from '../../common';
+import List from '../../list';
+import { ListItem } from '../ListItem';
+import {
+  SB_LIST_ITEM_ADDITIONAL_INFO as INFO,
+  SB_LIST_ITEM_CONTROLS as CONTROLS,
+} from '../_stories/subcomponents';
+import { disableControls } from '../_stories/helpers';
+import type { ListItemAvatarViewProps } from './ListItemAvatarView';
+
+const hideControls = disableControls(['badge', 'children']);
+
+const SIZES = [32, 40, 48, 56, 72] as const;
+const BADGES = {
+  'Country flag badge': { flagCode: 'GBP' },
+  'StatusIcon badge': { status: 'warning' },
+  'Icon badge': { icon: <Taxi /> },
+  'Default action badge': {
+    type: 'action',
+  },
+  'Default reference badge': {
+    type: 'reference',
+  },
+  'Action badge with custom icon': {
+    type: 'action',
+    icon: <Taxi />,
+  },
+  'Reference badge with custom icon': {
+    type: 'reference',
+    icon: <Taxi />,
+  },
+  'Custom badge': {
+    asset: (
+      <div
+        className="d-flex align-items-center justify-content-center"
+        style={{
+          backgroundColor: 'var(--color-bright-pink)',
+          color: 'var(--color-interactive-primary)',
+          width: '100%',
+          height: '100%',
+        }}
+      >
+        <Leaf />
+      </div>
+    ),
+  },
+} as const;
+
+export default {
+  component: ListItem.AvatarView,
+  title: 'Content/ListItem/ListItem.AvatarView',
+  parameters: {
+    docs: {
+      toc: true,
+    },
+  },
+  args: {
+    size: 48,
+    selected: false,
+    badge: { type: 'action' },
+    notification: false,
+    profileName: undefined,
+    profileType: undefined,
+    imgSrc: undefined,
+  },
+  argTypes: {
+    size: {
+      control: 'select',
+      options: SIZES,
+      description: 'Size of the avatar',
+    },
+    profileName: {
+      control: 'text',
+      description: 'Name used to generate initials when no image or icon is provided',
+    },
+    imgSrc: {
+      control: 'text',
+      description: 'URL of the profile image',
+    },
+    profileType: {
+      control: 'select',
+      options: [ProfileType.PERSONAL, ProfileType.BUSINESS],
+      description: 'Type of profile for default icons',
+      table: {
+        type: { summary: 'ProfileType' },
+      },
+    },
+    notification: {
+      control: 'boolean',
+      description: 'Shows notification dot',
+    },
+    selected: {
+      control: 'boolean',
+      description: 'Toggles selected state',
+    },
+    badge: {
+      description: 'Badge configuration object',
+      table: {
+        type: { summary: 'AvatarViewBadgeProps' },
+      },
+    },
+    children: {
+      table: {
+        type: { summary: 'ReactNode' },
+      },
+    },
+    style: {
+      table: {
+        disable: true,
+      },
+    },
+  },
+} satisfies Meta<ListItemAvatarViewProps>;
+
+type Story = StoryObj<ListItemAvatarViewProps>;
+
+export const Playground: Story = {
+  tags: ['!autodocs'],
+  render: (args: ListItemAvatarViewProps) => {
+    return (
+      <List>
+        <ListItem
+          title="John Smith"
+          subtitle="Personal account"
+          media={<ListItem.AvatarView {...args} />}
+          control={CONTROLS.iconButton}
+          additionalInfo={INFO.nonInteractive}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * AvatarView can display different types of content including icons, profile images, and initials. <br />
+ * Refer to the [design documentation](https://wise.design/components/avatar#:~:text=56%2C%20%E2%80%A8and%2072.-,Media,-There%20are%204) for details.
+ */
+export const ContentTypes: Story = {
+  args: {
+    badge: undefined,
+  },
+  argTypes: hideControls(['profileName', 'imgSrc', 'profileType']),
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: 'hidden',
+      },
+    },
+  },
+  render: (args) => {
+    return (
+      <List>
+        <ListItem
+          title="With icon"
+          subtitle="Default icon content"
+          media={
+            <ListItem.AvatarView {...args}>
+              <Taxi />
+            </ListItem.AvatarView>
+          }
+          control={CONTROLS.iconButton}
+        />
+
+        <ListItem
+          title="With profile image"
+          subtitle="User profile picture."
+          media={
+            <ListItem.AvatarView
+              {...args}
+              imgSrc="../avatar-square-dude.webp"
+              profileName="John Smith"
+            />
+          }
+          control={CONTROLS.iconButton}
+        />
+
+        <ListItem
+          title="With initials"
+          subtitle="Fallback for when no profile image is available."
+          media={<ListItem.AvatarView {...args} profileName="Sarah Johnson" />}
+          control={CONTROLS.iconButton}
+        />
+
+        <ListItem
+          title="Business profile"
+          subtitle="Fallback for when no logo is available"
+          media={<ListItem.AvatarView {...args} profileType={ProfileType.BUSINESS} />}
+          control={CONTROLS.iconButton}
+        />
+
+        <ListItem
+          title="Personal profile"
+          subtitle="Fallback for when no personal data is available or when image fails to load."
+          media={
+            <ListItem.AvatarView
+              {...args}
+              profileType={ProfileType.PERSONAL}
+              profileName="Alex Chen"
+            />
+          }
+          control={CONTROLS.iconButton}
+        />
+      </List>
+    );
+  },
+};
+
+/**
+ * AvatarView supports 5 sizes to fit different list item contexts: `32`, `40`, `48`, `56`, `72`. If decorated with a Badge, those will be sized accordingly as well. <br />
+ * Please refer to the [design documentation](https://wise.design/components/list-item#avatar:~:text=of%20the%20avatar.-,Avatar%20sizes,-List%20item%20supports) for details on when to use which one.
+ */
+export const Sizes: Story = {
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: 'hidden',
+      },
+    },
+  },
+  argTypes: hideControls(['profileName', 'imgSrc', 'profileType', 'size']),
+  render: (args) => {
+    return (
+      <List>
+        {SIZES.map((size) => (
+          <ListItem
+            key={size}
+            title={`Size ${size}`}
+            subtitle={lorem10}
+            media={
+              <ListItem.AvatarView {...args} size={size}>
+                <Taxi />
+              </ListItem.AvatarView>
+            }
+            control={CONTROLS.iconButton}
+          />
+        ))}
+      </List>
+    );
+  },
+};
+
+/**
+ * Similarly, AvatarView also support a notification dot, which also adjusts to the Avatar's size. <br />
+ * **NB:** You cannot use notification and badge at the same time – badge will always take precedence over notification.
+ */
+export const Notification: Story = {
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: 'hidden',
+      },
+    },
+  },
+  args: {
+    badge: undefined,
+  },
+  argTypes: hideControls([
+    'profileName',
+    'imgSrc',
+    'profileType',
+    'size',
+    'notification',
+    'selected',
+  ]),
+  render: (args) => {
+    return (
+      <List>
+        {SIZES.map((size) => (
+          <ListItem
+            key={size}
+            title={`Size ${size}`}
+            subtitle={lorem10}
+            media={
+              <ListItem.AvatarView {...args} size={size} notification>
+                <Taxi />
+              </ListItem.AvatarView>
+            }
+            control={CONTROLS.iconButton}
+          />
+        ))}
+      </List>
+    );
+  },
+};
+
+/**
+ * AvatarView supports different type of badges for additional context and information. <br />
+ * Refer to the [design documentation](https://wise.design/components/avatar#:~:text=support%20the%20information.-,With%20badge,-Badges%20contain%20additional) for details.
+ */
+export const Badges: Story = {
+  args: {
+    imgSrc: '../avatar-square-dude.webp',
+  },
+  argTypes: hideControls(['profileName', 'imgSrc', 'profileType', 'notification', 'selected']),
+  parameters: {
+    docs: {
+      canvas: {
+        sourceState: 'hidden',
+      },
+    },
+  },
+  render: (args) => {
+    return (
+      <List>
+        {Object.entries(BADGES).map(([title, badge]) => (
+          <ListItem
+            key={title}
+            title={title}
+            subtitle={lorem10}
+            media={<ListItem.AvatarView {...args} badge={badge} />}
+            control={CONTROLS.iconButton}
+          />
+        ))}
+      </List>
+    );
+  },
+};
+
+/**
+ * AvatarView supports selected state for interactive contexts.
+ */
+export const Selected: Story = {
+  argTypes: hideControls(['profileName', 'imgSrc', 'profileType', 'notification', 'selected']),
+  render: (args) => {
+    return (
+      <List>
+        <ListItem
+          title="Selected state"
+          subtitle="Currently selected item"
+          media={<ListItem.AvatarView profileName="Alex Chen" selected />}
+          control={CONTROLS.iconButton}
+        />
+      </List>
+    );
+  },
+};

package/src/listItem/AvatarView/ListItemAvatarView.tsx

@@ -0,0 +1,27 @@
+import { clsx } from 'clsx';
+import AvatarViewComp, { type AvatarViewProps } from '../../avatarView';
+import { useListItemMedia } from '../useListItemMedia';
+
+export type ListItemAvatarViewProps = Omit<AvatarViewProps, 'size' | 'interactive'> & {
+  size?: 32 | 40 | 48 | 56 | 72;
+};
+
+/**
+ * This component renders a single avatar. It's a thin wrapper around the
+ * [AvatarView component](https://storybook.wise.design/?path=/docs/content-avatarview--docs), but offers only
+ * a subset of its sizes, in line with the ListItem's constraints. <br />
+ * <br />
+ * Please refer to the [Design documentation](https://wise.design/components/list-item#avatar) for details.
+ */
+export const AvatarView = ({ className, size = 48, ...props }: ListItemAvatarViewProps) => {
+  useListItemMedia(size);
+
+  return (
+    <AvatarViewComp
+      {...props}
+      size={size}
+      className={clsx('wds-list-item-media-avatar-view', className)}
+    />
+  );
+};
+AvatarView.displayName = 'ListItem.AvatarView';

package/src/listItem/AvatarView/index.ts

@@ -0,0 +1,2 @@
+export type { ListItemAvatarViewProps } from './ListItemAvatarView';
+export { AvatarView } from './ListItemAvatarView';