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

package/README.md

@@ -1,31 +1,31 @@
 # @libs-ui/components-color-picker
 
-> 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
+> Component chọn màu sắc canvas-based với hỗ trợ đầy đủ HSL, RGB, HEX 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.
+`LibsUiComponentsColorPickerComponent` là một standalone Angular component cung cấp giao diện color picker trực quan dựa trên HTML5 Canvas. Component cho phép người dùng chọn màu qua thanh Hue, vùng Saturation/Lightness, thanh Alpha và các ô nhập liệu RGB/HSL/HEX. Mọi thay đổi màu sắc được emit theo thời gian thực ở nhiều định dạng khác nhau.
 
-### Tính năng
+## 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
+- Canvas-based color picker với thanh Hue và vùng Saturation/Lightness
+- Hỗ trợ Alpha channel (độ trong suốt 0–1)
+- Emit màu ở nhiều định dạng: HEX, RGB, RGBA, HSL, HSLA, alpha
+- Input fields cho từng kênh màu (R, G, B, H, S, L, Alpha, HEX)
+- Preview màu real-time
+- Nút copy mã màu HEX vào clipboard
+- Tùy chỉnh kích thước các thanh color bar
+- Bật/tắt từng nhóm input fields (RGB, HSL, HEX, Alpha)
+- Kiểm soát có emit event khi khởi tạo component hay không
+- 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 hỗ trợ nhiều định dạng màu (RGB, HSL, HEX) đồng thời
 - 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
+- Khi cần preview màu đã chọn real-time trước khi áp dụng
+- Khi cần tùy chỉnh kích thước giao diện color picker để phù hợp với layout
 
 ## Cài đặt
 
@@ -33,148 +33,274 @@
 npm install @libs-ui/components-color-picker
 ```
 
-## Sử dụng cơ bản
+## Import
 
 ```typescript
-import { Component } from '@angular/core';
+import { LibsUiComponentsColorPickerComponent } from '@libs-ui/components-color-picker';
+
+// Interfaces và types nếu cần
+import {
+  IPickerCustomOptions,
+  IOutputColorChangeMultipleType,
+} from '@libs-ui/components-color-picker';
+```
+
+## Ví dụ sử dụng
+
+### Cơ bản — Lắng nghe màu đã chọn dạng HEX
+
+```typescript
+import { Component, signal } from '@angular/core';
 import { LibsUiComponentsColorPickerComponent } from '@libs-ui/components-color-picker';
 
 @Component({
-  selector: 'app-example',
+  selector: 'app-basic-color-picker',
   standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [LibsUiComponentsColorPickerComponent],
   template: `
-    <libs_ui-components-color_picker (outColorChange)="onColorChange($event)" />
+    <libs_ui-components-color_picker
+      (outColorChange)="handlerColorChange($event)"
+    />
+    <p>Màu đã chọn: <code>{{ selectedColor() }}</code></p>
   `,
 })
