@libs-ui/components-avatar 0.2.355-10 → 0.2.355-12

package/README.md

@@ -0,0 +1,209 @@
+# 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
+

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@libs-ui/components-avatar",
-  "version": "0.2.355-10",
+  "version": "0.2.355-12",
   "peerDependencies": {
     "@angular/core": ">=18.0.0",
-    "@libs-ui/interfaces-types": "0.2.355-10",
-    "@libs-ui/utils": "0.2.355-10"
+    "@libs-ui/interfaces-types": "0.2.355-12",
+    "@libs-ui/utils": "0.2.355-12"
   },
   "sideEffects": false,
   "module": "fesm2022/libs-ui-components-avatar.mjs",