@libs-ui/pipes-format-date 0.2.357-1 → 0.2.357-11

package/README.md

@@ -6,27 +6,46 @@
 
 `@libs-ui/pipes-format-date` cung cấp hai pipe standalone:
 
-- **`LibsUiPipesFormatDatePipe`**: Chuyển đổi các kiểu đầu vào thời gian (string, number/Unix timestamp, Dayjs object) thành chuỗi hiển thị theo định dạng tùy chỉnh, hỗ trợ đa ngôn ngữ.
+- **`LibsUiPipesFormatDatePipe`**: Chuyển đổi các kiểu đầu vào thời gian (string, number/Unix timestamp, Dayjs object) thành chuỗi hiển thị theo 1 trong các định dạng alias cố định (xem bảng ở mục "Hành vi quan trọng"), hỗ trợ đa ngôn ngữ. **Không phải** cú pháp format Dayjs tự do.
 - **`LibsUiPipesGetDayjsPipe`**: Nhận một config object và trả về đối tượng `dayjs.Dayjs`, cho phép gọi các method của Dayjs trực tiếp trong template (`.year()`, `.format()`, v.v.).
 
 Cả hai pipe đều là Pure Pipe — Angular chỉ thực thi lại `transform` khi tham số đầu vào (reference) thay đổi, giúp tránh tính toán lại không cần thiết.
 
 ## Tính năng
 
-- Chấp nhận đầu vào đa dạng: ISO string, Unix timestamp (seconds), `dayjs.Dayjs`, `null`, `undefined`
-- Định dạng đầu ra hoàn toàn tùy chỉnh theo cú pháp Dayjs (vd: `DD/MM/YYYY`, `HH:mm:ss`, `dddd`)
-- Hỗ trợ đa ngôn ngữ (vi, en, ...) thông qua tham số `lang`
+- Chấp nhận đầu vào đa dạng: ISO string, Unix timestamp (giây), `dayjs.Dayjs`, `null`, `undefined`
+- Hỗ trợ đa ngôn ngữ (vi, en) thông qua tham số `lang`
 - Hỗ trợ `formatInput` để parse chuỗi đầu vào có định dạng không chuẩn (vd: `DD/MM/YYYY HH:mm`)
 - Tích hợp múi giờ `Asia/Ho_Chi_Minh` theo mặc định thông qua `getDayjs` từ `@libs-ui/utils`
 - Pure Pipe — hiệu năng cao, chỉ tính toán lại khi input thay đổi
 - Standalone — import trực tiếp vào component, không cần NgModule
 