-export class ExampleComponent {
-  onColorChange(color: string): void {
-    console.log('Selected color:', color); // "#3b82f6"
+export class BasicColorPickerComponent {
+  protected selectedColor = signal<string>('#ff0000');
+
+  protected handlerColorChange(event: string): void {
+    event.stopPropagation?.();
+    this.selectedColor.set(event);
   }
 }
 ```
 
-## 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 |
+### Với custom options — Alpha channel và HSL ẩn
 
-### 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
+```typescript
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  IOutputColorChangeMultipleType,
+  IPickerCustomOptions,
+  LibsUiComponentsColorPickerComponent,
+} from '@libs-ui/components-color-picker';
 
-### IPickerCustomOptions
+@Component({
+  selector: 'app-custom-options-color-picker',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [LibsUiComponentsColorPickerComponent],
+  template: `
+    <libs_ui-components-color_picker
+      [customOptions]="pickerOptions()"
+      (outColorChange)="handlerColorChange($event)"
+      (outColorChangeMultipleType)="handlerColorChangeMultiple($event)"
+    />
+    @if (colorOutput()) {
+      <ul>
+        <li>HEX: {{ colorOutput()!.hex }}</li>
+        <li>RGB: {{ colorOutput()!.rgb }}</li>
+        <li>RGBA: {{ colorOutput()!.rgba }}</li>
+        <li>HSL: {{ colorOutput()!.hsl }}</li>
+        <li>Alpha: {{ colorOutput()!.alpha }}</li>
+      </ul>
+    }
+  `,
+})
+export class CustomOptionsColorPickerComponent {
+  protected pickerOptions = signal<IPickerCustomOptions>({
+    color: '#ff6b6b',
+    showAlpha: true,
+    showHex: true,
+    showRgb: true,
+    showHsl: false,
+    format: 'hex',
+  });
 
-```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';
-}
-```
+  protected colorOutput = signal<IOutputColorChangeMultipleType | null>(null);
 
-### IOutputColorChangeMultipleType
+  protected handlerColorChange(event: string): void {
+    event.stopPropagation?.();
+  }
 
-```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
+  protected handlerColorChangeMultiple(event: IOutputColorChangeMultipleType): void {
+    this.colorOutput.set(event);
+  }
 }
 ```
 
-## Ví dụ nâng cao
-
-### Với Custom Options
+### Tùy chỉnh kích thước bars — Picker nhỏ hơn
 
 ```typescript
-import { Component, signal } from '@angular/core';
-import { LibsUiComponentsColorPickerComponent, IPickerCustomOptions, IOutputColorChangeMultipleType } from '@libs-ui/components-color-picker';
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import {
+  IPickerCustomOptions,
+  LibsUiComponentsColorPickerComponent,
+} from '@libs-ui/components-color-picker';
 
 @Component({
+  selector: 'app-compact-color-picker',
   standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
   imports: [LibsUiComponentsColorPickerComponent],
   template: `
     <libs_ui-components-color_picker
-      [customOptions]="pickerOptions()"
-      (outColorChange)="onColorChange($event)"
-      (outColorChangeMultipleType)="onColorChangeMultiple($event)" />
+      [customOptions]="compactOptions()"
+      (outColorChange)="handlerColorChange($event)"
+    />
   `,
 })
-export class ExampleComponent {
-  readonly pickerOptions = signal<IPickerCustomOptions>({
-    color: '#ff6b6b',
+export class CompactColorPickerComponent {
+  protected compactOptions = signal<IPickerCustomOptions>({
+    slBarSize: [300, 150],
+    hueBarSize: [300, 16],
+    alphaBarSize: [300, 16],
     showAlpha: true,
     showHex: true,
     showRgb: true,
     showHsl: false,
-    format: 'hex',
+    color: '#3b82f6',
   });
 
-  onColorChange(color: string): void {
-    console.log('HEX:', color);
+  protected handlerColorChange(event: string): void {
+    event.stopPropagation?.();
   }
+}
+```
+
+### Emit màu ngay khi khởi tạo component
+
+```typescript
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { LibsUiComponentsColorPickerComponent } from '@libs-ui/components-color-picker';
 
-  onColorChangeMultiple(colors: IOutputColorChangeMultipleType): void {
-    console.log('RGB:', colors.rgb);
-    console.log('HSL:', colors.hsl);
-    console.log('Alpha:', colors.alpha);
+@Component({
+  selector: 'app-emit-on-init-color-picker',
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [LibsUiComponentsColorPickerComponent],
+  template: `
+    <libs_ui-components-color_picker
+      [noEmitEventColorWhenInitComponent]="false"
+      (outColorChange)="handlerColorChange($event)"
+    />
+  `,
+})
+export class EmitOnInitColorPickerComponent {
+  protected handlerColorChange(event: string): void {
+    event.stopPropagation?.();
+    // Sẽ được gọi ngay khi component khởi tạo
   }
 }
 ```
 
-### Custom Bar Sizes
+## @Input()
+
+| Input | Type | Default | Mô tả | Ví dụ |
+|---|---|---|---|---|
+| `[customOptions]` | `IPickerCustomOptions` | `undefined` | Tùy chỉnh toàn bộ options của color picker: kích thước bars, màu mặc định, format parse, hiển thị các nhóm input | `[customOptions]="{ color: '#ff0000', showAlpha: true }"` |
+| `[noEmitEventColorWhenInitComponent]` | `boolean` | `true` | Không emit event `outColorChange` và `outColorChangeMultipleType` khi component khởi tạo lần đầu. Set `false` để emit ngay khi init | `[noEmitEventColorWhenInitComponent]="false"` |
+
+## @Output()
+
+| Output | Type | Mô tả | Handler TS | Binding HTML |
+|---|---|---|---|---|
+| `(outColorChange)` | `string` | Emit màu đã chọn dưới dạng HEX string (có alpha nếu `showAlpha: true`). Ví dụ: `"#3b82f6"` hoặc `"#3b82f6ff"` | `handlerColorChange(event: string): void { event.stopPropagation?.(); this.color.set(event); }` | `(outColorChange)="handlerColorChange($event)"` |
+| `(outColorChangeMultipleType)` | `IOutputColorChangeMultipleType` | Emit màu đã chọn ở tất cả các định dạng cùng lúc: hex, rgb, rgba, hsl, hsla và giá trị alpha số | `handlerColorChangeMultiple(event: IOutputColorChangeMultipleType): void { event.stopPropagation?.(); this.colorOutput.set(event); }` | `(outColorChangeMultipleType)="handlerColorChangeMultiple($event)"` |
+
+## Types & Interfaces
 
 ```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
-});
+import {
+  IPickerCustomOptions,
+  IOutputColorChangeMultipleType,
+} from '@libs-ui/components-color-picker';
 ```
 
-## Important Notes
+### IPickerCustomOptions
 
-⚠️ **Canvas Rendering**: Component sử dụng HTML5 Canvas để render color picker, cần browser hỗ trợ Canvas API.
+Interface để tùy chỉnh giao diện và hành vi của color picker. Tất cả các field đều là optional — chỉ truyền những gì muốn override so với giá trị mặc định.
 
-⚠️ **Signal-based**: Component sử dụng Angular Signals để quản lý state, đảm bảo reactivity tốt.
+```typescript
+interface IPickerCustomOptions {
+  /** Kích thước vùng Saturation/Lightness [width, height]. Default: [420, 200] */
+  slBarSize?: Array<number>;
 
-⚠️ **Multiple Formats**: Hỗ trợ nhiều format output (RGB, RGBA, HSL, HSLA, HEX, HEX with alpha).
+  /** Kích thước thanh Hue [width, height]. Default: [420, 20] */
+  hueBarSize?: Array<number>;
 
-⚠️ **Custom Options**: Có thể customize kích thước bars, hiển thị/ẩn các input fields.
+  /** Kích thước thanh Alpha [width, height]. Default: [420, 20] */
+  alphaBarSize?: Array<number>;
 
-⚠️ **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.
+  /** Hiển thị nhóm input HSL (H, S, L). Default: false */
+  showHsl?: boolean;
 
-## Dependencies
+  /** Hiển thị nhóm input RGB (R, G, B). Default: true */
+  showRgb?: boolean;
 
-- `@angular/core` >= 18.0.0
-- `@libs-ui/components-inputs-input`
-- `@libs-ui/services-notification`
-- `@libs-ui/utils`
+  /** Hiển thị ô nhập HEX. Default: true */
+  showHex?: boolean;
 
-## Demo
+  /** Hiển thị thanh và ô nhập Alpha. Default: false */
+  showAlpha?: boolean;
+
+  /** Màu khởi tạo ban đầu — nhận HEX string, CSS color name, hoặc mảng [r, g, b] / [r, g, b, a]. Default: '#ff0000' */
+  color?: string | Array<number>;
 
-Xem demo tại: [http://localhost:4500/color-picker](http://localhost:4500/color-picker)
+  /**
+   * Format dùng để parse giá trị color input ban đầu khi gọi handlerColorChange nội bộ.
+   * - 'color': Tự động parse từ nhiều format (mặc định)
+   * - 'rgb' / 'rgba': Parse từ mảng [r, g, b] / [r, g, b, a]
+   * - 'hsl' / 'hsla': Parse từ mảng [h, s, l] / [h, s, l, a]
+   * - 'hex': Parse từ HEX string
+   * Default: 'color'
+   */
+  format?: 'rgb' | 'rgba' | 'hsl' | 'hsla' | 'hex' | 'color';
+}
+```
 
-## License
+### IOutputColorChangeMultipleType
+
+Interface của object được emit qua `outColorChangeMultipleType`. Chứa màu đã chọn ở mọi định dạng phổ biến.
+
+```typescript
+interface IOutputColorChangeMultipleType {
+  /** HEX string. Ví dụ: "#3b82f6" hoặc "#3b82f6ff" khi có alpha */
+  hex: string;
+
+  /** CSS rgb(). Ví dụ: "rgb(59,130,246)" */
+  rgb: string;
+
+  /** CSS rgba(). Ví dụ: "rgba(59,130,246,1)" */
+  rgba: string;
+
+  /** CSS hsl(). Ví dụ: "hsl(217,91,60)" */
+  hsl: string;
+
+  /** CSS hsla(). Ví dụ: "hsla(217,91,60,1)" */
+  hsla: string;
+
+  /** Giá trị alpha trong khoảng 0–1. Ví dụ: 0.75 */
+  alpha: number;
+}
+```
+
+## Lưu ý quan trọng
+
+⚠️ **Canvas API bắt buộc**: Component dùng HTML5 Canvas để render vùng màu và các thanh bar. Cần chạy trên môi trường browser hỗ trợ Canvas API (không dùng được trong SSR/Node context).
+
+⚠️ **Không emit khi init mặc định**: Mặc định `noEmitEventColorWhenInitComponent = true`, nghĩa là `outColorChange` và `outColorChangeMultipleType` sẽ không fired khi component mount lần đầu. Nếu cần nhận giá trị màu ngay khi hiển thị, truyền `[noEmitEventColorWhenInitComponent]="false"`.
+
+⚠️ **Alpha chỉ hoạt động khi bật**: Thanh alpha và ô nhập alpha chỉ render khi `showAlpha: true` trong `customOptions`. Khi `showAlpha` là `false` (mặc định), giá trị alpha luôn là `1` và HEX output không kèm alpha.
+
+⚠️ **HEX output có alpha khi showAlpha bật**: Khi `showAlpha: true`, `outColorChange` emit HEX 8 ký tự dạng `#rrggbbaa` thay vì `#rrggbb` thông thường.
+
+⚠️ **customOptions không reactive sau init**: `customOptions` được đọc một lần trong `ngOnInit`. Thay đổi object sau khi component đã mount sẽ không cập nhật giao diện picker. Nếu cần thay đổi dynamic, hãy destroy và tạo lại component.
+
+## Demo
+
+```bash
+npx nx serve core-ui
+```
 
-MIT
+Truy cập: http://localhost:4500/components/color-picker

package/color-picker.component.d.ts

@@ -13,7 +13,7 @@ export declare class LibsUiComponentsColorPickerComponent implements OnInit, Aft
     protected g: import("@angular/core").WritableSignal<number>;
     protected b: import("@angular/core").WritableSignal<number>;
     protected a: import("@angular/core").WritableSignal<number>;
-    private slBarHelper;
+    private readonly slBarHelper;
     readonly customOptions: import("@angular/core").InputSignal<IPickerCustomOptions | undefined>;
     readonly noEmitEventColorWhenInitComponent: import("@angular/core").InputSignalWithTransform<boolean, boolean | undefined>;
     readonly outColorChange: import("@angular/core").OutputEmitterRef<string>;
@@ -25,8 +25,8 @@ export declare class LibsUiComponentsColorPickerComponent implements OnInit, Aft
     private readonly alphaEl;
     private readonly alphaPointerEl;
     private readonly previewEl;
-    private destroyRef;
-    private notificationService;
+    private readonly destroyRef;
+    private readonly notificationService;
     constructor();
     ngOnInit(): void;
     ngAfterViewInit(): void;