# Avatar

## Introduction

Avatar 컴포넌트는 사용자의 프로필 이미지, 이니셜 또는 아이콘을 표시하는 컴포넌트입니다. Joy UI의 Avatar를 기반으로 하며, 다양한 크기, 색상, 변형을 지원합니다. 사용자 인터페이스에서 개인을 시각적으로 나타내거나 그룹, 브랜드를 표현하는 데 사용됩니다.

```tsx
<Avatar alt="User avatar" />
```

| Field    | Description | Default       |
| -------- | ----------- | ------------- |
| variant  | —           | —             |
| color    | —           | —             |
| size     | —           | —             |
| src      | —           | —             |
| alt      | —           | "User avatar" |
| children | —           | —             |

## Usage

```tsx
import { Avatar } from '@ceed/cds';

function MyComponent() {
  return (
    <div>
      {/* 이미지가 있는 아바타 */}
      <Avatar src="/path/to/image.jpg" alt="사용자 이름" />

      {/* 이니셜 아바타 */}
      <Avatar>김철수</Avatar>

      {/* 단일 문자 아바타 */}
      <Avatar>김</Avatar>
    </div>
  );
}
```

## Examples

### Basic Usage

가장 기본적인 Avatar 사용법입니다.

```tsx
<Avatar alt="User avatar" />
```

### With Image

이미지를 사용한 아바타입니다.

```tsx
<Stack direction="row" spacing={2} alignItems="center">
  <Avatar {...args} />
</Stack>
```

### With Text

텍스트나 이니셜을 사용한 아바타입니다.

```tsx
<Stack direction="row" spacing={2} alignItems="center">
  <Avatar {...args} />
</Stack>
```

## Customization

### Variants

다양한 시각적 스타일을 적용할 수 있습니다.

```tsx
<Stack direction="row" spacing={2} alignItems="center">
  {variants.map(variant => <Avatar key={variant} {...args} variant={variant} />)}
</Stack>
```

- **solid**: 배경색이 채워진 스타일
- **soft**: 부드러운 배경색 스타일
- **outlined**: 테두리만 있는 스타일
- **plain**: 최소한의 스타일

### Sizes

다양한 크기의 아바타를 사용할 수 있습니다.

```tsx
<Stack direction="row" spacing={2} alignItems="center">
  {sizesWithXs.map(size => <Avatar key={size} {...args} size={size}>
  {getSizeContent(size)}
</Avatar>)}
</Stack>
```

- **xs**: 매우 작은 크기 (16px)
- **sm**: 작은 크기 (24px)
- **md**: 중간 크기 (32px, 기본값)
- **lg**: 큰 크기 (40px)

### Colors

다양한 색상 테마를 적용할 수 있습니다.

```tsx
<Stack direction="row" spacing={2} alignItems="center">
  {colors.map(color => <Avatar key={color} {...args} color={color} />)}
</Stack>
```

- **primary**: 주요 브랜드 색상
- **neutral**: 중립적인 회색톤
- **danger**: 경고나 오류를 나타내는 빨간색
- **success**: 성공을 나타내는 녹색
- **warning**: 주의를 나타내는 주황색

### All Combinations

모든 변형, 크기, 색상 조합을 확인할 수 있습니다.

```tsx
<Stack gap={8}>
  {variants.map(variant => <Stack key={variant} gap={2}>
  <Typography level="title-md">
    {variant.slice(0, 1).toLocaleUpperCase()}
    {variant.slice(1)} Variant
  </Typography>
  {colors.map(color => <Stack key={color} direction="row" gap={2} alignItems="center">
  {sizesWithXs.map(size => <Stack key={size} alignItems="center" gap={1}>
  <Avatar {...args} size={size} color={color} variant={variant}>
    {getSizeContent(size)}
  </Avatar>
  <Typography level="body-sm">{size}</Typography>
</Stack>)}
{/* With image */}
<Stack alignItems="center" gap={1}>
  <Avatar {...args} size="md" color={color} variant={variant} />
  <Typography level="body-sm">image</Typography>
</Stack>
</Stack>)}
</Stack>)}
</Stack>
```

