npm package: @libs-ui/pipes-format-text-first-letter-to-uppercase
Description: Pipe Angular viết hoa chữ cái **đầu tiên của chuỗi** (sentence case), hỗ trợ nhiều tùy chọn format text.
Latest version: 0.2.356-23

# First Letter To UpperCase Pipe

Pipe Angular viết hoa chữ cái **đầu tiên của chuỗi** (sentence case), hỗ trợ nhiều tùy chọn format text.

## Cài đặt

```bash
npm install @libs-ui/pipes-format-text-first-letter-to-uppercase
```

## Import

```typescript
import { LibsUiPipesFormatTextFirstLetterToUpperCasePipe } from '@libs-ui/pipes-format-text-first-letter-to-uppercase';
```

## Sử dụng

### Trong Template

```html
<!-- Cơ bản -->
<p>{{ 'hello world' | LibsUiPipesFormatTextFirstLetterToUpperCasePipe }}</p>
<!-- Output: Hello world -->

<!-- Sentence case (lowercase toàn bộ + hoa chữ đầu) -->
<p>{{ 'HELLO WORLD' | LibsUiPipesFormatTextFirstLetterToUpperCasePipe:{lowercaseOtherCharacter: true} }}</p>
<!-- Output: Hello world -->

<!-- Xóa emoji -->
<p>{{ '👋 hello world' | LibsUiPipesFormatTextFirstLetterToUpperCasePipe:{removeEmoji: true, trim: true} }}</p>
<!-- Output: Hello world -->
```

### Dùng trong TypeScript

Pipe là thin wrapper của hàm `firstLetterToUpperCase` trong `@libs-ui/utils`. Khi cần gọi trong TypeScript, import và dùng thẳng hàm đó — **không cần inject pipe**:

```typescript
import { firstLetterToUpperCase } from '@libs-ui/utils';

// Cơ bản
const result = firstLetterToUpperCase('hello world');
// Output: 'Hello world'

// Với options (sentence case):
const sentenceCase = firstLetterToUpperCase('HELLO WORLD', {
  lowercaseOtherCharacter: true,
  trim: true,
});
// Output: 'Hello world'
```

## API

### Syntax

```
value | LibsUiPipesFormatTextFirstLetterToUpperCasePipe : options
```

### Parameters

| Parameter                         | Type      | Default  | Description                                          |
| --------------------------------- | --------- | -------- | ---------------------------------------------------- |
| `value`                           | `string`  | required | Chuỗi cần format                                     |
| `options.uppercaseOtherCharacter` | `boolean` | `false`  | Viết hoa tất cả ký tự                                |
| `options.lowercaseOtherCharacter` | `boolean` | `false`  | Viết thường các ký tự còn lại (không phải đầu chuỗi) |
| `options.trim`                    | `boolean` | `false`  | Loại bỏ khoảng trắng đầu/cuối                        |
| `options.removeMultipleSpace`     | `boolean` | `false`  | Thay thế nhiều khoảng trắng liên tiếp bằng một       |
| `options.removeEmoji`             | `boolean` | `false`  | Loại bỏ emoji khỏi chuỗi                             |
| `options.removeUnicode`           | `boolean` | `false`  | Loại bỏ dấu unicode                                  |

### ITextFormatOptions Interface

```typescript
interface ITextFormatOptions {
  uppercaseOtherCharacter?: boolean; // Viết hoa tất cả
  lowercaseOtherCharacter?: boolean; // Viết thường các ký tự còn lại
  trim?: boolean; // Trim khoảng trắng
  removeMultipleSpace?: boolean; // Xóa khoảng trắng thừa
  removeEmoji?: boolean; // Xóa emoji
  removeUnicode?: boolean; // Xóa dấu unicode
}
```

## Sự khác biệt với Capitalize Pipe

| Pipe                     | Input           | Output          |
| ------------------------ | --------------- | --------------- |
| `firstLetterToUpperCase` | `'hello world'` | `'Hello world'` |
| `capitalize`             | `'hello world'` | `'Hello World'` |

- **FirstLetterToUpperCase**: Chỉ viết hoa ký tự **đầu tiên** của toàn bộ chuỗi (sentence case)
- **Capitalize**: Viết hoa ký tự **đầu mỗi từ** (title case)

## Hidden Logic

- **Thứ tự xử lý options**: `uppercaseOtherCharacter` → `lowercaseOtherCharacter` → `removeMultipleSpace` → `removeEmoji` → `removeUnicode` → `trim` → viết hoa ký tự đầu tiên
- **Guard clause**: Nếu chuỗi đầu vào là `null`, `undefined`, hoặc rỗng, pipe trả về nguyên giá trị ban đầu (không throw error)
- **Position 0**: Sử dụng `uppercaseByPosition(text, 0)` — viết hoa ký tự tại vị trí 0

## Demo

Xem demo tại: `pipes/format-text/first-letter-to-upperCase`