@ledgerhq/lumen-ui-rnative 0.0.68 → 0.0.70

package/src/lib/Components/Avatar/Avatar.mdx

@@ -0,0 +1,323 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks';
+import * as AvatarStories from './Avatar.stories';
+import { Avatar } from './Avatar';
+import { CustomTabs, Tab } from '../../../../.storybook/components';
+import { DoVsDontRow, DoBlockItem, DontBlockItem } from '../../../../.storybook/components/DoVsDont';
+import CommonRulesDoAndDont from '../../../../.storybook/components/DoVsDont/CommonRulesDoAndDont.mdx';
+import { Box } from '../Utility';
+
+<Meta title='Communication/Avatar' of={AvatarStories} />
+
+# 👤 Avatar
+
+<CustomTabs>
+  <Tab label="Overview">
+
+## Introduction
+
+The Avatar component displays a circular user profile image with automatic fallback to a User icon when the image is unavailable or fails to load. It supports an optional notification indicator and two size variants. This React Native implementation ensures consistent behavior across mobile platforms while maintaining design system coherence.
+
+> View in [Figma](https://www.figma.com/design/JxaLVMTWirCpU0rsbZ30k7/2.-Components-Library?node-id=10546-614&p=f&m=dev).
+
+## Anatomy
+
+<Canvas of={AvatarStories.Base} />
+
+- **Image/Fallback Icon**: The circular user image or User icon fallback displayed when image is unavailable
+- **Notification Indicator (optional)**: A red dot positioned at the top-right corner to indicate notifications
+- **Container**: Rounded full background with muted styling
+
+## Properties
+
+### Overview
+
+<Canvas of={AvatarStories.Base} />
+<Controls of={AvatarStories.Base} />
+
+### Size
+
+Avatars come in two different sizes:
+
+- **sm** (40px)
+- **md** (48px, default)
+
+<Canvas of={AvatarStories.SizeShowcase} />
+
+### States
+
+The Avatar component handles two primary states automatically:
+
+- **With Image**: Displays the provided image when `src` is valid and loads successfully
+- **Fallback**: Shows a User icon when `src` is undefined or the image fails to load
+
+<Canvas of={AvatarStories.FallbackShowcase} />
+
+### Notification Indicator
+
+An optional notification indicator can be displayed to show status or alerts:
+
+- **showNotification**: Boolean prop to toggle the notification dot (default: false)
+
+<Canvas of={AvatarStories.NotificationShowcase} />
+
+### As Interactive Trigger
+
+Avatars are commonly used as interactive triggers for navigation or actions:
+
+<Canvas of={AvatarStories.InteractiveShowcase} />
+
+## Accessibility
+
+To be implemented:
+
+- **Color contrast**
+- **Text zoom support**
+- **Semantic alt text for images**
+- **Screen reader announcements for notification state**
+- **Touch target sizing** (minimum 44px)
+
+</Tab>
+<Tab label="Implementation">
+
+## Setup
+
+Install and set up the library with our [Setup Guide →](?path=/docs/getting-started-setup--docs).
+
+### Basic Usage
+
+```tsx
+import { Avatar } from '@ledgerhq/lumen-ui-rnative';
+
+function MyComponent() {
+  return <Avatar src="https://example.com/photo.jpg" size="md" />;
+}
+```
+
+### Fallback Handling
+
+The Avatar component automatically displays a fallback User icon when the image source is undefined or fails to load:
+
+```tsx
+import { Avatar } from '@ledgerhq/lumen-ui-rnative';
+
+function MyComponent() {
+  // Fallback will be shown automatically
+  return <Avatar size="md" alt="User profile" />;
+}
+```
+
+### With Notification
+
+Display a notification indicator to show status or alerts:
+
+```tsx
+import { Avatar } from '@ledgerhq/lumen-ui-rnative';
+
+function MyComponent() {
+  const hasNotifications = true;
+  
+  return (
+    <Avatar 
+      src="https://example.com/photo.jpg" 
+      showNotification={hasNotifications}
+      size="md" 
+      alt="User profile"
+    />
+  );
+}
+```
+
+### Different Sizes
+
+Choose between small and medium sizes based on your layout needs:
+
+```tsx
+import { Avatar, Box } from '@ledgerhq/lumen-ui-rnative';
+
+function MyComponent() {
+  return (
+    <Box lx={{ flexDirection: 'row', alignItems: 'center', gap: 's8' }}>
+      <Avatar src="https://example.com/photo.jpg" size="sm" />
+      <Avatar src="https://example.com/photo.jpg" size="md" />
+    </Box>
+  );
+}
+```
+
+### As Interactive Trigger
+
+Avatars are commonly used as interactive triggers for navigation or actions. Wrap the Avatar in a `Pressable` component:
+
+```tsx
+import { Avatar } from '@ledgerhq/lumen-ui-rnative';
+import { Pressable, Linking } from 'react-native';
+
+function UserProfile() {
+  const handlePress = () => {
+    // Navigate or perform action
+    console.log('Avatar pressed');
+  };
+
+  return (
+    <Pressable
+      onPress={handlePress}
+      style={({ pressed }) => ({
+        borderRadius: 9999,
+        opacity: pressed ? 0.7 : 1,
+        backgroundColor: pressed ? 'rgba(0, 0, 0, 0.05)' : 'transparent',
+      })}
+    >
+      <Avatar 
+        src="https://example.com/photo.jpg"
+        size="md" 
+        alt="User menu" 
+        showNotification 
+      />
+    </Pressable>
+  );
+}
+```
+
+**Key points:**
+- Wrap Avatar in a `Pressable` component for touch interactions
+- Use `borderRadius: 9999` to maintain circular touch area
+- Add opacity changes for visual feedback on press
+- Provide appropriate `alt` text for accessibility
+
+### Custom Styling
+
+While the component comes with predefined styles, you can extend them using the `lx` prop for token-based styling:
+
+```tsx
+<Avatar 
+  src="https://example.com/photo.jpg" 
+  size="md" 
+  lx={{ marginRight: 's8' }} // Layout positioning with design tokens
+/>
+```
+
+You can also use the `style` prop for escape-hatch styling when needed:
+
+```tsx
+<Avatar 
+  src="https://example.com/photo.jpg" 
+  size="md" 
+  style={{ marginRight: 8 }} // Raw style values
+/>
+```
+
+### Complete Example
+
+Here's a comprehensive example showing all Avatar features in a user profile context:
+
+```tsx
+import { Avatar, Box, Text } from '@ledgerhq/lumen-ui-rnative';
+import { Pressable } from 'react-native';
+import { useState } from 'react';
+
+function UserProfileHeader() {
+  const [user, setUser] = useState({
+    name: 'John Doe',
+    avatar: 'https://example.com/photo.jpg',
+    hasNotifications: true,
+  });
+
+  const handleProfilePress = () => {
+    console.log('Opening user menu...');
+    // Navigate to profile or show menu
+  };
+
+  return (
+    <Box lx={{ flexDirection: 'row', alignItems: 'center', gap: 's12', padding: 's16' }}>
+      <Pressable
+        onPress={handleProfilePress}
+        style={({ pressed }) => ({
+          borderRadius: 9999,
+          opacity: pressed ? 0.7 : 1,
+          backgroundColor: pressed ? 'rgba(0, 0, 0, 0.05)' : 'transparent',
+        })}
+      >
+        <Avatar
+          src={user.avatar}
+          size="md"
+          showNotification={user.hasNotifications}
+          alt={`${user.name} profile picture`}
+        />
+      </Pressable>
+      <Box lx={{ flexDirection: 'column' }}>
+        <Text>{user.name}</Text>
+        {user.hasNotifications && (
+          <Text style={{ fontSize: 12, color: '#666' }}>
+            You have new notifications
+          </Text>
+        )}
+      </Box>
+    </Box>
+  );
+}
+```
+
+## Do's and Don'ts
+
+The following guidelines ensure consistent usage of the Avatar component and maintain design system principles.
+
+<Box lx={{ flexDirection: 'column', gap: 's24' }}>
+  <DoVsDontRow>
+    <DoBlockItem
+      title='Provide descriptive alt text'
+      description='Use meaningful alt text for better accessibility and screen reader support'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Avatar 
+  src="https://example.com/photo.jpg" 
+  alt="John Doe profile picture" 
+  size="md"
+/>
+```
+
+    </DoBlockItem>
+    <DontBlockItem
+      title="Don't omit alt text"
+      description='Missing alt text reduces accessibility for screen reader users'
+    >
+
+{/* prettier-ignore */}
+```tsx
+<Avatar 
+  src="https://example.com/photo.jpg" 
+  size="md"
+/>
+```
+
+    </DontBlockItem>
+
+  </DoVsDontRow>
+
+  <CommonRulesDoAndDont />
+</Box>
+
+## Platform Considerations
+
+### iOS Specific
+
+- Avatars automatically adapt to iOS design guidelines
+- Touch feedback uses appropriate opacity transitions
+- Respects iOS accessibility settings like reduced motion
+
+### Android Specific
+
+- Material Design touch feedback is supported through React Native's Pressable
+- Handles Android back button interactions appropriately
+- Respects Android accessibility services
+
+### Cross-Platform
+
+- Consistent visual appearance across platforms
+- Platform-appropriate touch feedback via Pressable
+- Unified API regardless of platform
+- Images load using React Native's Image component with cross-platform optimization
+
+</Tab>
+</CustomTabs>

package/src/lib/Components/Avatar/Avatar.stories.tsx

@@ -0,0 +1,127 @@
+import { Meta, StoryObj } from '@storybook/react-native-web-vite';
+import { View, Text, Pressable, Linking } from 'react-native';
+
+import { Box } from '../Utility';
+import { Avatar } from './Avatar';
+
+const meta = {
+  component: Avatar,
+  title: 'Communication/Avatar',
+  parameters: {
+    docs: {
+      source: {
+        language: 'tsx',
+        format: true,
+        type: 'code',
+      },
+    },
+  },
+} satisfies Meta<typeof Avatar>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const exampleSrc =
+  'https://plus.unsplash.com/premium_photo-1689551670902-19b441a6afde?q=80&w=774&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D';
+
+export const Base: Story = {
+  args: {
+    src: exampleSrc,
+    alt: 'avatar',
+    size: 'md',
+    showNotification: false,
+  },
+  render: (args) => <Avatar {...args} />,
+  parameters: {
+    docs: {
+      source: {
+        code: `<Avatar src="https://example.com" size="md" alt="avatar" showNotification={false} />`,
+      },
+    },
+  },
+};
+
+export const SizeShowcase: Story = {
+  render: () => (
+    <Box
+      lx={{
+        alignItems: 'stretch',
+        flexDirection: 'row',
+        gap: 's16',
+      }}
+    >
+      <View style={{ alignItems: 'center', justifyContent: 'flex-end' }}>
+        <Avatar
+          src={exampleSrc}
+          alt='avatar'
+          size='sm'
+          showNotification={false}
+        />
+        <Text style={{ marginTop: 4 }}>sm</Text>
+      </View>
+      <View style={{ alignItems: 'center', justifyContent: 'flex-end' }}>
+        <Avatar
+          src={exampleSrc}
+          alt='avatar'
+          size='md'
+          showNotification={false}
+        />
+        <Text style={{ marginTop: 4 }}>md</Text>
+      </View>
+    </Box>
+  ),
+};
+
+export const FallbackShowcase: Story = {
+  args: {
+    src: 'https://brokenLink.random',
+    size: 'md',
+    alt: 'Fallback example',
+    showNotification: false,
+  },
+  render: (args) => <Avatar {...args} />,
+  parameters: {
+    docs: {
+      source: {
+        code: `<Avatar src="https://brokenLink.random" size="md" alt="Fallback example" showNotification={false} />`,
+      },
+    },
+  },
+};
+
+export const NotificationShowcase: Story = {
+  render: () => (
+    <Box
+      lx={{
+        flexDirection: 'row',
+        gap: 's16',
+      }}
+    >
+      <Avatar
+        src={exampleSrc}
+        alt='avatar'
+        size='md'
+        showNotification={false}
+      />
+      <Avatar src={exampleSrc} alt='avatar' size='md' showNotification={true} />
+    </Box>
+  ),
+};
+
+const onPressRedirect = () =>
+  Linking.openURL('https://shop.ledger.com/pages/ledger-nano-gen5');
+
+export const InteractiveShowcase: Story = {
+  render: () => (
+    <Pressable
+      onPress={onPressRedirect}
+      style={({ pressed }) => ({
+        borderRadius: 9999,
+        opacity: pressed ? 0.7 : 1,
+        backgroundColor: pressed ? 'rgba(0, 0, 0, 0.05)' : 'transparent',
+      })}
+    >
+      <Avatar src={exampleSrc} size='md' showNotification />
+    </Pressable>
+  ),
+};

package/src/lib/Components/Avatar/Avatar.test.tsx

@@ -0,0 +1,215 @@
+import { describe, it, expect } from '@jest/globals';
+import { ledgerLiveThemes } from '@ledgerhq/lumen-design-core';
+import { render, waitFor } from '@testing-library/react-native';
+import React from 'react';
+import { ThemeProvider } from '../ThemeProvider/ThemeProvider';
+import { Avatar } from './Avatar';
+
+const { colors, sizes } = ledgerLiveThemes.dark;
+
+const TestWrapper = ({ children }: { children: React.ReactNode }) => (
+  <ThemeProvider themes={ledgerLiveThemes} colorScheme='dark' locale='en'>
+    {children}
+  </ThemeProvider>
+);
+
+describe('Avatar Component', () => {
+  const testSrc =
+    'https://plus.unsplash.com/premium_photo-1689551670902-19b441a6afde?q=80&w=774&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D';
+  it('should render correctly with minimal props', () => {
+    const { getByLabelText } = render(
+      <TestWrapper>
+        <Avatar src={testSrc} />
+      </TestWrapper>,
+    );
+    getByLabelText('avatar');
+  });
+
+  it('should render with custom alt text', () => {
+    const { getByLabelText } = render(
+      <TestWrapper>
+        <Avatar src={testSrc} alt='user profile' />
+      </TestWrapper>,
+    );
+    getByLabelText('user profile');
+  });
+
+  it('should render with different sizes', () => {
+    const { getByTestId, rerender } = render(
+      <TestWrapper>
+        <Avatar testID='avatar-id' size='sm' />
+      </TestWrapper>,
+    );
+    expect(getByTestId('avatar-id').props.style.width).toBe(sizes.s40);
+    expect(getByTestId('avatar-id').props.style.height).toBe(sizes.s40);
+
+    rerender(
+      <TestWrapper>
+        <Avatar testID='avatar-id' size='md' />
+      </TestWrapper>,
+    );
+    expect(getByTestId('avatar-id').props.style.width).toBe(sizes.s48);
+    expect(getByTestId('avatar-id').props.style.height).toBe(sizes.s48);
+  });
+
+  it('should render fallback icon when no src is provided', () => {
+    const { getByLabelText, getByTestId } = render(
+      <TestWrapper>
+        <Avatar />
+      </TestWrapper>,
+    );
+
+    const avatarContainer = getByLabelText('avatar');
+    expect(avatarContainer).toBeTruthy();
+    expect(avatarContainer.props.accessibilityRole).toBe('image');
+
+    expect(getByTestId('avatar-fallback-icon')).toBeTruthy();
+  });
+
+  it('should render image when src is provided', () => {
+    const { getByLabelText, getByTestId } = render(
+      <TestWrapper>
+        <Avatar src='https://example.com/avatar.jpg' alt='user avatar' />
+      </TestWrapper>,
+    );
+
+    const avatarContainer = getByLabelText('user avatar');
+    expect(avatarContainer).toBeTruthy();
+    expect(avatarContainer.props.accessibilityRole).toBe('image');
+
+    const image = getByTestId('avatar-image');
+    expect(image.props.source).toEqual({
+      uri: 'https://example.com/avatar.jpg',
+    });
+  });
+
+  it('should render fallback icon on image error', async () => {
+    const { getByLabelText, getByTestId, queryByTestId, rerender } = render(
+      <TestWrapper>
+        <Avatar src='https://example.com/invalid.jpg' alt='broken image' />
+      </TestWrapper>,
+    );
+
+    const avatarContainer = getByLabelText('broken image');
+    expect(avatarContainer).toBeTruthy();
+
+    const image = getByTestId('avatar-image');
+    expect(image).toBeTruthy();
+
+    image.props.onError();
+
+    rerender(
+      <TestWrapper>
+        <Avatar src='https://example.com/invalid.jpg' alt='broken image' />
+      </TestWrapper>,
+    );
+
+    await waitFor(() => {
+      expect(queryByTestId('avatar-image')).toBeNull();
+      expect(getByTestId('avatar-fallback-icon')).toBeTruthy();
+    });
+  });
+
+  it('should reset error state when src changes', async () => {
+    const { getByLabelText, getByTestId, rerender } = render(
+      <TestWrapper>
+        <Avatar src='https://example.com/avatar1.jpg' alt='avatar image' />
+      </TestWrapper>,
+    );
+
+    const avatarContainer = getByLabelText('avatar image');
+    expect(avatarContainer).toBeTruthy();
+
+    const image = getByTestId('avatar-image');
+    image.props.onError();
+
+    rerender(
+      <TestWrapper>
+        <Avatar src='https://example.com/avatar2.jpg' alt='avatar image' />
+      </TestWrapper>,
+    );
+
+    await waitFor(() => {
+      const newImage = getByTestId('avatar-image');
+      expect(newImage.props.source).toEqual({
+        uri: 'https://example.com/avatar2.jpg',
+      });
+    });
+  });
+
+  it('should show notification indicator when showNotification is true', () => {
+    const { getByTestId } = render(
+      <TestWrapper>
+        <Avatar testID='avatar-id' showNotification />
+      </TestWrapper>,
+    );
+
+    const avatar = getByTestId('avatar-id');
+    const notificationIndicator = avatar.props.children[0];
+
+    expect(notificationIndicator).toBeTruthy();
+    expect(notificationIndicator.props.style.backgroundColor).toBe(
+      colors.bg.errorStrong,
+    );
+  });
+
+  it('should not show notification indicator by default', () => {
+    const { getByTestId } = render(
+      <TestWrapper>
+        <Avatar testID='avatar-id' />
+      </TestWrapper>,
+    );
+
+    const avatar = getByTestId('avatar-id');
+    const notificationIndicator = avatar.props.children[0];
+
+    expect(notificationIndicator).toBe(false);
+  });
+
+  it('should apply correct notification indicator size based on avatar size', () => {
+    const { getByTestId, rerender } = render(
+      <TestWrapper>
+        <Avatar testID='avatar-id' size='sm' showNotification />
+      </TestWrapper>,
+    );
+
+    let avatar = getByTestId('avatar-id');
+    let notificationIndicator = avatar.props.children[0];
+    expect(notificationIndicator.props.style.width).toBe(sizes.s10);
+    expect(notificationIndicator.props.style.height).toBe(sizes.s10);
+
+    rerender(
+      <TestWrapper>
+        <Avatar testID='avatar-id' size='md' showNotification />
+      </TestWrapper>,
+    );
+
+    avatar = getByTestId('avatar-id');
+    notificationIndicator = avatar.props.children[0];
+    expect(notificationIndicator.props.style.width).toBe(sizes.s12);
+    expect(notificationIndicator.props.style.height).toBe(sizes.s12);
+  });
+
+  it('should apply custom styles', () => {
+    const customStyle = { borderWidth: 2 };
+    const { getByTestId } = render(
+      <TestWrapper>
+        <Avatar testID='avatar-id' style={customStyle} />
+      </TestWrapper>,
+    );
+
+    const avatar = getByTestId('avatar-id');
+    expect(avatar.props.style.borderWidth).toBe(2);
+  });
+
+  it('should pass additional props to the Box component', () => {
+    const { getByTestId } = render(
+      <TestWrapper>
+        <Avatar testID='custom-test-id' accessibilityLabel='Profile Avatar' />
+      </TestWrapper>,
+    );
+
+    const avatar = getByTestId('custom-test-id');
+    expect(avatar.props.accessibilityLabel).toBe('Profile Avatar');
+  });
+});