+## ⚠️ Hành vi quan trọng — `formatOutput` KHÔNG phải chuỗi format Dayjs tự do
+
+**Đây là điểm khác biệt lớn nhất so với dùng Dayjs trực tiếp.** `formatDate` (hàm bên trong pipe) **không** truyền thẳng `formatOutput` vào `dayjs().format(...)`. Thay vào đó, nó so khớp `formatOutput` với một danh sách alias cố định (qua `getTypeByFormat`) để quy về 1 trong 8 kiểu định dạng nội bộ. **Nếu `formatOutput` không khớp bất kỳ alias nào trong bảng dưới, pipe sẽ ÂM THẦM dùng định dạng mặc định `dmy hm` (`MMM D, YYYY HH:mm` / `D MMM, YYYY HH:mm`) — KHÔNG throw lỗi, KHÔNG cảnh báo.**
+
+**Bảng alias hợp lệ cho `formatOutput` (accepted values):**
+
+| Alias truyền vào `formatOutput` | Kiểu nội bộ | Output tiếng Anh (`lang` mặc định/`'en'`) | Output tiếng Việt (`lang: 'vi'`) |
+|---|---|---|---|
+| `'dm'`, `'MM-DD'`, `'dd/MM'`, `'dd/mm'` | `dm` | `MMM D` → `Dec 25` | `D MMM` → `25 Thg 12` |
+| `'dmy'`, `'DD/MM/YYYY'`, `'YYYY-MM-DD'`, `'dd/MM/yyyy'`, `'dd-MM-yyyy'`, `'dd/mm/yyyy'` | `dmy` | `MMM D, YYYY` → `Dec 25, 2024` | `D MMM, YYYY` → `25 Thg 12, 2024` |
+| `'dmy hm'` (mặc định khi không truyền hoặc không khớp alias nào) | `dmy hm` | `MMM D, YYYY HH:mm` → `Dec 25, 2024 00:00` | `D MMM, YYYY HH:mm` → `25 Thg 12, 2024 00:00` |
+| `'my'`, `'M/YYYY'`, `'YYYY-MM'`, `'MM/yyyy'` | `my` | `MMM YYYY ` → `Dec 2024 ` | `MMM, YYYY` → `Thg 12, 2024` |
+| `'dmy hms'`, `'YYYY/MM/DD hh:mm:ss'`, `'dd/mm/yyyy hh:mm:ss'` | `dmy hms` | `MMM D, YYYY HH:mm:ss` → `Dec 25, 2024 00:00:00` | `D MMM, YYYY HH:mm:ss` → `25 Thg 12, 2024 00:00:00` |
+| `'hh:mm'`, `'HH:mm'` | `hh:mm` | `HH:mm` → `00:00` | `HH:mm` → `00:00` |
+| `'hh:mm A'`, `'HH:mm A'` | `hh:mm A` | `HH:mm A` → `00:00 AM` | `HH:mm A` → `00:00 AM` |
+| `'dd/mm/yyyy hh:mm:ss:ss'`, `'yyyy/mm/dd hh:mm:ss:ss'`, `'yyyy-mm-dd hh:mm:ss:ss'`, `'dd-mm-yyyy hh:mm:ss:ss'` (không phân biệt hoa thường) | `dmy hmsS` | `MMM D, YYYY HH:mm:ss:SSS` | `D MMM, YYYY HH:mm:ss:SSS` |
+| Bất kỳ chuỗi nào khác (vd: `'DD/MM/YYYY HH:mm:ss'`, `'dddd, DD MMMM YYYY'`, `'YYYY/MM/DD HH:mm'`) | Không khớp → fallback `dmy hm` | `MMM D, YYYY HH:mm` | `D MMM, YYYY HH:mm` |
+
+⚠️ **Hệ quả quan trọng nhất**: Giá trị mặc định của tham số `formatOutput` là `'YYYY/MM/DD HH:mm'` — chuỗi này **không nằm trong bảng alias**, nên khi KHÔNG truyền `formatOutput`, pipe **KHÔNG** trả về dạng `2024/12/25 00:00` mà trả về dạng mặc định `dmy hm`, ví dụ: `Dec 25, 2024 00:00` (en) hoặc `25 Thg 12, 2024 00:00` (vi). Muốn format tùy ý theo cú pháp Dayjs gốc (không bị giới hạn bởi bảng alias), dùng `LibsUiPipesGetDayjsPipe` rồi gọi `.format(...)` trực tiếp (xem mục 4).
+
 ## Khi nào sử dụng
 
-- Cần hiển thị ngày/giờ theo định dạng cụ thể trong template HTML (vd: `DD/MM/YYYY`, `HH:mm`)
-- Cần định dạng thời gian có ngôn ngữ (thứ, tháng bằng tiếng Việt hoặc tiếng Anh)
-- Cần parse chuỗi thời gian có định dạng lạ (vd: `10/03/2025 15:12`) sang định dạng chuẩn
-- Cần lấy đối tượng Dayjs trong template để gọi các method như `.year()`, `.month()`, `.diff()`
+- Cần hiển thị ngày/giờ theo 1 trong các dạng chuẩn có sẵn (ngày/tháng/năm, giờ:phút, giờ:phút:giây...) — xem bảng alias ở trên
+- Cần định dạng thời gian có ngôn ngữ (thứ/tháng viết tắt bằng tiếng Việt hoặc tiếng Anh) theo các alias `dm`/`dmy`/`dmy hm`/`my`/`dmy hms`/`dmy hmsS`
+- Cần parse chuỗi thời gian có định dạng lạ (vd: `10/03/2025 15:12`) làm đầu vào (`formatInput`)
+- Cần format hoàn toàn tự do theo cú pháp Dayjs (vd: `dddd, DD MMMM YYYY`) → dùng `LibsUiPipesGetDayjsPipe` + `.format()` thay vì `LibsUiPipesFormatDatePipe`
 - Xử lý timestamp Unix (giây) nhận về từ API backend
 
 ## Cài đặt
@@ -50,7 +69,7 @@ export class MyComponent {}
 
 ## Ví dụ sử dụng
 
-### 1. Định dạng mặc định (YYYY/MM/DD HH:mm)
+### 1. Định dạng mặc định (không truyền `formatOutput`)
 
 ```typescript
 import { Component } from '@angular/core';
@@ -61,7 +80,7 @@ import { LibsUiPipesFormatDatePipe } from '@libs-ui/pipes-format-date';
   imports: [LibsUiPipesFormatDatePipe],
   template: `
     <p>{{ now | LibsUiPipesFormatDatePipe }}</p>
