npm package: @libs-ui/components-avatar
Description: > Version: `0.2.355-10` > > Component hiển thị avatar (ảnh đại diện) với khả năng fallback sang text/icon khi ảnh lỗi hoặc không có.
Latest version: 0.2.356-23

# Avatar Component

> Version: `0.2.355-10`
>
> Component hiển thị avatar (ảnh đại diện) với khả năng fallback sang text/icon khi ảnh lỗi hoặc không có.

## Giới thiệu

`LibsUiComponentsAvatarComponent` là một standalone Angular component để hiển thị avatar (ảnh đại diện) của người dùng. Component hỗ trợ nhiều kích thước, hình dạng (circle/rectangle), và có cơ chế fallback thông minh khi ảnh lỗi.

### Tính năng

- ✅ Hiển thị ảnh avatar từ URL
- ✅ Fallback tự động sang text/icon khi ảnh lỗi
- ✅ Hỗ trợ nhiều kích thước: 16, 24, 32, 40, 48, 64px
- ✅ Hỗ trợ 2 hình dạng: circle (mặc định) và rectangle
- ✅ Tự động tạo màu nền dựa trên ID (hash color)
- ✅ Preview ảnh khi click (tùy chọn)
- ✅ OnPush Change Detection
- ✅ Angular Signals

## Lưu ý quan trọng (Important Notes)

> ⚠️ **Caveats**:
>
> - **Thứ tự Input quan trọng**: Nếu sử dụng `getLastTextAfterSpace`, phải truyền input này **TRƯỚC** `textAvatar` để logic transform hoạt động đúng.
> - **Error Handling Chain**: Component có chuỗi xử lý lỗi: `linkAvatar` → `linkAvatarError` → `textAvatar` + `idGenColor`. Nếu tất cả đều fail, sẽ hiển thị icon với text.
> - **Màu nền tự động**: Màu nền được tạo từ `idGenColor` thông qua hàm hash. Cùng ID sẽ luôn có cùng màu.
> - **Font size tự động**: Font size của text avatar được tính tự động dựa trên `size` (16/24 → 6, 32 → 4, 40 → 3, 64 → 1, default → 4).
> - **Preview Image**: Khi `clickPreviewImage = true`, click vào ảnh sẽ mở gallery viewer. Component tự quản lý lifecycle của gallery viewer.

## Khi nào sử dụng

- Hiển thị ảnh đại diện người dùng trong danh sách, comment, profile
- Hiển thị avatar với fallback khi ảnh không tải được
- Cần hiển thị avatar với nhiều kích thước khác nhau
- Cần preview ảnh khi click vào avatar

## Cài đặt

```bash
npm install @libs-ui/components-avatar
```

## Import

```typescript
import { LibsUiComponentsAvatarComponent, TYPE_SHAPE_AVATAR, TYPE_SIZE_AVATAR_CONFIG, IAvatarConfig } from '@libs-ui/components-avatar';

@Component({
  standalone: true,
  imports: [LibsUiComponentsAvatarComponent],
  // ...
})
```

## Cách sử dụng

### 1. Basic - Avatar với ảnh

```html
<libs_ui-components-avatar
  [linkAvatar]="'https://example.com/avatar.jpg'"
  [size]="32" />
```

### 2. Avatar với fallback text

```html
<libs_ui-components-avatar
  [linkAvatar]="'https://example.com/avatar.jpg'"
  [linkAvatarError]="'https://example.com/fallback.jpg'"
  [textAvatar]="'John Doe'"
  [idGenColor]="'user-123'"
  [size]="40" />
```

### 3. Avatar rectangle

```html
<libs_ui-components-avatar
  [linkAvatar]="'https://example.com/avatar.jpg'"
  [typeShape]="'rectangle'"
  [size]="48" />
```

### 4. Avatar với preview

```html
<libs_ui-components-avatar
  [linkAvatar]="'https://example.com/avatar.jpg'"
  [clickPreviewImage]="true"
  [zIndexPreviewImage]="1000"
  [size]="64" />
```

### 5. Avatar với custom classes

```html
<libs_ui-components-avatar
  [linkAvatar]="'https://example.com/avatar.jpg'"
  [classInclude]="'mr-4 mb-2'"
  [classImageInclude]="'rounded-lg'"
  [size]="32" />
```

