@libs-ui/services-format-date 0.2.356-9 → 0.2.357-0

package/README.md

@@ -1,15 +1,28 @@
-# Format Date Service
+# @libs-ui/services-format-date
 
-Service định dạng ngày giờ dựa trên dayjs. Thin wrapper của `formatDate()` từ `@libs-ui/utils`. Hỗ trợ nhiều kiểu input, định dạng tùy chỉnh, đa ngôn ngữ (vi/en) và format aliases locale-aware.
+> Service Angular định dạng ngày giờ linh hoạt, hỗ trợ nhiều kiểu input, format aliases locale-aware và đa ngôn ngữ vi/en.
+
+## Giới thiệu
+
+`FormatDateService` là một thin wrapper của hàm `formatDate()` từ `@libs-ui/utils`, được đóng gói thành Angular service để dễ dàng inject qua DI và sử dụng trực tiếp trong template. Service hỗ trợ nhiều kiểu đầu vào (Unix timestamp giây, ISO string, dayjs object), định dạng tùy chỉnh theo chuẩn dayjs, format aliases ngắn gọn tự động chọn format phù hợp theo ngôn ngữ vi/en, cùng cơ chế override toàn cục cho các project cần custom logic.
 
 ## Tính năng
 
-- ✅ Input types đa dạng: Unix timestamp (giây), ISO string, dayjs object, Date
+- ✅ Input types đa dạng: Unix timestamp (giây), ISO string, dayjs object
 - ✅ Format aliases locale-aware: `dmy`, `dmy hm`, `dmy hms`, `my`, `dm`... tự chọn format theo ngôn ngữ
-- ✅ Đa ngôn ngữ: vi/en — tiếng Việt ngày trước tháng, tiếng Anh tháng trước ngày
-- ✅ Tự lấy ngôn ngữ từ `UtilsCache.getLang()` nếu không truyền
-- ✅ null/undefined → trả về `''` (không throw error)
-- ✅ Custom format override hook toàn cục (`updateFunctionFormatDate`)
+- ✅ Đa ngôn ngữ: `vi`/`en` — tiếng Việt ngày trước tháng, tiếng Anh tháng trước ngày
+- ✅ Tự động lấy ngôn ngữ từ `UtilsCache.getLang()` nếu không truyền `lang`
+- ✅ `null`/`undefined` → trả về `''` (không throw error)
+- ✅ Custom format override toàn cục qua `updateFunctionFormatDate`
+- ✅ Múi giờ chuẩn hóa qua `getDayjs()` (mặc định `Asia/Ho_Chi_Minh`)
+- ✅ `providedIn: 'root'` — không cần khai báo providers thủ công
+
+## Khi nào sử dụng
+
+- Cần inject service để dùng `transform()` trực tiếp trong template Angular (ví dụ: trong computed, `@switch`, binding).
+- Muốn mock service trong unit test — dễ mock hơn hàm utils standalone.
+- Cần format ngày giờ theo ngôn ngữ hiện tại của ứng dụng mà không muốn tự quản lý lang.
+- Cần format date trong TypeScript class thông qua DI (nếu không cần DI, dùng thẳng `formatDate()` từ `@libs-ui/utils`).
 
 ## Cài đặt
 
@@ -23,9 +36,9 @@ npm install @libs-ui/services-format-date
 import { FormatDateService } from '@libs-ui/services-format-date';
 ```
 
-## Cách sử dụng
+## Ví dụ sử dụng
 
-### Trong Component
+### Ví dụ 1 — Cơ bản: Unix timestamp với format mặc định
 
 ```typescript
 import { Component, inject } from '@angular/core';