-    <!-- Output: 2024/12/25 10:30 -->
+    <!-- Output: Jul 2, 2026 18:09 (định dạng mặc định "dmy hm" — KHÔNG phải "2026/07/02 18:09") -->
   `,
 })
 export class OrderCreatedAtComponent {
@@ -69,7 +88,7 @@ export class OrderCreatedAtComponent {
 }
 ```
 
-### 2. Custom format và đa ngôn ngữ
+### 2. Dùng alias hợp lệ và đa ngôn ngữ
 
 ```typescript
 import { Component } from '@angular/core';
@@ -79,29 +98,31 @@ import { LibsUiPipesFormatDatePipe } from '@libs-ui/pipes-format-date';
   standalone: true,
   imports: [LibsUiPipesFormatDatePipe],
   template: `
-    <!-- Chỉ lấy ngày tháng năm -->
+    <!-- Alias 'DD/MM/YYYY' → quy về kiểu nội bộ "dmy" -->
     <p>{{ dateStr | LibsUiPipesFormatDatePipe:'DD/MM/YYYY' }}</p>
-    <!-- Output: 25/12/2024 -->
+    <!-- Output: Dec 25, 2024 (KHÔNG phải 25/12/2024 — vì "dmy" luôn render "MMM D, YYYY") -->
 
-    <!-- Có giờ phút giây -->
-    <p>{{ dateStr | LibsUiPipesFormatDatePipe:'YYYY-MM-DD HH:mm:ss' }}</p>
-    <!-- Output: 2024-12-25 00:00:00 -->
+    <!-- Alias 'dmy hms' → có giờ phút giây -->
+    <p>{{ dateStr | LibsUiPipesFormatDatePipe:'dmy hms' }}</p>
+    <!-- Output: Dec 25, 2024 00:00:00 -->
 
-    <!-- Tên thứ tiếng Việt -->
-    <p>{{ timestamp | LibsUiPipesFormatDatePipe:'dddd, DD MMMM YYYY':'vi' }}</p>
-    <!-- Output: Thứ Hai, 20 Tháng Năm 2024 -->
+    <!-- Alias 'dmy' + lang 'vi' → tháng viết tắt tiếng Việt -->
+    <p>{{ timestamp | LibsUiPipesFormatDatePipe:'dmy':'vi' }}</p>
+    <!-- Output: 20 Thg 5, 2024 -->
 
-    <!-- Tên thứ tiếng Anh -->
-    <p>{{ timestamp | LibsUiPipesFormatDatePipe:'dddd, MMMM DD, YYYY':'en' }}</p>
-    <!-- Output: Monday, May 20, 2024 -->
+    <!-- Alias 'dmy hm' + lang 'en' -->
+    <p>{{ timestamp | LibsUiPipesFormatDatePipe:'dmy hm':'en' }}</p>
+    <!-- Output: May 20, 2024 15:30 -->
   `,
 })
 export class EventDateComponent {
   dateStr = '2024-12-25';
-  timestamp = 1716222600; // May 20, 2024 15:30:00 GMT+7
+  timestamp = 1716222600; // 20/05/2024 15:30:00 GMT+7
 }
 ```
 
+⚠️ Muốn format tự do đúng nghĩa đen theo cú pháp Dayjs (vd: `dddd, DD MMMM YYYY` để ra "Thứ Hai, 20 Tháng Năm 2024") — pipe `LibsUiPipesFormatDatePipe` **không hỗ trợ**, vì mọi format truyền vào đều bị quy về 1 trong 8 alias ở bảng trên. Dùng `LibsUiPipesGetDayjsPipe` (mục 4) rồi gọi `.format('dddd, DD MMMM YYYY')` trực tiếp trên đối tượng Dayjs trả về.
+
 ### 3. Custom input format (parse chuỗi định dạng lạ)
 
 ```typescript
@@ -114,12 +135,13 @@ import { LibsUiPipesFormatDatePipe } from '@libs-ui/pipes-format-date';
   template: `
     <!--
       Chuỗi đầu vào có định dạng DD/MM/YYYY HH:mm → cần truyền formatInput
-      để dayjs parse đúng trước khi định dạng lại đầu ra
+      để dayjs parse đúng trước khi định dạng lại đầu ra.
+      formatOutput 'dmy hm' là alias hợp lệ (giữ nguyên giờ:phút).
     -->
     <p>
-      {{ rawDate | LibsUiPipesFormatDatePipe:'YYYY/MM/DD HH:mm':undefined:'DD/MM/YYYY HH:mm' }}
+      {{ rawDate | LibsUiPipesFormatDatePipe:'dmy hm':undefined:'DD/MM/YYYY HH:mm' }}
     </p>
