npm package: @libs-ui/components-inputs-valid
Description: `@libs-ui/components-inputs-valid` là một component cấp cao (high-level component) kết hợp giữa nhãn (label), ô nhập liệu (input) và cơ chế kiểm tra tính hợp lệ (validation). Nó giúp đơn giản hóa việc xây dựng các biểu mẫu (forms) bằng cách tự động quản l
Latest version: 0.2.356-23

# Valid Input Component

`@libs-ui/components-inputs-valid` là một component cấp cao (high-level component) kết hợp giữa nhãn (label), ô nhập liệu (input) và cơ chế kiểm tra tính hợp lệ (validation). Nó giúp đơn giản hóa việc xây dựng các biểu mẫu (forms) bằng cách tự động quản lý trạng thái lỗi và hiển thị thông báo.

## Tính năng nổi bật

- 🔗 **Auto Binding**: Liên kết trực tiếp với một trường dữ liệu trong đối tượng thông qua `fieldNameBind`.
- 🏷️ **Integrated Label**: Tích hợp sẵn `LibsUiComponentsLabelComponent` với đầy đủ tính năng (required mark, description, popover, buttons).
- ✅ **Comprehensive Validation**: Hỗ trợ nhiều loại kiểm tra:
  - `validRequired`: Bắt buộc nhập.
  - `validMinLength` / `validMaxLength`: Độ dài chuỗi.
  - `validMinValue` / `validMaxValue`: Giá trị số.
  - `validPattern`: Kiểm tra theo biểu thức chính quy (Regex).
  - `functionValid`: Hàm kiểm tra tùy chỉnh (hỗ trợ Async).
- 🧩 **Flexible Layout**:
  - Hỗ trợ đơn vị (units) bên trái và bên phải.
  - Chế độ chọn nhanh (Radio/Checkbox) tích hợp.
  - Hỗ trợ căn chỉnh `baseline` cho các bố cục phức tạp.
- ⏱️ **Debounced Validation**: Khả năng trì hoãn việc kiểm tra (`debounceTimeValidate`) để tối ưu hiệu năng.
- 🛠️ **Full Control**: Cung cấp các hàm điều khiển như `checkIsValid()`, `setMessageError()`, `focus()`, `blur()`...

## Cài đặt

Sử dụng npm hoặc yarn để cài đặt:

```bash
npm install @libs-ui/components-inputs-valid
```

## Cách sử dụng

### Import Module

```typescript
import { LibsUiComponentsInputsValidComponent } from '@libs-ui/components-inputs-valid';

@Component({
  standalone: true,
  imports: [LibsUiComponentsInputsValidComponent],
  // ...
})
export class YourComponent {}
```

### Ví dụ cơ bản (Bắt buộc nhập và Kiểm tra độ dài)

```html
<libs_ui-components-inputs-input-valid
  [(item)]="userData"
  [fieldNameBind]="'username'"
  [labelConfig]="{ labelLeft: 'Tên đăng nhập', required: true }"
  [validRequired]="{ isRequired: true, message: 'Vui lòng nhập tên đăng nhập' }"
  [validMinLength]="{ length: 5, message: 'Tối thiểu 5 ký tự' }"></libs_ui-components-inputs-input-valid>
```

### Kiểm tra Regex và Hàm tùy chỉnh

```html
<libs_ui-components-inputs-input-valid
  [(item)]="userData"
  [fieldNameBind]="'email'"
  [validPattern]="[{ pattern: /^[\\w-\\.]+@([\\w-]+\\.)+[\\w-]{2,4}$/, message: 'Email không hợp lệ' }]"
  [functionValid]="customValidator"></libs_ui-components-inputs-input-valid>
```

## API Reference

### Inputs

