@libs-ui/components-color-picker 0.2.355-9 → 0.2.356-0

package/README.md

@@ -1,3 +1,180 @@
-# color-picker
+# @libs-ui/components-color-picker
 
-This library was generated with [Nx](https://nx.dev).
+> Component chọn màu sắc với giao diện trực quan, hỗ trợ nhiều định dạng màu và alpha channel
+
+## Giới thiệu
+
+`LibsUiComponentsColorPickerComponent` là một standalone Angular component để chọn màu sắc một cách trực quan thông qua giao diện canvas-based color picker.
+
+### Tính năng
+
+- ✅ Canvas-based color picker với Hue, Saturation/Lightness bars
+- ✅ Hỗ trợ Alpha channel (độ trong suốt)
+- ✅ Nhiều định dạng output (RGB, RGBA, HSL, HSLA, HEX, HEX with alpha)
+- ✅ Input fields cho từng giá trị màu (R, G, B, H, S, L, Alpha, HEX)
+- ✅ Preview màu real-time
+- ✅ Copy mã màu nhanh chóng
+- ✅ Tùy chỉnh kích thước bars và hiển thị fields
+- ✅ OnPush Change Detection
+- ✅ Angular Signals
+- ✅ Standalone Component
+
+## Khi nào sử dụng
+
+- Khi cần cho phép người dùng chọn màu sắc một cách trực quan
+- Khi cần hỗ trợ nhiều định dạng màu (RGB, HSL, HEX)
+- Khi cần điều chỉnh độ trong suốt (alpha channel)
+- Khi cần preview màu đã chọn real-time
+- Khi cần copy mã màu nhanh chóng
+
+## Cài đặt
+
+```bash
+npm install @libs-ui/components-color-picker
+```
+
+## Sử dụng cơ bản
+
+```typescript
+import { Component } from '@angular/core';
+import { LibsUiComponentsColorPickerComponent } from '@libs-ui/components-color-picker';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [LibsUiComponentsColorPickerComponent],
+  template: `
+    <libs_ui-components-color_picker (outColorChange)="onColorChange($event)" />
+  `,
+})
+export class ExampleComponent {
+  onColorChange(color: string): void {
+    console.log('Selected color:', color); // "#3b82f6"
+  }
+}
+```
+
+## API
+
+### Inputs
+
+| Property                              | Type                   | Default     | Description                             |
+| ------------------------------------- | ---------------------- | ----------- | --------------------------------------- |
+| `[customOptions]`                     | `IPickerCustomOptions` | `undefined` | Tùy chỉnh options cho color picker      |
+| `[noEmitEventColorWhenInitComponent]` | `boolean`              | `true`      | Không emit event khi khởi tạo component |
+
+### Outputs
+
+| Property                       | Type                             | Description                           |
+| ------------------------------ | -------------------------------- | ------------------------------------- |
+| `(outColorChange)`             | `string`                         | Emit màu đã chọn dưới dạng HEX string |
+| `(outColorChangeMultipleType)` | `IOutputColorChangeMultipleType` | Emit màu với nhiều format             |
+
+## Interfaces
+
+### IPickerCustomOptions
+
+```typescript
+export interface IPickerCustomOptions {
+  slBarSize?: Array<number>; // Kích thước Saturation/Lightness bar [width, height]
+  hueBarSize?: Array<number>; // Kích thước Hue bar [width, height]
+  alphaBarSize?: Array<number>; // Kích thước Alpha bar [width, height]
+  showHsl?: boolean; // Hiển thị HSL input fields
+  showRgb?: boolean; // Hiển thị RGB input fields
+  showHex?: boolean; // Hiển thị HEX input field
+  showAlpha?: boolean; // Hiển thị Alpha slider
+  color?: string | Array<number>; // Màu mặc định
+  format?: 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'hex' | 'color';
+}
+```
+
+### IOutputColorChangeMultipleType
+
+```typescript
+export interface IOutputColorChangeMultipleType {
+  rgba: string; // "rgba(59, 130, 246, 1)"
+  rgb: string; // "rgb(59, 130, 246)"
+  hex: string; // "#3b82f6" hoặc "#3b82f6ff" (nếu có alpha)
+  hsl: string; // "hsl(217, 91, 60)"
+  hsla: string; // "hsla(217, 91, 60, 1)"
+  alpha: number; // 0-1
+}
+```
+
+## Ví dụ nâng cao
+
+### Với Custom Options
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { LibsUiComponentsColorPickerComponent, IPickerCustomOptions, IOutputColorChangeMultipleType } from '@libs-ui/components-color-picker';
+
+@Component({
+  standalone: true,
+  imports: [LibsUiComponentsColorPickerComponent],
+  template: `
+    <libs_ui-components-color_picker
+      [customOptions]="pickerOptions()"
+      (outColorChange)="onColorChange($event)"
+      (outColorChangeMultipleType)="onColorChangeMultiple($event)" />
+  `,
+})
+export class ExampleComponent {
+  readonly pickerOptions = signal<IPickerCustomOptions>({
+    color: '#ff6b6b',
+    showAlpha: true,
+    showHex: true,
+    showRgb: true,
+    showHsl: false,
+    format: 'hex',
+  });
+
+  onColorChange(color: string): void {
+    console.log('HEX:', color);
+  }
+
+  onColorChangeMultiple(colors: IOutputColorChangeMultipleType): void {
+    console.log('RGB:', colors.rgb);
+    console.log('HSL:', colors.hsl);
+    console.log('Alpha:', colors.alpha);
+  }
+}
+```
+
+### Custom Bar Sizes
+
+```typescript
+readonly customSizeOptions = signal<IPickerCustomOptions>({
+  slBarSize: [300, 200],      // Larger SL bar
+  hueBarSize: [300, 20],      // Wider hue bar
+  alphaBarSize: [300, 20],    // Wider alpha bar
+  showAlpha: true
+});
+```
+
+## Important Notes
+
+⚠️ **Canvas Rendering**: Component sử dụng HTML5 Canvas để render color picker, cần browser hỗ trợ Canvas API.
+
+⚠️ **Signal-based**: Component sử dụng Angular Signals để quản lý state, đảm bảo reactivity tốt.
+
+⚠️ **Multiple Formats**: Hỗ trợ nhiều format output (RGB, RGBA, HSL, HSLA, HEX, HEX with alpha).
+
+⚠️ **Custom Options**: Có thể customize kích thước bars, hiển thị/ẩn các input fields.
+
+⚠️ **Event Timing**: Mặc định không emit event khi khởi tạo component (`noEmitEventColorWhenInitComponent = true`). Set thành `false` nếu muốn emit event ngay khi init.
+
+## Dependencies
+
+- `@angular/core` >= 18.0.0
+- `@libs-ui/components-inputs-input`
+- `@libs-ui/services-notification`
+- `@libs-ui/utils`
+
+## Demo
+
+Xem demo tại: [http://localhost:4500/color-picker](http://localhost:4500/color-picker)
+
+## License
+
+MIT

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@libs-ui/components-color-picker",
-  "version": "0.2.355-9",
+  "version": "0.2.356-0",
   "peerDependencies": {
     "@angular/core": ">=18.0.0",
-    "@libs-ui/components-inputs-input": "0.2.355-9",
-    "@libs-ui/services-notification": "0.2.355-9",
-    "@libs-ui/utils": "0.2.355-9",
+    "@libs-ui/components-inputs-input": "0.2.356-0",
+    "@libs-ui/services-notification": "0.2.356-0",
+    "@libs-ui/utils": "0.2.356-0",
     "rxjs": "~7.8.0"
   },
   "sideEffects": false,