-    <!-- Output: 2025/03/10 15:12 -->
+    <!-- Output: Mar 10, 2025 15:12 -->
   `,
 })
 export class ImportedDateComponent {
@@ -153,26 +175,30 @@ export class DateInfoComponent {
 
 ### 5. Dùng `formatDate` trực tiếp trong TypeScript (không inject pipe)
 
-Pipe chỉ là thin wrapper của hàm `formatDate` từ `@libs-ui/utils`. Khi cần dùng trong logic TypeScript, import thẳng hàm đó — không cần inject pipe.
+Pipe chỉ là thin wrapper của hàm `formatDate` từ `@libs-ui/utils`. Khi cần dùng trong logic TypeScript, import thẳng hàm đó — không cần inject pipe. Hành vi alias mô tả ở trên áp dụng y hệt cho hàm này.
 
 ```typescript
 import { formatDate } from '@libs-ui/utils';
 
-// Định dạng mặc định
+// Không truyền formatOutput → alias mặc định 'dmy hm'
 const result1 = formatDate(Date.now() / 1000);
-// Output: '2024/12/25 10:30'
+// Output: 'Jul 2, 2026 18:09' (KHÔNG phải '2026/07/02 18:09')
+
+// Alias 'dmy' hợp lệ
+const result2 = formatDate('2024-12-25', 'dmy');
+// Output: 'Dec 25, 2024'
 
-// Custom format
-const result2 = formatDate('2024-12-25', 'DD/MM/YYYY');
-// Output: '25/12/2024'
+// Alias 'dmy' + ngôn ngữ tiếng Việt
+const result3 = formatDate(1716222600, 'dmy', 'vi');
+// Output: '20 Thg 5, 2024'
 
-// Với ngôn ngữ tiếng Việt
-const result3 = formatDate(1716222600, 'dddd, DD MMMM YYYY', 'vi');
-// Output: 'Thứ Hai, 20 Tháng Năm 2024'
+// Với formatInput để parse chuỗi định dạng lạ (formatOutput là alias hợp lệ 'dmy hm')
+const result4 = formatDate('10/03/2025 15:12', 'dmy hm', undefined, 'DD/MM/YYYY HH:mm');
+// Output: 'Mar 10, 2025 15:12'
 
-// Với formatInput để parse chuỗi định dạng lạ
-const result4 = formatDate('10/03/2025 15:12', 'YYYY/MM/DD HH:mm', undefined, 'DD/MM/YYYY HH:mm');
-// Output: '2025/03/10 15:12'
+// formatOutput KHÔNG khớp alias nào → fallback 'dmy hm', KHÔNG throw lỗi
+const result5 = formatDate('2024-12-25', 'DD/MM/YYYY HH:mm:ss A');
+// Output: 'Dec 25, 2024 00:00' (không phải định dạng đã truyền vào)
 ```
 
 ## Transform — LibsUiPipesFormatDatePipe
@@ -188,17 +214,17 @@ value | LibsUiPipesFormatDatePipe : formatOutput : lang : formatInput
 | Tham số | Type | Bắt buộc | Default | Mô tả | Ví dụ |
 |---|---|---|---|---|---|
 | `time` (value) | `string \| number \| dayjs.Dayjs \| null \| undefined` | Không | `undefined` | Giá trị thời gian cần định dạng | `1716222600`, `'2024-12-25'`, `dayjsObj` |
-| `formatOutput` | `string` | Không | `'YYYY/MM/DD HH:mm'` | Định dạng đầu ra theo cú pháp Dayjs | `'DD/MM/YYYY'`, `'HH:mm:ss'`, `'dddd, DD MMMM YYYY'` |
-| `lang` | `string` | Không | `undefined` | Locale hiển thị cho thứ/tháng | `'vi'`, `'en'` |
-| `formatInput` | `string` | Không | `undefined` | Định dạng của chuỗi đầu vào khi Dayjs không tự nhận diện được | `'DD/MM/YYYY HH:mm'`, `'MM-DD-YYYY'` |
+| `formatOutput` | `string` | Không | `'YYYY/MM/DD HH:mm'` | **PHẢI là 1 trong các alias ở bảng "Hành vi quan trọng" phía trên** — không phải cú pháp Dayjs tự do. Giá trị mặc định `'YYYY/MM/DD HH:mm'` không khớp alias nào nên thực tế luôn fallback về `dmy hm` | `'dmy'`, `'DD/MM/YYYY'`, `'hh:mm A'` |
+| `lang` | `string` | Không | `undefined` | Locale hiển thị cho thứ/tháng (`vi` dùng tháng viết tắt kiểu `Thg 5`) | `'vi'`, `'en'` |
+| `formatInput` | `string` | Không | `undefined` | Định dạng của chuỗi đầu vào khi Dayjs không tự nhận diện được (đây là cú pháp Dayjs tự do, không bị giới hạn alias) | `'DD/MM/YYYY HH:mm'`, `'MM-DD-YYYY'` |
 
 **Ví dụ template:**
 
 ```html
 {{ now | LibsUiPipesFormatDatePipe }}