@@ -33,69 +46,194 @@ import { FormatDateService } from '@libs-ui/services-format-date';
 
 @Component({
   standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
   template: `
     <p>{{ formatDateService.transform(timestamp) }}</p>
-    <p>{{ formatDateService.transform(date, 'dmy hm', 'vi') }}</p>
+    <!-- Output: "2024/05/20 17:30" -->
+
+    <p>{{ formatDateService.transform(timestamp, 'DD/MM/YYYY') }}</p>
+    <!-- Output: "20/05/2024" -->
   `,
 })
 export class ExampleComponent {
   readonly formatDateService = inject(FormatDateService);
 
   timestamp = 1716222600; // Unix timestamp (giây)
-  date = '2024-05-20T10:30:00'; // ISO string
 }
 ```
 
-### Dùng trong TypeScript (khuyến nghị)
+### Ví dụ 2 — Format aliases locale-aware (vi/en)
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { FormatDateService } from '@libs-ui/services-format-date';
+
+@Component({
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <!-- lang='vi': "20 Thg 5, 2024 10:30" -->
+    <p>{{ formatDateService.transform(dateStr, 'dmy hm', 'vi') }}</p>
+
+    <!-- lang='en': "May 20, 2024 10:30" -->
+    <p>{{ formatDateService.transform(dateStr, 'dmy hm', 'en') }}</p>
+
+    <!-- Chỉ ngày tháng năm (vi): "20 Thg 5, 2024" -->
+    <p>{{ formatDateService.transform(dateStr, 'dmy', 'vi') }}</p>
+
+    <!-- Chỉ tháng năm (vi): "Thg 5, 2024" -->
+    <p>{{ formatDateService.transform(dateStr, 'my', 'vi') }}</p>
+  `,
+})
+export class LocaleExampleComponent {
+  readonly formatDateService = inject(FormatDateService);
+
+  dateStr = '2024-05-20T10:30:00'; // ISO string
+}
+```
+
+### Ví dụ 3 — Trong TypeScript class (computed, xử lý logic)
+
+```typescript
+import { Component, inject, computed, signal } from '@angular/core';
+import { FormatDateService } from '@libs-ui/services-format-date';
+
+@Component({
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `<p>{{ displayDate() }}</p>`,
+})
+export class ComputedExampleComponent {
+  private readonly formatDateService = inject(FormatDateService);
+
+  private rawTimestamp = signal<number>(1716222600);
+
+  protected displayDate = computed(() =>
+    this.formatDateService.transform(this.rawTimestamp(), 'dmy hm', 'vi')
+  );
+}
+```
+
+### Ví dụ 4 — ISO string với format giây
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { FormatDateService } from '@libs-ui/services-format-date';
+
+@Component({
+  standalone: true,
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `
+    <!-- Output: "20/05/2024 10:30:00" -->
+    <p>{{ formatDateService.transform(isoDate, 'DD/MM/YYYY HH:mm:ss') }}</p>
 
-Service là thin wrapper của `formatDate` trong `@libs-ui/utils`. Khi cần dùng trong TypeScript, import thẳng hàm đó — **không cần inject service**:
+    <!-- null/undefined → '' (không crash) -->
+    <p>{{ formatDateService.transform(null) }}</p>
+  `,
+})
+export class IsoExampleComponent {
+  readonly formatDateService = inject(FormatDateService);
+
+  isoDate = '2024-05-20T10:30:00';
+}
+```
+
+### Ví dụ 5 — Không dùng DI: `formatDate()` từ `@libs-ui/utils` (khuyến nghị cho TypeScript thuần)
 
 ```typescript
 import { formatDate } from '@libs-ui/utils';
 
-// Không cần inject service
+// Không inject service — dùng thẳng hàm utils
 const result = formatDate(1716222600, 'YYYY/MM/DD HH:mm');
 // Output: '2024/05/20 17:30'
 
-const viDate = formatDate('2024-05-20', 'dmy hm', 'vi');
-// Output: '20 Th5, 2024 00:00'
+const viDate = formatDate('2024-05-20T10:30:00', 'dmy hm', 'vi');
+// Output: '20 Thg 5, 2024 10:30'
 
-// Trong component class:
-class ExampleComponent {
-  formattedDate = formatDate(this.rawDate, 'DD/MM/YYYY');
-}
+const enDate = formatDate('2024-05-20T10:30:00', 'dmy hm', 'en');
+// Output: 'May 20, 2024 10:30'
 ```
 