## Common Use Cases

### User Profile

사용자 프로필에서 아바타를 사용하는 경우입니다.

```tsx
<Stack direction="row" spacing={2} alignItems="center">
  <Avatar src="/user-profile.jpg" alt="김철수" size="lg" />
  <Stack>
    <Typography level="title-md">김철수</Typography>
    <Typography level="body-sm" color="neutral">
      kim@example.com
    </Typography>
  </Stack>
</Stack>
```

### Navigation Bar

네비게이션 바에서 현재 사용자를 표시할 때 사용합니다.

```tsx
<Stack direction="row" spacing={2} alignItems="center" sx={{ ml: 'auto' }}>
  <Avatar size="sm" variant="soft" color="primary">
    김
  </Avatar>
  <Typography level="body-sm">김철수</Typography>
  <IconButton variant="plain" size="sm">
    <ExpandMoreIcon />
  </IconButton>
</Stack>
```

### Comment System

댓글이나 피드에서 사용자를 나타낼 때 사용합니다.

```tsx
<Stack direction="row" spacing={2}>
  <Avatar size="md" variant="soft" color="primary">
    김
  </Avatar>
  <Stack flex={1}>
    <Stack direction="row" spacing={1} alignItems="center">
      <Typography level="title-sm">김철수</Typography>
      <Typography level="body-xs" color="neutral">
        2시간 전
      </Typography>
    </Stack>
    <Typography level="body-md">이것은 사용자의 댓글 내용입니다.</Typography>
  </Stack>
</Stack>
```

### Team Members

팀 구성원 목록을 표시할 때 사용합니다.

```tsx
<Stack spacing={3}>
  <Typography level="title-lg">팀 구성원</Typography>

  {teamMembers.map((member) => (
    <Stack key={member.id} direction="row" spacing={2} alignItems="center">
      <Avatar src={member.avatar} alt={member.name} size="md" variant="soft" color="primary">
        {member.name.charAt(0)}
      </Avatar>
      <Stack flex={1}>
        <Typography level="title-sm">{member.name}</Typography>
        <Typography level="body-sm" color="neutral">
          {member.role}
        </Typography>
      </Stack>
      <Chip variant="soft" size="sm" color="success">
        온라인
      </Chip>
    </Stack>
  ))}
</Stack>
```

### Avatar Groups

여러 사용자를 그룹으로 표시할 때 사용합니다.

```tsx
<Stack direction="row" spacing={-1}>
  <Avatar size="sm" variant="solid" color="primary">
    김
  </Avatar>
  <Avatar size="sm" variant="solid" color="success">
    이
  </Avatar>
  <Avatar size="sm" variant="solid" color="warning">
    박
  </Avatar>
  <Avatar size="sm" variant="outlined" color="neutral">
    <Typography level="body-xs">+3</Typography>
  </Avatar>
</Stack>
```

### Status Indicators

사용자 상태를 함께 표시할 때 사용합니다.

```tsx
<Box sx={{ position: 'relative', display: 'inline-block' }}>
  <Avatar src="/user-avatar.jpg" alt="사용자" size="lg" />
  <Box
    sx={{
      position: 'absolute',
      bottom: 0,
      right: 0,
      width: 12,
      height: 12,
      bgcolor: 'success.500',
      borderRadius: '50%',
      border: '2px solid',
      borderColor: 'background.body',
    }}
  />
</Box>
```

### Empty State

데이터가 없을 때 플레이스홀더로 사용합니다.

```tsx
<Stack alignItems="center" spacing={2}>
  <Avatar size="lg" variant="outlined" color="neutral">
    <PersonIcon />
  </Avatar>
  <Typography level="body-md" color="neutral">
    프로필 이미지를 업로드하세요
  </Typography>
  <Button variant="outlined" size="sm">
    이미지 선택
  </Button>
</Stack>
```