-{{ dateStr | LibsUiPipesFormatDatePipe:'DD/MM/YYYY' }}
-{{ timestamp | LibsUiPipesFormatDatePipe:'dddd, DD MMMM YYYY':'vi' }}
-{{ rawDate | LibsUiPipesFormatDatePipe:'YYYY/MM/DD':undefined:'DD/MM/YYYY' }}
+{{ dateStr | LibsUiPipesFormatDatePipe:'dmy' }}
+{{ timestamp | LibsUiPipesFormatDatePipe:'dmy':'vi' }}
+{{ rawDate | LibsUiPipesFormatDatePipe:'dmy hm':undefined:'DD/MM/YYYY HH:mm' }}
 ```
 
 **Ví dụ standalone (không dùng template):**
@@ -209,16 +235,16 @@ import { LibsUiPipesFormatDatePipe } from '@libs-ui/pipes-format-date';
 const pipe = new LibsUiPipesFormatDatePipe();
 
 pipe.transform('2024-12-25');
-// Output: '2024/12/25 00:00'
+// Output: 'Dec 25, 2024 00:00' (alias mặc định 'dmy hm')
 
-pipe.transform('2024-12-25', 'DD/MM/YYYY');
-// Output: '25/12/2024'
+pipe.transform('2024-12-25', 'dmy');
+// Output: 'Dec 25, 2024'
 
-pipe.transform(1716222600, 'dddd, DD MMMM YYYY', 'vi');
-// Output: 'Thứ Hai, 20 Tháng Năm 2024'
+pipe.transform(1716222600, 'dmy', 'vi');
+// Output: '20 Thg 5, 2024'
 
-pipe.transform('10/03/2025 15:12', 'DD/MM/YYYY HH:mm', undefined, 'DD/MM/YYYY HH:mm');
-// Output: '10/03/2025 15:12'
+pipe.transform('10/03/2025 15:12', 'dmy hm', undefined, 'DD/MM/YYYY HH:mm');
+// Output: 'Mar 10, 2025 15:12'
 
 pipe.transform(null);
 // Output: '' (chuỗi rỗng — không throw lỗi)
@@ -276,6 +302,8 @@ pipe.transform({ date: undefined }); // Trả về undefined
 
 ## Lưu ý quan trọng
 
+⚠️ **`formatOutput` chỉ nhận alias cố định, KHÔNG phải cú pháp Dayjs tự do**: Xem đầy đủ bảng alias ở mục "Hành vi quan trọng" phía trên. Truyền chuỗi format Dayjs tùy ý không nằm trong bảng sẽ bị âm thầm bỏ qua và fallback về `dmy hm`.
+
 ⚠️ **Unix timestamp tính bằng giây, không phải milliseconds**: Backend thường trả về Unix timestamp theo giây (`1716222600`). Nếu bạn có timestamp theo milliseconds (JavaScript `Date.now()`), cần chia 1000 trước khi truyền vào pipe: `Date.now() / 1000`.
 
 ⚠️ **Múi giờ mặc định là Asia/Ho_Chi_Minh**: Pipe dùng `getDayjs` từ `@libs-ui/utils` — đã được cấu hình mặc định múi giờ `Asia/Ho_Chi_Minh`. Nếu cần múi giờ UTC, dùng `LibsUiPipesGetDayjsPipe` với `{ utc: true }`.
@@ -290,18 +318,10 @@ pipe.transform({ date: undefined }); // Trả về undefined
 <!-- SAI — gọi function trong template, tính toán lại mỗi change detection cycle -->
 <p>{{ formatDate(order.createdAt) }}</p>
 
-<!-- ĐÚNG — dùng pipe -->
-<p>{{ order.createdAt | LibsUiPipesFormatDatePipe:'DD/MM/YYYY' }}</p>
-```
-
-## Demo
-
-```bash
-npx nx serve core-ui
+<!-- ĐÚNG — dùng pipe. 'dmy' là alias hợp lệ (xem bảng alias phía trên) -->
+<p>{{ order.createdAt | LibsUiPipesFormatDatePipe:'dmy' }}</p>
 ```
 
-Truy cập: http://localhost:4500/pipes/format-date
-
 ## Unit Tests
 
 ```bash

package/package.json

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