-## API
+## Methods (Service)
+
+| Method | Signature | Mô tả |
+|---|---|---|
+| `transform` | `transform(time, format?, lang?): string` | Định dạng giá trị thời gian thành chuỗi. Trả về `''` nếu `time` là `null`/`undefined`. |
 
-### `transform(time, format?, lang?)`
+### Chi tiết tham số `transform()`
 
-| Parameter | Type                                                   | Default                | Mô tả                                    |
-| --------- | ------------------------------------------------------ | ---------------------- | ---------------------------------------- |
-| `time`    | `string \| number \| dayjs.Dayjs \| undefined \| null` | -                      | Giá trị thời gian. null/undefined → `''` |
-| `format`  | `string`                                               | `'YYYY/MM/DD HH:mm'`   | Format dayjs hoặc alias ngắn gọn         |
-| `lang`    | `string \| undefined`                                  | `UtilsCache.getLang()` | Ngôn ngữ: `'vi'` hoặc `'en'`             |
+| Tham số | Type | Default | Mô tả |
+|---|---|---|---|
+| `time` | `string \| number \| dayjs.Dayjs \| undefined \| null` | — | Giá trị thời gian cần format. `null`/`undefined` → trả về `''`. |
+| `format` | `string` | `'YYYY/MM/DD HH:mm'` | Format dayjs chuẩn hoặc alias ngắn gọn (xem bảng Format Aliases). |
+| `lang` | `string \| undefined` | `UtilsCache.getLang()` | Ngôn ngữ: `'vi'` hoặc `'en'`. Không truyền → tự lấy từ cache toàn cục. |
 
-**Returns:** `string` — chuỗi đã format, hoặc `''` nếu input là null/undefined.
+**Returns:** `string` — chuỗi đã format, hoặc `''` nếu input là `null`/`undefined`.
 
 ## Format Aliases (locale-aware)
 
-| Alias      | Format vi                  | Format en                  | Ghi chú                 |
-| ---------- | -------------------------- | -------------------------- | ----------------------- |
-| `dmy hm`   | `D MMM, YYYY HH:mm`        | `MMM D, YYYY HH:mm`        | Ngày tháng năm giờ phút |
-| `dmy`      | `D MMM, YYYY`              | `MMM D, YYYY`              | Ngày tháng năm          |
-| `dm`       | `D MMM`                    | `MMM D`                    | Ngày tháng              |
-| `my`       | `MMM, YYYY`                | `MMM YYYY`                 | Tháng năm               |
-| `dmy hms`  | `D MMM, YYYY HH:mm:ss`     | `MMM D, YYYY HH:mm:ss`     | Có giây                 |
-| `dmy hmsS` | `D MMM, YYYY HH:mm:ss:SSS` | `MMM D, YYYY HH:mm:ss:SSS` | Có millisecond          |
-| `HH:mm`    | `HH:mm`                    | `HH:mm`                    | 24h format              |
-| `HH:mm A`  | `HH:mm A`                  | `HH:mm A`                  | 12h AM/PM               |
+Các alias dưới đây tự động chọn format phù hợp theo ngôn ngữ (`lang`). Format string trực tiếp (như `DD/MM/YYYY`) không phụ thuộc ngôn ngữ.
 