### List Items

리스트 아이템에서 사용자나 항목을 표현할 때 사용합니다.

```tsx
<List>
  {users.map((user) => (
    <ListItem key={user.id}>
      <ListItemDecorator>
        <Avatar src={user.avatar} alt={user.name} size="sm">
          {user.name.charAt(0)}
        </Avatar>
      </ListItemDecorator>
      <ListItemContent>
        <Typography level="title-sm">{user.name}</Typography>
        <Typography level="body-sm" color="neutral">
          {user.email}
        </Typography>
      </ListItemContent>
    </ListItem>
  ))}
</List>
```

## Image Handling

### Fallback Behavior

이미지 로드가 실패했을 때 자동으로 이니셜이나 아이콘으로 대체됩니다.

```tsx
<Avatar src="/broken-image-url.jpg" alt="김철수" color="primary" variant="soft">
  김
</Avatar>
```

### Loading States

이미지 로딩 중에는 children이 표시되다가 이미지 로드 완료 후 이미지로 전환됩니다.

```tsx
<Avatar src="/slow-loading-image.jpg" alt="사용자" color="neutral" variant="soft">
  <PersonIcon />
</Avatar>
```

## Accessibility

Avatar 컴포넌트는 다음과 같은 접근성 기능을 제공합니다:

### Image Alt Text

이미지 아바타의 경우 적절한 alt 텍스트를 제공해야 합니다.

```tsx
<Avatar src="/user-profile.jpg" alt="김철수의 프로필 사진" />
```

### Semantic Meaning

아바타가 단순히 장식적 목적이 아닌 의미를 가질 때는 적절한 역할을 제공하세요.

```tsx
<Avatar src="/user-avatar.jpg" alt="현재 사용자" role="img" aria-label="현재 로그인한 사용자의 프로필 이미지" />
```

### Color Contrast

텍스트 아바타의 경우 충분한 색상 대비를 유지하세요.

```tsx
// 좋은 대비를 제공하는 색상 조합
<Avatar variant="solid" color="primary">김</Avatar>
<Avatar variant="soft" color="neutral">이</Avatar>
```

## Best Practices

1. **적절한 크기 선택**: 사용 맥락에 맞는 적절한 크기를 선택하세요.

```tsx
// ✅ 적절한 크기 사용
<Avatar size="sm">김</Avatar>  // 리스트 아이템에서
<Avatar size="lg">김</Avatar>  // 프로필 페이지에서

// ❌ 부적절한 크기 사용
<Avatar size="lg">김</Avatar>  // 네비게이션 바에서 (너무 큼)
```

2. **일관된 스타일**: 같은 컨텍스트에서는 일관된 변형과 색상을 사용하세요.

3. **이미지 최적화**: 아바타 이미지는 적절한 크기로 최적화하여 사용하세요.

4. **폴백 제공**: 이미지가 없거나 로드 실패 시를 대비해 적절한 폴백을 제공하세요.

```tsx
<Avatar src={user.avatar} alt={user.name} color="primary" variant="soft">
  {user.name?.charAt(0) || '?'}
</Avatar>
```

5. **의미적 사용**: 아바타가 누구를 나타내는지 명확하게 식별할 수 있어야 합니다.

## Performance Considerations

1. **이미지 최적화**: 아바타 이미지는 작은 크기로 최적화하여 로딩 속도를 향상시키세요.

2. **Lazy Loading**: 많은 아바타가 있는 페이지에서는 지연 로딩을 고려하세요.

3. **캐싱**: 자주 사용되는 아바타 이미지는 적절히 캐싱하세요.

Avatar는 사용자 인터페이스에서 개인을 시각적으로 나타내는 중요한 컴포넌트입니다. 적절한 크기, 색상, 변형을 선택하여 일관되고 접근 가능한 사용자 경험을 제공할 수 있습니다.