## API

### libs_ui-components-avatar

#### Inputs

| Property | Type | Default | Description |
|----------|------|---------|-------------|
| `[typeShape]` | `TYPE_SHAPE_AVATAR \| undefined` | `'circle'` | Hình dạng avatar: 'circle' hoặc 'rectangle' |
| `[classInclude]` | `string \| undefined` | `'mr-[8px]'` | Class CSS tùy chỉnh cho container |
| `[size]` | `TYPE_SIZE_AVATAR_CONFIG \| undefined` | `32` | Kích thước avatar: 16, 24, 32, 40, 48, 64 |
| `[linkAvatar]` | `string` | `-` | URL ảnh avatar chính |
| `[linkAvatarError]` | `string` | `-` | URL ảnh fallback khi `linkAvatar` lỗi |
| `[classImageInclude]` | `string \| undefined` | `''` | Class CSS tùy chỉnh cho thẻ img |
| `[zIndexPreviewImage]` | `number` | `-` | Z-index cho gallery viewer khi preview |
| `[clickPreviewImage]` | `boolean` | `-` | Bật preview ảnh khi click |
| `[idGenColor]` | `string` | `-` | ID để generate màu nền (hash color) |
| `[getLastTextAfterSpace]` | `boolean` | `-` | Lấy text cuối cùng sau khoảng trắng (phải truyền TRƯỚC textAvatar) |
| `[textAvatar]` | `string \| undefined` | `''` | Text hiển thị khi không có ảnh (tự động clean unicode và ký tự đặc biệt) |
| `[textAvatarClassInclude]` | `string` | `''` | Class CSS tùy chỉnh cho text |
| `[containertextAvatarClassInclude]` | `string` | `''` | Class CSS tùy chỉnh cho container text |

#### Outputs

| Property | Type | Description |
|----------|------|-------------|
| `(outAvatarError)` | `EventEmitter<void>` | Emit khi cả `linkAvatar` và `linkAvatarError` đều lỗi |
| `(outEventPreviewImage)` | `EventEmitter<'open' \| 'remove'>` | Emit khi mở/đóng gallery viewer |

## Types & Interfaces

```typescript
export type TYPE_SIZE_AVATAR_CONFIG = 16 | 24 | 32 | 40 | 48 | 64;

export type TYPE_SHAPE_AVATAR = 'circle' | 'rectangle';

export interface IAvatarConfig {
  classImageInclude?: string;
  classInclude?: string;
  size?: TYPE_SIZE_AVATAR_CONFIG;
  linkAvatar?: string;
  linkAvatarError?: string;
  idGenColor?: string;
  textAvatar?: string;
  typeShape?: TYPE_SHAPE_AVATAR;
  getLastTextAfterSpace?: boolean;
}
```

### Type Descriptions

- **TYPE_SIZE_AVATAR_CONFIG**: Các kích thước avatar được hỗ trợ. Font size của text sẽ tự động điều chỉnh theo size.
- **TYPE_SHAPE_AVATAR**: Hình dạng avatar. 'circle' có border-radius 50%, 'rectangle' có border-radius 4px.
- **IAvatarConfig**: Interface để định nghĩa object config, hữu ích khi truyền config từ parent component.

## Styling

### CSS Classes

| Class | Description |
|-------|-------------|
| `.libs_ui-component-avatar` | Container chính của avatar |
| `.libs_ui-component-avatar-rectangle` | Class khi `typeShape = 'rectangle'` |
| `.libs_ui-component-avatar-icon` | Container cho text/icon fallback |

### CSS Variables

Component không sử dụng CSS variables, màu nền được generate từ `idGenColor` thông qua hàm hash.

## Công nghệ

| Technology | Version | Purpose |
|------------|---------|---------|
| Angular | 18+ | Framework |
| Angular Signals | - | State management |
| TailwindCSS | 3.x | Styling |
| OnPush | - | Change Detection |

## Demo

```bash
npx nx serve core-ui
```

Truy cập: `http://localhost:4500/avatar`

## Unit Tests

```bash
# Chạy tests
npx nx test components-avatar

# Coverage
npx nx test components-avatar --coverage

# Watch mode
npx nx test components-avatar --watch
```

## License

MIT