-Format string trực tiếp (như `DD/MM/YYYY`, `YYYY-MM-DD`...) cũng được hỗ trợ — không locale-aware.
+| Alias | Format `vi` | Format `en` | Ghi chú |
+|---|---|---|---|
+| `dmy hm` | `D MMM, YYYY HH:mm` | `MMM D, YYYY HH:mm` | Ngày tháng năm giờ phút |
+| `dmy` | `D MMM, YYYY` | `MMM D, YYYY` | Ngày tháng năm |
+| `dm` | `D MMM` | `MMM D` | Ngày tháng |
+| `my` | `MMM, YYYY` | `MMM YYYY` | Tháng năm |
+| `dmy hms` | `D MMM, YYYY HH:mm:ss` | `MMM D, YYYY HH:mm:ss` | Có giây |
+| `dmy hmsS` | `D MMM, YYYY HH:mm:ss:SSS` | `MMM D, YYYY HH:mm:ss:SSS` | Có millisecond |
+| `HH:mm` | `HH:mm` | `HH:mm` | 24h format |
+| `HH:mm A` | `HH:mm A` | `HH:mm A` | 12h AM/PM |
+
+**Các format string tương đương được map tự động:**
+
+| Format string truyền vào | Map sang alias |
+|---|---|
+| `DD/MM/YYYY`, `YYYY-MM-DD`, `dd/MM/yyyy` | `dmy` |
+| `MM-DD`, `dd/MM`, `dd/mm` | `dm` |
+| `M/YYYY`, `YYYY-MM`, `MM/yyyy` | `my` |
+| `YYYY/MM/DD hh:mm:ss`, `dd/mm/yyyy hh:mm:ss` | `dmy hms` |
+| Bất kỳ format khác không thuộc danh sách trên | Mặc định map sang `dmy hm` |
+
+## Types & Interfaces
+
+```typescript
+import { TYPE_FUNCTION_FORMAT_DATE } from '@libs-ui/utils';
+
+// Type của hàm custom override (dùng với updateFunctionFormatDate)
+// type TYPE_FUNCTION_FORMAT_DATE = (time: dayjs.ConfigType, formatOutput: string, lang?: string) => string;
+```
+
+## Custom Override toàn cục
+
+Dùng `updateFunctionFormatDate` từ `@libs-ui/utils` để override toàn bộ logic format — chạy một lần khi app khởi động:
+
+```typescript
+import { updateFunctionFormatDate } from '@libs-ui/utils';
+
+// Trong AppComponent hoặc app initializer:
+updateFunctionFormatDate((time, format, lang) => {
+  // Custom format logic của project
+  return myCustomFormatter(time, format, lang);
+});
+```
 
 ## Lưu ý quan trọng
 
-- **Inject service hay dùng thẳng utils?** Nếu chỉ cần trong TypeScript class, dùng thẳng `formatDate()` từ `@libs-ui/utils` — không inject service. Inject service khi cần DI (mock test) hoặc dùng trong template qua service reference.
-- **lang** không truyền → tự lấy từ `UtilsCache.getLang()`. Đảm bảo set ngôn ngữ global trước khi dùng.
-- **Unix timestamp** là số nguyên **giây** (không phải milliseconds). `Date.now()` trả về ms → chia 1000.
-- **Format aliases** chỉ có tác dụng locale-aware khi dùng với `lang='vi'` hoặc `lang='en'`. Format string trực tiếp không phụ thuộc ngôn ngữ.
+⚠️ **Inject service hay dùng thẳng utils?**: Nếu chỉ cần format date trong TypeScript (không trong template hoặc không cần DI/mock), dùng thẳng `formatDate()` từ `@libs-ui/utils`. Inject `FormatDateService` khi cần DI (mock test) hoặc dùng trong Angular template qua service reference.
+
+⚠️ **Unix timestamp là giây, không phải milliseconds**: `Date.now()` trả về milliseconds. Khi dùng JS timestamp làm input, phải chia 1000: `service.transform(Date.now() / 1000)`.
+
+⚠️ **lang không truyền → tự lấy từ UtilsCache**: Đảm bảo ngôn ngữ global đã được set trước khi dùng service (thường trong AppComponent hoặc i18n setup). Nếu chưa set, format aliases có thể không trả về đúng locale.
+
+⚠️ **Format aliases chỉ locale-aware khi truyền `lang='vi'` hoặc `lang='en'`**: Format string trực tiếp như `DD/MM/YYYY HH:mm` không phụ thuộc ngôn ngữ, luôn cho cùng kết quả bất kể `lang`.
+
+⚠️ **Múi giờ mặc định `Asia/Ho_Chi_Minh`**: Service dùng `getDayjs()` đã cấu hình timezone. Để đổi timezone toàn cục, gọi `setDefaultTimeZone('America/New_York')` từ `@libs-ui/utils` trước khi dùng.
+
+## Demo
+
+```bash
+npx nx serve core-ui
+```
+
+Truy cập: http://localhost:4500/services/format-date