| Thuộc tính                       | Kiểu dữ liệu                | Mặc định    | Mô tả                                                           |
| :------------------------------- | :-------------------------- | :---------- | :-------------------------------------------------------------- |
| `acceptNegativeValue`            | `boolean`                   | `undefined` | Cho phép nhập số âm.                                            |
| `autoAddZeroLessThan10InTypeInt` | `boolean`                   | `undefined` | Tự động thêm số 0 nếu giá trị < 10 (cho kiểu int).              |
| `autoRemoveEmoji`                | `boolean`                   | `undefined` | Tự động loại bỏ emoji khi nhập.                                 |
| `backgroundNone`                 | `boolean`                   | `undefined` | Loại bỏ màu nền input.                                          |
| `borderError`                    | `boolean`                   | `undefined` | Luôn hiển thị border đỏ bất kể trạng thái lỗi.                                  |
| `classContainerBottomInput`      | `string`                    | `undefined` | Class CSS cho vùng dưới input.                                  |
| `classContainerInput`            | `string`                    | `undefined` | Class CSS cho container bao quanh input.                        |
| `classInclude`                   | `string`                    | `undefined` | Class CSS tổng thể cho component.                               |
| `classIncludeInput`              | `string`                    | `undefined` | Class CSS cho thẻ input/textarea.                               |
| `classMessageErrorInclude`       | `string`                    | `undefined` | Class CSS cho thông báo lỗi.                                    |
| `configUnitLeft`                 | `IInputValidUnitConfig`     | `{...}`     | Cấu hình cho đơn vị bên trái.                                   |
| `configUnitRight`                | `IInputValidUnitConfig`     | `{...}`     | Cấu hình cho đơn vị bên phải.                                   |
| `dataType`                       | `TYPE_DATA_TYPE_INPUT`      | `'string'`  | Loại dữ liệu (string, number, int, bigint...).                  |
| `debounceTimeValidate`           | `number`                    | `0`         | Thời gian chờ trước khi thực hiện validate (ms).                |
| `defaultHeight`                  | `number`                    | `undefined` | Chiều cao mặc định của input.                                   |
| `disable`                        | `boolean`                   | `undefined` | Vô hiệu hóa input.                                              |
| `disableComponentSelectItem`     | `boolean`                   | `undefined` | Vô hiệu hóa checkbox/radio chọn item.                           |
| `emitEmptyInDataTypeNumber`      | `boolean`                   | `undefined` | Emit giá trị rỗng khi kiểu dữ liệu là number.                   |
| `fieldNameBind`                  | `string`                    | `required`  | Tên trường trong `item` để liên kết giá trị.                    |
| `fixedFloat`                     | `number`                    | `undefined` | Số lượng chữ số thập phân cố định.                              |
| `focusTimeOut`                   | `number`                    | `undefined` | Thời gian chờ focus.                                            |
| `functionValid`                  | `TYPE_FUNCTION_INPUT_VALID` | `undefined` | Hàm kiểm tra tùy chỉnh (trả về Promise hoặc IMessageTranslate). |
| `iconLeftClass`                  | `string`                    | `undefined` | Class cho icon bên trái input.                                  |
| `iconRightClass`                 | `string`                    | `undefined` | Class cho icon bên phải input.                                  |
| `ignoreBlockInputMaxValue`       | `boolean`                   | `undefined` | Không chặn nhập khi giá trị vượt quá max value.                 |
| `ignoreContentLeft`              | `boolean`                   | `undefined` | Ẩn nội dung bên trái (label/units).                             |
| `ignoreContentRight`             | `boolean`                   | `undefined` | Ẩn nội dung bên phải (units).                                   |
| `ignoreShowError`                | `boolean`                   | `undefined` | ⚠️ `@deprecated` — Sử dụng `ignoreShowMessageError` thay thế.                |
| `ignoreShowMessageError`         | `boolean`                   | `undefined` | Ẩn message lỗi nhưng vẫn hiển thị border đỏ khi có lỗi.                 |
| `ignoreStopPropagationEvent`     | `boolean`                   | `undefined` | Ngăn chặn event propagation.                                    |
| `ignoreUnitRightClassReadOnly`   | `boolean`                   | `undefined` | Không thêm class readonly cho unit bên phải.                    |
| `ignoreWidthInput100`            | `boolean`                   | `undefined` | Không set width 100% cho input.                                 |
| `isBaselineStyle`                | `boolean`                   | `undefined` | Căn align-items-baseline — dùng khi cần căn input thẳng hàng với các phần tử khác dù có validate. |
| `item`                           | `Record<string, any>`       | `{}`        | Đối tượng chứa dữ liệu cần bind (model).                        |
| `keepPlaceholderOnly`            | `boolean`                   | `undefined` | Chỉ hiển thị placeholder.                                       |
| `keySelectedUnitLeft`            | `any`                       | `undefined` | Key của unit bên trái đang được chọn.                           |
| `keySelectedUnitRight`           | `any`                       | `undefined` | Key của unit bên phải đang được chọn.                           |
| `labelConfig`                    | `ILabel`                    | `undefined` | Cấu hình cho nhãn phía trên input.                              |
| `maxHeightTextArea`              | `number`                    | `undefined` | Chiều cao tối đa cho textarea.                                  |
| `maxLength`                      | `number`                    | `undefined` | Độ dài tối đa của chuỗi.                                        |
| `maxLengthNumberCount`           | `number`                    | `undefined` | Độ dài tối đa của số lượng (count).                             |
| `maxValueNumber`                 | `number`                    | `undefined` | Giá trị số tối đa.                                              |
| `minHeightTextArea`              | `number`                    | `undefined` | Chiều cao tối thiểu cho textarea.                               |
| `minValueNumber`                 | `number`                    | `undefined` | Giá trị số tối thiểu.                                           |
| `modeInput`                      | `TYPE_MODE_INPUT`           | `undefined` | Chế độ nhập (password, text...).                                |
| `noBorder`                       | `boolean`                   | `undefined` | Ẩn viền input.                                                  |
| `onlyAcceptNegativeValue`        | `boolean`                   | `undefined` | Chỉ chấp nhận số âm.                                            |
| `paddingRightCustomSpecific`     | `number`                    | `undefined` | Custom padding-right khi count không tự tính được (#52185).                     |
| `placeholder`                    | `string`                    | `undefined` | Placeholder cho input.                                          |
| `popoverContentIconLeft`         | `string`                    | `undefined` | Nội dung popover cho icon trái.                                 |
| `popoverContentIconRight`        | `string`                    | `undefined` | Nội dung popover cho icon phải.                                 |
| `positionMessageErrorStartInput` | `boolean`                   | `undefined` | Hiển thị message lỗi bắt đầu từ vị trí ô input thay vì từ template trái.    |
| `readonly`                       | `boolean`                   | `undefined` | Chế độ chỉ đọc.                                                 |
| `resetAutoCompletePassword`      | `boolean`                   | `undefined` | Reset autocomplete password.                                    |
| `resize`                         | `TYPE_INPUT_RESIZE_MODE`    | `undefined` | Chế độ resize cho textarea.                                     |
| `showCount`                      | `boolean`                   | `undefined` | Hiển thị bộ đếm ký tự.                                          |
| `tagInput`                       | `TYPE_TAG_INPUT`            | `undefined` | Loại thẻ input (input/textarea).                                |
| `templateLeftBottomInput`        | `TemplateRef`               | `undefined` | Template hiển thị góc dưới trái input.                          |
| `templateRightBottomInput`       | `TemplateRef`               | `undefined` | Template hiển thị góc dưới phải input.                          |
| `textAreaEnterNotNewLine`        | `boolean`                   | `undefined` | Phím Enter không xuống dòng (trong textarea).                   |
| `typeComponentSelectItem`        | `'radio' \| 'checkbox'`     | `undefined` | Hiển thị thêm radio hoặc checkbox bên trái.                     |
| `typeInput`                      | `TYPE_INPUT`                | `undefined` | Kiểu input (text, number, ...).                                 |
| `unitsLeft`                      | `any[]`                     | `[]`        | Danh sách đơn vị bên trái.                                      |
| `unitsRight`                     | `any[]`                     | `[]`        | Danh sách đơn vị bên phải.                                      |
| `useColorModeExist`              | `boolean`                   | `undefined` | Sử dụng màu sắc theo chế độ hiện tại.                           |
| `validMaxValue`                  | `IMessageTranslate`         | `undefined` | Cấu hình kiểm tra giá trị tối đa.                               |
| `validMaxLength`                 | `IMessageTranslate`         | `undefined` | Cấu hình kiểm tra độ dài tối đa.                                |
| `validMinLength`                 | `IValidLength`              | `undefined` | Cấu hình kiểm tra độ dài tối thiểu.                             |
| `validMinValue`                  | `IMessageTranslate`         | `undefined` | Cấu hình kiểm tra giá trị tối thiểu.                            |
| `validPattern`                   | `Array<IValidPattern>`      | `undefined` | Danh sách các regex để kiểm tra.                                |
| `validRequired`                  | `IValidRequired`            | `undefined` | Cấu hình kiểm tra bắt buộc nhập.                                |
| `valueComponentSelectItem`       | `boolean`                   | `undefined` | Giá trị của checkbox/radio chọn item.                           |
| `valuePatternShowError`          | `boolean`                   | `false`     | Hiển thị lỗi khi pattern match (true) hoặc unmatch (false).     |
| `valueUpDownNumber`              | `number`                    | `undefined` | Bước nhảy cho nút up/down number.                               |
| `zIndexPopoverContent`           | `number`                    | `undefined` | Z-index cho popover content.                                    |

### Outputs

| Sự kiện                        | Kiểu dữ liệu                      | Mô tả                                                  |
| :----------------------------- | :-------------------------------- | :----------------------------------------------------- |
| `outChangeValueByButtonUpDown` | `void`                            | Phát ra khi giá trị thay đổi bởi nút tăng/giảm.        |
| `outClickButtonLabel`          | `IButton`                         | Phát ra khi click vào button trên label.               |
| `outEnterInputEvent`           | `IEvent`                          | Phát ra khi nhấn phím Enter trong ô nhập liệu.         |
| `outFocusAndBlur`              | `IFocusAndBlurEvent`              | Phát ra khi focus hoặc blur input.                     |
| `outFunctionsControl`          | `IInputValidFunctionControlEvent` | Cung cấp các phương thức điều khiển component.         |
| `outHeightAreaChange`          | `{ isChange: boolean }`           | Phát ra khi chiều cao textarea thay đổi (auto resize). |
| `outIconLeft`                  | `string`                          | Phát ra khi click icon trái.                           |
| `outIconRight`                 | `string`                          | Phát ra khi click icon phải.                           |
| `outLabelRightClick`           | `boolean`                         | Phát ra khi click vào label bên phải.                  |
| `outSelect`                    | `boolean`                         | Sự kiện khi click vào checkbox/radio tích hợp.         |
| `outSwitchEventLabel`          | `ISwitchEvent`                    | Phát ra khi thay đổi switch trên label.                |
| `outValueChange`               | `any`                             | Phát ra giá trị mới sau khi đã qua debounce validate.  |

### Methods (via outFunctionsControl)

- `checkIsValid()`: Thực hiện kiểm tra toàn bộ điều kiện và trả về kết quả (Boolean).
- `setMessageError(message)`: Cài đặt thông báo lỗi thủ công.
- `focus()` / `blur()`: Điều khiển tiêu điểm của ô nhập liệu.
- `resetValue()`: Xóa giá trị hiện tại.

## Types & Interfaces

### IValidRequired

Giao diện cho cấu hình kiểm tra bắt buộc nhập.

```typescript
export interface IValidRequired extends IMessageTranslate {
  isRequired: boolean;
}
```

### IValidPattern

Giao diện cho cấu hình kiểm tra theo Regex.

```typescript
export interface IValidPattern extends IMessageTranslate {
  pattern: any; // RegExp object
  valuePatternShowError?: boolean; // Mặc định false (báo lỗi khi test() trả về false)
}
```

### IValidLength

Giao diện cho cấu hình kiểm tra độ dài.

```typescript
export interface IValidLength extends IMessageTranslate {
  length: number;
}
```

### IInputValidFunctionControlEvent

Giao diện điều khiển component, kế thừa từ `IInputFunctionControlEvent`.

```typescript
export interface IInputValidFunctionControlEvent extends IInputFunctionControlEvent {
  checkIsValid: () => Promise<boolean>;
  setMessageError: (message: string) => Promise<void>;
  currentStateIsValid?: () => Promise<boolean>;
}
```

### TYPE_FUNCTION_INPUT_VALID

Kiểu cho hàm validate tùy chỉnh.

```typescript
export type TYPE_FUNCTION_INPUT_VALID = (value: any) => Promise<IMessageTranslate>;
```

## Tech Stack

- **Core**: Angular 18+, Signals, RxJS
- **Dependencies**: `@libs-ui/components-inputs-input`, `@libs-ui/components-label`.

## License

MIT