package/fesm2022/libs-ui-services-format-date.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"libs-ui-services-format-date.mjs","sources":["../../../../../libs-ui/services/format-date/src/format-date.service.ts","../../../../../libs-ui/services/format-date/src/libs-ui-services-format-date.ts"],"sourcesContent":["import { Injectable } from '@angular/core';\nimport { formatDate } from '@libs-ui/utils';\nimport dayjs from 'dayjs';\n\n@Injectable({ providedIn: 'root' })\nexport class FormatDateService {\n  public transform(time: string | number | dayjs.Dayjs | undefined | null, format = 'YYYY/MM/DD HH:mm', lang?: string): string {\n    return formatDate(time, format, lang) || '';\n  }\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;;;MAKa,iBAAiB,CAAA;AACrB,IAAA,SAAS,CAAC,IAAsD,EAAE,MAAM,GAAG,kBAAkB,EAAE,IAAa,EAAA;QACjH,OAAO,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE;IAC7C;wGAHW,iBAAiB,EAAA,IAAA,EAAA,EAAA,EAAA,MAAA,EAAA,EAAA,CAAA,eAAA,CAAA,UAAA,EAAA,CAAA;AAAjB,IAAA,OAAA,KAAA,GAAA,EAAA,CAAA,qBAAA,CAAA,EAAA,UAAA,EAAA,QAAA,EAAA,OAAA,EAAA,SAAA,EAAA,QAAA,EAAA,EAAA,EAAA,IAAA,EAAA,iBAAiB,cADJ,MAAM,EAAA,CAAA;;4FACnB,iBAAiB,EAAA,UAAA,EAAA,CAAA;kBAD7B,UAAU;mBAAC,EAAE,UAAU,EAAE,MAAM,EAAE;;;ACJlC;;AAEG;;;;"}
+{"version":3,"file":"libs-ui-services-format-date.mjs","sources":["../../../../../libs-ui/services/format-date/src/format-date.service.ts","../../../../../libs-ui/services/format-date/src/libs-ui-services-format-date.ts"],"sourcesContent":["import { Injectable } from '@angular/core';\nimport { formatDate } from '@libs-ui/utils';\nimport dayjs from 'dayjs';\n\n@Injectable({ providedIn: 'root' })\nexport class FormatDateService {\n  public transform(time: string | number | dayjs.Dayjs | undefined | null, format = 'YYYY/MM/DD HH:mm', lang?: string): string {\n    return formatDate(time, format, lang) || '';\n  }\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;;;MAKa,iBAAiB,CAAA;AACrB,IAAA,SAAS,CAAC,IAAsD,EAAE,MAAM,GAAG,kBAAkB,EAAE,IAAa,EAAA;QACjH,OAAO,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;KAC7C;wGAHU,iBAAiB,EAAA,IAAA,EAAA,EAAA,EAAA,MAAA,EAAA,EAAA,CAAA,eAAA,CAAA,UAAA,EAAA,CAAA,CAAA;AAAjB,IAAA,OAAA,KAAA,GAAA,EAAA,CAAA,qBAAA,CAAA,EAAA,UAAA,EAAA,QAAA,EAAA,OAAA,EAAA,SAAA,EAAA,QAAA,EAAA,EAAA,EAAA,IAAA,EAAA,iBAAiB,cADJ,MAAM,EAAA,CAAA,CAAA;;4FACnB,iBAAiB,EAAA,UAAA,EAAA,CAAA;kBAD7B,UAAU;mBAAC,EAAE,UAAU,EAAE,MAAM,EAAE,CAAA;;;ACJlC;;AAEG;;;;"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@libs-ui/services-format-date",
-  "version": "0.2.356-9",
+  "version": "0.2.357-0",
   "peerDependencies": {
     "@angular/core": ">=18.0.0",
     "dayjs": "1.11.5",
-    "@libs-ui/utils": "0.2.356-9"
+    "@libs-ui/utils": "0.2.357-0"
   },
   "sideEffects": false,
   "module": "fesm2022/libs-ui-services-format-date.mjs",